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.
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.
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.
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.
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
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.
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.
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.
(C) Copyright IBM Corporation 1992, 2005. All Rights Reserved.