The function of WHENEVER statements is to perform general error and exception handling routines for all subsequent SQL statements. Different kinds of errors and exceptions can thereby be distinguished. In application programming, WHENEVER statements help to handle error situations. WHENEVER statements should always be used when SQLCODE or SQLWARNING is not checked after every individual SQL statement. Those SQL statements are considered to be subsequent that textually (statically) follow the WHENEVER statement in the program. A WHENEVER error handling routine is valid until it is changed by another WHENEVER statement.
The WHENEVER statement checks four classes of ADABAS return codes (values of SQLWARN0 or SQLCODE) and offers four default actions that can be taken in response. The general format of the WHENEVER statement is:
WHENEVER <condition> <action>
One of the following cases can be specified for <condition>:
SQLWARNING exists when SQLWARN0 is set to 'W'. Then, at least one SQLWARNING is set.
SQLERROR indicates that SQLCODE has a negative value, which means that an unexpected error occurred. The program should be aborted and analyzed. The possible error codes and adequate user actions in response to them are described in the manualonline help Messages and Codes.
SQLEXCEPTION indicates a positive SQLCODE value greater than +100. Messages of this kind generally are exceptional cases which should be handled within the program.
NOT FOUND is valid when no (further) table row has been found and SQLCODE has the value +100 (ROW NOT FOUND).
One of the following cases can be specified for <action>:
STOP causes the regular resetting of the current transaction and abortion of the program (COMMIT WORK RELEASE).
CONTINUE does not perform an action when the condition occurs and therefore suspends another WHENEVER condition which has previously been set.
GO TO <LAB> causes a jump to the indicated label (maximum length of the label: 32 characters).
CALL <PROC> has the effect that a PERFORM is issued on the section designated by <PROC>.
If no WHENEVER statements are included, CONTINUE is the default action for all conditions. User error handling can be implemented by checking SQLCODE. If another WHENEVER statement has previously been specified, it must be suspended by WHENEVER ... CONTINUE.
If SQL statements are issued in the WHENEVER error handling code, then the corresponding WHENEVER action must be set to CONTINUE in order to avoid an endless loop generated by repeated calls of the WHENEVER error handling routine.
The WHENEVER statements can also be used to call COBOL statements before and after each SQL statement (see Section WHENEVER Statements).
Example:
In this example, the procedure WARNPROC is called for all SQL statements when SQLWARN0 is set. The default error handling for a negative SQLCODE (SQLERROR), on the other hand, varies. Only the SELECT statement lies within the scope of the first WHENEVER SQLERROR statement. The second WHENEVER SQLERROR statement refers to all subsequent SQL statements. The DELETE statement is not placed within the scope of a (preceding) WHENEVER SQLERROR statement. Therefore, the default action CONTINUE is operative.