F$SEARCH()

F$SEARCH() is a lexical function that searches directory files for the file specified as the parameter, and returns the complete file specification of that file

Syntax

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

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.

Examples

$LOOP:
$     FILE = F$SEARCH("DKA0:[...]*.*;*")
$     IF FILE .EQS. "" THEN EXIT
$     SHOW SYMBOL FILE
$     GOTO LOOP
 

This loop displays every file in every directory on DKA0.

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