ILE COBOL Programmer's Guide

Date, Time, and Timestamp Fields

In ILE COBOL programs, you can use DDS date, time, and timestamp fields in two ways:

Class Date-Time

A DDS date, time, and timestamp field can be declared as a FILLER item in ILE COBOL or with its DDS name depending on the *DATETIME option of the CVTOPT parameter of CRTCBLMOD or CRTBNDCBL. If *NODATETIME is specified DDS date, time, and timestamp fields are declared as FILLER items in ILE COBOL. When *DATETIME is specified DDS date, time, and timestamp items are declared with their DDS names in ILE COBOL.

By default, DDS date, time, and timestamp fields create COBOL alphanumeric data items. That is, COPY DDS generates a PIC X(n) for each DDS date, time, or timestamp field. In order to generate a FORMAT clause, and thus create COBOL class date-time items, you must specify the CVTOPT values:

The equivalent PROCESS statement options for the above CVTOPT parameter values are DATE, TIME, and TIMESTAMP, respectively.

See Working with Date-Time Data Types for more information of working with items of class date-time.

DDS zoned, packed, and character fields can have a DATFMT keyword. Normally, such fields will generate a PICTURE clause when a COPY DDS occurs. The resulting COBOL item will be a numeric zoned, a numeric packed, or an alphanumeric data type. However, you can use COPY DDS to generate a FORMAT clause for these items (in which case a COBOL date data item of class date-time is created). If you specify the *CVTTODATE value of the CVTOPT parameter, the DDS zoned, packed, and character fields with the DATFMT keyword will result in a date data item. The *NOCVTTODATE value of the CVTOPT parameter generates a numeric zoned, numeric packed, or alphanumeric field, respectively. These two values also exist on the PROCESS statement as CVTTODATE and NOCVTTODATE options.

Table 20 and Table 21 list 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.

Table 20 is for character and zoned fields; USAGE DISPLAY is assumed.

Table 20. DATFMT Parameters Allowed for Character and Zoned Fields

OS/400 Format COBOL-Generated Format Description Format Length
*MDY %m%d%y MonthDayYear mmddyy 6
*DMY %d%m%y DayMonthYear ddmmyy 6
*YMD %y%m%d YearMonthDay yymmdd 6
*JUL %y%j Julian yyddd 5
*ISO @Y%m%d International Standards Organization yyyymmdd 8
*USA %m%d@Y IBM USA Standard mmddyyyy 8
*EUR %d%m@Y IBM European Standard ddmmyyyy 8
*JIS @Y%m%d Japanese Industrial Standard Christian Era yyyymmdd 8
*CMDY @C%m%d%y CenturyMonthDayYear cmmddyy 7
*CDMY @C%d%m%y CenturyDayMonthYear cddmmyy 7
*CYMD @C%y%m%d CenturyYearMonthDay cyymmdd 7
*MDYY %m%d@Y MonthDayYear mmddyyyy 8
*DMYY %d%m@Y DayMonthYear ddmmyyyy 8
*YYMD @Y%m%d YearMonthDay yyyymmdd 8
*YM %y%m YearMonth yymm 4
*MY %m%y MonthYear mmyy 4
*YYM @Y%m YearMonth yyyymm 6
*MYY %m@Y MonthYear mmyyyy 6
*LONGJUL @Y%j Julian yyyyddd 7

Table 21 is for packed fields; USAGE PACKED-DECIMAL is generated.

Table 21. DATFMT Parameters Allowed for Packed Fields

OS/400 Format COBOL-Generated Format Description Format Length
*MDY %m%d%y MonthDayYear mmddyy 4
*DMY %d%m%y DayMonthYear ddmmyy 4
*YMD %y%m%d YearMonthDay yymmdd 4
*JUL %y%j Julian yyddd 3
*ISO @Y%m%d International Standards Organization yyyymmdd 5
*USA %m%d@Y IBM USA Standard mmddyyyy 5
*EUR %d%m@Y IBM European Standard ddmmyyyy 5
*JIS @Y%m%d Japanese Industrial Standard Christian Era yyyymmdd 5
*CMDY @C%m%d%y CenturyMonthDayYear cmmddyy 4
*CDMY @C%d%m%y CenturyDayMonthYear cddmmyy 4
*CYMD @C%y%m%d CenturyYearMonthDay cyymmdd 4
*MDYY %m%d@Y MonthDayYear mmddyyyy 5
*DMYY %d%m@Y DayMonthYear ddmmyyyy 5
*YYMD @Y%m%d YearMonthDay yyyymmdd 5
*YM %y%m YearMonth yymm 3
*MY %m%y MonthYear mmyy 3
*YYM @Y%m YearMonth yyyymm 4
*MYY %m@Y MonthYear mmyyyy 4
*LONGJUL @Y%j Julian yyyyddd 4

Class Alphanumeric

This section describes how to use date, time, and timestamp data items as alphanumeric fields in ILE COBOL programs. Contrast this with using date, time, or timestamp data items of class date-time as described in Class Date-Time.

By default, DDS date, time or timestamp fields are brought into an ILE COBOL program as fixed-length character fields. Your ILE COBOL program can perform any valid character operations on the fixed-length fields. These operations will follow the standard COBOL rules for alphanumeric data items. The *NODATE, *NOTIME, and *NOTIMESTAMP CVTOPT parameter values of the CRTCBLMOD and CRTBNDCBL commands will cause COPY DDS to generate alphanumeric COBOL data items. These CVTOPT parameter values also exist on the PROCESS statement as: NODATE, NOTIME, and NOTIMESTAMP respectively.

Date, time, and timestamp fields are brought into your program only if you specify the *DATETIME option of the CVTOPT parameter of CRTCBLMOD or CRTBNDCBL command, or the DATETIME option of the PROCESS statement. For a description and the syntax of the CVTOPT parameter, see CVTOPT Parameter. If *DATETIME is not specified, date, time, and timestamp fields are ignored and are declared as FILLER fields in your ILE COBOL program.

The date, time, and timestamp data types each have their own format.

If a field containing date, time, or timestamp information is updated by your program, and the updated information is to be passed back to your database, the format of the field must be exactly the same as it was when the field was retrieved from the database. If you do not use the same format, an error will occur. For information on valid formats for each data type, see the Database and File Systems category in the iSeries 400 Information Center at this Web site -http://publib.boulder.ibm.com/pubs/html/as400/infocenter.htm.

To obtain information on how to enter source statements using the CL commands, refer to the CL and APIs section of the Programming category in the iSeries 400 Information Center at this Web site -http://publib.boulder.ibm.com/pubs/html/as400/infocenter.htm.

If you try to WRITE a record before moving an appropriate value to a date, time, or timestamp field, the WRITE operation will fail, and file status 90 will be returned. An error will also occur for a READ or START operation that tries to use a key field that is a date, time, or timestamp field, and that does not have an appropriate value.

If you declare date, time or timestamp items in your program as FILLER, do not attempt to WRITE records containing these fields, since you will not be able to set them to values that will be accepted by the system.

DDS date, time, and timestamp fields which are generated as alphanumeric data types in ILE COBOL can be specified as a SORT/MERGE key; however, they will be compared as alphanumeric data items, not as date, time, and timestamp data items.

Examples of How the *DATETIME Compiler Option Works with *DATE

Figure 106 defines the DDS date item DATEITEM. This section only describes how DDS date items are affected.

Figure 106. DDS File Defining Date and Time Fields


 ....+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
       A          R DATETIME
       A*
       A            VARITEM      100          VARLEN
       A*
       A            TIMEITEM        T         TIMFMT(*HMS)
       A            DATEITEM        L         DATFMT(*YMD)
       A            TIMESTAMP       Z

The following examples show you how the combinations in which the *DATETIME option of the CVTOPT parameter can be specified with the *DATE option of the CVTOPT parameter, and how these combinations affect the way in which DATEITEM is brought into the program.

Example 1

If *NODATETIME is specified with *NODATE, DATEITEM is brought into the program as follows:

05 FILLER    PIC X(8).

Example 2

If *DATETIME is specified with *NODATE, DATEITEM is brought into the program as follows:

05 DATEITEM    PIC X(8).

Example 3

If *DATETIME is specified with *DATE, DATEITEM is brought into the program as follows:

05 DATEITEM    FORMAT DATE '%y/%m/%d'.

Example 4

If *NODATETIME is specified with *DATE, DATEITEM is brought into the program as follows:

05 FILLER    FORMAT DATE '%y/%m/%d'.


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