HP OpenVMS Systems Documentation

HP OpenVMS DCL Dictionary

Searches a directory file and returns the full file specification for a file you specify.

Format

F$SEARCH (filespec[,stream-id])

Return Value

Arguments

filespec

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 filespec argument.

stream-id

Specifies a positive integer representing the search stream identification number.

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.

Description

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, see 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.

Note 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 returned.

Examples

$ START:
$     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.

$ START:
$    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 is maintained.

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

$ 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 quotation marks.

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.