ILE COBOL Programmer's Guide


Working with Date-Time Data Types

Items of COBOL class date-time, include date, time, and timestamp items. These items are declared with the FORMAT clause of a data description entry. For example:

01  group-item.
    05 date1 FORMAT DATE "%m/%d/@Y".
    05 date2 FORMAT DATE.
    05 time1 FORMAT TIME SIZE 8 LOCALE german-locale.
    05 time2 FORMAT TIME "%H:%M:%S".
    05 time3 FORMAT TIME.
    05 timestamp1 FORMAT TIMESTAMP. 

For items of class date-time the FORMAT clause is used in place of a PICTURE clause. In the example above, after the keyword FORMAT one of the words DATE, TIME, or TIMESTAMP appears. These words identify the category of the date-time item.

Note:
The words DATE and TIME are reserved words; whereas, the word TIMESTAMP is a context-sensitive word.

After the reserved word or context-sensitive word that dictates the category of the date-time item a format literal may appear. A format literal is a non-numeric literal that describes the format of a date or time item.

In the case of data item date1 the %m stands for months, %d for days, and the @Y for year (including a 2-digit century). The % and @ character begin a specifier. The three specifiers used in the format literal of date1 are part of a set of specifiers documented in WebSphere Development Studio: ILE COBOL Reference. A format literal is a combination of specifiers and separators. So again looking at date1 there are two separators, both of which are the character /.

In the above example each specifier has a pre-determined size. For example data item time2 has three specifiers: %H, %M, and %S, which stand for hours (2 digits), minutes (2 digits), and seconds (2 digits); as well as two specifiers both of which are the character :. Thus the total size of time2 is 8 characters.

Separators and specifiers may come in any order in a format literal; and must obey the following rules:

In the above example neither date2 nor timestamp1 have format literals specified. Items of category timestamp can not have user defined format literals; however, they do have a default format literal of @Y-%m-%d-%H.%M.%S.@Sm. For an item of category date or time, if a format literal is not explicitly specified in the data description entry one can be specified in the SPECIAL-NAMES paragraph. An example is shown below:

      SPECIAL-NAMES.  FORMAT OF DATE IS "@C:%y:%j",
                      FORMAT OF TIME IS "%H:%M:%S:@Sm". 

If the above SPECIAL-NAMES paragraph had been specified in the same program as group item group-item, the date format of date2 would have been @C:%y:%j. On the other hand, if a SPECIAL-NAMES paragraph did not exist, the format of the date item would default to ISO. An ISO date has the format @Y-%m-%d. The only item of category time without a format literal (implicitly or explicitly defined) is time3, so if the above SPECIAL-NAMES paragraph did exist, time3 would have the time format %H:%M:%S:@Sm. On the other hand, if no FORMAT OF TIME clause appeared in the SPECIAL-NAMES paragraph, the format would default to ISO. An ISO time has the format %H.%M.%S.

By default when COPY DDS declares items of class date-time it generates a PICTURE clause for an alphanumeric item. In order to change the PICTURE clause into a FORMAT clause, several new CVTOPT parameter values have been defined, these are:

When *DATE has been specified, any DDS date data types are converted to COBOL date items, for example, a FORMAT clause is generated instead of a PICTURE clause.

In DDS to specify the format of a date field, the DATFMT keyword can be specified. The DATFMT keyword can also be specified on zoned, packed, and character fields. For these types of fields, COPY DDS would normally generate a PICTURE clause for a numeric zoned, numeric packed, and alphanumeric data item, respectively. You can force COPY DDS to generate a FORMAT clause for these items by specifying the *CVTTODATE value of the CVTOPT parameter.

For a list of the DATFMT parameters allowed for zoned, packed, and character DDS fields, and their equivalent ILE COBOL format that is generated from COPY DDS when the CVTOPT(*CVTTODATE) conversion parameter is specified, refer to Class Date-Time.

As mentioned above, the FORMAT clause of a data description entry defines an item of class date-time. This data description entry can also contain one or more of the following clauses:

This same data description entry can have one or more 88 (condition-names) associated with it. The VALUE clause of the condition-name can contain a THRU phrase. The following clauses can refer to a class date-time data description entry:

The following code fragment shows various definitions of class date-time items:

 01  TimestampT IS TYPEDEF
          FORMAT TIMESTAMP VALUE "1997-12-01-05.52.50.000000".
 01  group-item.
     05  date1 FORMAT DATE OCCURS 3 TIMES VALUE "1997-05-08".
     05  date2 FORMAT DATE "@Y-%m-%d" VALUE "2001-09-08".
     05  date3 REDEFINES date2 FORMAT DATE.
        88  date3-key-dates VALUE "1997-05-01" THRU "2002-05-01".
     05  time1 FORMAT TIME "%H:%M" VALUE "14:10".
     05  time2 LIKE time1.
     05  timestamp1 TYPE TimestampT. 

Each of the above clauses has various rules when used with an item of class date-time.

The SYNCHRONIZED clause can be specified for a date-time item; however, it is just treated as documentation (it does not align the item).

The USAGE clause for a date-time item can be DISPLAY or PACKED-DECIMAL for a date or time item; however, timestamps can only be USAGE DISPLAY. If a date-time item has a USAGE of PACKED-DECIMAL, then the format literal must contain specifiers only (no separators) and the specifiers must result in numeric digits.

The VALUE clause for a date-time item should be a non-numeric literal in the format of the date-time item. No checks are made at compile time to verify that the format of the VALUE clause non-numeric literal matches the FORMAT clause. It is up to the programmer to make sure the VALUE clause non-numeric literal is correct.

The level 88 (condition-names) associated with a date-time item can have a THRU phrase. The VALUE clause of a level-88 item associated with a date-time item should contain a non-numeric literal whose format matches the parent item. Level-88 items used in relational conditions result in a date-time comparison.

A LIKE clause that refers to a date-time item cannot modify its size. The LIKE clause causes the new item to inherit all the attributes of the FORMAT clause, including the SIZE and LOCALE clauses.

Date-time data items can be used with the following statements, clauses, and intrinsic functions:

Date-time data types can also be used in SORT (and MERGE) operations, however, some restrictions apply. For more information about these restrictions, refer to Date-Time Data Type Considerations.


[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]