ILE COBOL Programmer's Guide

Processing a Transaction File

The following is a list of all of the Procedure Division statements that have extensions specifically for processing TRANSACTION files in an ILE COBOL program. See the WebSphere Development Studio: ILE COBOL Reference for a detailed discussion of each of these statements.

Opening a Transaction File

To process a TRANSACTION file in the Procedure Division, you must first open the file. You use the Format 3 OPEN statement to open a TRANSACTION file. A TRANSACTION file must be opened in I-O mode.

OPEN I-O file-name.

Acquiring Program Devices

You must acquire a program device for the TRANSACTION file. Once acquired, the program device is available for input and output operations. You can acquire a program device implicitly or explicitly.

You implicitly acquire one program device when you open the TRANSACTION file. If the file is an ICF file, the single implicitly acquired program device is determined by the ACQPGMDEV parameter of the CRTICFF command. If the file is a display file, the single implicitly acquired program device is determined by the first entry in the DEV parameter of the CRTDSPF command. Additional program devices must be explicitly acquired.

You explicitly acquire a program device by using the ACQUIRE statement. For an ICF file, the device must have been defined to the file with the ADDICFDEVE or OVRICFDEVE CL command before the file was opened. For display files, there is no such requirement. That is, the device named in the ACQUIRE statement does not have to be specified in the DEV parameter of the CRTDSPF command, CHGDSPF command, or the OVRDSPF command. However, when you create the display file, you must specify the number of devices that may be acquired (the default is one). For a display file, the program device name must match the display device.

ACQUIRE program-device-name FOR transaction-file-name.

Writing to a Transaction File

Once you have opened the TRANSACTION file and acquired a program device for it, you are now ready to perform input and output operations on it.

The first input/output operation you typically perform on a TRANSACTION file is to write a record to the display. This record is used to prompt the user to enter a response or some data.

You use the Format 4 WRITE statement to write a logical record to the TRANSACTION file. You simply code the WRITE statement as follows:

WRITE record-name FORMAT IS format-name.

In some situations, you may have multiple data records, each with a different format, that you want active for a TRANSACTION file. In this case, you must use the FORMAT phrase of the Format 4 WRITE statement to specify the format of the output data record you want to write to the TRANSACTION file.

If you have explicitly acquired multiple program devices for the TRANSACTION file, you must use the TERMINAL phrase of the Format 4 WRITE statement to specify the program device to which you want the output record to be sent.

You can control the line number on the display where the WRITE statement will write the output record by specifying the STARTING phrase and ROLLING phrase of the Format 4 WRITE statement. The STARTING phrase specifies the starting line number for the record formats that use the variable record start line keyword. The ROLLING phrase allows you to move lines displayed on the workstation screen. All or some of the lines on the screen can be rolled up or down.

WRITE record-name FORMAT IS format-name
                  TERMINAL IS program-device-name
                  STARTING AT LINE start-line-no
                  AFTER ROLLING LINES first-line-no THRU last-line-no
                                DOWN no-of-lines LINES
END-WRITE.

Reading from a Transaction File

You use the Format 4 READ statement to read a logical record from the TRANSACTION file. If data is available when the READ statement is executed, it is returned in the record area. The names of the record format and the program device are returned in the I-O-FEEDBACK area and in the CONTROL-AREA area.

Before you use the READ statement, you must have acquired at least one program device for the TRANSACTION file. If a READ statement is performed and there are no acquired program devices, a logic error is reported by setting the file status to 92.

You can use the READ statement in its simplest form as follows:

READ record-name RECORD.

If you have only acquired one program device, this simple form of the READ statement will always wait for data to be made available. Even if the job receives a controlled cancellation, or a wait time is specified in the WAITRCD parameter for the display file or ICF file, the program will never regain control from the READ statement.

If you have acquired multiple program devices, this simple form of the READ statement will receive data from the first invited program device that has data available. When multiple program devices have been acquired, this simple form of the READ statement can complete without returning any data if there are no invited devices and a wait time is not specified, a controlled cancellation of the job occurs, or the specified wait time expires.

For a detailed explanation of how the READ operation is performed, refer to the section on the READ statement in the WebSphere Development Studio: ILE COBOL Reference.

In those cases where you have acquired multiple program devices, you can explicitly specify the program device from which you read data by identifying it in the TERMINAL phrase of the READ statement.

In those cases where you want to receive the data in a specific format, you can identify this format in the FORMAT phrase of the READ statement. If the data available does not match the requested record format, a file status of 9K is set.

The following are examples of the READ statement with the TERMINAL and FORMAT phrases specified.

READ record-name RECORD
     FORMAT IS record-format
END-READ
READ record-name RECORD
     TERMINAL IS program-device-name
END-READ
READ record-name RECORD
     FORMAT IS record-format
     TERMINAL IS program-device-name
END-READ

When the READ statement is performed, the following conditions can arise:

  1. Data is immediately available and the AT END condition does not exist. The AT END condition occurs when there are no invited program devices and a wait time is not specified.
  2. Data is not immediately available.
  3. The AT END condition exists.

You can transfer control to various statements of your ILE COBOL program from the READ statement based on the condition that results from performing the READ statement by specifying the NO DATA phrase, AT END phrase, or NOT AT END phrase.

To perform a group of statements when the READ statement completes successfully, specify the NOT AT END phrase of the READ statement.

To perform a group of statements when the data is not immediately available, specify the NO DATA phrase of the READ statement. The NO DATA phrase prevents the READ statement from waiting for data to become available.

To perform a group of statements when the AT END condition exists, specify the AT END phrase of the READ statement.

The following are examples of the READ statement with the NO DATA, NOT AT END, and AT END phrases specified.

READ record-name RECORD
     TERMINAL IS program-device-name
     NO DATA imperative-statement-1
END-READ
READ record-name RECORD
     TERMINAL IS program-device-name
     AT END imperative-statement-2
     NOT AT END imperative-statement-3
END-READ

Dropping Program Devices

Once you have finished using a program device that you had previously acquired for a TRANSACTION file, you should drop it. Dropping a program device means that it will no longer be available for input or output operations through the TRANSACTION file. Dropping a program device makes it available to other applications. You can drop a program device implicitly or explicitly.

You implicitly drop all program devices attached to a TRANSACTION file when you close the file.

You explicitly drop a program device by indicating it in the DROP statement. The device, once dropped, can be re-acquired again, if necessary.

DROP program-device-name FROM transaction-file-name.

Closing a TRANSACTION File

When you have finished using a TRANSACTION file, you must close it. Use the Format 1 CLOSE statement to close the TRANSACTION file. Once you close the file, it cannot be processed again until it is opened again.

CLOSE transaction-file-name.


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