WHENEVER

The WHENEVER statement specifies the host language statement to be executed when a specified exception condition occurs.

Invocation

This statement can be embedded only in a COBOL application program. It is not an executable statement.

Syntax

Read syntax diagramSkip visual syntax diagramWHENEVER NOT FOUNDSQLERRORSQLWARNING CONTINUEGOTOGO TO:host-label

Description

The following keyword parameters are defined for the WHENEVER statement:
The NOT FOUND, SQLERROR, or SQLWARNING clause is used to identify the type of exception condition.
NOT FOUND
Identifies any condition that results in an SQLIMSCODE of +100 (equivalently, an SQLIMSSTATE code of '02000').
SQLERROR
Identifies any condition that results in a negative SQLIMSCODE.
SQLWARNING
Identifies any condition that results in a warning condition (SQLIMSWARN0 is W), or that results in a positive SQLIMSCODE other than +100.

The CONTINUE or GO TO clause specifies the next statement to be executed when the identified type of exception condition exists.

CONTINUE
Specifies the next sequential statement of the source program.
GOTO or GO TO host-label
Specifies the statement identified by host-label. For host-label, substitute a single token, optionally preceded by a colon. The form of the token depends on the host language. In COBOL, for example, it can be section-name or an unqualified paragraph-name.

Notes

There are three types of WHENEVER statements:

  • WHENEVER NOT FOUND
  • WHENEVER SQLERROR
  • WHENEVER SQLWARNING

Every executable SQL statement in an application program is within the scope of one implicit or explicit WHENEVER statement of each type. The scope of a WHENEVER statement is related to the listing sequence of the statements in the application program, not their execution sequence.

An SQL statement is within the scope of the last WHENEVER statement of each type that is specified before that SQL statement in the source program. If a WHENEVER statement of some type is not specified before an SQL statement, that SQL statement is within the scope of an implicit WHENEVER statement of that type in which CONTINUE is specified.

Examples

The following statements can be embedded in a COBOL program.

Example 1: Go to the label HANDLER for any statement that produces an error. 

   EXEC SQLIMS WHENEVER SQLERROR GOTO HANDLER END-EXEC.

Example 2: Continue processing for any statement that produces a warning. 

   EXEC SQLIMS WHENEVER SQLWARNING CONTINUE END-EXEC.

Example 3: Go to the label ENDDATA for any statement that does not return. 

   EXEC SQLIMS WHENEVER NOT FOUND GO TO ENDDATA END-EXEC.