FORMATTIME

Selects the format of date and time.

Syntax

FORMATTIME

Condition: ERROR

Description

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

The following example shows the effect of some of the options of the FORMATTIME command:

EXEC CICS ASKTIME
          ABSTIME(utime)
EXEC CICS FORMATTIME
          ABSTIME(utime)
          DATESEP('-')
          DDMMYY(date)
          TIME(time)
          TIMESEP

If utime has the value 002837962864828 in milliseconds on completion of the ASKTIME ABSTIME command, this gives the values 06-12-89 for date and 19:01:05 for time.

To obtain an elapsed time in a particular format, the ABSTIME argument can be the difference between two values that are returned by ASKTIME, and options such as DAYCOUNT and TIME can be specified.

Options

ABSTIME(data-area)

Specifies the time, in milliseconds since 0000 hours (local time) on 1 January 1900, that is to be converted to an alternative format.

The format of the argument is:

COBOL

PIC S9(15) COMP-3

C or C++

char data_area[8];

PL/I

FIXED DEC(15);

If the ABSTIME argument is in an incorrect form, the ERROR condition occurs.

DATE(data-area)

Specifies an eight-character field that is to receive the date in the format that is indicated by the DateForm attribute in the Region Definitions (RD). The separator (if any) that is used in the returned value is determined by the DATESEP option. You should normally use this option only if the 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.

FULLDATE(date-area)

Specifies the variable that is to receive the date in the format that is specified in the DATEFORM system initialization parameter, with the year expanded to four digits. The return value is in the 10-character format.

Separator characters are defined by the DATESEP option, as at present for DATE.

DATEFORM(data-area)

Specifies a six-character field that is to receive the format of the installation-defined date. CICS® returns YYMMDD, DDMMYY, or MMDDYY according to the DateForm attribute in the RD.

DATESEP(data-value)

Specifies the character that is to be used as the separator between the year and the month, between the day and the month, and between the year and the day (according to the date format).

If you omit this option, no separator is supplied.

If you omit data-value, a slash (/) is assumed as the separator.

DAYCOUNT(data-area)

Specifies a 32-bit binary field that is to receive the number of days since 1 January 1900 (day 0). This option is useful if you need to compare the current date with a previous date that has, for example, been stored in a file.

DAYOFMONTH(data-area)

Specifies a 32-bit binary field that is to receive the number of the day in the month.

DAYOFWEEK(data-area)

Specifies a 32-bit binary field that is to receive the relative day number of the week: Sunday=0, Saturday=6. You can convert this number, in your application program, to a textual form of day in any language.

DDMMYY(data-area)

Specifies an eight-character field that is to receive the date in DDMMYY format; for example, 21/10/90.

DDMMYYYY(data-area)

Specifies a ten-character field that is to receive the date in DDMMYYYY format; for example, 21/10/1996.

MMDDYY(data-area)

Specifies an eight-character field that is to receive the date in MMDDYY format; for example, 10/21/90.

MMDDYYYY(data-area)

Specifies a ten-character field that is to receive the date in MMDDYYYY format; for example, 10/21/1996.

MONTHOFYEAR(data-area)

Specifies a 32-bit binary field that is to receive the relative month number of the year: January=1, December=12. You can convert this number, in your application program, to the name of the month in any language.

TIME(data-area)

Specifies an eight-character field that is to receive the current 24-hour clock time in the form hh:mm:ss, where the separator (shown here as :) is determined by the TIMESEP option.

TIMESEP(data-value)

Specifies the character that is 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 the eight-character TIME field. If you omit data-value, a colon (:) is used as the separator.

YEAR(data-area)

Specifies a 32-bit binary field that is to receive the full four-digit number of the year; for example, 1990.

YYDDD(data-area)

Specifies a six-character field that is to receive the date in YYDDD format; for example, 90/301.

YYDDMM(data-area)

Specifies an eight-character field hat is to receive the date in YYDDMM format; for example, 90/21/10.

YYMMDD(data-area)

Specifies an eight-character field that is to receive the date in YYMMDD format; for example, 96/10/21.

YYYYDDD(data-area)

Specifies an eight-character field that is to receive the date in YYYYDDD format; for example, 1996/200.

YYYYDDMM(data-area)

Specifies a tent-character field that is to receive the date in YYYYDDMM format; for example, 1996/21/10.

YYYYMMDD(data-area)

Specifies a ten-character field that is to receive the date in YYYYMMDD format; for example, 1996/10/21.

Conditions

ERROR: Occurs if the ABSTIME argument is specified in an incorrect form.
Default action: Terminates the task abnormally.