ODBC Server Reference Manual

Stored Procedures
HP NonStop ODBC Server Reference Manual—429151-002
5-43
SPELIB Interface
SPELIB Errors
For error-handling purpose, a Pathway server class program that emulates a stored
procedure is considered to have two sets of errors: SPELIB errors and other errors.
The latter might be NonStop SQL/MP execution errors, Pathway program errors, and
so on. SPELIB provides SP_SRV_ENCODE_SQL_DIAGNOSTIC for encoding SQL
errors or warnings, SP_SRV_ENCODE_RAISERROR for encoding non-SQL errors
and SP_SRV_ENCODE_PRINTMSG for reporting informational messages. When the
NonStop ODBC Server receives SQL diagnostic or “raise error” messages, it does not
terminate processing the SPE messages coming back from server class program.
However, it is recommended that SP_SRV_ENCODE_SQL_DIAGNOSTIC (when an
SQLCA error—not a warning—occurs) or SP_SRV_ENCODE_RAISERROR should be
the last message encoded before issuing SP_SRV_ENCODE_END_STMT or
SP_SRV_ENCODE_END_PROC.
SPELIB also provides SP_SRV_ENCODE_SPELIB_ERROR for SPELIB errors. Each
SPELIB function returns a status code that signals the success or failure of the called
function. It is recommended that if an SPELIB function returns an error on which the
server class program cannot take action (or if it is difficult to recover), the server class
program should call SP_SRV_ENCODE_SPELIB_ERROR to return the error, then call
the system function REPLY to indicate the end of the server processing. It is the
responsibility of the server class program to return the reply buffer, with or without a
reply error code. A reply error code is normally used for file errors and I/O errors (for
example, cannot open the requester for call-back activity). For an SPELIB error, it is
recommended that the server class program reply with the reply buffer and with the
reply error code set to zero.
For other fatal program errors (for example, “cannot allocate buffer for
encode/decode”), a server class program can return a reply buffer with its length set to
zero and the reply error code also set to zero.
When the NonStop ODBC Server receives a reply (or write) buffer from the server
class program, it checks whether there is any I/O error or if the buffer is empty (an
empty reply buffer is considered a fatal error of the server class program). In both
cases, the NonStop ODBC Server does not decode the buffer; however, it does send
an error message to the client, and also aborts the transaction.
If there is no I/O error, and the buffer is not empty, the NonStop ODBC Server decodes
the buffer and sends a result back to the client. If the NonStop ODBC Server
encounters any SPELIB error, the NonStop ODBC Server ends further decoding
processes, sends an error message back to the client, and aborts the transaction.
Note that SPELIB enforces certain validation to keep the SPE environment intact;
however, if the NonStop ODBC Server detects any SPE environment error (bad
sequence, bad pointers, and the like), the NonStop ODBC Server cancels the
PATHSEND operation.