This chapter examines the need for runtime status checking.
It describes the sqlca and the conditions under which
its data items are set by ALLBASE/SQL. It also gives several
examples of implicit and explicit status checking, some of which
use SQLEXPLAIN to display a status message. Examples of handling
specific status checking tasks are included under "Approaches to
Status Checking."
When an SQL command is executed, ALLBASE/SQL returns
information describing how the command
executed. This information signals one or more of
the following status conditions:
The command was successfully executed.
The command could not be executed because an error
condition occurred, but the current transaction will continue.
No rows qualified for a data manipulation operation.
A specific number of rows were placed into output
host variables.
A specific number of rows qualified for an INSERT, UPDATE,
or DELETE operation.
The command was executed, but a warning condition resulted.
The command was executed, but a character string was truncated.
The command was executed, but a null value was eliminated from an
aggregate function.
The command could not be executed because the number of variables in a
SELECT or FETCH statement
is unequal to the number of columns in the table being operated on.
This applies to dynamic processing only.
The command could not be executed because an error condition
necessitated rolling back the current transaction.
Based on this runtime status information, a program can COMMIT WORK,
ROLLBACK WORK, continue, terminate, display a message, or
perform some other appropriate activity.
You can use the WHENEVER command to perform
implicit status checking. This means that
ALLBASE/SQL checks the sqlcode and sqlwarn[0] values for
you, then takes an action based on information you
provide in the WHENEVER command.
You can write C code that explicitly examines
one or more of the seven sqlca elements,
then proceeds on the basis of their values. This kind of status
checking is called explicit status checking.
You can use a combination of both implicit and explicit
status checking.
In conjunction with status checking of any kind, you can use the
SQLEXPLAIN command. This command retrieves a message
from the ALLBASE/SQL message catalog that describes an error or warning
condition.
When several errors or warnings occur, you can use SQLEXPLAIN to
retrieve messages for all of them.
Messages are available to your program in the order in which the
errors or warnings occurred.
When ALLBASE/SQL rolls back the current transaction,
it does not continue to look for errors. This means that the last
message retrieved will indicate the cause of the roll back.
An example of this scenario is presented later in this chapter under
"sqlcode." Refer to the ALLBASE/SQL Message Manual
for an explanation of all error and
warning messages.
