Home

	Expand Search

Open Client Client-Library/C Reference Manual

Chapter 2 Topics

Error handling

Error handling

All Client-Library routines return success or failure indications. Sybase recommends that applications check these return codes.

Error reporting during initialization

This section describes how error information is returned during the initialization of a Client Library application.

When an application call to either cs_ctx_alloc or cs_ctx_global returns CS_FAIL, extended error information is sent to standard error (STDERR) and to the file sybinit.err. The sybinit.err file is created in the current working directory.

When an application call to ct_init returns CS_FAIL due to a Net-Library(TM) error, extended error information is sent to standard error (STDERR) and to the file sybinit.err. The sybinit.err file is created in the current working directory.

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" .

The CS_EXTRA_INF property

The CS_EXTRA_INF property determines whether or not Client-Library returns certain kinds of informational messages.

An application that is retrieving messages into a SQLCA, SQLCODE, or SQLSTATE should set the Client-Library property CS_EXTRA_INF to CS_TRUE. This is because the SQL structures require information that Client-Library does not customarily return. If CS_EXTRA_INF is not set, you may lose information.

An application that is not using the SQL structures can also set CS_EXTRA_INF to CS_TRUE. In this case, the extra information is returned as standard Client-Library messages.

The additional information returned includes the number of rows affected by the most recent command.

Sequencing long messages

Message callback routines and ct_diag return Client-Library and server messages in CS_CLIENTMSG and CS_SERVERMSG structures. In the CS_CLIENTMSG structure, the message text is stored in the msgstring field. In the CS_SERVERMSG structure, the message text is stored in the text field. Both msgstring and text are CS_MAX_MSG bytes long.

If a message longer than CS_MAX_MSG, minus one bytes is generated, Client-Library's default behavior is to truncate the message. However, an application can use the CS_NO_TRUNCATE property to tell Client-Library to sequence long messages instead of truncating them.

When Client-Library is sequencing long messages, it uses as many CS_CLIENTMSG or CS_SERVERMSG structures as necessary to return the full text of a message. The message's first CS_MAX_MSG bytes are returned in one structure, its second CS_MAX_MSG bytes are returned in a second structure, and so forth.

Client-Library null-terminates only the last chunk of a message. If a message is exactly CS_MAX_MSG bytes long, the message is returned in two chunks: The first contains CS_MAX_MSG bytes of the message, and the second contains a null terminator.

If an application is using callback routines to handle messages, Client-Library calls the callback routine once for each message chunk.

If an application is using ct_diag to handle messages, it must call ct_diag once for each message chunk.

The SQLCA, SQLCODE, and SQLSTATE structures do not support sequenced messages. An application cannot use these structures to retrieve sequenced messages. Messages that are too long for these structures are truncated.

Operating system messages are reported via the osstring field of the CS_CLIENTMSG structure. Client-Library does not sequence operating system messages.

• The status field in the CS_CLIENTMSG and CS_SERVERMSG structures indicates whether the structure contains a whole message or a chunk of a message.

  The following status values are related to sequenced messages:

  Symbolic value	Meaning
  CS_FIRST_CHUNK	The message text is the first chunk of the message.
  CS_LAST_CHUNK	The message text is the last chunk of the message.

  • If CS_FIRST_CHUNK and CS_LAST_CHUNK are both on, then the message text in the structure is the entire message.

  • If neither CS_FIRST_CHUNK nor CS_LAST_CHUNK is on, then the message text in the structure is a middle chunk.

• The msgstringlen field in the CS_CLIENTMSG structure and the textlen field in the CS_SERVERMSG structure reflect the length of the current message chunk.

• All other fields in the CS_CLIENTMSG and CS_SERVERMSG are repeated with each message chunk.

If a sequenced server message has extended error data associated with it, an application can retrieve the extended error data while processing any single chunk of the sequenced message. Once the application has retrieved the extended error data, however, it is no longer available. For more information about extended error data, see "Extended error data".

If an application is using sequenced error messages, ct_diag acts on message chunks instead of messages. This has the following effects:

• A ct_diag(CS_GET, index) call returns the message chunk that has number index.

• A ct_diag(CS_MSGLIMIT) call limits the number of chunks, not the number of messages, that Client-Library will store.

• A ct_diag(CS_STATUS) call returns the number of currently stored chunks, not the number of currently stored messages.

Extended error data

Some server messages have extended error data associated with them. Extended error data is simply additional information about the error.

For Adaptive Server messages, the additional information is usually which column or columns provoked the error.

Client-Library makes extended error data available to an application in the form of a parameter result set, where each result item is a piece of extended error data. A piece of extended error data may be named and can be of any datatype.

An application can retrieve extended error data but is not required to do so.

Applications that allow end users to enter or edit data often need to report errors to their users at the column level. The standard server message mechanism, however, makes column-level information available only within the text of the server message. Extended error data provides a means for applications to conveniently access column-level information.

For example, imagine an application that allows end users to enter and edit data in the titleauthor table in the pubs2 database. titleauthor uses a key composed of two columns, au_id and title_id. Any attempt to enter a row with an au_id and title_id that match an existing row will cause a "duplicate key" message to be sent to the application.

On receiving this message, the application needs to identify the problem column or columns to the end user, so that the user can correct them. This information is not available in the duplicate key message, except in the message text. The information is available, however, as extended error data.

Not all server messages provide extended error data. When Client-Library returns standard server message information to an application in a CS_SERVERMSG structure, it sets the CS_HASEED bit of the status field of the CS_SERVERMSG structure if extended error data is available for the message.

Extended error data is returned to an application in the form of a parameter result set that is available on a special CS_COMMAND structure that Client-Library provides.

To retrieve extended error data, an application processes the parameter result set.

Within a server message callback routine, an application retrieves the CS_COMMAND with the extended error data by calling ct_con_props with property as CS_EED_CMD:

CS_RETCODE      ret;

 CS_COMMAND      *eed_cmd;

 CS_INT          outlen;

ret = ct_con_props(connection, CS_GET, CS_EED_CMD,

     &eed_cmd, CS_UNUSED, &outlen);

ct_con_props sets eed_cmd to point to the CS_COMMAND on which the extended error data is available.

Once it has the CS_COMMAND, the callback routine processes the extended error data as a normal parameter result set, calling ct_res_info, ct_describe, ct_bind, ct_fetch, and ct_get_data to describe, bind, and fetch the parameters. It is not necessary for the callback routine to call ct_results.

An application that is handling server messages inline retrieves the CS_COMMAND with the extended error data by calling ct_diag with operation as CS_EED_CMD:

CS_RETCODE      ret;

 CS_COMMAND      *eed_cmd;

 CS_INT          index;

ret = ct_diag (connection, CS_EED_CMD,

     CS_SERVERMSG_TYPE, index, &eed_cmd);

In this call, type must be CS_SERVERMSG_TYPE and index must be the index of the message for which extended error data is available. ct_diag sets eed_cmd to point to the CS_COMMAND on which the extended error data is available.

Once it has the CS_COMMAND, the application processes the extended error data as a normal parameter result set, calling ct_res_info, ct_describe, ct_bind, ct_fetch, and ct_get_data to describe, bind, and fetch the parameters. It is not necessary for the application to call ct_results.

Server transaction states

Server transaction state information is useful when an application needs to determine the outcome of a transaction.

The following table lists the symbolic values that represent transaction states:

In mainline code, an application retrieves a transaction state by calling ct_res_info with type as CS_TRANS_STATE:

CS_RETCODE      ret;

 CS_INT          outlen;

 CS_INT          trans_state;

ret = ct_res_info (cmd, CS_TRANS_STATE,

     &trans_state, CS_UNUSED, &outlen)

ct_res_info sets trans_state to one of the symbolic values listed in Table 2-21.

Transaction state information is available only for CS_COMMAND structures with pending results or an open cursor. That is, transaction state information is available if an application's last call to ct_results returned CS_SUCCEED.

Transaction state information is guaranteed to be correct only after ct_results sets *result_type to CS_CMD_DONE, CS_CMD_SUCCEED, or CS_CMD_FAIL.

An application retrieves transaction states inside a server message callback only if extended error data is available.

Within a server message callback, Client-Library indicates that extended error data is available by setting the CS_HASEED bit of the status field of the CS_SERVERMSG structure describing the message.

If extended error data is available, the application retrieves the current transaction state by:

1. Retrieving the CS_COMMAND with the extended error data by calling ct_con_props with property as CS_EED_CMD.

2. Calling ct_res_info with type as CS_TRANS_STATE. ct_res_info sets its *buffer parameter to one of the symbolic values listed in Table 2-21.