Using a File Error (INFSR) Subroutine

To handle a file error or exception you can write a file error (INFSR) subroutine. When a file exception occurs:

The INFDS is updated.
A file error subroutine (INFSR) receives control if the exception occurs:
- On an implicit (primary or secondary) file operation
- On an explicit file operation that does not have an indicator specified in positions 73 - 74.

A file error subroutine can handle errors in more than one file.

The following restrictions apply:

If a file exception occurs during the start or end of a program, (for example, on an implicit open at the start of the cycle) control passes to the ILE RPG default exception handler, and not to the error subroutine handler. Consequently, the file error subroutine will not be processed.
If an error occurs that is not related to the operation (for example, an array-index error on a CHAIN operation), then any INFSR error subroutine would be ignored. The error would be treated like any other program error.
An INFSR cannot handle errors in a global file used by a subprocedure.

To add a file error subroutine to your program, you do the following steps:

Enter the name of the subroutine after the keyword INFSR on a File Description specification. The subroutine name can be *PSSR, which indicates that the program error subroutine is given control for the exception on this file.
Optionally identify the file information data structure on a File Description specification using the keyword INFDS.
Enter a BEGSR operation where the Factor 1 entry contains the same subroutine name that is specified for the keyword INFSR.
Identify a return point, if any, and code it on the ENDSR operation in the subroutine. For a discussion of the valid entries for Factor 2, see Specifying a Return Point in the ENDSR Operation. A Factor 2 is not allowed for a file error subroutine in a subprocedure.
Code the rest of the file error subroutine. While any of the ILE RPG compiler operations can be used in the file error subroutine, it is not recommended that you use I/O operations to the same file that got the error. The ENDSR operation must be the last specification for the file error subroutine.

Figure 138 shows an example of exception handling using an INFSR error subroutine. The program TRNSUPDT is a simple inventory update program. It uses a transaction file TRANSACT to update a master inventory file PRDMAS. If an I/O error occurs, then the INFSR error subroutine is called. If it is a record lock error, then the record is written to a backlog file. Otherwise, an inquiry message is issued.

Note that the File specification for PRDMAS identifies both the INFDS and identifies the INFSR to be associated with it.

The following is done for each record in the TRANSACT file:

The appropriate record in the product master file is located using the transaction product number.
If the record is found, then the quantity of the inventory is updated.
If an error occurs on the UPDATE operation, then control is passed to the INFSR error subroutine.
If the record is not found, then the product number is written to an error report.

Figure 138. Example of File Exception Handling

      *=================================================================*
      * TRNSUPDT: This program is a simple inventory update program.    *
      * The transaction file (TRANSACT) is processed consecutively.     *
      * The product number in the transaction is used as key to access  *
      * the master file (PRDMAS) randomly.                              *
      * 1. If the record is found, the quantity of the inventory will   *
      *    be updated.                                                  *
      * 2. If the record is not found, an error will be printed on a    *
      *    report.                                                      *
      * 3. If the record is currently locked, the transaction will be   *
      *    written to a transaction back log file which will be         *
      *    processed later.                                             *
      * 4. Any other unexpected error will cause a runtime error        *
      *    message.                                                     *
      *=================================================================*
      *-----------------------------------------------------------------*
      * Define the files:                                               *
      *   1) PRDMAS      - Product master file                          *
      *   2) TRANSACT    - Transaction file                             *
      *   3) TRNBACKLG   - Transaction backlog file                     *
      *   2) PRINT       - Error report.                                *
      *-----------------------------------------------------------------*
     FPRDMAS    UF   E           K DISK
     F                                     INFSR(PrdInfsr)
     F                                     INFDS(PrdInfds)
     FTRANSACT  IP   E             DISK
     FTRNBACKLG O    E             DISK
     FPRINT     O    F   80        PRINTER
      *-----------------------------------------------------------------*
      * Define the file information data structure for file PRDMAS.     *
      * The *STATUS field is used to determine what action to take.     *
      *-----------------------------------------------------------------*
     D PrdInfds        DS
     D  PrdStatus        *STATUS
      *-----------------------------------------------------------------*
      * List of expected exceptions.                                    *
      *-----------------------------------------------------------------*
     D ErrRecLock      C                   CONST(1218)

      *-----------------------------------------------------------------*
      * Access the product master file using the transaction product    *
      * number.                                                         *
      *-----------------------------------------------------------------*
     C     TRNPRDNO      CHAIN     PRDREC                             10
      *-----------------------------------------------------------------*
      * If the record is found, update the quantity in the master file. *
      *-----------------------------------------------------------------*
     C                   IF        NOT *IN10
     C                   SUB       TRNQTY        PRDQTY
     C                   UPDATE    PRDREC
      *-----------------------------------------------------------------*
      * If the record is not found, write to the error report           *
      *-----------------------------------------------------------------*
     C                   ELSE
     C                   EXCEPT    NOTFOUND
     C                   ENDIF
     C                   SETON                                        LR
      *-----------------------------------------------------------------*
      * Error handling routine.                                         *
      *-----------------------------------------------------------------*
     C     PrdInfsr      BEGSR
      *-----------------------------------------------------------------*
      * If the master record is currently locked, write the transaction *
      * record to the back log file and skip to next transaction.       *
      *-----------------------------------------------------------------*
     C     PrdStatus     DSPLY
     C                   IF        (PrdStatus = ErrRecLock)
     C                   WRITE     TRNBREC
     C                   MOVE      '*GETIN'      ReturnPt          6
      *-----------------------------------------------------------------*
      * If unexpected error occurs, cause inquiry message to be issued. *
      *-----------------------------------------------------------------*
     C                   ELSE
     C                   MOVE      *BLANK        ReturnPt
     C                   ENDIF
     C                   ENDSR     ReturnPt
      *-----------------------------------------------------------------*
      * Error report format.                                            *
      *-----------------------------------------------------------------*
     OPRINT     E            NOTFOUND
     O                       TRNPRDNO
     O                                           29 'NOT IN PRDMAS FILE'

When control is passed to the error subroutine, the following occurs:

If the error is due to a record lock, then the record is written to a backlog file and control returns to the main part with the next transaction (via *GETIN as the return point).
If the error is due to some other reason, then blanks are moved to ReturnPt. This will result in the RPG default handler receiving control. The recovery action at that point will depend on the nature of the error.

Note that the check for a record lock error is done by matching the *STATUS subfield of the INFDS for PRDMAS against the field ErrRecLock which is defined with the value of the record lock status code. The INFSR could be extended to handle other types of I/O errors by defining other errors, checking for them, and then taking an appropriate action.

[ Top of Page | Previous Page | Next Page | Contents | Index ]