The FAIL (or FT) Parameter

For many of the statements that set true/false status indicators, the statement format also offers a fail action type parameter. These statements include the process-type statements (such as INPUT, OUTPUT, STATUS, etc.) and certain file-related statements (such as CREATE, IF EXIST, READ, etc.) as shown in the example below.

          STATUS   TAR END OF MONTH STATUS              SUBPROCESS   END? Y  FAIL 3
or
          READ     TAR UNPAID                 HOLD 0 FT 2 BY UNPAID KEY
or
          SCRATCH  TAR TEMP                FAIL 0 CACHE? N

The FAIL (or FT) parameter controls what additional action to take if the statement returns a false condition, as follows:

·    0 = Do nothing,

·    1 = Issue a warning message,

·    2 = Issue an error message, or

·    3 = Cancel.

Note that the system message generated according to a FAIL parameter is descriptive in nature and may not contain sufficient detail to locate the point of failure in the program. For instance, if an OPEN statement with FAIL = 2 were to fail, the message generated could simply be "Error - File Does Not Exist". Therefore, it might be desirable to code WARNING or ERROR messages on a false condition as an alternative or to provide supplemental information as shown in the example below.

          OPEN     TGL ACCTMS    SHARE? Y  FAIL 2 CACHE? N
    F     ERROR    Unexpected Error OPEN TGL ACCTMS (see error message above)

However, if a cancel is issued, either by use of FAIL = 3 or by a CANCEL statement, any supplemental warning/error messages will only appear if an output report or error log is also generated.

File-related statements with the FAIL parameter that return a false condition also set the STATUS CODE predefined field, a token field containing the reason for the I/O command failure. It can be used to obtain a descriptive error message from the system message file (this is the same message that would be generated by a FAIL parameter set to 1-3).