HP OpenVMS Systems Documentation

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])

Return Value

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, see the OpenVMS User's Manual or the online help topic Date.

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 (default)	The requested information should be returned in the 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, DAYOFYEAR, HOUROFYEAR, MINUTEOFYEAR, SECONDOFYEAR.

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, YEAR, DAYOFYEAR, HOUROFYEAR, MINUTEOFYEAR, or SECONDOFYEAR.

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

Description

When using the F$CVTIME function, you can omit optional arguments that can be used to the right of the last argument you specify; however, you must include commas (,) as placeholders if you omit optional arguments to the left of the last argument you specify.

When specifying the input time argument in either absolute or combination time format, you can specify ABSOLUTE or COMPARISON as the output_time_format argument; you cannot specify DELTA.

When specifying the input_time argument in delta time format, you must specify DELTA as the output_time_format argument.

Examples

$ TIME = F$TIME()
$ SHOW SYMBOL TIME
  TIME = "14-DEC-2002 10:56:23.10"
$ TIME = F$CVTIME(TIME)
$ SHOW SYMBOL TIME 
  TIME = "2002-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

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

In this example, 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.

$ SHOW TIME
  27-MAR-2002 09:50:31
$ WRITE SYS$OUTPUT F$CVTIME(,,"DAYOFYEAR")
86
$ WRITE SYS$OUTPUT F$CVTIME(,,"HOUROFYEAR")
2049
$ WRITE SYS$OUTPUT F$CVTIME(,,"MINUTEOFYEAR")
122991
$ WRITE SYS$OUTPUT F$CVTIME(,,"SECONDOFYEAR")
7379476
      

In this example, F$CVTIME returns the values for the following keywords: DAYOFYEAR, HOUROFYEAR, MINUTEOFYEAR, and SECONDOFYEAR.