Transform absolute date and time into a specified format.

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.
DATESTRING(data-area)
specifies
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: 
If 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.


- 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.
STRINGFORMAT(cvda)
specifies
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".

- 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”.