Home

	Expand Search

Open Client Client-Library/C Reference Manual

Chapter 2 Topics

Error handling

Error and message handling

Error and message handling

After initialization, Client-Library applications must handle two types of error and informational messages:

• Client-Library messages, or client messages, are generated by Client-Library. They range in severity from informational messages to fatal errors.

• Server messages are generated by the server. They range in severity from informational messages to fatal errors.

  Adaptive Server stores the text of its messages in the sysmessages system table. See the Adaptive Server Reference Manual for a description of this table.

  See the Open Server Server-Library/C Reference Manual for a list of Open Server messages.

  Do not confuse Client-Library and server messages with a result set of type CS_MSG_RESULT. Client-Library and server messages are the means through which Client-Library and the server communicate error and informational conditions to an application. An application accesses Client-Library and server messages either through message callback routines or inline, using ct_diag. A message result set, on the other hand, is one of several types of result sets that a server may return to an application. An application processes a result set of type CS_MSG_RESULT by calling ct_res_info to get the message's ID.

An application handles Client-Library and server messages in one of two ways:

• By installing callback routines to handle messages

• Inline, using the Client-Library routine ct_diag

The callback method has the advantages of:

• Centralizing message handling code.

• Providing a method to gracefully handle unexpected errors. Client-Library automatically calls the appropriate message callback whenever a message is generated, so an application will not fail to trap unexpected errors. An application using only mainline error-handling logic may not successfully trap errors that have not been anticipated.

Inline message handling has the advantage of allowing an application to check for messages at particular times. For example, an application that is creating a connection might choose to wait until all connection-related commands are issued before checking for messages.

Most applications use the callback method to handle messages. However, an application that is running on a platform and language combination that does not support callbacks must use the inline method.

An application indicates which method it will use by calling ct_callback to install message callbacks or by calling ct_diag to initialize inline message handling.

An application uses different methods on different connections. For example, an application installs message callbacks at the context level, allocates two connections, and then calls ct_diag to initialize inline message handling for one of the connections. The other connection will use the default message callbacks that it picked up from its parent context.

An application may switch back and forth between the inline and callback methods:

• Installing either a client message callback or a server message callback turns off inline message handling. Any saved messages are discarded.

• Likewise, calling ct_diag to initialize inline message handling de-installs a connection's message callbacks. If this occurs, the connection's first CS_GET call to ct_diag will retrieve a warning message to this effect.

If a callback of the proper type is not installed and inline message handling is not enabled, Client-Library discards message information.

An application calls ct_callback to install message callbacks.

Client-Library stores callbacks in the CS_CONNECTION and CS_CONTEXT structures. Because of this, when a Client-Library error occurs that makes a CS_CONNECTION or CS_CONTEXT structure unusable, Client-Library cannot call the client message callback. However, the routine that caused the error still returns CS_FAIL.

For more information about using callbacks to handle Client-Library and server messages, see "Callbacks" and the ct_callback reference page.

An application calls ct_diag to initialize inline message handling for a connection. A typical application calls ct_diag immediately after calling ct_con_alloc to allocate the connection structure.

An application cannot use ct_diag at the context level. That is, an application cannot use ct_diag to retrieve messages generated by routines that take a CS_CONTEXT (and no CS_CONNECTION) as a parameter. These messages are unavailable to an application that is using inline error handling.

An application that is retrieving messages into a SQLCA, SQLCODE, or SQLSTATE should set the Client-Library property CS_EXTRA_INF to CS_TRUE. See "The CS_EXTRA_INF property" for more information.

The CS_DIAG_TIMEOUT property controls whether Client-Library fails or retries when a Client-Library routine generates a timeout error.

If a Client-Library error occurs that makes a CS_CONNECTION structure unusable, ct_diag returns CS_FAIL when called to retrieve information about the original error.

For more information about the inline method of handling Client-Library and server messages, see ct_diag.

Client-Library uses the following structures to return message information:

• CS_CLIENTMSG - described in the section, "Client-Library and SQL Structures".

• CS_SERVERMSG - described in the section, "Client-Library and SQL Structures".

• SQLCA - described in the section, "Client-Library and SQL Structures".

• SQLCODE - described in the section, "Client-Library and SQL Structures".

• SQLSTATE - described in the section, "Client-Library and SQL Structures" .