The COBOL-85 Tutorial, Chapter 9

Index-sequential files in COBOL.

Copyright © 1998-2017

Kim Kjærsulf.

This chapter (TOC)

Index sequential file.
Declaring an index sequential file.
Commands.

OPEN.
CLOSE.
READ.
READ ... KEY.
READ ... NEXT.
READ ... PREVIOUS.
START.
WRITE.
REWRITE.
DELETE.
DELETE FILE.
UNLOCK.
COMMIT.

Error routines.
Locking files in connection with multi-user software.

Exclusive.
Shareable.
Single record lock.
Multi-record lock.

An example of how to handle index-sequential files.
Exercises

IndexSequential file.

[This chapter] [TOC] [Tutorial]

An index-sequential file in COBOL can briefly be described as a file with at least one key concept.
A key can be used to establish unique information and to retrieve the data in an ordered way.

The indexes that makes this possible is maintained by the runtime system, so the programmer only have to declare the file and supply the data.

Declaring an index sequential file.

[This chapter] [TOC] [Tutorial]

Before a file can be used in a COBOL program its organization has to be defined, partly in an ENVIRONMENT DIVISION, where the physical file name and organization is stated, and partly in a DATA DIVISION, which is used to describe the record layout.

Below is an example of a description of an index-sequential file, used both for input and output data in random order. See the manual for further details.

                ENVIRONMENT DIVISION.
       input-output section.
       file-control.
(a)        select isamfile assign "INOUTFILE"      
(b)            organization is indexed
(b1)           access is random
(b2)           record key is acctno 
(c)            status is file-error.
 
                DATA DIVISION.
(d)    fd  isamfile.
(e)    01  in-record.
           03  acctno      pic 99.
           03  amount      pic 99999v99.

      *  ------  variable declarations.
       working-storage section.
(f)    01  file-error         pic XX.

Comments on the example:

Line Explanation
a

There must be a SELECT for every file. The name immediately after the SELECT is the name that is to be used internally by the program; on the other hand, the name after ASSIGN is the physical file name. It is of course possible to operate with a variable in the working storage section.

b

Index-sequential files are organized using the word "indexed".

b1

The access for an index-sequential file can vary, depending on the purpose of the program:

Random All access occurs via the given key value.

Sequential Records must be read sequentially, the order in accordance with given key.

Dynamic If you wish to "mix" the first two access forms.

b2

The compiler uses this information to decide the position of the key in the record. It is possible to specify a higher level when operating with a split key. A second method of specifying a compound key to be used when the fields are not in the correct order is as follows:
			record key is split-key = field1, field2, ...
Where necessary, specify alternative keys with:
		alternate key is [split-key = ]field1[, field2,..]
If a key is not unique, specify it:
		with duplicates
after the relevant key.

c

The variable file-error will contain a status code after each file operation. See the manual for details of actual codes.

d

There must be an FD for every file. The name after FD is the same as that written after the SELECT in line a.

e

A number of different record descriptions can be added after the FD.

f

The variable to the status code must be declared in the working-storage section, as stated in the manual.

Commands.

[This chapter] [TOC] [Tutorial]

This review of the commands available does not take into consideration problems related to a multi-user environment. See following chapter for a description of these.

OPEN.

[This chapter] [TOC] [Tutorial]

OPEN [WITH LOCK] {INPUT | OUTPUT| I-O} file-name

File is opened.

	OPEN  OUTPUT  file-name ....

You can only write records to the file. The file will be created. If the file all ready exists it will be deleted and a new file created.

	OPEN INPUT file-name ....

You can only read data from the file. Depending on the word "OPTIONAL" in the file's SELECT statement, a missing file will give an IO error on being opened or merely give an "AT END" the first time it is read.

	OPEN I-O file-name ....

You can retrieve, insert and update data in the file. Usually you can not open a file in this mode unless it previously have been created by an open output.

CLOSE.

[This chapter] [TOC] [Tutorial]

CLOSE file-name.

File is closed and all locks released.

READ.

[This chapter] [TOC] [Tutorial]

READ file-name.

The record that meets the key conditions is searched for and read.
The key is the same as was used in the last READ ... KEY or is the primary key if no READ ... KEY has been carried out.

READ ... KEY.

[This chapter] [TOC] [Tutorial]

READ file-name KEY key-name

The record that meets the key conditions is searched for and read.

READ ... NEXT.

[This chapter] [TOC] [Tutorial]

READ file-name NEXT.

Reads the record after that searched for. The current key concept decides which record will be the next.

ACCESS MODE must be sequential or dynamic.

READ ... PREVIOUS.

[This chapter] [TOC] [Tutorial]

READ file-name PREVIOUS

As READ ... NEXT, but now the previous record.

START.

[This chapter] [TOC] [Tutorial]

START file-name ....

This instruction is used to position the file prior to the execution of a subsequent sequential read command. See the manual for variations of this command.

ACCESS MODE must be dynamic.

WRITE.

[This chapter] [TOC] [Tutorial]

WRITE record.

Add a new record to the file. Updates index for all keys.

REWRITE.

[This chapter] [TOC] [Tutorial]

REWRITE record.

Update a current record, usually the last. Updates index for all keys.

DELETE.

[This chapter] [TOC] [Tutorial]

DELETE file-name.

Deletes a current record, usually the last. Updates index for all keys.

DELETE FILE.

[This chapter] [TOC] [Tutorial]

DELETE FILE file-name.

Deletes entire file. The file must be closed.

UNLOCK.

[This chapter] [TOC] [Tutorial]

UNLOCK file-name.

Releases all locks in the file.

COMMIT.

[This chapter] [TOC] [Tutorial]

COMMIT.

Releases all locks in all files in this program.

Error routines.

[This chapter] [TOC] [Tutorial]

Errors occurring in file operations can be detected with procedures written in the "DECLARATIVES" section at the beginning of the procedure division.

It is possible to operate with a general procedure, a joint procedure for all input and output files, or one procedure per file. The example below deals with all errors relating to a file called "in-file":

      *  ------  Trap for IO-errors
       declaratives.
       in-errors section.
(a)        use after error procedure on isamfile.
       in-error.
           display "Error when accessing directory : " 
                                     line 24 position 1.
           display file-error line 24.
(b)        stop run.   <- remove this line and the error will be ignored.
       in-error-out.
           exit.

Comments on the example:

Line Explanation
a

use describes in which connection the error procedure is to be used.

b

In this case the program is interrupted by any type of error - including locked record. Alternatively, the program could be allowed to continue immediately after the statement that triggered the error. In the program itself it is therefore important to make sure you "tidy up" after an error - either via declaratives or via the various I/O statements.

Locking files in connection with multi-user software.

[This chapter] [TOC] [Tutorial]

There are two levels of locked files:

Exclusive

The locking program has exclusive rights to the file while ever the lock is in place. This lock can therefore only be used if other programs have not opened the file.

This allows several programs to share the contents on the file at the same time, but to also operate with mutual protection against overwriting records.

Exclusive.

[This chapter] [TOC] [Tutorial]

Exclusive locks can be set up in one of two ways:

Directly specify in a file's SELECT statement that it is to be locked.

By using OPEN OUTPUT.

Shareable.

[This chapter] [TOC] [Tutorial]

For sequential files

The last read record can be locked. Exclusive is the usual choice when writing in sequential files.

For ISAM and relative files

See the table below.
The difference between an ISAM and a relative file is that the record in an ISAM file contains a key, while the key to a relative file is the record's relative number.
Single record lock allows the program to operate with a lock on only one record at a time.
With Multi-record lock it is possible to lock several records in one file at the same time.

Single record lock.
Manual locking		Automatic locking
A record is locked when it is read with	and remains locked until one of the following instructions is used	Automatic locking is specified in the file's SELECT statement. Each READ will lock the read record, which is then released as described for manual locking.
READ WITH LOCK	UNLOCK file-name COMMIT CLOSE file-name READ file-name WRITE record
Multi-record lock
Manual multi-locking		Automatic locking
A record is locked when read with	and remains locked until one of the following instructions are used	Automatic locking is specified in the file's SELECT statement. Each READ will lock the read record, which is then released as described for manual locking.
READ WITH KEPT LOCK	UNLOCK file-name COMMIT CLOSE file-name

The lock is not affected by START.

An example of how to handle index-sequential files.

[This chapter] [TOC] [Tutorial]

This program is an example of a program that reads an index-sequential file. It creates accounts with the relevant balances and subsequently changes the balances as required.

       identification division.
      *  ------  program identication.
       program-id.    isamfile.
       author.        kik.

       environment division.
      *  ------  program environment.
       configuration section.
       special-names.
            console is crt
            decimal-point is comma.
       input-output section.
       file-control.
           select isamfile assign "INOUTFILE"
               organization is indexed
               access is random
               record key is acctno
               status is file-error.
       data division.
      *  ------  description of files.
       fd  isamfile.
       01  in-record.
           03  acctno      pic 99.
           03  amount      pic 99999v99.

      *  ------  variable declarations
       working-storage section.
       01  file-error         pic XX.
       procedure division.
      *  ------  Trap for IO-errors
       declaratives.
       in-errors section.
           use after error procedure on isamfile.
       in-error.
           display "Error when accessing diectory: " 
                                  line 24 position 1. 
           display file-error line 24.
           stop run.
       in-error-out.
           exit.
      *
       end declaratives.
      *
      *  ------  executable instructions.
       main section.
           perform open-files.
           perform show-screen.
           perform read-acct.
           perform process 
                   until acctno in in-record = zero.
           perform close-files.
           stop run.
      *
       show-screen.
          display space.
          display "Index-sequential files" line 1 position 25.            display "Account number ..:" line 4 position 10.
           display "Balance .........:" line 6 position 10.
      *
       open-files.
           open i-o isamfile.
      *
       process.
           read isamfile
                invalid key
                   move zero to amount in in-record
                not invalid key
                   display amount in in-record
                                line 6 position 26
                end-read.
           perform read-amount.
           rewrite in-record
                invalid key
                   write in-record.
           perform read-account.
      *
       read-account.
           accept acctno in in-record line 4 position 26.            *
       read-amount.
           accept amount in in-record line 6 position 26.             *
       close-files.
           close isamfile.

Exercise 1.

[This chapter] [TOC] [Tutorial]

The purpose of this exercise is to train the following points:

COBOL's facilities for handling sequential files.
COBOL's facilities for handling index-sequential files.

Design a program with which you can:

Transfer the sequential file to a corresponding index-sequential file.

File description:

Physical file-name : "INDXDATA"

Record layout:

The same as for "SEQUDATA" above.
Customer number, 4 characters, value set: 0-9999.
Transaction code, 2 characters, value set: 1, 2, 3, 4, 99.
Movement, 6 characters + 2 decimals (no decimal point).
Balance, 6 characters + 2 decimals (no decimal point).

The file should be sorted according to customer and transaction code.

Model answer for this exercise.

Exercise 2.

[This chapter] [TOC] [Tutorial]

The purpose of this exercise is to train the following points:

COBOL's facilities for handling index-sequential files in a sequential mode.

The program in exercise 1 produced an index sequential file, but do you know if it is the right file?

Prepare a small testprogram, that will display the records in the ISAM-file upon the screen.

Model answer for this exercise.

Copyright © 1998-2017

Kim Kj�rsulf

Last Updated october 3, 2003
For more information contact: Kim Kj�rsulf