 |
HP OpenVMS RTL Library (LIB$) Manual
LIB$FID_TO_NAME
The Convert Device and File ID to File Specification routine converts a
disk device name and file identifier to a file specification.
Format
LIB$FID_TO_NAME device-name ,file-id ,filespec [,filespec-length]
[,directory-id] [,acp-status]
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Arguments
device-name
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
read only |
| mechanism: |
by descriptor |
Device name to be converted. The device-name argument
is the address of a descriptor pointing to the device name. It must
reference a disk device, and must contain 64 characters or less.
LIB$FID_TO_NAME obtains device-name from the NAM$T_DVI
field of an OpenVMS RMS name block.
file-id
| OpenVMS usage: |
vector_word_unsigned |
| type: |
word (unsigned) |
| access: |
read only |
| mechanism: |
by reference, array reference |
Specifies the file identifier. The file-id argument is
the address of an array of three words containing the file
identification. LIB$FID_TO_NAME obtains file-id from
the NAM$W_FID field of an OpenVMS RMS name block. The $FIDDEF macro
defines the structure of file-id.
filespec
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
write only |
| mechanism: |
by descriptor |
Receives the file specification. The filespec argument
is the address of a descriptor pointing to the file specification
string. As of OpenVMS Version 7.2, the maximum file specification
string that can be returned is 4095 bytes on Alpha and I64 systems, and
510 bytes on VAX systems. On versions prior to Version 7.2, the maximum
is 510 bytes on both platforms. Refer to the Description section for
more information about the file specification returned.
filespec-length
| OpenVMS usage: |
word_unsigned |
| type: |
word (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Receives the number of characters written into
filespec, excluding padding in the case of a
fixed-length string. The optional filespec-length
argument is the address of an unsigned word containing the number of
characters.
If the output string is truncated to the number of characters specified
in filespec, then filespec-length is
set to that truncated size. Therefore, you can always use
filespec-length to access a valid substring of
filespec.
directory-id
| OpenVMS usage: |
vector_word_unsigned |
| type: |
word (unsigned) |
| access: |
read only |
| mechanism: |
by reference, array reference |
Specifies a directory file identifier. The
directory-id argument is the address of an array of
three words containing the directory file identifier. LIB$FID_TO_NAME
obtains this array from the NAM$W_DID field of an OpenVMS RMS name
block. The $FIDDEF macro defines the structure of
directory-id.
This parameter is relevant only for a structure level-1 disk on OpenVMS
VAX systems. This parameter is ignored on OpenVMS Alpha and I64 systems
because level-1 disks are not supported on OpenVMS Alpha and I64
systems.
acp-status
| OpenVMS usage: |
longword_unsigned |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
The status resulting from traversing the backward links. The optional
acp-status argument is the address of an unsigned
longword containing the status.
Description
LIB$FID_TO_NAME converts a disk device name and file identifier to a
file specification by requesting the ACP file specification attribute.
On OpenVMS Alpha and I64 systems, if the file specification is longer
than can be accommodated by the filespec buffer, a
directory in the path may be replaced by a DID abbreviation (see the
Guide to OpenVMS File Applications). If the file specification, even after DID abbreviation,
is longer than can be accommodated by the buffer, the file
specification is truncated, and LIB$STRTRU is returned as an alternate
success status.
On OpenVMS VAX systems, if you use the LIB$FID_TO_NAME routine on a
structure level 1 disk, specify the directory-id
argument to ensure proper operation of the routine.
LIB$FID_TO_NAME uses the directory backpointer stored in the file
header. With files in SYS$COMMON, the directory structure is duplicated
because of some SET FILE/ENTERs of directory names. If directory names
have been renamed or the tree structure modified (which the OpenVMS
operating system does with the [SYCOMMON] tree), the file specification
returned by this routine may not be useful.
LIB$FID_TO_NAME stores the output arguments (filespec,
filespec-length, and acp-status) only
if the routine successfully finishes.
Note
This routine calls LIB$GET_EF. Please read the note in the
Description section of that routine.
|
Condition Values Returned
|
LIB$_NORMAL
|
Routine successfully completed.
|
|
LIB$STRTRU
|
Output string truncated (qualified success).
|
|
LIB$_INVARG
|
Required argument omitted, or
device-name is longer than 64 characters.
|
|
LIB$_INVFILSPE
|
The
device-name argument does not reference a disk.
|
Any condition value returned by RTL routine LIB$ANALYZE_SDESC, or the
$ASSIGN, $QIO, or $DASSGN system services.
LIB$FILE_SCAN
The File Scan routine searches an area, such as a directory, for all
files matching the file specification given and transfers program
execution to the specified user-written routine. Wildcards are
acceptable. An action routine is called for each file and/or error
found. LIB$FILE_SCAN allows the search sequence to continue even if an
error occurs while processing a particular file.
Format
LIB$FILE_SCAN fab ,user-success-procedure ,user-error-procedure
[,context]
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Arguments
fab
| OpenVMS usage: |
fab |
| type: |
unspecified |
| access: |
read only |
| mechanism: |
by reference |
File Access Block (FAB) referencing a valid NAM block or NAML block.
The fab argument is the address of the FAB that
contains the address and length of the file specification being
searched for by LIB$FILE_SCAN. On Alpha and I64 systems, NAML blocks
support the use of file specifications with a maximum length of
NAML$C_MAXRSS. See the OpenVMS Record Management Services Reference Manual for information on NAML blocks.
user-success-procedure
| OpenVMS usage: |
procedure |
| type: |
procedure value |
| access: |
function call (before return) |
| mechanism: |
by value |
User-supplied success routine that LIB$FILE_SCAN calls when a file is
found. The success routine is invoked with the FAB address that was
passed to LIB$FILE_SCAN. The user context may be pased to this routine
using the FAB$L_CTX field in the FAB.
user-error-procedure
| OpenVMS usage: |
procedure |
| type: |
procedure value |
| access: |
function call (before return) |
| mechanism: |
by value |
User-supplied error routine that LIB$FILE_SCAN calls when it encounters
an error. The error routine is called with the FAB argument that was
passed to LIB$FILE_SCAN.
context
| OpenVMS usage: |
context |
| type: |
longword (unsigned) |
| access: |
modify |
| mechanism: |
by reference |
Default file context used in processing file specifications for
multiple input files. The context argument is the
address of a longword, which must be initialized to zero by your
program before the first call to LIB$FILE_SCAN. After the first call,
LIB$FILE_SCAN maintains this longword. You must not change the value of
context in subsequent calls to LIB$FILE_SCAN.
Name blocks and file specification strings are allocated by
LIB$FILE_SCAN, and context is used to retain their
addresses so they may be deallocated later. If the
context argument is not passed, unspecified portions
of the file specification will be inherited from the previous file
specification processed, rather than from multiple input file
specifications.
Description
LIB$FILE_SCAN is called with the address of a File Access Block (FAB)
and calls an action routine for each file found and/or error returned.
LIB$FILE_SCAN allows the search sequence to continue even if an error
occurs while processing a particular file.
If this routine is called once for each file specification argument in
a command line, portions of the file specifications which are not
specified by the user are inherited from the last files processed.
On Alpha and I64 systems, support for a file specification greater than
255 characters is provided by the use of NAML blocks rather than NAM
blocks. See the OpenVMS Record Management Services Reference Manual for information on NAML blocks.
You must call LIB$FILE_SCAN_END before initiating a new sequence of
calls to LIB$FILE_SCAN.
Condition Values Returned
Any condition value returned by the RMS Parse service.
LIB$FILE_SCAN_END
The End-of-File Scan routine is called after each sequence of calls to
LIB$FILE_SCAN. LIB$FILE_SCAN_END deallocates any saved OpenVMS RMS
context and/or deallocates the virtual memory that had been allocated
for holding the related file specification information.
Format
LIB$FILE_SCAN_END [fab] [,context]
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Arguments
fab
| OpenVMS usage: |
fab |
| type: |
unspecified |
| access: |
modify |
| mechanism: |
by reference |
File access block (FAB) used with LIB$FILE_SCAN. The optional
fab argument is the address of the FAB that contains
the address and length of the file specification.
context
| OpenVMS usage: |
context |
| type: |
longword (unsigned) |
| access: |
modify |
| mechanism: |
by reference |
Temporary default context used in LIB$FILE_SCAN. The optional
context argument is the address of a longword
containing this temporary default context.
Description
Your program should call LIB$FILE_SCAN_END after each sequence of calls
to LIB$FILE_SCAN. The function that LIB$FILE_SCAN_END performs depends
upon the arguments you specify. If you specify fab,
LIB$FILE_SCAN_END parses the null string to deallocate any saved RMS
context. If you specify context, LIB$FILE_SCAN_END
deallocates any virtual memory that was allocated for holding the
related file specification information. If you specify both
fab and context, LIB$FILE_SCAN_END
performs both functions. However, if you do not specify either
argument, LIB$FILE_SCAN_END does nothing.
If LIB$FILE_SCAN is directed to process the specifications for multiple
input files, LIB$FILE_SCAN_END is used to deallocate those saved file
specifications. If LIB$FILE_SCAN_END is called by your program after
each sequence of calls to LIB$FILE_SCAN, it will prevent the defaults
from the previous call from affecting context value in the next call to
LIB$FILE_SCAN. LIB$FILE_SCAN_END does this by replacing the context
value passed to it with a temporary context value that your program
passes to LIB$FILE_SCAN the next time it is called.
Condition Values Returned
|
SS$_NORMAL
|
Routine successfully completed.
|
|
RMS$_FAB
|
The
fab argument is not the address of a valid FAB.
|
LIB$FIND_FILE
The Find File routine is called with a file specification for which it
searches. LIB$FIND_FILE returns one file specification for each call.
The file specification may contain wildcards.
Format
LIB$FIND_FILE filespec ,resultant-filespec ,context [,default-filespec]
[,related-filespec] [,status-value] [,flags]
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Arguments
filespec
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
read only |
| mechanism: |
by descriptor |
File specification, which may contain wildcards, that LIB$FIND_FILE
uses to search for the desired file. The filespec
argument is the address of a descriptor pointing to the file
specification. If running on Alpha or I64 and flag LIB$M_FIL_LONG_NAMES
is set, the maximum length of a file specification is specified by
NAML$C_MAXRSS, otherwise the maximum length of a file specification is
255 bytes.
The file specification used may also contain a search list logical
name. If present, the search list logical name elements can be used as
accumulative to related file specifications, so that portions of file
specifications not specified by the user are inherited from previous
file specifications.
resultant-filespec
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
modify |
| mechanism: |
by descriptor |
Resultant file specification that LIB$FIND_FILE returns when it finds a
file that matches the specification in the filespec
argument. The resultant-filespec argument is the
address of a descriptor pointing to the resultant file specification.
context
| OpenVMS usage: |
context |
| type: |
longword (unsigned) |
| access: |
modify |
| mechanism: |
by reference |
A longword integer variable into which the routine stores a context
value for use by future calls to LIB$FIND_FILE or LIB$FIND_FILE_END.
The context argument is an unsigned longword integer
containing the address of the context. This variable must be set to
zero before the first call to LIB$FIND_FILE. You can use the same
context argument from one LIB$FIND_FILE call to
another provided you have not called LIB$FIND_FILE_END for that
context first. LIB$FIND_FILE uses this argument to
retain the context when processing multiple input files. Portions of
file specifications that the user does not specify may be inherited
from the last files processed because the file contexts are retained in
this argument. You must not change the value of
context in subsequent calls to LIB$FIND_FILE.
default-filespec
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
read only |
| mechanism: |
by descriptor |
Default file specification. The default-filespec
argument is the address of a descriptor pointing to the default file
specification. See the OpenVMS Record Management Services Reference Manual for information about default file
specifications.
related-filespec
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
read only |
| mechanism: |
by descriptor |
Related file specification containing the context of the last file
processed. The related-filespec argument is the
address of a descriptor pointing to the related file specification.
The related file specification is useful when you are processing lists
of file specifications. Unspecified portions of the file specification
are inherited from the last file processed. For more information on
related file specifications, see the OpenVMS Record Management Services Reference Manual.
status-value
| OpenVMS usage: |
longword_unsigned |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
RMS secondary status value from a failing RMS operation. The
status-value argument is an unsigned longword
containing the address of a longword-length buffer to receive the RMS
secondary status value (usually returned in the file access block
field, FAB$L_STV).
flags
| OpenVMS usage: |
mask_longword |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
User flags. The flags argument is the address of an
unsigned longword containing the user flags.
The flag bits and their corresponding symbols are described in the
following table:
| Bit |
Symbol |
Description |
|
0
|
LIB$M_FIL_NOWILD
|
If set, LIB$FIND_FILE returns an error if a wildcard character is input.
|
|
1
|
LIB$M_FIL_MULTIPLE
|
If set, this performs temporary defaulting for multiple input files and
the
related-filespec argument is ignored. See description
of
context in LIB$FILE_SCAN. Each time LIB$FIND_FILE is
called with a different file specification, the specification from the
previous call is automatically used as a related file specification.
This allows parsing of the elements of a search-list logical name such
as DISK2:[SMITH] FIL1.TYP,FIL*2.TYP, and so on. Use of this feature is
required to get the desired defaulting with search list logical name.
LIB$FIND_FILE_END must be called between each command line in
interactive use or the defaults from the previous command line affect
the current file specification.
|
|
2
|
LIB$M_FIL_LONG_NAMES
|
(Alpha and I64 only) If set, LIB$FIND_FILE can process file
specifications with a maximum length of NAML$C_MAXRSS. If clear,
LIB$FIND_FILE can process file specifications with a maximum length of
255 (default).
|
Description
LIB$FIND_FILE returns one file specification per call unless it fails
to find the target file specification. In this case, the routine
returns the condition value RMS$_NMF (no more files). Each successful
call to LIB$FIND_FILE results in a new
resultant-filespec.
When you call LIB$FIND_FILE repeatedly using the same
context, filespec is saved only if
you set the MULTIPLE bit. If you specify a different
filespec on your next call and set the MULTIPLE bit,
the file specification from the previous call defaults as the related
file specification.
For each LIB$FIND_FILE call, RMS first applies the defaults from
default-filespec and then uses the defaults from
related-filespec, if relevant. Default file
specifications are used only if components are missing from the
filespec argument and the needed components are found
in default-filespec. The
related-filespec argument is used when you process
lists of file specifications. Unspecified portions of the file
specification are inherited from the last file processed. This provides
an extra level of file specification defaults. For additional
information on related file specifications and input file parsing, see
the Guide to OpenVMS File Applications.
The filespec argument can contain wildcard characters.
LIB$FIND_FILE can be called repeatedly using the same
context argument until the error RMS$_NMF (no more
files) is returned.
LIB$FIND_FILE searches for a certain wildcard file specification and
returns all file specifications that satisfy that wildcard file
specification.
If you make multiple calls to LIB$FIND_FILE, be aware of the following
behavior:
- If the NOWILD bit is not set and the file specification does not
contain any wildcard characters, LIB$FIND_FILE returns the appropriate
file name on the first call and the condition value RMS$_NMF on the
next call.
- If the NOWILD bit is set and you use the same nonwildcard file
specification, LIB$FIND_FILE returns the file name on the first call as
well as each subsequent call.
On Alpha and I64 systems, support for file specifications longer than
255 characters is provided only when the LIB$M_FIL_LONG_NAMES flag is
set in the flags argument. When this flag is set, a
NAML block (rather than a NAM block) is part of the context, and file
specifications can have a maximum length of NAML$C_MAXRSS. See the
OpenVMS Record Management Services Reference Manual for information on NAML blocks.
You must call LIB$FIND_FILE_END before initiating a new sequence of
calls to LIB$FIND_FILE to properly deallocate all of the internal data
structures that were allocated in the calls to LIB$FIND_FILE. After you
call LIB$FIND_FILE_END, the context value is no longer valid and cannot
be used on any subsequent LIB$FIND_FILE calls.
If the error RMS$_CHN is returned, RMS has no more channels to assign.
There are two possible reasons for this:
- You did not call LIB$FIND_FILE_END before initiating a new call
with a context variable to LIB$FIND_FILE. (This is the most common
reason.)
- The system parameter CHANNELCNT is too low.
Condition Values Returned
|
RMS$_NORMAL
|
Routine successfully completed.
|
|
LIB$_NOWILD
|
A wildcard character was present in the file specification parsed, and
the wildcard flag bit was set to no wildcard. (This is actually the
SHR$_NOWILD error message after application of the LIB$ facility code.)
|
|
RMS$_CHN
|
No more channels.
|
|
RMS$_NMF
|
No more files.
|
Any condition value returned by RMS Parse and Search services,
LIB$GET_VM, LIB$GET_VM_64, LIB$FREE_VM, LIB$FREE_VM_64, LIB$SCOPY_R_DX,
or LIB$SCOPY_R_DX_64.
|
