ct_diag

Description

Manage inline error handling.

Syntax

CS_RETCODE ct_diag(connection, operation, type, index,
               buffer)

CS_CONNECTION    *connection;
CS_INT                      operation;
CS_INT                      type;
CS_INT                      index;
CS_VOID                   *buffer;

Parameters

connection: A pointer to a CS_CONNECTION structure. A CS_CONNECTION structure contains information about a particular client/server connection.

operation: The operation to perform. Table 3-20 lists the symbolic values for operation.

type

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:

**Table 3-19: Values for ct_diag type parameter**
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.

index

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.

buffer

A pointer to data space.

Depending on the value of operation, buffer can point to a structure or a CS_INT.

Returns

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

Usage

**Table 3-20: Summary of ct_diag parameters**
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.

Initializing inline error handling

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.

Clearing messages

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.

Retrieving messages

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:

Limiting messages

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.

Retrieving the number of messages

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.

Getting the CS_COMMAND for extended error data

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

Sequenced messages and ct_diag

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