ILE COBOL Programmer's Guide

Describing Files Using Data Description Specifications (DDS)

You can use Data Description Specifications (DDS) to describe files at the field level to the operating system. In DDS, each record format in an externally described file is identified by a unique record format name.

The record format specifications describe the fields in a record and the location of the fields in a record. The fields are located in the record in the order specified in DDS. The field description generally includes the field name, the field type (character, binary, external decimal, internal decimal, internal floating-point), and the field length (including the number of decimal positions in a numeric field). Instead of being specified in the record format for a physical or logical file, the field attributes can be defined in a field reference file. (See Figure 93.)

The keys for a record format are specified in DDS. When you use a Format 2 COPY statement, a table of comments is generated in the source program listing showing how the keys for the format are defined in DDS.

In addition, DDS keywords can be used to:

For a complete list of the DDS keywords that are valid for a database file, refer to 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.

Figure 93. Example of a Field Reference File


 ....+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
      A**FLDREF    DSTREF     DISTRIBUTION APPLICATION FIELDS REFERENCE
      A          R DSTREF                    TEXT('DISTRIBUTION FIELD REF')
      A* COMMON FIELDS USED AS REFERENCE
   (1)A            BASDAT         6  0       EDTCDE(Y)
      A                                      TEXT('BASE DATE FIELD')
      A* FIELDS USED BY CUSTOMER MASTER FILE
   (2)A            CUST           5          CHECK(MF)
      A                                      COLHDG('CUSTOMER' 'NUMBER')
      A            NAME          20          COLHDG('CUSTOMER NAME')
   (3)A            ADDR      R               REFFLD(NAME)
      A                                      COLHDG('CUSTOMER ADDRESS')
      A            CITY      R               REFFLD(NAME)
      A                                      COLHDG('CUSTOMER CITY')
   (2)A            STATE          2          CHECK(MF)
      A                                      COLHDG('STATE')
      A            SRHCOD         6          CHECK(MF)
      A                                      COLHDG('SEARCH' 'CODE')
      A                                      TEXT('CUSTOMER NUMBER SEARCH CODE')
   (2)A            ZIP            5  0       CHECK(MF)
      A                                      COLHDG('ZIP' 'CODE')
   (4)A            CUSTYP         1  0       RANGE(1 5)
      A                                      COLHDG('CUST' 'TYPE')
      A                                      TEXT('CUSTOMER TYPE 1=GOV 2=SCH 3=B+
      A                                      US 4=PT 5=OTH')
   (5)A            ARBAL          8  2       COLHDG('ACCTS REC' 'BALANCE')
      A                                      EDTCDE(J)
   (6)A            ORDBAL    R               REFFLD(ARBAL)
      A                                      COLHDG('A/R AMT IN' 'ORDER FILE')
      A            LSTAMT    R               REFFLD(ARBAL)
      A                                      COLHDG('LAST' 'AMOUNT' 'PAID')
   (7)A                                      TEXT('LAST AMOUNT PAID IN A/R')
      A            LSTDAT    R               REFFLD(ARBAL)
      A                                      COLHDG('LAST' 'DATE' 'PAID  ')
      A                                      TEXT('LAST DATE PAID IN A/R')
      A            CRDLMT         8  2       COLHDG('CUSTOMER' 'CREDIT' 'LIMIT')
      A                                      EDTCDE(J)
      A            SLSYR         10  2       COLHDG('CUSTOMER' 'SALES' 'THIS YEAR')
      A                                      EDTCDE(J)
      A            SLSLYR        10  2       COLHDG('CUSTOMER' 'SALES' 'LAST YEAR')
      A                                      EDTCDE(J)

This example of a field reference file (Figure 93) shows the definitions of the fields that are used by the CUSMSTL (customer master logical) file, which is shown in Figure 94. The field reference file normally contains the definitions of fields that are used by other files. The following text describes some of the entries for this field reference file.

(1)
The BASDAT field is edited by the Y edit code, as indicated by the keyword EDTCDE (Y). If this field is used in an externally described output file for a ILE COBOL program, the COBOL-generated field is compatible with the data type specified in the DDS. The field is edited when the record is written. When the field is used in a program-described output file, compatibility with the DDS fields in the file is the user's responsibility. When DDS is not used to create the file, appropriate editing of the field in the ILE COBOL program is also the user's responsibility.

(2)
The CHECK(MF) entry specifies that the field is a mandatory fill field when it is entered from a display workstation. Mandatory fill means that all characters for the field must be entered from the display workstation.

(3)
The ADDR and CITY fields share the same attributes that are specified for the NAME field, as indicated by the REFFLD keyword.

(4)
The RANGE keyword, which is specified for the CUSTYP field, ensures that the only valid numbers that can be entered into this field from a display work station are 1 through 5.

(5)
The COLHDG keyword provides a column head for the field if it is used by the Application Development ToolSet tools.

(6)
The ARBAL field is edited by the J edit code, as indicated by the keyword EDTCDE(J).

(7)
A text description (TEXT keyword) is provided for some fields. The TEXT keyword is used for documentation purposes and appears in various listings.

Using Externally Described Files in an ILE COBOL Program

You can incorporate the file description in your program by coding a Format 2 COPY statement. The information from the external description is then retrieved by the ILE COBOL compiler, and an ILE COBOL data structure is generated.

The following pages provide examples of DDS usage and the ILE COBOL code that would result from the use of a Format 2 COPY statement. (See the WebSphere Development Studio: ILE COBOL Reference for a detailed description of the Format 2 COPY statement.)

Figure 94. Example of Data Description Specifications for a Logical File


 ....+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
   (1)A** LOGICAL  CUSMSTL   CUSTOMER MASTER FILE
      A                                   (2)UNIQUE
      A       (3)R CUSREC                    PFILE(CUSMSTP)
      A                                      TEXT('CUSTOMER MASTER RECORD')
      A            CUST
      A            NAME
      A            ADDR
      A            CITY
      A            STATE
      A            ZIP
      A            SRHCOD
      A            CUSTYP
      A            ARBAL
      A            ORDBAL
      A            LSTAMT
      A            LSTDAT
      A            CRDLMT
      A            SLSYR      (5)
      A            SLSLYR
      A       (4)K CUST

(1)
A logical file for processing the customer master physical file (CUSMSTP) is defined and named CUSMSTL.

(2)
The UNIQUE keyword indicates that duplicate key values for this file are not allowed.

(3)
One record format (CUSREC) is defined for the CUSMSTL file, which is to be based upon the physical file CUSMSTP.

(4)
The CUST field is identified as the key field for this file.

(5)
If field attributes (such as length, data type, and decimal positions) are not specified in the DDS for a logical file, the attributes are obtained from the corresponding field in the physical file. Any field attributes specified in the DDS for the logical file override the attributes for the corresponding field in the physical file. The definition of the fields in the physical file could refer to a field reference file. A field reference file is a data description file consisting of field names and their definitions, such as size and type. When a field reference file is used, the same fields that are used in multiple record formats have to be defined only once in the field reference file. For more information on field reference files, see the DB2 Universal Database for AS/400 section of 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.

Figure 93 shows an example of a field reference file that defines the attributes of the fields used in the database file.

Figure 95. Example of the Results of the Format 2 COPY Statement (DDS)


                                     S o u r c e
 
  STMT PL SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME   CHG DATE
 
 
    18     000200 01  CUSTOMER-INVOICE-RECORD.
           000210     COPY DDS-CUSREC OF CUSMSTL.
           +000001*    I-O FORMAT:CUSREC     FROM FILE CUSMSTL    OF LIBRARY TESTLIB            CUSREC
           +000002*                          CUSTOMER MASTER RECORD                            CUSREC
           +000003*          USER SUPPLIED KEY BY RECORD KEY CLAUSE                            CUSREC
    19    +000004       05  CUSREC.                                                            CUSREC
    20    +000005           06 CUST                  PIC X(5).                                 CUSREC
          +000006*                  CUSTOMER NUMBER                                            CUSREC
    21    +000007           06 NAME                  PIC X(25).                                CUSREC
          +000008*                  CUSTOMER NAME                                              CUSREC
    22    +000009           06 ADDR                  PIC X(20).                                CUSREC
          +000010*                  CUSTOMER ADDRESS                                           CUSREC
    23    +000011           06 CITY                  PIC X(20).                                CUSREC
          +000012*                  CUSTOMER CITY                                              CUSREC
    24    +000013           06 STATE                 PIC X(2).                                 CUSREC
          +000014*                  STATE                                                      CUSREC
    25    +000015           06 ZIP                   PIC S9(5)       COMP-3.                   CUSREC
          +000016*                  ZIP CODE                                                   CUSREC
    26    +000017           06 SRHCOD                PIC X(6).                                 CUSREC
          +000018*                  CUSTOMER NUMBER SEARCH CODE                                CUSREC
    27    +000019           06 CUSTYP                PIC S9(1)       COMP-3.                   CUSREC
          +000020*                  CUSTOMER TYPE 1=GOV 2=SCH 3=BUS 4=PVT 5=OT                 CUSREC
    28    +000021           06 ARBAL                 PIC S9(6)V9(2)  COMP-3.                   CUSREC
          +000022*                  ACCOUNTS REC. BALANCE                                      CUSREC
    29    +000023           06 ORDBAL                PIC S9(6)V9(2)  COMP-3.                   CUSREC
          +000024*                  A/R AMT. IN ORDER FILE                                     CUSREC
    30    +000025           06 LSTAMT                PIC S9(6)V9(2)  COMP-3.                   CUSREC
          +000026*                  LAST AMT. PAID IN A/R                                      CUSREC
    31    +000027           06 LSTDAT                PIC S9(6)       COMP-3.                   CUSREC
          +000028*                  LAST DATE PAID IN A/R                                      CUSREC
    32    +000029           06 CRDLMT                PIC S9(6)V9(2)  COMP-3.                   CUSREC
          +000030*                  CUSTOMER CREDIT LIMIT                                      CUSREC
    33    +000031           06 SLSYR                 PIC S9(8)V9(2)  COMP-3.                   CUSREC
          +000032*                  CUSTOMER SALES THIS YEAR                                   CUSREC
    34    +000033           06 SLSLYR                PIC S9(8)V9(2)  COMP-3.                   CUSREC
          +000034*                  CUSTOMER SALES LAST YEAR                                   CUSREC

Figure 96. Example of Data Description Specifications with ALIAS


 ....+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
      A** LOGICAL  CUSMSTL   CUSTOMER MASTER FILE
      A                                      UNIQUE
      A          R CUSREC                    PFILE(CUSMSTP)
      A                                      TEXT('CUSTOMER MASTER RECORD')
      A            CUST                      ALIAS(CUSTOMER_NUMBER)
      A            NAME                   (1)ALIAS(CUSTOMER_NAME)
      A            ADDR                      ALIAS(ADDRESS)
      A            CITY
      A            STATE
      A            ZIP
      A            SRHCOD                    ALIAS(SEARCH_CODE)
      A            CUSTYP                    ALIAS(CUSTOMER_TYPE)
      A            ARBAL                     ALIAS(ACCT_REC_BALANCE)
      A            ORDBAL
      A            LSTAMT
      A            LSTDAT
      A            CRDLMT
      A            SLSYR
      A            SLSLYR
      A          K CUST

(1)
This is the name associated with the ALIAS keyword, which will be included in the program. Available through the DDS ALIAS option, an alias is an alternative name that allows a data name of up to 30 characters to be included in an ILE COBOL program.

Figure 97. Example of the Results of the Format 2 COPY Statement (DD) with the ALIAS Keyword


                                     S o u r c e
 
  STMT PL SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME   CHG DATE
 
 
    18     002000 01  CUSTOMER-INVOICE-RECORD.
           002100     COPY DDS-CUSREC OF CUSMSTL ALIAS.
          +000001*    I-O FORMAT:CUSREC     FROM FILE CUSMSTL    OF LIBRARY TESTLIB            CUSREC
          +000002*                          CUSTOMER MASTER RECORD                             CUSREC
          +000003*          USER SUPPLIED KEY BY RECORD KEY CLAUSE                             CUSREC
    19    +000004       05  CUSREC.                                                            CUSREC
    20    +000005           06 CUSTOMER-NUMBER       PIC X(5).                                 CUSREC
          +000006*                  CUSTOMER NUMBER                                            CUSREC
    21    +000007           06 CUSTOMER-NAME         PIC X(25).                                CUSREC
          +000008*                  CUSTOMER NAME                                              CUSREC
    22    +000009           06 ADDRESS-DDS           PIC X(20).                                CUSREC
          +000010*                  CUSTOMER ADDRESS                                           CUSREC
    23    +000011           06 CITY                  PIC X(20).                                CUSREC
          +000012*                  CUSTOMER CITY                                              CUSREC
    24    +000013           06 STATE                 PIC X(2).                                 CUSREC
          +000014*                  STATE                                                      CUSREC
    25    +000015           06 ZIP                   PIC S9(5)       COMP-3.                   CUSREC
          +000016*                  ZIP CODE                                                   CUSREC
    26    +000017           06 SEARCH-CODE           PIC X(6).                                 CUSREC
          +000018*                  CUSTOMER NUMBER SEARCH CODE                                CUSREC
    27    +000019           06 CUSTOMER-TYPE         PIC S9(1)       COMP-3.                   CUSREC
          +000020*                  CUSTOMER TYPE 1=GOV 2=SCH 3=BUS 4=PVT 5=OT                 CUSREC
    28    +000021           06 ACCT-REC-BALANCE      PIC S9(6)V9(2)  COMP-3.                   CUSREC
          +000022*                  ACCOUNTS REC. BALANCE                                      CUSREC
    29    +000023           06 ORDBAL                PIC S9(6)V9(2)  COMP-3.                   CUSREC
          +000024*                  A/R AMT. IN ORDER FILE                                     CUSREC
    30    +000025           06 LSTAMT                PIC S9(6)V9(2)  COMP-3.                   CUSREC
          +000026*                  LAST AMT. PAID IN A/R                                      CUSREC
    31    +000027           06 LSTDAT                PIC S9(6)       COMP-3.                   CUSREC
          +000028*                  LAST DATE PAID IN A/R                                      CUSREC
    32    +000029           06 CRDLMT                PIC S9(6)V9(2)  COMP-3.                   CUSREC
          +000030*                  CUSTOMER CREDIT LIMIT                                      CUSREC
    33    +000031           06 SLSYR                 PIC S9(8)V9(2)  COMP-3.                   CUSREC
          +000032*                  CUSTOMER SALES THIS YEAR                                   CUSREC
    34    +000033           06 SLSLYR                PIC S9(8)V9(2)  COMP-3.                   CUSREC
          +000034*                  CUSTOMER SALES LAST YEAR                                   CUSREC

In addition to placing the external description of the file in the program through the use of the Format 2 COPY statement, you can also use standard record definition and redefinition to describe external files or to provide a group definition for a series of fields. It is the programmer's responsibility to ensure that program-described definitions are compatible with the external definitions of the file.

Figure 98 shows how ILE COBOL programs can relate to files on the iSeries server, making use of external file descriptions from DDS.

Figure 98. Example Showing How ILE COBOL Can Relate to iSeries Files

illustration of the four cases described below

(1)
The ILE COBOL program uses the field level description of a file that is defined to the operating system. You code a Format 2 COPY statement for the record description. At compilation time, the compiler copies in the external field-level description and translates it into a syntactically correct ILE COBOL record description. The file must exist at compilation time.

(2)
An externally described file is used as a program-described file in the ILE COBOL program. The entire record description for the file is coded in the ILE COBOL program. This file does not have to exist at compilation time.

(3)
A file is described to the operating system as far as the record level only. The entire record description must be coded in the ILE COBOL program. This file does not have to exist at compilation time.

(4)
A file name can be specified at compilation time, and a different file name can be specified at run time. An ILE COBOL Format 2 COPY statement generates the record description for the file at compilation time. At run time, a different library list or a file override command can be used so that a different file is accessed by the program. The file description copied in at compilation time is used to describe the input records used at run time.
Note:
For externally described files, the two file formats must be the same. Otherwise, a level check error will occur.

Specifying Nonkeyed and Keyed Record Retrieval

The description of an externally described file contains the access path that describes how records are to be retrieved from the file. Records can be retrieved based on an arrival sequence (nonkeyed) access path or on a keyed sequence access path. For a complete description of the access paths for an externally described database file, see the DB2 Universal Database for AS/400 section of 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.

The arrival sequence access path is based on the order in which the records are stored in the file. Records are added only to the end of the file.

For the keyed sequence access path, the sequence in which records are retrieved from the file is based on the contents of the key fields defined in the DDS for the file. For example, in the DDS shown in Figure 94, CUST is defined as the key field. The keyed sequence access path is updated whenever records are added, deleted, or when the contents of a key field change. For a keyed sequence access path, one or more fields can be defined in the DDS to be used as the key fields for a record format. Not all record formats in a file have to have the same key fields. For example, an order header record can have the ORDER field defined as the key field, and the order detail records can have the ORDER and LINE fields defined as the key fields.

If you do not specify a format on the I/O operation then the key for a file is determined by the valid keys for the record formats in that file. The file's key is determined in the following manner:

In ILE COBOL, you must specify a RECORD KEY for an indexed file to identify the record you want to process. ILE COBOL compares the key value with the key of the file or record, and processes the specified operation on the record whose key matches the RECORD KEY value.

When RECORD KEY IS EXTERNALLY-DESCRIBED-KEY is specified:

Note:
For a file containing multiple key fields to be processed in ILE COBOL, the key fields must be contiguous in the record format used by the ILE COBOL program, except when RECORD KEY IS EXTERNALLY-DESCRIBED-KEY is specified.

Level Checking the Externally Described Files

When an ILE COBOL program uses an externally described file, the operating system provides a level check function (LVLCHK). This function ensures that the formats of the file have not changed since compilation time.

The compiler always provides the information required by level checking when an externally described file is used (that is, when a record description was defined for the file by using the Format 2 COPY statement). Only those formats that were copied by the Format 2 COPY statement under the FD for a file are level checked. The level check function will be initiated at run time based on the selection made on the create, change, or override file commands. The default on the create file command is to request level checking. If level checking was requested, level checking occurs on a record format basis when the file is opened. If a level check error occurs, ILE COBOL sets a file status of 39.

When LVLCHK(*NO) is specified on the CRTxxxF, CHGxxxF, or OVRxxxF CL commands, and the file is re-created using an existing format, existing ILE COBOL programs that use that format may not work without recompilation, depending on the changes to the format.

You should use extreme caution when using files in ILE COBOL programs without level checking. You risk program failure and data corruption if you use ILE COBOL programs without level checking or recompiling.

Note:
The ILE COBOL compiler does not provide level checking for program-described files.

For more information on level checking, refer to the DB2 Universal Database for AS/400 section of the Database and File Systems category in the iSeries 400 Information Center at this Web site - http://www.ibm.com/eserver/iseries/infocenter.


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