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
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.
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 |
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 |
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
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:
Then the file's key is field A, the key field common to all record formats.
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:
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.
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.
(C) Copyright IBM Corporation 1992, 2005. All Rights Reserved.