VMS Help Lexicals, F$SEARCH  *Conan The Librarian (sorry for the slow response - running on an old VAX)

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

    Format

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

1 - Return Value

    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 ("").

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

3 - Examples

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

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

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