File Exception/Error Subroutine (INFSR)

To identify the user-written RPG IV subroutine that may receive control following file exception/errors, specify the INFSR keyword on the File Description specification with the name of the subroutine that receives control when exception/errors occur on this file. The subroutine name can be *PSSR, which indicates that the program exception/error subroutine is given control for the exception/errors on this file.

A file exception/error subroutine (INFSR) receives control when an exception/error occurs on an implicit (primary or secondary) file operation or on an explicit file operation that does not have an indicator specified in positions 73 and 74,does not have an (E) extender, and is not in the monitor block of a MONITOR group that can handle the error.. The file exception/error subroutine can also be run by the EXSR operation code. Any of the RPG IV operations can be used in the file exception/error subroutine. Factor 1 of the BEGSR operation and factor 2 of the EXSR operation must contain the name of the subroutine that receives control (same name as specified with the INFSR keyword on the file description specifications).
Note: The INFSR keyword cannot be specified if the keyword MAIN or NOMAIN keyword is specified on the Control specification, or if the file is to be accessed by a subprocedure. To handle errors for the file in your procedure, you can use the (E) extender to handle errors for an individual I/O operation, or you can use a MONITOR group to handle errors for several operations. The ON-ERROR section of your MONITOR group could call a subprocedure to handle the details of the error handling.
The ENDSR operation must be the last specification for the file exception/error subroutine and should be specified as follows:
Position
Entry
6
C
7-11
Blank
12-25
Can contain a label that is used in a GOTO specification within the subroutine.
26-35
ENDSR
36-49
Optional entry to designate where control is to be returned following processing of the subroutine. The entry must be a 6-position character field, literal, or array element whose value specifies one of the following return points.
Note: If the return points are specified as literals, they must be enclosed in apostrophes. If they are specified as named constants, the constants must be character and must contain only the return point with no leading blanks. If they are specified in fields or array elements, the value must be left-adjusted in the field or array element.
*DETL
Continue at the beginning of detail lines.
*GETIN
Continue at the get input record routine.
*TOTC
Continue at the beginning of total calculations.
*TOTL
Continue at the beginning of total lines.
*OFL
Continue at the beginning of overflow lines.
*DETC
Continue at the beginning of detail calculations.
*CANCL
Cancel the processing of the program.
Blanks
Return control to the RPG IV default error handler. This applies when factor 2 is a value of blanks and when factor 2 is not specified. If the subroutine was called by the EXSR operation and factor 2 is blank, control returns to the next sequential instruction. Blanks are only valid at runtime.
50-76
Blank.
Remember the following when specifying the file exception/error subroutine:
  • The programmer can explicitly call the file exception/error subroutine by specifying the name of the subroutine in factor 2 of the EXSR operation.
  • After the ENDSR operation of the file exception/error subroutine is run, the RPG IV language resets the field or array element specified in factor 2 to blanks. Thus, if the programmer does not place a value in this field during the processing of the subroutine, the RPG IV default error handler receives control following processing of the subroutine unless the subroutine was called by the EXSR operation. Because factor 2 is set to blanks, the programmer can specify the return point within the subroutine that is best suited for the exception/error that occurred. If the subroutine was called by the EXSR operation and factor 2 of the ENDSR operation is blank, control returns to the next sequential instruction following the EXSR operation. A file exception/error subroutine can handle errors in more than one file.
  • If a file exception/error occurs during the start or end of a program, control passes to the RPG IV default error handler, and not to the user-written file exception/error or subroutine (INFSR).
  • Because the file exception/error subroutine may receive control whenever a file exception/error occurs, an exception/error could occur while the subroutine is running if an I/O operation is processed on the file in error. If an exception/error occurs on the file already in error while the subroutine is running, the subroutine is called again; this will result in a program loop unless the programmer codes the subroutine to avoid this problem. One way to avoid such a program loop is to set a first-time switch in the subroutine. If it is not the first time through the subroutine, set on a halt indicator and issue the RETURN operation as follows:
Figure 1. Setting a First-time Switch
*...1....+....2....+....3....+....4....+....5....+....6....+....7...

CL0N01Factor1+++++++Opcode(E)+Factor2+++++++Result++++++++Len++D+HiLoEq..

C* If INFSR is already handling the error, exit.

C     ERRRTN        BEGSR

C     SW            IFEQ      '1'

C                   SETON                                        H1

C                   RETURN

C* Otherwise, flag the error handler.

C                   ELSE

C                   MOVE      '1'           SW

C                     :

C                     :

C                     :

C                   ENDIF

C* End error processing.

C                   MOVE      '0'           SW

C                   ENDSR
Note: It may not be possible to continue processing the file after an I/O error has occurred. To continue, it may be necessary to issue a CLOSE operation and then an OPEN operation to the file.