Date Directive

Syntax

$XFD DATE=date-format-string

  or

*(( XFD DATE=date-format-string ))

This directive implies the NUMERIC directive.

If no date-format-string is specified, then six-digit (or six-character) fields are retrieved as YYMMDD from the database. Eight-digit fields are retrieved as YYYYMMDD.

The date-format-string is a description of the desired date format, composed of characters from the following list:

 M       month (01 - 12)
 Y        year (2 or 4-digit)
 D       day of month (01 - 31)
 J       Julian day (00000000 - 99999999)
 E       day of year (001 - 366)
 H       hour (00 - 23)
 N       minute
 S       second
 T       hundredths of a second

Any other characters cause the date format string to be invalid, and result in a corrupt XFD error or a compile-time warning.

Each character in a date format string can be considered a place holder that represents the type of information stored at that location. The characters also determine how many digits will be used for each type of data.

For example, although you would typically represent the month with two digits, if you specify MMM as part of your date format, the resulting date will use three digits for the month, left-zero-filling the value. If the month is given as M, the resulting date will use a single digit, and will truncate on the left.

Julian dates

Because the definition of Julian day varies, the DATE directive offers a great deal of flexibility for representing Julian dates. Many source books define the Julian day as the day of the year, with January 1st being 001, January 2nd being 002, and so forth. If you want to use this definition for Julian day, simply use EEE (day of year) in your date formats.

Other reference books define the Julian day as the number of days since some specific base date in the past. This definition is represented in the DATE directive with the letter J (for example, a six-digit date field would be preceded with the directive $XFD DATE=JJJJJJ). The default base date for this form of Julian date is 12/31/4714 BC.

You may define your own base date for Julian date calculations by setting the runtime configuration variable 4GL-JULIAN-BASE-DATE .

Handling invalid dates

Acu4GL considers dates in the following range to be valid:

01/01/0001 to 12/31/9999

If Acu4GL considers a date valid and passes it to an RDBMS that considers it invalid, the results depend on the particular RDBMS. Some systems return an error code. Some store the date as NULL and do not return an error. Some store the date in an unpredictable fashion and do not return an error. We recommend that you determine the error handling procedures of the RDBMS in use.

If a COBOL program attempts to write a record containing a date that Acu4GL knows is invalid, Acu4GL inserts NULLs into the date field and writes the record.

If a COBOL program attempts to read into a record from a table with a NULL date field, zeroes are inserted into that field in the COBOL record.

For date fields having two-digit years, by default years 0 through 19 are inserted as 2000 through 2019, and years 20 through 99 are inserted as 1920 through 1999. You can change this behavior by changing the value of the variable 4GL-2000-CUTOFF . Also, see the A4GL-MAX-DATE and A4GL-MIN-DATE variables in the same section for information regarding invalid dates when the date is in a key.

Using group items

You may place the DATE directive in front of a group item, so long as you also use the USE GROUP directive.

Example 1

$xfd date

 03  date-hired  pic 9(8).

 03  pay-scale   pic x(3).

The column date_hired will have eight digits and will be type DATE in the database, with a format of YYYYMMDD.

Example 2

*(( XFD DATE, USE GROUP ))

 03  date-hired.

  05  yyyy      pic 9(4).

  05  mm        pic 9(2).

  05  dd        pic 9(2).

This also will produce a column named date_hired with eight digits and type DATE in the database, format YYYYMMDD.

Example 3

*(( XFD DATE=EEEYYYY))

 03 date-sold   pic 9(7).

 03 sales-rep   pic x(30).

This will produce a column named date_sold with seven digits and type DATE in the database. The date will contain the day of the year (for example, February 1st would be 032), followed by the four-digit year, such as 1999).