An indexed file is a file whose default access path is built on key values. One way to create a keyed access path for an indexed file is by using DDS.
An indexed file is identified by the ORGANIZATION IS INDEXED clause of the SELECT statement.
The key fields identify the records in an indexed file. The user specifies the key field in the RECORD KEY clause of the SELECT statement. The RECORD KEY data item must be defined within a record description for the indexed file. If there are multiple record descriptions for the file, only one need contain the RECORD KEY data name. However, the same positions within the record description that contains the RECORD KEY data item are accessed in the other record descriptions as the KEY value for any references to the other record descriptions for that file.
Alternate keys can also be specified with the ALTERNATE RECORD KEY clause. Using alternate keys, you can access the indexed file to read records in a sequence other than the prime key sequence.
An indexed file can be accessed sequentially, randomly by key, or dynamically.
To write Standard COBOL programs that access an indexed file, you must create
the file with certain characteristics. Table 26 lists these characteristics and what controls them.
Table 26. Characteristics of Indexed Files that are Accessible to Standard COBOL Programs
Characteristic | Control |
---|---|
The file must be a physical file. | Create the file using the CRTPF CL command. |
The file cannot be a shared file. | Specify SHARE(*NO) on the CRTPF CL command. |
A key must be defined for the file. | Define at least one key field in the Data Description Specifications (DDS) of the file, using a line with K in position 17. |
Keys must be contiguous within the record. | Specify a single key field in the file DDS, or specify key fields that immediately follow each other in descending order of key significance. |
Key fields must be alphanumeric. They cannot be numeric. | Specify A or H in position 35 when defining any field that is to be used as a DDS key field. |
The value of the key used for sequencing must include all 8 bits of every byte. | Specify alphanumeric key fields. |
The file cannot have records with duplicate key values. | Specify the UNIQUE keyword in the file DDS. |
Keys must be in ascending sequence. | Do not specify the DESCEND keyword in the file DDS. |
A starting position for retrieving records cannot be specified. | Do not issue the OVRDBF CL command with the POSITION parameter. |
Select/omit level keywords cannot be used for the file. | Do not include any line with S or O in position 17 in the file DDS. Do not specify the COMP, RANGE, VALUES, or ALL keywords. |
Records in the file cannot contain NULL fields. | Do not specify the ALWNULL keyword in the file DDS. |
The OPEN, READ, WRITE, START, REWRITE, DELETE, and CLOSE statements are used to access data that is stored in an indexed file. Refer to the WebSphere Development Studio: ILE COBOL Reference for a description of each of these statements. When accessing indexed files, the FORMAT phrase is optional for DATABASE files, and not allowed for DISK files. If the FORMAT phrase is not specified, the default format name of the file is used. The default format name of the file is the first format name defined in the file. The special register, DB-FORMAT-NAME, can be used to retrieve the format name used on the last successful I/O operation.
When you read records sequentially from an indexed file, the records will be returned in arrival sequence or in keyed sequence depending on how the file is described in your ILE COBOL program. To retrieve the records in arrival sequence, use
ORGANIZATION IS SEQUENTIAL ACCESS IS SEQUENTIAL
with the SELECT statement for the indexed file. To retrieve the records in keyed sequence (typically in ascending order), use
ORGANIZATION IS INDEXED ACCESS IS SEQUENTIAL
with the SELECT statement for the indexed file.
For indexed files that are accessed sequentially, the SELECT clause KEY phrase is ignored except for the START statement. If the KEY phrase is not specified on the START statement, the RECORD KEY phrase in the SELECT clause is used and KEY IS EQUAL is assumed.
For indexed files that are accessed randomly or dynamically, the SELECT clause KEY phrase is used except for the START statement. If the KEY phrase is not specified on the START statement, the RECORD KEY phrase in the SELECT clause is used and KEY IS EQUAL is assumed.
NEXT, PRIOR, FIRST, or LAST can be specified for the READ statement for DATABASE files with DYNAMIC access. NEXT can also be specified for the READ statement for DATABASE files with SEQUENTIAL access. If NEXT, PRIOR, FIRST, or LAST is specified, the SELECT clause KEY phrase is ignored.
All physical database files with INDEXED organization that are opened for OUTPUT are cleared.
The DDS for the file specifies the fields to be used as the key field. If the file has multiple key fields, the key fields must be contiguous in each record unless RECORD KEY IS EXTERNALLY-DESCRIBED-KEY is specified.
When the DDS specifies only one key field for the file, the RECORD KEY must be a single field of the same length as the key field defined in the DDS.
If a Format 2 COPY statement is specified for the file, the RECORD KEY clause must specify one of the following:
When the DDS specifies multiple contiguous key fields, the RECORD KEY data name must be a single field with its length equal to the sum of the lengths of the multiple key fields in the DDS. If a Format 2 COPY statement is specified for the file, there must also be a program-described record description for the file that defines the RECORD KEY data name with the proper length and at the proper position in the record.
Contiguous items are consecutive elementary or group items in the Data Division that are contained in a single data hierarchy.
A START statement allows the use of a partial key. The KEY IS phrase is required.
Refer to the "START Statement" in the WebSphere Development Studio: ILE COBOL Reference for information about the rules for specifying a search argument that refers to a partial key.
Figure 117 shows an example of START statements using a program-described file.
Figure 117. START Statements Using a Program-Described File
5722WDS V5R3M0 030905 LN IBM ILE COBOL CBLGUIDE/STRTPGMD ISERIES1 03/09/15 14:41:49 Page 2 S o u r c e STMT PL SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE 1 000100 IDENTIFICATION DIVISION. 2 000200 PROGRAM-ID. STRTPGMD. 000300 3 000400 ENVIRONMENT DIVISION. 4 000500 CONFIGURATION SECTION. 5 000600 SOURCE-COMPUTER. IBM-ISERIES. 6 000700 OBJECT-COMPUTER. IBM-ISERIES. 7 000800 INPUT-OUTPUT SECTION. 8 000900 FILE-CONTROL. 9 001000 SELECT FILE-1 ASSIGN TO DISK-NAMES 00/08/15 11 001100 ACCESS IS DYNAMIC RECORD KEY IS FULL-NAME IN FILE-1 13 001200 ORGANIZATION IS INDEXED. 001300 14 001400 DATA DIVISION. 15 001500 FILE SECTION. 16 001600 FD FILE-1. 17 001700 01 RECORD-DESCRIPTION. 18 001800 03 FULL-NAME. 19 001900 05 LAST-AND-FIRST-NAMES. 20 002000 07 LAST-NAME PIC X(20). 21 002100 07 FIRST-NAME PIC X(20). 22 002200 05 MIDDLE-NAME PIC X(20). 23 002300 03 LAST-FIRST-MIDDLE-INITIAL-NAME REDEFINES FULL-NAME 002400 PIC X(41). 24 002500 03 REST-OF-RECORD PIC X(50). 002600 25 002700 PROCEDURE DIVISION. 002800 MAIN-PROGRAM SECTION. 002900 MAINLINE. 26 003000 OPEN INPUT FILE-1. 003100* 003200* POSITION THE FILE STARTING WITH RECORDS THAT HAVE A LAST NAME OF 003300* "SMITH" 27 003400 MOVE "SMITH" TO LAST-NAME. 28 003500 START FILE-1 KEY IS EQUAL TO LAST-NAME 29 003600 INVALID KEY DISPLAY "NO DATA IN SYSTEM FOR " LAST-NAME 30 003700 GO TO ERROR-ROUTINE 003800 END-START. 003900* . 004000* . 004100* . 004200* 004300* POSITION THE FILE STARTING WITH RECORDS THAT HAVE A LAST NAME OF 004400* "SMITH" AND A FIRST NAME OF "ROBERT" 31 004500 MOVE "SMITH" TO LAST-NAME. 32 004600 MOVE "ROBERT" TO FIRST-NAME. 33 004700 START FILE-1 KEY IS EQUAL TO LAST-AND-FIRST-NAMES 34 004800 INVALID KEY DISPLAY "NO DATA IN SYSTEM FOR " 004900 LAST-AND-FIRST-NAMES 35 005000 GO TO ERROR-ROUTINE 005100 END-START. 005200* . 005300* . 5722WDS V5R3M0 030905 LN IBM ILE COBOL CBLGUIDE/STRTPGMD ISERIES1 03/09/15 14:41:49 Page 3 STMT PL SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE 005400* . 005500* 005600* POSITION THE FILE STARTING WITH RECORDS THAT HAVE A LAST NAME OF 005700* "SMITH", A FIRST NAME OF "ROBERT", AND A MIDDLE INITIAL OF "M" 005800 36 005900 MOVE "SMITH" TO LAST-NAME. 37 006000 MOVE "ROBERT" TO FIRST-NAME. 38 006100 MOVE "M" TO MIDDLE-NAME. 39 006200 START FILE-1 KEY IS EQUAL TO LAST-FIRST-MIDDLE-INITIAL-NAME 40 006300 INVALID KEY DISPLAY "NO DATA IN SYSTEM FOR " 006400 LAST-FIRST-MIDDLE-INITIAL-NAME 41 006500 GO TO ERROR-ROUTINE 006600 END-START. 006700 006800 006900 ERROR-ROUTINE. 42 007000 STOP RUN. * * * * * E N D O F S O U R C E * * * * * |
Figure 118 and Figure 119 show an example of START statements using an externally described file.
Figure 118. START Statements Using an Externally Described File -- DDS
....+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A UNIQUE A R RDE TEXT('RECORD DESCRIPTION') A FNAME 20 TEXT('FIRST NAME') A MINAME 1 TEXT('MIDDLE INITIAL NAME') A MNAME 19 TEXT('REST OF MIDDLE NAME') A LNAME 20 TEXT('LAST NAME') A PHONE 10 0 TEXT('PHONE NUMBER') A DATA 40 TEXT('REST OF DATA') A K LNAME A K FNAME A K MINAME A K MNAME |
Figure 119. START Statements Using an Externally Described File
5722WDS V5R3M0 030905 LN IBM ILE COBOL CBLGUIDE/STRTEXTD ISERIES1 03/09/15 14:43:17 Page 2 S o u r c e STMT PL SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE 1 000100 IDENTIFICATION DIVISION. 2 000200 PROGRAM-ID. STRTEXTD. 000300 3 000400 ENVIRONMENT DIVISION. 4 000500 CONFIGURATION SECTION. 5 000600 SOURCE-COMPUTER. IBM-ISERIES 6 000700 OBJECT-COMPUTER. IBM-ISERIES 7 000800 INPUT-OUTPUT SECTION. 8 000900 FILE-CONTROL. 9 001000 SELECT FILE-1 ASSIGN TO DATABASE-NAMES 11 001100 ACCESS IS DYNAMIC RECORD KEY IS EXTERNALLY-DESCRIBED-KEY 13 001200 ORGANIZATION IS INDEXED. 001300 14 001400 DATA DIVISION. 15 001500 FILE SECTION. 16 001600 FD FILE-1. 17 001700 01 RECORD-DESCRIPTION. 001800 COPY DDS-RDE OF NAMES. +000001* I-O FORMAT:RDE FROM FILE NAMES OF LIBRARY CBLGUIDE RDE +000002* RECORD DESCRIPTION RDE +000003*THE KEY DEFINITIONS FOR RECORD FORMAT RDE RDE +000004* NUMBER NAME RETRIEVAL ALTSEQ RDE +000005* 0001 LNAME ASCENDING NO RDE +000006* 0002 FNAME ASCENDING NO RDE +000007* 0003 MINAME ASCENDING NO RDE +000008* 0004 MNAME ASCENDING NO RDE 18 +000009 05 RDE. RDE 19 +000010 06 FNAME PIC X(20). RDE +000011* FIRST NAME RDE 20 +000012 06 MINAME PIC X(1). RDE +000013* MIDDLE INITIAL NAME RDE 21 +000014 06 MNAME PIC X(19). RDE +000015* REST OF MIDDLE NAME RDE 22 +000016 06 LNAME PIC X(20). RDE +000017* LAST NAME RDE 23 +000018 06 PHONE PIC S9(10) COMP-3. RDE +000019* PHONE NUMBER RDE 24 +000020 06 DATA-DDS PIC X(40). RDE +000021* REST OF DATA RDE 25 001900 66 MIDDLE-NAME RENAMES MINAME THRU MNAME. 002000 26 002100 PROCEDURE DIVISION. 002200 MAIN-PROGRAM SECTION. 002300 MAINLINE. 27 002400 OPEN INPUT FILE-1. 002500* 002600* POSITION THE FILE STARTING WITH RECORDS THAT HAVE A LAST NAME 002700* OF "SMITH" 28 002800 MOVE "SMITH" TO LNAME. 29 002900 START FILE-1 KEY IS EQUAL TO LNAME 30 003000 INVALID KEY DISPLAY "NO DATA IN SYSTEM FOR " LNAME 31 003100 GO TO ERROR-ROUTINE 003200 END-START. 5722WDS V5R3M0 030905 LN IBM ILE COBOL CBLGUIDE/STRTEXTD ISERIES1 03/09/15 14:43:17 Page 3 STMT PL SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE 003300* . 003400* . 003500* . 003600* 003700* POSITION THE FILE STARTING WITH RECORDS THAT HAVE A LAST NAME 003800* OF "SMITH" AND A FIRST NAME OF "ROBERT" 32 003900 MOVE "SMITH" TO LNAME. 33 004000 MOVE "ROBERT" TO FNAME. 34 004100 START FILE-1 KEY IS EQUAL TO LNAME, FNAME 35 004200 INVALID KEY DISPLAY "NO DATA IN SYSTEM FOR " 004300 LNAME " " FNAME 36 004400 GO TO ERROR-ROUTINE 004500 END-START. 004600* . 004700* . 004800* . 004900* 005000* POSITION THE FILE STARTING WITH RECORDS THAT HAVE A LAST NAME OF 005100* "SMITH", A FIRST NAME OF "ROBERT", AND A MIDDLE INITIAL OF "M" 37 005200 MOVE "SMITH" TO LNAME. 38 005300 MOVE "ROBERT" TO FNAME. 39 005400 MOVE "M" TO MINAME. 40 005500 START FILE-1 KEY IS EQUAL TO LNAME, FNAME, MINAME 41 005600 INVALID KEY DISPLAY "NO DATA IN SYSTEM FOR " 005700 LNAME SPACE FNAME SPACE MINAME 42 005800 GO TO ERROR-ROUTINE 005900 END-START. 006000 006100 006200 ERROR-ROUTINE. 43 006300 STOP RUN. * * * * * E N D O F S O U R C E * * * * * |
Alternate keys are associated with alternate indexes, which can be temporary or permanent.
A temporary alternate index is one that ILE COBOL creates when the file is opened. When the file is closed, the temporary index no longer exists. By default, ILE COBOL will not create temporary indexes. You must specify the CRTARKIDX option to use temporary alternate indexes.
However, if ILE COBOL is able to find a permanent index, it still uses the permanent index instead of creating a temporary one. A permanent alternate index is one that persists even when the ILE COBOL program ends. Permanent indexes are associated with logical files, so you must create logical files before you can use permanent indexes in your COBOL program.
The DDS specification for the logical file should be the same as the specification for the physical file except for the key field(s). The key field(s) for the logical files should be defined to match the corresponding alternate key data-item. Note that the ILE COBOL program does not refer to these logical files in any way.
The use of permanent indexes will have a performance improvement over temporary ones. The length and starting position of the alternate key data-item within the record area must match the length and starting position of the corresponding DDS field. This DDS field also cannot be a keyed field since DDS key fields are associated with the prime key. If the alternate key data-item maps to multiple DDS fields, the starting position of the alternate key data-item must match the first DDS field, and the length of the alternate key data-item must be equal to the sum of the lengths of all the DDS fields that make up this key.
The EXTERNALLY-DESCRIBED-KEY clause cannot be specified for files that also have alternate keys.
The key used for any specific input-output request is known as the key of reference. The key of reference can be changed with the READ or START statements.
When a logical file with multiple record formats, each having associated key fields, is processed as an indexed file in ILE COBOL, the following restrictions and considerations apply:
In both cases, the value of the RECORD KEY data item is ignored.
Figure 120 and Figure 121 show examples of how to use DDS to describe the access path for indexed files.
Figure 120. Using Data Description Specifications to Define the Access Path for an Indexed File
....+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A R FORMATA PFILE(ORDDTLP) A TEXT('ACCESS PATH FOR INDEXED FILE') A FLDA 14 A ORDERN 5S 0 A FLDB 101 A K ORDERN |
Data description specifications can be used to create the access path for a program-described indexed file.
In the DDS, shown in Figure 120, for the record format FORMATA for the logical file ORDDTLL, the field ORDERN, which is five digits long, is defined as the key field. The definition of ORDERN as the key field establishes the keyed access path for this file. Two other fields, FLDA and FLDB, describe the remaining positions in this record as character fields.
The program-described input file ORDDTLL is described in the FILE-CONTROL section in the SELECT clause as an indexed file.
The ILE COBOL descriptions of each field in the FD entry must agree with the corresponding description in the DDS file. The RECORD KEY data item must be defined as a five-digit numeric integer beginning in position 15 of the record.
....+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 A R FORMATA PFILE(ORDDTLP) A TEXT('ACCESS PATH FOR INDEXED FILE') A FLDA 14 A ORDERN 5S 0 A ITEM 5 A FLDB 96 A K ORDERN A K ITEM |
In this example, the DDS, shown in Figure 121, defines two key fields for the record format FORMAT in the logical file ORDDTLL. For the two fields to be used as a composite key for a program-described indexed file, the key fields must be contiguous in the record.
The ILE COBOL description of each field must agree with the corresponding description in the DDS file. A 10-character item beginning in position 15 of the record must be defined in the RECORD KEY clause of the file-control entry. The ILE COBOL descriptions of the DDS fields ORDERN and ITEM would be subordinate to the 10-character item defined in the RECORD KEY clause.
For more information on the use of format selector programs and on logical file processing, 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://publib.boulder.ibm.com/pubs/html/as400/infocenter.htm.
(C) Copyright IBM Corporation 1992, 2005. All Rights Reserved.