FORMATTIME

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.

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.

When you use the DATESTRING option to request an architected date and time stamp string that requires the clock time to be at 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 UTC. All other values 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 showing one date and time, and return other values showing 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:

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 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, 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 returns 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). 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 specified in the DATFORM system initialization parameter, with the year expanded to four 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, 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 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, for example Tue, 01 Apr 2003 10:01:02 +0000. 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). 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 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 timestamp showing the decimal fraction of a second and the letter Z for a zero offset is 2003-04-01T10:01:02.498Z. If you want 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.

STRINGZONE(cvda)

Specifies the timezone in which the time stamp returned in DATESTRING is to be returned. The CVDA values are:

UTC

DATESTRING is to be returned in UTC. This is the default setting.

LOCAL

DATESTRING is to be returned in LOCAL timezone.

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.