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

    Converts an absolute or a combination time string to a string of
    the form yyyy-mm-dd hh:mm:ss.cc. The F$CVTIME function can also
    return information about an absolute, combination, or delta time
    string.

    Format

      F$CVTIME([input_time] [,output_time_format] [,output_field])

1 - Return Value

    A character string containing the requested information.

2 - Arguments

 input_time

    Specifies a string containing absolute, a delta, or a combination
    time, or TODAY, TOMORROW, or YESTERDAY. Specify the input time
    string as a character string expression. If the input_time
    argument is omitted or is specified as a null string (""), the
    current system date and time, in absolute format, is used. If
    parts of the date field are omitted, the missing values default
    to the current date. If parts of the time field are omitted, the
    missing values default to zero.

    For more information on specifying time values, refer to the
    OpenVMS User's Manual or the online help topic DCL_Tips (subtopic
    Date_Time).

    If the input_time argument is a delta time, you must specify the
    output_time_format argument as DELTA.

 output_time_format

    Specifies the time format for the information you want returned.
    Specify the output_time_format argument as one of the following
    character string expressions:

    ABSOLUTE    The requested information should be returned
                in absolute time format, which is dd-mmm-yyyy
                hh:mm:ss.cc. Single-digit days are returned with
                no leading space or zero.

    COMPARISON  The requested information should be returned in the
    (default)   form yyyy-mm-dd hh:mm:ss.cc (used for comparing two
                times).

    DELTA       The requested information should be returned in delta
                format, which is dddd-hh:mm:ss.cc. If you specify
                DELTA as the output_time_format argument, then you
                must also provide a delta time specification for the
                input_time argument.

 output_field

    Specifies a character string expression containing one of the
    following (do not abbreviate): DATE, MONTH, DATETIME (default),
    SECOND, DAY, TIME, HOUR, WEEKDAY, HUNDREDTH, YEAR, MINUTE. The
    information is returned in the time format specified by the
    output_time_format argument. If the input_time argument is a
    delta time and the output_time_format argument is DELTA, you
    cannot specify MONTH, WEEKDAY, or YEAR.

    When the weekday is returned, the first letter is in uppercase,
    and the following letters are in lowercase.

3 - Examples

    1.$ TIME = F$TIME()
      $ SHOW SYMBOL TIME
        TIME = "14-DEC-2001 10:56:23.10"
      $ TIME = F$CVTIME(TIME)
      $ SHOW SYMBOL TIME
        TIME = "2001-12-14 10:56:23.10"

      This example uses the F$TIME function to return the system
      time as a character string and to assign the time to the symbol
      TIME. Then the F$CVTIME function is used to convert the system
      time to an alternate time format. Note that you do not need to
      place quotation marks (" ")  around the argument TIME because
      it is a symbol. Symbols are automatically evaluated when they
      are used as arguments for lexical functions.

      You can use the resultant string to compare two dates (using
      .LTS. and .GTS. operators). For example, you can use F$CVTIME
      to convert two time strings and store the results in the
      symbols TIME_1 and TIME_2. You can compare the two values,
      and branch to a label, based on the following results:

          $ IF TIME_1 .LTS. TIME_2 THEN GOTO FIRST

    2.$ NEXT = F$CVTIME("TOMORROW",,"WEEKDAY")
      $ SHOW SYMBOL NEXT
       NEXT = "Tuesday"

      In this example, the F$CVTIME returns the weekday that
      corresponds to the absolute time keyword "TOMORROW". You must
      enclose the arguments "TOMORROW" and "WEEKDAY" in quotation
      marks because they are character string expressions. Also,
      you must include a comma as a placeholder for the output_time_
      format argument that is omitted.