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)-'
>--+-------------------------+--+-------------------+----------->
'-MILLISECONDS(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 that is returned by an ASKTIME ABSTIME command.
To obtain an elapsed time in a particular format, the
ABSTIME data value can be the difference between two values that are
returned by ASKTIME, and options such as DAYCOUNT(d) and TIME(t) can
be specified.
When you
use the DATESTRING option to request an architected date and time
stamp string that requires the clock time to be at GMT or Coordinated
Universal Time (UTC), CICS calculates the required timezone offset
from your supplied ABSTIME value, which is in local time, and produces
the date and time stamp string in GMT or UTC. All other values that
are returned by the FORMATTIME command, such as the TIME value, are
returned in local time. It is therefore normal for the FORMATTIME
command to produce an architected date and time stamp string that
shows one date and time, and return other values that show another
date and time, for the same supplied ABSTIME value.
Options
- ABSTIME(data-area)
- Specifies
the data area for the number of milliseconds since 00:00 on 1 January
1900, which is known as absolute time. The time is taken from the
system time-of-day clock, adjusted for leap seconds and to apply the
local timezone offset (including Daylight Saving Time), truncated
to the millisecond, and returned as a packed decimal of length 8 bytes.
You can use FORMATTIME to change the data into other familiar formats.
The
format of the parameter is as follows:
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 that is 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 normally use this option only when a date is needed for output
purposes. Where a date is needed for analysis, request the date in
explicit form; for example, by using the MMDDYY option.
- DATEFORM(data-area)
- Specifies
the format of the installation-defined date. CICS® returns
YYMMDD, DDMMYY, or MMDDYY (6 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 returns the architected date
and time stamp string in the format that is specified by the STRINGFORMAT
option. If STRINGFORMAT is not specified, the default format that
is provided is the RFC 1123 format (RFC1123). If you are using the
DATESTRING option, first run the ASKTIME ABSTIME command 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
that 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 function 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 returns 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 returns 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 returns the date, in the format
that is 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 normally
use this option only when a date is needed for output purposes. Where
a date is needed for analysis, request the date in explicit form,
for example, by using the MMDDYYYY option.
- MILLISECONDS(data-area)
- Returns
the number of milliseconds in the current second specified by ABSTIME,
as a binary integer in the range 0 - 999.
- MMDDYY(data-area)
- Specifies
the 8-character user field in which CICS returns 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 returns 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 that is
returned in DATESTRING. The CVDA values are:
- RFC1123
- Specifies the RFC 1123
format, which is suitable for use in HTTP messages. 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
. This
format does not include milliseconds, and the number of seconds is
truncated.
- RFC3339
- Specifies the RFC 3339
format, also known as the XML dateTime data type. This format is an
implementation of a subset of the ISO 8601 standard. An example of
a date and time stamp in this format is "2003-04-24T10:01:02+00:00".
Date and time stamps in this format are in UTC (Coordinated Universal
Time, which differs only slightly from GMT). This date and time stamp
string contains the date and the 24-hour clock time. The time zone
offset (-12:00 to +12:00) is indicated at the end of the date and
time stamp. The FORMATTIME command always returns the time with a
zero offset from UTC.
The RFC 3339 specification allows the letter
Z to be used for a zero offset (+00:00). A decimal fraction of a second
in the 24-hour clock time is optional in the specification, and the
FORMATTIME command does not include it. An example of a time stamp
that shows the decimal fraction of a second and the letter Z for a
zero offset is 2003-04-01T10:01:02.498Z. To add the
decimal fraction of a second using your application, you can use the
MILLISECONDS option to return the number of milliseconds that have
also elapsed.
- 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. The number of seconds is truncated. Use the MILLISECONDS
option to return the number of milliseconds that have also elapsed.
- 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 6 bytes are returned
in an 8-character field. If you omit 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 returns 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 returns 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 returns 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 returns 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 returns 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 returns 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
- 16 INVREQ
- RESP2
values:
- 1
- The ABSTIME value is less than zero or not in packed-decimal format.
- 2
- Invalid CVDA value for the STRINGFORMAT option.
Default action: terminate the task abnormally.
Examples
The following example
shows the effect of some of the options of the command when
utime contains
the value 002837962864828 in milliseconds.
EXEC CICS ASKTIME ABSTIME(utime)
EXEC CICS FORMATTIME ABSTIME(utime)
DATESEP('-') DDMMYY(date)
TIME(time) TIMESEP(':')
This example gives the values 06-12-89 for date and
19:01:05 for time.