Determining the Type of Error Through the File Status Key

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:

Method A (all files):
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).
Method B (transaction files):
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 IBM® Rational® Development Studio for i: ILE COBOL Reference.
Method C (all files):
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 IBM Rational Development Studio for i: 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
 ––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––