|
||||||||||
|
|
|
|
|
|
|
|
|
|
|
|
||||||||||
|
 |
 |
HP OpenVMS systems documentation |
|
| Previous | Contents | Index |
The Convert Device and File ID to File Specification routine converts a disk device name and file identifier to a file specification.
LIB$FID_TO_NAME device-name ,file-id ,filespec [,filespec-length] [,directory-id] [,acp-status]
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
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.
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.
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.
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.
LIB$FILE_SCAN fab ,user-success-procedure ,user-error-procedure [,context]
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
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.
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.
Any condition value returned by the RMS Parse service.
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.
LIB$FILE_SCAN_END [fab] [,context]
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
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.
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.
SS$_NORMAL Routine successfully completed. RMS$_FAB The fab argument is not the address of a valid FAB.
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.
LIB$FIND_FILE filespec ,resultant-filespec ,context [,default-filespec] [,related-filespec] [,status-value] [,flags]
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
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).
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.
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.
| Previous | Next | Contents | Index |