HP OpenVMS DCL Dictionary
Searches a directory file and returns the full file specification for a
file you specify.
A character string containing the expanded file specification for the
filespec argument. If the F$SEARCH function does not
find the file in the directory, the function returns a null string ("").
Specifies a character string containing the file specification to be
searched for. If the device or directory names are omitted, the
defaults from your current default disk and directory are used. The
F$SEARCH function does not supply defaults for a file name or type. If
the version is omitted, the specification for the file with the highest
version number is returned. If the filespec argument
contains the asterisk (*) or the percent sign (%) wildcard characters,
each time F$SEARCH is called, the next file specification that agrees
with the filespec argument is returned. A null string
is returned after the last file specification that agrees with the
Specifies a positive integer representing the search stream
The search stream identification number is used to maintain separate
search contexts when you use the F$SEARCH function more than once and
when you supply different filespec arguments. If you
use the F$SEARCH function more than once in a command procedure and if
you also use different filespec arguments, specify
stream-id arguments to identify each search separately.
If you omit the stream-id argument, the F$SEARCH
function starts searching at the beginning of the directory file each
time you specify a different filespec argument.
The lexical function F$SEARCH invokes the RMS service $SEARCH to search
a directory file and return the full file specification for a file you
specify. The F$SEARCH function allows you to search for files in a
directory by using the RMS service $SEARCH. For more information on the
$SEARCH routine, refer to the OpenVMS Record Management Services Reference Manual.
You can use the F$SEARCH function in a loop in a command procedure to
return file specifications for all files that match a
filespec argument containing an asterisk (*) or a
percent sign (%) wildcard character. Each time the F$SEARCH function is
executed, it returns the next file specification that matches the file
specification that contains a wildcard character. After the last file
specification is returned, the next F$SEARCH call returns a null
string. When you use the F$SEARCH function in a loop, you must include
an asterisk (*) or the percent sign (%) wildcard characters in the
filespec argument; otherwise, the F$SEARCH always
returns the same file specification.
Note that you must maintain the context of the search stream in one of
the following ways:
- Explicitly, by stating a stream-id argument
- Implicitly, by omitting the stream-id argument and
by using the same filespec argument each time you
execute the F$SEARCH function
If you do not maintain the context of the search stream, you start a
new search at the beginning of the directory file each time you specify
a different filespec argument.
The lexical function F$SEARCH can return any file that matches the
selection criteria you specify, and that exists in the directory at
some time between the beginning and the end of the search. Files that
are created, renamed, or deleted during the search may or may not be
$ FILE = F$SEARCH("SYS$SYSTEM:*.EXE")
$ IF FILE .EQS. "" THEN EXIT
$ SHOW SYMBOL FILE
$ GOTO START
This command procedure displays the file specifications of the latest
version of all .EXE files in the SYS$SYSTEM directory. (Only the latest
version is returned because an asterisk (*) wildcard character is not
used as the version number.) The filespec argument
SYS$SYSTEM:*.EXE is surrounded by quotation marks (" ")
because it is a character string expression.
Because no stream-id argument is specified, the
F$SEARCH function uses a single search stream. Each subsequent F$SEARCH
call uses the same filespec argument to return the
next file specification of an .EXE file from SYS$SYSTEM:. After the
latest version of each .EXE file has been displayed, the F$SEARCH
function returns a null string ("") and the procedure exits.
$ COM = F$SEARCH ("*.COM;*",1)
$ DAT = F$SEARCH ("*.DAT;*",2)
$ SHOW SYMBOL COM
$ SHOW SYMBOL DAT
$ IF (COM.EQS. "") .AND. (DAT.EQS. "") THEN EXIT
$ GOTO START
This command procedure searches the default disk and directory for both
.COM and .DAT files. Note that the stream-id argument
is specified for each F$SEARCH call so that the context for each search
The first F$SEARCH call starts searching from the top of the directory
file for a file with a type .COM. When it finds a .COM file, a pointer
is set to maintain the search context. When the F$SEARCH function is
used the second time, it again starts searching from the top of the
directory file for a file with a type .DAT. When the procedure loops
back to the label START, the stream-id argument allows
F$SEARCH to start searching in the correct place in the directory file.
After all versions of .COM and .DAT files are returned, the procedure
$ FILESPEC = F$SEARCH("TRNTO""SMITH SALLY""::DKA1:[PROD]*.DAT")
$ SHOW SYMBOL FILESPEC
FILESPEC = "TRNTO"smith password"::DKA1:[PROD]CARS.DAT"
This example uses the F$SEARCH function to return a file specification
for a file at a remote node. The access control string is enclosed in
quotation marks because it is part of a character string expression
when it is an argument for the F$SEARCH function. To include quotation
marks in a character string expression, you must use two sets of
Note that, when the F$SEARCH function returns a node name containing an
access control string, it substitutes the word "password" for
the actual user password.