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

    Extracts the specified characters from the specified string.

    Format

      F$EXTRACT(start,length,string)

1 - Return Value

    A character string containing the characters delimited by the
    start and length arguments.

2 - Arguments

 start

    Specifies the offset of the starting character of the string
    you want to extract. Specify the start argument as an integer
    expression that is greater than or equal to zero.

    The offset is the relative position of a character or a substring
    with respect to the beginning of the string. Offset positions
    begin with zero. The string always begins with the leftmost
    character.

    If you specify an offset that is greater than or equal to the
    length of the string, F$EXTRACT returns a null string ("").

 length

    Specifies the number of characters you want to extract; must be
    less than or equal to the size of the string. Specify the length
    as an integer expression that is greater than or equal to zero.

    If you specify a length that exceeds the number of characters
    from the offset to the end of the string, the F$EXTRACT function
    returns the characters from the offset through the end of the
    string.

 string

    Specifies the character string to be edited. Specify the string
    as a character string expression.

3 - Examples

    1.$ NAME = "PAOLO TESTA"
      $ FIRST = F$EXTRACT(0,5,NAME)
      $ SHOW SYMBOL FIRST
        FIRST = "PAOLO"

      This portion of a command procedure uses the F$EXTRACT function
      to extract the first 5 characters from the character string
      assigned to the symbol NAME. The offset and length arguments
      are integers, and the string argument is a symbol. You do not
      need to use quotation marks (" ")  around integers or symbols
      when they are used as arguments for lexical functions.

    2.$ P1 = "MYFILE.DAT"
      $ FILENAME = F$EXTRACT(0,F$LOCATE(".",P1),P1)

      This portion of a command procedure shows how to locate a
      character within a string, and how to extract a substring
      ending at that location.

      The lexical function F$LOCATE gives the numeric value
      representing the offset position of a period in the character
      string value of P1. (The offset position of the period is equal
      to the length of the substring before the period.)

      This F$LOCATE function is used as an argument in the F$EXTRACT
      function to specify the number of characters to extract from
      the string. If a procedure is invoked with the parameter
      MYFILE.DAT, these statements result in the symbol FILENAME
      being given the value MYFILE.

      Note that the F$LOCATE function in the above example assumes
      that the file specification does not contain a node name or
      a directory specification containing a subdirectory name. To
      obtain the file name from a full file specification, use the
      F$PARSE function.

    3.$ IF F$EXTRACT(12,2,F$TIME()) .GES. "12" THEN GOTO AFTERNOON
      $ MORNING:
      $ WRITE SYS$OUTPUT "Good morning!"
      $ EXIT
      $ AFTERNOON:
      $ WRITE SYS$OUTPUT "Good afternoon!"
      $ EXIT

      This example shows a procedure that displays a different
      message, depending on whether the current time is morning or
      afternoon. It first obtains the current time of day by using
      the F$TIME function. The F$TIME function returns a character
      string, which is the string argument for the F$EXTRACT
      function. The F$TIME function is automatically evaluated when
      it is used as an argument, so you do not need to use quotation
      marks.

      Next, the F$EXTRACT function extracts the hours from the date
      and time string returned by F$TIME. The string returned by
      F$TIME always contains the hours field beginning at an offset
      of 12 characters from the start of the string.

      The F$EXTRACT function extracts 2 characters from the string,
      beginning at this offset, and compares the string value
      extracted with the string value 12. If the comparison is true,
      then the procedure writes "Good afternoon!". Otherwise, it
      writes "Good morning!".

      Note that you can also use the F$CVTIME function to extract
      the hour field from a time specification. This method is easier
      than the one shown in the above example.