Document revision date: 30 March 2001

## OpenVMS RTL Library (LIB$) Manual

Previous | Contents | Index

## 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 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 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 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.

## LIB$FIND_FILE_END

> The End of Find File routine is called once after each sequence of calls to LIB$FIND_FILE. LIB$FIND_FILE_END deallocates any saved OpenVMS RMS context and deallocates the virtual memory used to hold the allocated context block.

### Format

> LIB$FIND_FILE_END context

### RETURNS

> OpenVMS usage: | cond_value
> type: | longword (unsigned)
> access: | write only
> mechanism: | by value

### Argument

> #### context

> OpenVMS usage: | context
> type: | longword (unsigned)
> access: | read only
> mechanism: | by reference

> Zero or the address of a FAB/NAM buffer from a previous call to LIB$FIND_FILE. The context argument is the address of a longword that contains this context.

### Description

> LIB$FIND_FILE_END should be called by your program after each sequence of calls to LIB$FIND_FILE. This will prevent the default values from the previous call from affecting the next file specification.

> LIB$FIND_FILE_END deallocates the context used in the last call to LIB$FIND_FILE so that the context retained will not be used in subsequent calls to LIB$FIND_FILE. If LIB$FIND_FILE was directed to process file specifications for multiple input files, the saved file specifications are also deallocated.

### Condition Values Returned

> SS$_NORMAL | Routine successfully completed.
> RMS$_FAB | File access block argument is not the address of a valid FAB.

## LIB$FIND_IMAGE_SYMBOL

> The Find Universal Symbol in Shareable Image File routine reads universal symbols from the shareable image file. This routine then dynamically activates a shareable image into the P0 address space of a process.

### Format

> LIB$FIND_IMAGE_SYMBOL filename ,symbol ,symbol-value [,image-name] [,flags]

### RETURNS

> OpenVMS usage: | cond_value
> type: | longword (unsigned)
> access: | write only
> mechanism: | by value

### Arguments

> #### filename

> OpenVMS usage: | char_string
> type: | character string
> access: | read only
> mechanism: | by descriptor

> Name of the file for which LIB$FIND_IMAGE_SYMBOL is searching. The filename argument is the address of a descriptor pointing to this file name string. This argument may contain only the file name. File type cannot be indicated. If any file specification punctuation characters (:, [, <, ;, .) are present, the error SS$_IVLOGNAM is returned.

> You can specify a file specification for the image name with the optional image-name argument. If you do not specify image-name, a default file specification of SYS$SHARE:.EXE is applied to the file name. If the file is not in SYS$SHARE:.EXE, a logical name must be used to direct this routine to locate the correct file. Only logical names defined in the system logical name table with the /EXEC attribute will be considered while the image activator is processing a request from an image that was installed with privileges. If the calling image was installed with privileges, the image being activated and any shareable images or message sections it references must be installed as a known image with the INSTALL utility. Running an image to which you have only Execute (not Read) access results in the same restrictions on logical names and shareable images as does running a privileged image.

> On VAX systems, the filename descriptor must be class D, S, or Z.

> #### symbol

> OpenVMS usage: | char_string
> type: | character string
> access: | read only
> mechanism: | by descriptor

> Symbol for which LIB$FIND_IMAGE_SYMBOL is searching in the filename file. The symbol argument is the address of a descriptor pointing to the symbol name string. The symbol name string can be input in uppercase, lowercase, or mixed case letters.

> #### symbol-value

> OpenVMS usage: | longword_signed
> type: | longword (signed)
> access: | write only
> mechanism: | by reference

> Symbol value that LIB$FIND_IMAGE_SYMBOL has located. The symbol-value argument is the address of a signed longword integer into which LIB$FIND_IMAGE_SYMBOL returns the symbol value. If the symbol is relocatable, the starting virtual address of the shareable image in memory is added to the symbol value.

> #### image-name

> OpenVMS usage: | char_string
> type: | character string
> access: | read only
> mechanism: | by descriptor

> Default file specification applied to the image name. The optional image-name argument is a string used as the RMS default file specification when parsing filename as the primary filename. If image-name is not supplied, then a default file specification of SYS$SHARE:.EXE is applied to the image name.

> On VAX systems, the image-name descriptor must be class D, S, or Z.

> #### flags

> OpenVMS usage: | mask_longword
> type: | longword (unsigned)
> access: | read only
> mechanism: | by reference

> Control flags. The flags argument is the address of a longword integer that contains the control flags.

> Bit | Value | Description
> --- | --- | ---
> 0 | Reserved to Compaq |
> 1 | Reserved to Compaq |
> 2 | Reserved to Compaq |
> 3 | Reserved to Compaq |
> 4 | LIB$M_FIS_MIXEDCASE | Causes LIB$FIND_IMAGE_SYMBOL to look for the symbol without converting it to uppercase.

> This is an optional argument. If omitted, the default is 0. If omitted, or if LIB$M_FIS_MIXEDCASE (bit 4) is 0, LIB$FIND_IMAGE_SYMBOL converts the specified symbol to uppercase before it is used.

### Description

> The shareable image that LIB$FIND_IMAGE_SYMBOL activates must have been already linked and must be position independent. You must have read access to the shareable image file to use this routine.

> LIB$FIND_IMAGE_SYMBOL writes the symbol value that it has located into the symbol-value argument.

> After the first call to LIB$FIND_IMAGE_SYMBOL for a particular image, successive calls for that image are processed quickly. The image is activated only once and an in-memory database is maintained. There is no way to deallocate this database, nor is there any supported method to remove an activated image from the address space. All images are activated into P0 space.

> LIB$FIND_IMAGE_SYMBOL locates the universal symbol in its database qualified by the file name exactly as given in the filename argument. Therefore, a reference to a lexically different but equivalent file name causes a new copy of the same shareable image to be loaded and searched. To avoid this situation, always specify the desired file name in the same form.

> To work properly with translated VAX images on Alpha systems, LIB$FIND_IMAGE_SYMBOL may modify the name of the file being searched and may retry the search if the first search failed. If called from a translated image, LIB$FIND_IMAGE_SYMBOL appends "_TV" to the file name before searching. This locates the translated version of the image being searched. If the search fails to find the file or the file does not define the symbol, LIB$FIND_IMAGE_SYMBOL trys again with the unmodified original file name. This locates the native Alpha version of the image. If the second search also fails, an error is returned. If LIB$FIND_IMAGE_SYMBOL is called from a native Alpha program, the order of the searches is reversed. The first search is done with the unmodified original file name. If that fails, the second search is done with "_TV" appended to the file name. If the second search fails, an error is returned.

> LIB$FIND_IMAGE_SYMBOL disables AST recognition while it is executing. AST recognition is reenabled before returning to the caller only if AST recognition was previously enabled.

> LIB$FIND_IMAGE_SYMBOL signals all errors and returns the status in R0.

### Condition Values Returned

> LIB$_BADCCC | Illegal compilation code.
> LIB$_EOMERROR | Compilation errors.
> LIB$_EOMFATAL | Fatal compilation errors.
> LIB$_EOMWARN | Compilation warnings.
> LIB$_GSDTYP | Illegal universal symbol directory record type.
> LIB$_ILLFMLCNT | Maximum argument count exceeds maximum for routine.
> LIB$_ILLMODNAM | Illegal module name length.
> LIB$_ILLPSCLEN | Illegal program section length.
> LIB$_ILLRECLEN | Illegal record length in module.
> LIB$_ILLRECLN2 | Illegal record length.
> LIB$_ILLRECTYP | Illegal record type in module.
> LIB$_ILLRECTY2 | Illegal record type.
> LIB$_ILLSYMLEN | Illegal symbol length.
> LIB$_NOEOM | No end of module record contained in the module.
> LIB$_RECTOOSML | Record too small; data overflows object record in module.
> LIB$_SEQUENCE | Illegal record sequence in module.
> LIB$_SEQUENCE2 | Illegal record sequence.
> LIB$_STRVL | Illegal object language structure level in module.
> Note that all of the above error messages indicate a format error in the shareable image. |
> LIB$_INSVIRMEM | Insufficient virtual memory.
> SS$_IVLOGNAM | The filename argument contained more than just a file name; a device or directory specification was found in the string.

Any condition values returned by RTL routines LIB$INSERT_TREE or LIB$LOOKUP_TREE.

Previous | Next | Contents | Index

| privacy and legal statement |
5932PRO_017.HTML