FORMAT Statements

The syntax of the FORMAT specification is as follows:


FORMAT minlen,'name',pcodelabel,aux,EXIT=exit,
   UNITS=units,FLAG=flag,SKIP=skip

FORMAT

Macro name for defining a format. It must be preceded by a space. Typically, it starts in column 10.

minlen

Minimum length, in bytes, of fields which can use this format.

'name'

Name used to identify this field. It must be delimited with apostrophes. Maximum length is 11 bytes.

pcodelabel

Label of a series of PCODE specifications that detail the fields used by this format.

aux

Auxiliary information based on character type.

For character data: The delimiter character used in the format. The specified value can be the character (C‘/') or the wild card indicator (DATEDELIM_WC).

For binary data: The number of decimal digits required to represent the date. Frequently, binary numbers must be converted into numeric characters to be parsed correctly. For example, December 31, 1998 formatted as YYYYMMDD would be 19981231 decimal or 0130E3AF in hex. To parse the value, it must be converted into unpacked decimal. In this case, the aux value should be set to 8. Once the value is converted to character, the standard PCODE mapping definitions for the equivalent character format date can be used.

If the binary number is saved in 2's complement, the number of characters should be increased by 128. For example, FFE1AE47 is the 2's complement of 1987001, a date in YYYYDDD format. In this case, aux should be set to 135 (128 + 7) to properly convert the date.

exit

Optional. The 1-8 character name of the site-written exit routine.

The exit is called for GET, PUT and TERM processing.

For more information about the exit, see Define User Exits for Date Aging. (Two sample exits written in COBOL, FOPHXIT1 and FOPHXIT2, are included in the samples library (SFOPSAMP).)

units

An override to the units value used on the PCODE entries. Use this when it is necessary to override the processing by changing units required for a format. If more than one unit is needed, code them with a plus sign, “+”, between them (for example, YEAR+JDAY).

flag

Optional. Indicates special processing.

NOCLEAR: Specifies whether only part of a field containing a date is aged. The unused portion retains the original value. For example, with this operand you can direct Optim™ to process only the YYMMDDD value of a packed format such as:
YYMMDDHHMMSSF
NOLIST: Do not include this format in the selection list.
GREGORIAN: When aging dates in Julian or Gregorian relative day number format by years or days, the results are determined by adding the aging amount. For example, when you age the Julian date 1999/200 (July 19, 1999) by one year, the result is 2000/200 (July 18, 2000). The day of the month is different because 2000 is a leap year. To maintain the same day of the month, age by 12 months or specify the Gregorian flag on the FORMAT being used. Examples are provided on the GYYDDD and GD1900R1 formats.

skip

Optional. Specifies the SKIP statement(s) that defines values to be skipped for this format. If omitted and the format includes a base day or month number on the corresponding PCODE specifications, no skip processing is performed. If omitted and a base was not provided, the global list of skipped dates is checked.

Specify SKIP=NONE to bypass skipped date checking for this format. For more information and examples, see Customizing Skip Values.

Modifying FORMAT

Edit online

The FORMAT statements are provided in the FOP9SAPF member and grouped by data type.

Within the member, comments indicate logical locations for inserting additional FORMAT statements to handle site-specific requirements. When you define a new format, you must define it for each corresponding data type.

Each FORMAT statement must have a unique name, however more than one can point to a specific PCODE.

Examples

Edit online

The following examples demonstrate the FORMAT statement.

Adding an entry for a 3 byte decimal (COMP-3) field, which represents the number of days since 1900. (January 1 1900 is day 0.)
Find the following comments in the FOP9SAPF member:
```
*-----------------------------------------------------------
*   INSERT SITE SPECIFIC DECIMAL   FORMAT ENTRIES BELOW HERE      
*-----------------------------------------------------------
```
Insert the following entry after these comments:
```
   FORMAT 3,'D1900',D_D1900
```
This will define a format named D1900 that can be used on decimal fields that are at least 3 bytes in length. The D_D1900 label refers to the PCODE entries that will be defined in the next section.
Adding an entry for a 2 byte (16 bit) binary (COMP) field, which represents the year, month, and day in the following format:
```
YEAR    - 7 bits
MONTH     - 4 bits
DAY - 5 bits
```
Find the following comments in the FOP9SAPF member:
```
*-----------------------------------------------------------
*  INSERT SITE SPECIFIC BINARY    FORMAT ENTRIES BELOW HERE 
*-----------------------------------------------------------
```
Insert the following entry after these comments:
```
   FORMAT 2,'BINPACK',B_BINPACK
```
This will define a format named BINPACK that can be used on binary fields that are at least 2 bytes in length. The B_BINPACK label refers to the PCODE entries that will be defined in the next section.
Adding an entry for a 4-byte binary number consisting of the year, month, and day (YYYYMMDD) in 9's complement format. For example, December 31, 1998, would be represented in memory by:
```
  99999999
 -19981231
  80018768   =      4C4FD50   (hex)
```
After the preceding example, insert the following entry:
```
     FORMAT 4,'YYYYMMDD9',B_YYYYMMDD9,8
```
This will define a format to map fullword binary numbers. Because this format must be converted to its decimal equivalent before it can be broken into the individual date components, the number of decimal digits, 8, is specified at the end of the macro.