The file status key is updated after each input-output operation on a file by placing values in the two digits of the file status key. In general, a zero in the first digit indicates a successful operation, and a zero in both digits means "nothing abnormal to report".
You must provide a FILE-CONTROL entry to specify the organization and access method for each file used by your ILE COBOL program. You can also code a FILE STATUS clause in this entry.
The FILE STATUS clause designates one or two data items (coded in the WORKING-STORAGE section) to hold a copy of the result of an I/O operation. Your copy of the first of these items is called the external file status. If you use a TRANSACTION file, you have a further record of the result called the external return code, which consists of the external major and minor return codes.
ILE COBOL keeps its information corresponding to these two data items in the ILE COBOL File Field Descriptor (FFD). ILE COBOL's copies of these two data items are called the internal file status and internal return code. In this chapter, file status and (major/minor) return code refer to ILE COBOL's copies unless otherwise specified.
During the processing of an I/O statement, the file status can be updated in one of three ways, as described below. The contents of the file status determine which error handling procedures to run.
Error handling procedures take control after an unsuccessful input or output operation, which is denoted by a file status of other than zero. Before any of these procedures run, the file status is copied into the external file status.
The file status is set in one of three ways:
ILE COBOL checks the contents of variables in file control blocks. If the contents are not what is expected, a file status of other than zero is set. Most file statuses set in this way result from checking the ILE COBOL File Field Descriptor (FFD) and the system User File Control Block (UFCB).
ILE COBOL checks the major and minor return codes from the system. If the major return code is not zero, the return code (consisting of major and minor return codes) is translated into a file status. If the major return code is zero, the file status may have been set by Method A or C.
For subfile READ, WRITE, and REWRITE operations, only Methods A and C apply.
For a list of return codes and their corresponding file statuses, see "File Structure Support Summary and Status Key Values" in the WebSphere Development Studio: ILE COBOL Reference.
A message is sent by the system when ILE COBOL calls data management to perform an I/O operation. ILE COBOL then monitors for these messages and sets a file status accordingly. Each ILE COBOL I/O operation is handled by a routine within a service program, which is supplied with the ILE COBOL compiler. This routine then calls data management to perform the I/O operation. In most cases, a single message monitor is enabled around these call to the routine in the service program.
The message monitor for each I/O operation handles typical I/O exceptions resulting in CPF messages that begin with The message monitor sets the file status based on the CPF message that it receives. For a list of messages that the message monitor handles, see "File Structure Support Summary and Status Key Values" in the WebSphere Development Studio: ILE COBOL Reference.
Through the use of message monitors in this fashion, file status is set consistently for each type of I/O operation regardless of what other types of I/O operations you have in your program. Refer to Handling Messages through Condition Handlers for more information on message monitors.
HOW FILE STATUS IS SET 0100 .---. '001' '---' - Start the I/O operation. - Reset the internal file status. - Method A: Check the contents of the variables in the file control blocks. (Check, for example, that the file has been opened properly.) ARE THE VARIABLES IN THE FILE CONTROL BLOCKS SET AS EXPECTED? YES NO ' ' ' .'--. ' '002' ' '---' ' - Set internal file status to indicate that an error has occurred. ' - Continue at -- Step 'INT2EXT' unknown -- .'--. '003' '---' - Call on data management to perform the I/O operation. DOES DATA MANAGEMENT RETURN AN EXCEPTION? YES NO ' ' ' .'--. ' '004' ' '---' ' - Method A: Check the contents of the variables in the file control blocks. ' ARE THE VARIABLES IN THE FILE CONTROL BLOCKS SET AS EXPECTED? ' YES NO ' ' ' ' ' .'--. ' ' '005' ' ' '---' ' ' - Set internal file status to indicate that an error has occurred. ' ' - Continue at -- Step 'INT2EXT' unknown -- ' ' ' .'--. ' '006' ' '---' ' - Move internal file status to external file status (specified in file ' status clause). ' - Based on internal file status, run the error handling code. ' ---------------------------------------------------------------------------- .'--. '007' '---' IS THE FILE A TRANSACTION FILE? YES NO ' ' ' .'--. ' '008' ' '---' ' - Method C: Set the internal file status according to the CPF message sent ' by data management. ' - Continue at Step 004 .'--. '009' '---' ARE MAJOR AND MINOR RETURN CODES AVAILABLE FROM THE SYSTEM? YES NO ' ' ' .'--. ' '010' ' '---' ' - Method C: Set the internal file status according to the CPF message sent ' by data management. ' - Continue at Step 004 .'--. '011' '---' - Method B: Set the internal file status based on the major and minor return codes available from the system. - Continue at Step 004 --------------------------------------------------------------------------------
When you specify a TRANSACTION file in your program, the FILE STATUS clause of your SELECT statement can contain two data names: the external file status, and the external (major and minor) return code. As described under Determining the Type of Error Through the File Status Key, a file status can be set in one of three ways; however, return codes are set by the system after any transaction I/O that calls data management. Consequently, most error conditions that result in a system message also have an associated return code.
Return codes are similar to file status values. That is, CPF messages sent by the system are grouped together by the ILE COBOL run time exception handler and each group of CPF messages is used to set one or more file statuses. Similarly, each major return code is also generated by a group of CPF messages. (The minor return code is not necessarily the same.) The main difference between file statuses and return codes is that the grouping of CPF messages is different.
Although ILE COBOL only sets return codes for TRANSACTION files, other types of files (such as printer files) also set return codes. You can access the return codes for these files through an ACCEPT from I-O-FEEDBACK operation.
A condition handler provides a way for an ILE procedure or program object to handle messages sent by the system or by another ILE procedure or program object. A condition handler can handle one or more messages.
In some respects, a condition handler resembles a USE procedure. Similar to the way in which a USE procedure specifies actions to take in response to an I/O error, a condition handler specifies an action to take when an error occurs during the processing of a machine interface (MI) instruction. An MI instruction error is signalled by a system message, and each ILE COBOL statement is composed of one or more MI instructions.
There are two types of condition handlers:
(C) Copyright IBM Corporation 1992, 2005. All Rights Reserved.