ILE COBOL Programmer's Guide

Processing Indexed Files

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.

Valid RECORD KEYs

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.

Referring to a Partial Key

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 Record Keys

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.

Processing Logical File as Indexed Files

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:

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.

Figure 121. Data Description Specifications for Defining the Access Path (a Composite Key) of 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            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.


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