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.

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.

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).