Document revision date: 30 March 2001

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.

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.

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.

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.

	privacy and legal statement
5932PRO_017.HTML