Manage inline error handling.
CS_RETCODE ct_diag(connection, operation, type, index,
buffer)
CS_CONNECTION *connection; CS_INT operation; CS_INT type; CS_INT index; CS_VOID *buffer;
A pointer to a CS_CONNECTION structure. A CS_CONNECTION structure contains information about a particular client/server connection.
The operation to perform. Table 3-20 lists the symbolic values for operation.
Depending on the value of operation, type indicates either the type of structure to receive message information, the type of message on which to operate, or both. Table 3-19 lists the symbolic values for type:
Value of type |
Meaning |
|---|---|
SQLCA_TYPE |
A SQLCA structure. |
SQLCODE_TYPE |
A SQLCODE structure, which is a long integer. |
SQLSTATE_TYPE |
A SQLSTATE structure, which is a six-element character array. |
CS_CLIENTMSG_TYPE |
A CS_CLIENTMSG structure. Also used to indicate Client-Library messages. |
CS_SERVERMSG_TYPE |
A CS_SERVERMSG structure. Also used to indicate server messages. |
CS_ALLMSG_TYPE |
Client-Library and server messages. |
The index of the message of interest. The first message has an index of 1, the second an index of 2, and so forth.
If type is CS_CLIENTMSG_TYPE, then index refers to Client-Library messages only. If type is CS_SERVERMSG_TYPE, then index refers to server messages only. If type is CS_ALLMSG_TYPE, then index refers to Client-Library and server messages combined.
A pointer to data space.
Depending on the value of operation, buffer can point to a structure or a CS_INT.
ct_diag returns the following values:
Return value |
Meaning |
|---|---|
CS_SUCCEED |
The routine completed successfully. |
CS_FAIL |
The routine failed. ct_diag returns CS_FAIL if the original error has made the connection unusable. |
CS_NOMSG |
The application attempted to retrieve a message whose index is higher than the highest valid index. For example, the application attempted to retrieve message number 3, but only 2 messages are queued. |
CS_BUSY |
An asynchronous operation is already pending for this connection. For more information, see “Asynchronous programming”. |
Common reasons for a ct_diag failure include:
Invalid connection
Inability to allocate memory
Invalid parameter combination
Value of operation |
Resulting action |
Type is |
Index is |
Buffer is |
|---|---|---|---|---|
CS_INIT |
Initializes inline error handling. |
CS_UNUSED |
CS_UNUSED |
NULL |
CS_MSGLIMIT |
Sets the maximum number of messages to store. |
CS_CLIENTMSG_TYPE to limit Client-Library messages only. CS_SERVERMSG_TYPE to limit server messages only. CS_ALLMSG_TYPE to limit the total number of Client-Library and server messages combined. |
CS_UNUSED |
A pointer to an integer value. |
CS_CLEAR |
Clears message information for this connection. If buffer is not NULL and type is not CS_ALLMSG_TYPE, ct_diag also clears the *buffer structure by initializing it with blanks and/or NULLs, as appropriate. |
Any valid type value. If type is CS_CLIENTMSG_TYPE, ct_diag clears Client-Library messages only. If type is CS_SERVERMSG_TYPE, ct_diag clears server messages only. If type has any other valid value, ct_diag clears both Client-Library and server messages. |
CS_UNUSED |
A pointer to a structure whose type is defined by type, or NULL. |
CS_GET |
Retrieves a specific message. |
Any valid type value except CS_ALLMSG_TYPE. If type is CS_CLIENTMSG_TYPE, a Client-Library message is retrieved into a CS_CLIENTMSG structure. If type is CS_SERVERMSG_TYPE, a server message is retrieved into a CS_SERVERMSG structure. If type has any other valid value, then either a Client-Library or server message is retrieved. |
The one-based index of the message to retrieve. |
A pointer to a structure whose type is defined by type. |
CS_STATUS |
Returns the current number of stored messages. |
CS_CLIENTMSG_TYPE to retrieve the number of Client-Library messages. CS_SERVERMSG_TYPE to retrieve the number of server messages. CS_ALLMSG_TYPE to retrieve the total number of Client-Library and server messages combined. |
CS_UNUSED |
A pointer to an integer variable. |
CS_EED_CMD |
Sets *buffer to the address of the CS_COMMAND structure containing extended error data. |
CS_SERVERMSG_TYPE |
The one-based index of the message for which extended error data is available. |
A pointer to a pointer variable. |
A Client-Library application can handle Client-Library and server messages in two ways:
The application can call ct_callback to install client message and server message callbacks to handle Client-Library and server messages.
The application can handle Client-Library and server messages inline, using ct_diag.
An application can switch back and forth between the two methods. For information about how to do this, see “Error handling”.
ct_diag manages inline message handling for a specific connection. If an application has more than one connection, it must make separate ct_diag calls for each connection.
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 can perform operations on either Client-Library messages, server messages, or both.
For example, an application can clear Client-Library messages without affecting server messages by using:
ct_diag(connection, CS_CLEAR, CS_CLIENTMSG,
CS_UNUSED, NULL);
ct_diag allows an application to retrieve message information into standard Client-Library structures (CS_CLIENTMSG and CS_SERVERMSG) or a SQLCA, SQLCODE, or SQLSTATE. When retrieving messages, ct_diag assumes that buffer points to a structure of the type indicated by type.
An application that is retrieving messages into a SQLCA, SQLCODE, or SQLSTATE must set the Client-Library property CS_EXTRA_INF to CS_TRUE. This is because the SQL structures require information that is not ordinarily returned by Client-Library’s error handling mechanism.
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.
If ct_diag does not have sufficient internal storage space in which to save a new message, it throws away all unread messages and stops saving messages. The next time it is called with operation as CS_GET, it returns a special message to indicate the space problem. After returning this message, ct_diag starts saving messages again.
To initialize inline error handling, an application calls ct_diag with operation as CS_INIT.
Generally, if a connection will use inline error handling, the application should call ct_diag to initialize inline error handling for a connection immediately after allocating it.
To clear message information for a connection, an application calls ct_diag with operation as CS_CLEAR.
To clear Client-Library messages only, an application passes type as CS_CLIENTMSG_TYPE.
To clear server messages only, an application passes type as CS_SERVERMSG.
To clear both Client-Library and server messages, pass type as SQLCA_TYPE, SQLCODE_TYPE, SQLSTATE_TYPE, or CS_ALLMSG_TYPE.
If type is not CS_ALLMSG_TYPE:
ct_diag assumes that buffer points to a structure whose type corresponds the value of type.
ct_diag clears the *buffer structure by setting it to blanks and/or NULLs, as appropriate.
Message information is not cleared until an application explicitly calls ct_diag with operation as CS_CLEAR. Retrieving a message does not remove it from the message queue.
To retrieve message information, an application calls ct_diag with operation as CS_GET, type as the type of structure in which to retrieve the message, index as the one-based index of the message of interest, and *buffer as a structure of the appropriate type.
If type is CS_CLIENTMSG_TYPE, then index refers only to Client-Library messages. If type is CS_SERVERMSG_TYPE, index refers only to server messages. If type has any other value, index refers to the collective “queue” of both types of messages combined.
ct_diag fills in the *buffer structure with the message information.
If an application attempts to retrieve a message whose index is higher than the highest valid index, ct_diag returns CS_NOMSG to indicate that no message is available.
For information about these structure, see:
Applications running on platforms with limited memory may want to limit the number of messages that Client-Library saves.
An application can limit the number of saved Client-Library messages, the number of saved server messages, and the total number of saved messages.
To limit the number of saved messages, an application calls ct_diag with operation as CS_MSGLIMIT and type as CS_CLIENTMSG_TYPE, CS_SERVERMSG_TYPE, or CS_ALLMSG_TYPE:
If type is CS_CLIENTMSG_TYPE, then the number of Client-Library messages is limited.
If type is CS_SERVERMSG_TYPE, then the number of server messages is limited.
If type is CS_ALLMSG_TYPE, then the total number of Client-Library and server messages combined is limited.
When a specific message limit is reached, Client-Library discards any new messages of that type. When a combined message limit is reached, Client-Library discards any new messages. If Client-Library discards messages, it saves a message to this effect.
An application cannot set a message limit that is less than the number of messages currently saved.
Client-Library’s default behavior is to save an unlimited number of messages. An application can restore this default behavior by setting a message limit of CS_NO_LIMIT.
To retrieve the number of current messages, an application calls ct_diag with operation as CS_STATUS and type as the type of message of interest.
To retrieve a pointer to the CS_COMMAND structure containing extended error data (if any), call ct_diag with operation as CS_EED_CMD and type as CS_SERVERMSG_TYPE. ct_diag sets *buffer to the address of the CS_COMMAND structure containing the extended error data.
When an application retrieves a server message into a CS_SERVERMSG structure, Client-Library indicates that extended error data is available for the message by setting the CS_HASEED bit in the status field in the CS_SERVERMSG structure.
It is an error to call ct_diag with operation as CS_EED_CMD when extended error data is not 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 with number index.
A ct_diag(CS_MSGLIMIT) call limits the number of chunks, not the number of messages, that Client-Library stores.
A ct_diag(CS_STATUS) call returns the number of currently stored chunks, not the number of currently stored messages.
For more information about sequenced messages, see “Sequencing long messages”.
“Error handling” “CS_CLIENTMSG structure”, “CS_SERVERMSG structure”, “SQLCA structure”, “SQLCODE structure”, “SQLSTATE structure”, ct_callback, ct_options
