The WHENEVER statement causes SQL to check the SQLSTATE and SQLCODE
and continue processing your program, or branch to another area in your program
if an error, exception, or warning exists as a result of running an SQL statement.
An exception condition handling subroutine (part of your program)
can then examine the SQLCODE or SQLSTATE field to take an action specific
to the error or exception situation.
Note: The WHENEVER statement is not allowed
in REXX procedures.
The WHENEVER statement allows you to specify what you want to
do whenever a general condition is true. You can specify more than one WHENEVER
statement for the same condition. When you do this, the first WHENEVER statement
applies to all subsequent SQL statements in the source program until another
WHENEVER statement is specified.
The WHENEVER statement looks like this:
EXEC SQL
WHENEVER condition action
END-EXEC.
There are three conditions you can specify:
- SQLWARNING
- Specify SQLWARNING to indicate what you want done when SQLWARN0 = W or
SQLCODE contains a positive value other than 100 (SUBSTR(SQLSTATE,1,2) ='01').
Note: SQLWARN0
could be set for several different reasons. For example, if the value of a
column was truncated when it was moved into a host variable, your program
might not regard this as an error.
- SQLERROR
- Specify SQLERROR to indicate what you want done when an error code is
returned as the result of an SQL statement (SQLCODE < 0) (SUBSTR(SQLSTATE,1,2) >
'02').
- NOT FOUND
- Specify NOT FOUND to indicate what you want done when an SQLCODE of +100
and a SQLSTATE of '02000' is returned because:
- After a single-row SELECT is issued or after the first FETCH is issued
for a cursor, the data the program specifies does not exist.
- After a subsequent FETCH, no more rows satisfying the cursor select-statement
are left to retrieve.
- After an UPDATE, a DELETE, or an INSERT, no row meets the search condition.
You can also specify the action you want taken:
- CONTINUE
- This causes your program to continue to the next statement.
- GO TO label
- This causes your program to branch to an area in the program. The label
for that area may be preceded with a colon. The WHENEVER ... GO TO statement:
- Must be a section name or an unqualified paragraph name in COBOL
- Is a label in PL/I and C
- Is the label of a TAG in RPG
For example, if you are retrieving rows using a cursor, you expect
that SQL will eventually be unable to find another row when the FETCH statement
is issued. To prepare for this situation, specify a WHENEVER NOT FOUND GO
TO ... statement to cause SQL to branch to a place in the program where you
issue a CLOSE statement in order to close the cursor properly.
Note: A WHENEVER
statement affects all subsequent source SQL statements until another
WHENEVER is encountered.
In other words, all SQL statements coded between two WHENEVER
statements (or following the first, if there is only one) are governed by
the first WHENEVER statement, regardless of the path the program takes.
Because of this, the WHENEVER statement must precede the
first SQL statement it is to affect. If the WHENEVER follows the SQL
statement, the branch is not taken on the basis of the value of the SQLCODE
and SQLSTATE set by that SQL statement. However, if your program checks the
SQLCODE or SQLSTATE directly, the check must be done after the SQL statement
is run.
The WHENEVER statement does not provide a CALL to a subroutine
option. For this reason, you might want to examine the SQLCODE or SQLSTATE
value after each SQL statement is run and call a subroutine, rather than use
a WHENEVER statement.