HP 3000 Manuals HP 3000 Manuals
Chapter 4 Runtime Status Checking and the sqlca
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.