Locates a specified portion of a character string and returns as
    an integer the offset of the first character. (An offset is the
    position of a character or a substring relative to the beginning
    of the string. The first character in a string is always offset
    position 0 from the beginning of the string.)

    If the substring is not found, F$LOCATE returns the length (the
    offset of the last character in the character string plus one) of
    the searched string.

    Format

      F$LOCATE(substring,string)

1  –  Return Value

    An integer value representing the offset of the substring
    argument. An offset is the position of a character or a substring
    relative to the beginning of the string. The first character in
    a string is always offset position 0 from the beginning of the
    string (which always begins at the leftmost character).
    If the substring is not found, the F$LOCATE function returns
    an offset of the last character in the character string plus 1.
    (This equals the length of the string.)

2  –  Arguments

 substring

    Specifies the character string that you want to locate within the
    string specified in the string argument.

 string

    Specifies the character string to be edited by F$LOCATE.

3  –  Examples

    1.$ FILE_SPEC = "MYFILE.DAT;1"
      $ NAME_LENGTH = F$LOCATE(".",FILE_SPEC)

      The F$LOCATE function in this example returns the position of
      the period (.)  in the string with respect to the beginning of
      the string. The period is in offset position 6, so the value
      6 is assigned to the symbol NAME_LENGTH. Note that NAME_LENGTH
      also equals the length of the file name portion of the file
      specification MYFILE.DAT, that is, 6.

      The substring argument, the period, is specified as a string
      literal and is therefore enclosed in quotation marks (" ").
      The string argument FILE_SPEC is a symbol, so it should not be
      placed within quotation marks. It is automatically replaced by
      its current value during the processing of the function.

    2.$ INQUIRE TIME "Enter time"
      $ IF F$LOCATE(":",TIME) .EQ. F$LENGTH(TIME) THEN -
        GOTO NO_COLON

      This section of a command procedure compares the results of the
      F$LOCATE and F$LENGTH functions to see if they are equal. This
      technique is commonly used to determine whether a character or
      substring is contained in a string.

      In the example, the INQUIRE command prompts for a time value
      and assigns the user-supplied time to the symbol TIME. The IF
      command checks for the presence of a colon (:)  in the string
      entered in response to the prompt. If the value returned by
      the F$LOCATE function equals the value returned by the F$LENGTH
      function, the colon is not present. You use the .EQ. operator
      (rather than .EQS.) because the F$LOCATE and F$LENGTH functions
      return integer values.

      Note that quotation marks are used around the substring
      argument, the colon, because it is a string literal; however,
      the symbol TIME does not require quotation marks because it is
      automatically evaluated as a string expression.