FORMATTIME

Transform absolute date and time into a specified format.

Read syntax diagramSkip visual syntax diagram
FORMATTIME

>>-FORMATTIME--ABSTIME(data-area)--+-----------------+---------->
                                   '-DATE(data-area)-'   

>--+---------------------+--+---------------------+------------->
   '-FULLDATE(data-area)-'  '-DATEFORM(data-area)-'   

>--+--------------------------+--+---------------------+-------->
   '-DATESEP-+--------------+-'  '-DAYCOUNT(data-area)-'   
             '-(data-value)-'                              

>--+-----------------------+--+----------------------+---------->
   '-DAYOFMONTH(data-area)-'  '-DAYOFWEEK(data-area)-'   

>--+-------------------+--+---------------------+--------------->
   '-DDMMYY(data-area)-'  '-DDMMYYYY(data-area)-'   

>--+-------------------+--+---------------------+--------------->
   '-MMDDYY(data-area)-'  '-MMDDYYYY(data-area)-'   

>--+------------------------+----------------------------------->
   '-MONTHOFYEAR(data-area)-'   

>--+-----------------------------------------------+------------>
   '-TIME(data-area)--+--------------------------+-'   
                      '-TIMESEP-+--------------+-'     
                                '-(data-value)-'       

>--+-----------------+--+------------------+-------------------->
   '-YEAR(data-area)-'  '-YYDDD(data-area)-'   

>--+-------------------+--+-------------------+----------------->
   '-YYDDMM(data-area)-'  '-YYMMDD(data-area)-'   

>--+--------------------+--+---------------------+-------------->
   '-YYYYDDD(data-area)-'  '-YYYYDDMM(data-area)-'   

>--+---------------------+--+-----------------------+----------->
   '-YYYYMMDD(data-area)-'  '-DATESTRING(data-area)-'   

>--+--------------------+--------------------------------------><
   '-STRINGFORMAT(cvda)-'   

Condition: INVREQ

This command is threadsafe.

 

Description

FORMATTIME transforms the absolute date and time into any of a variety of formats. Normally, the ABSTIME argument is the value returned by an ASKTIME ABSTIME command.

If the milliseconds come to 500 or more, the returned seconds and, if necessary, the minutes and hours, are rounded up. The day, month, and year are, however, never rounded up. However, in the case where the ABSTIME argument contains a value representing the half-second before midnight, no rounding is performed, and the TIME parameter returns 23:59:59.

To obtain an elapsed time in a particular format, the ABSTIME data value can be the difference between two values returned by ASKTIME, and options such as DAYCOUNT(d) and TIME(t) can be specified.

Options

ABSTIME(data-area)
specifies the data value for the time, in packed decimal, since 00:00 hours on 1 January 1900 (in milliseconds rounded to the nearest hundredth of a second) that is to be converted to an alternative format.
The format of the parameter is:
COBOL:  PIC S9(15) COMP-3
C:      char data_ref[8];
PL/I:   FIXED DEC(15);
ASM:    PL8
DATE(data-area)
specifies the variable that is to receive the date in the format specified in the DATFORM system initialization parameter. A separator is present if requested by the DATESEP option. If no separator is requested, the returned value is left-justified in the 8-character user field. You should normally use this option only when a date is needed for output purposes. Where a date is needed for analysis, you should request the date in explicit form, for example, using the MMDDYY option.
DATEFORM(data-area)
specifies the format of the installation-defined date. CICS® returns YYMMDD, DDMMYY, or MMDDYY (six characters) according to the DATFORM system initialization parameter.
DATESEP(data-value)
specifies the character to be inserted as the separator between the year and the month, and between the day and the month; or between the year and the day if form YYDDD is specified.

If you omit this option, no separator is supplied. If you omit “data-value”, a slash (/) is assumed as the separator.

Start of changeDATESTRING(data-area)End of change
Start of changespecifies the 64-character user field where CICS is to return the architected date and time stamp string in the format specified by the STRINGFORMAT option. If STRINGFORMAT is not specified, the default format provided is the RFC 1123 format (RFC1123).
Note: Start of changeIf you are using the DATESTRING option, run the ASKTIME ABSTIME command first to obtain a value for the ABSTIME option. If the value for the ABSTIME option is from any other source, the architected date and time stamp string which is returned by the FORMATTIME command might be incorrect.End of change
End of change
DAYCOUNT(data-area)
returns the number of days since 1 January 1900 (day 1), as a fullword binary number. This is useful if you need to compare the current date with a previous date that has, for example, been stored in a data set.
DAYOFMONTH(data-area)
returns the number of the day in the month as a fullword binary number.
DAYOFWEEK(data-area)
returns the relative day number of the week as a fullword binary number: Sunday=0, Saturday=6. This number can be converted to a textual form of day in any language.
DDMMYY(data-area)
specifies the 8-character user field where CICS is to return the date, in day/month/year format (for example, 21/10/98). A separator is present if requested by the DATESEP option. If no separator is requested, the returned value is left-justified in the 8-character user field.
DDMMYYYY(data-area)
specifies the 10-character user field where CICS is to return the date, in day/month/year format (for example 17/06/1995). A separator is present if requested by the DATESEP option. If no separator is requested, the returned value is left-justified in the 10-character user field.
FULLDATE(data-area)
specifies the 10-character user field where CICS is to return the date, in the format specified in the DATFORM system initialization parameter, with the year expanded to 4 digits. A separator is present if requested by the DATESEP option. If no separator is requested, the returned value is left-justified in the 10-character user field. You should normally use this option only when a date is needed for output purposes. Where a date is needed for analysis, you should request the date in explicit form, for example, using the MMDDYYYY option.
MMDDYY(data-area)
specifies the 8-character user field in which CICS is to return the date, in month/day/year format (for example, 10/21/95). A separator is present if requested by the DATESEP option. If no separator is requested, the returned value is left-justified in the 8-character user field.
MMDDYYYY(data-area)
specifies the 10-character user field where CICS is to return the date, in month/day/year format (for example 11/21/1995). A separator is present if requested by the DATESEP option. If no separator is requested, the returned value is left-justified in the 10-character user field.
MONTHOFYEAR(data-area)
“data-area” is set to the relative month number of the year as a fullword binary number (January=1, December=12). You can convert this number, in your application program, to the name of the month in any language.
Start of changeSTRINGFORMAT(cvda)End of change
Start of changespecifies the format for the architected date and time stamp string returned in DATESTRING. The only CVDA value available at present is:
RFC1123
specifies the RFC 1123 format, which is suitable for use on the Internet. This date and time stamp string contains the day, date, and 24-hour clock time at GMT, for example "Tue, 01 Apr 2003 10:01:02 GMT".
End of change
TIME(data-area)
“data-area” is set as an 8-character field to the current 24-hour clock time in the form hh:mm:ss, where the separator is specified by the TIMESEP option.
TIMESEP(data-value)
specifies the character to be used as the separator in the returned time. If you omit this option, no separator is assumed and six bytes are returned in an 8-character field. If you omit the “data-value”, a colon (:) is used as a separator.
YEAR(data-area)
specifies the full 4-figure number of the year as a fullword binary number (for example, 1995, 2001).
YYDDD(data-area)
specifies the 6-character user field where CICS is to return the date, in year/day format (for example, 95/301). A separator is present if requested by the DATESEP option. If no separator is requested, the returned value is left-justified in the 6-character user field.
YYDDMM(data-area)
specifies the 8-character user field where CICS is to return the date, in year/day/month format (for example, 95/30/10). A separator is present if requested by the DATESEP option. If no separator is requested, the returned value is left-justified in the 8-character user field.
YYMMDD(data-area)
specifies the 8-character user field where CICS is to return the date, in year/month/day format (for example, 95/10/21). A separator is present if requested by the DATESEP option. If no separator is requested, the returned value is left-justified in the 8-character user field.
YYYYDDD(data-area)
specifies the 8-character user field where CICS is to return the date, in year/day format (for example 1995/200). A separator is present if requested by the DATESEP option. If no separator is requested, the returned value is left-justified in the 8-character user field.
YYYYDDMM(data-area)
specifies the 10-character user field where CICS is to return the date, in year/day/month format (for example 1995/21/06). A separator is present if requested by the DATESEP option. If no separator is requested, the returned value is left-justified in the 10-character user field.
YYYYMMDD(data-area)
specifies the 10-character user field where CICS is to return the date, in year/month/day format (for example 1995/06/21). A separator is present if requested by the DATESEP option. If no separator is requested, the returned value is left-justified in the 10-character user field.

Conditions

INVREQ
RESP2 values:
1
The ABSTIME value is less than zero or not in packed-decimal format.

Default action: terminate the task abnormally.

Examples

The following example shows the effect of some of the options of the command. Let “utime” contain the value 002837962864828 in milliseconds.
EXEC CICS ASKTIME ABSTIME(utime)
EXEC CICS FORMATTIME ABSTIME(utime)
          DATESEP('-') DDMMYY(date)
          TIME(time) TIMESEP

This gives the values 06-12-89 for “date” and 19:01:05 for “time”.