ILE COBOL Programmer's Guide

Processing a Subfile 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 Subfile 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 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 display files, 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 Subfile 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 5 WRITE statement to write a logical record to the subfile TRANSACTION file. You simply code the WRITE statement as follows:

WRITE SUBFILE 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 5 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 5 WRITE statement to specify the program device's subfile to which you want the output record to be sent.

WRITE SUBFILE record-name
      FORMAT IS format-name
      TERMINAL IS program-device-name
END-WRITE.

Before or after filling the subfile TRANSACTION file with records using the Format 5 WRITE statement, you can write the subfile control record to the program device using the Format 4 WRITE statement. Refer to Writing to a Transaction File for a description of how to use the Format 4 WRITE statement to write to a TRANSACTION file. Writing the subfile control record could cause the display of either the subfile control record, the subfile records, or both the subfile control record and subfile records.

Reading from a Subfile Transaction File

You use the Format 4 READ statement to read a subfile control record. Refer to Reading from a Transaction File for a description of how to use the Format 4 READ statement to read to a TRANSACTION file. Reading the subfile control record physically transfers records from the program device so that they can be made available to the subfile.

Once the records are available to the subfile, you use the Format 5 READ statement to read a specified record from the subfile TRANSACTION file. The Format 5 READ statement can only be used to read a format that is a subfile record; it cannot be used for communications devices.

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 read a subfile sequentially or randomly.

To read a subfile sequentially, you must specify the NEXT MODIFIED phrase in the Format 5 READ statement. When the NEXT MODIFIED phrase is specified, the record made available is the first record in the subfile that has been modified. For information about how a subfile record is marked as being modified, refer to the Database anf File Systems category in the iSeries 400 Information Center at this Web site -http://publib.boulder.ibm.com/pubs/html/as400/infocenter.htm.

If there are no next modified subfile records available, the AT END condition exists, the file status is set to 12, and the value of the RELATIVE KEY data item is set to the key of the last record in the subfile.

When reading a subfile sequentially, you should also specify the AT END phrase in the Format 5 READ statement. The AT END phrase allows you to specify an imperative statement to be executed when the AT END condition arises.

READ SUBFILE subfile-name NEXT MODIFIED RECORD
     AT END imperative-statement
END-READ

To read a subfile randomly, you must specify, in the RELATIVE KEY data item, the relative record number of the subfile record you want to read and you must not specify the NEXT MODIFIED phrase in the Format 5 READ statement. When the NEXT MODIFIED phrase is not specified, the record made available is the record in the subfile with a relative key record number that corresponds to the value of the RELATIVE KEY data item. If the RELATIVE KEY data item, at the time that the READ statement is performed, contains a value that does not correspond to a relative record number for the subfile, the INVALID KEY condition exists.

When reading a subfile randomly, you should also specify the INVALID KEY phrase in the Format 5 READ statement. The INVALID KEY phrase allows you to specify an imperative statement to be executed when the INVALID KEY condition arises.

READ SUBFILE subfile-name RECORD
     INVALID KEY imperative-statement
END-READ

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 SUBFILE subfile-name RECORD
     FORMAT IS record-format
END-READ
READ SUBFILE subfile-name RECORD
     TERMINAL IS program-device-name
END-READ
READ SUBFILE subfile-name RECORD
     FORMAT IS record-format
     TERMINAL IS program-device-name
END-READ

Replacing (Rewriting) a Subfile Record

Once you have read and modified a subfile record, you can replace it in the subfile using the REWRITE statement.

REWRITE SUBFILE record-name
        FORMAT IS record-format
        TERMINAL IS program-device-name
END-REWRITE

The record replaced in the subfile is the record in the subfile accessed by the previous successful READ operation.

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 Subfile Transaction File

When you have finished using a subfile 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 ]