Manages inline error handling.
CS_RETCODE cs_diag(context, operation, type, index,
buffer)
CS_CONTEXT *context;
CS_INT operation;
CS_INT type;
CS_INT index;
CS_VOID *buffer;
A pointer to a CS_CONTEXT structure.
The operation to perform. Table 2-5 lists the legal symbolic values for operation.
Depending on the value of operation, type indicates either the type of structure to receive message information or the type of message on which to operate, or both.
Possible values are:
Value of type |
Indicates |
|---|---|
SQLCA_TYPE |
A SQLCA structure. |
SQLCODE_TYPE |
A SQLCODE structure, which is a long integer. |
SQLSTATE_TYPE |
A SQLSTATE structure, which is a 6-element character array. |
CS_CLIENTMSG_TYPE |
A CS_CLIENTMSG structure. Also used to indicate CS-Library 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.
A pointer to data space.
Depending on the value of operation, buffer can point to a structure or a CS_INT.
cs_diag returns:
Returns |
Indicates |
|---|---|
CS_SUCCEED |
The routine completed successfully. |
CS_FAIL |
The routine failed. |
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 were available. |
Common reasons for a cs_diag failure include:
Invalid context
Inability to allocate memory
Invalid parameter combination
Value of operation |
cs_diag |
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 |
CS_UNUSED |
A pointer to an integer value. |
CS_CLEAR |
Clears message information for this context. If buffer is not NULL, cs_diag also clears the *buffer structure by initializing it with blanks and/or NULLs, as appropriate. |
One of the legal type values. |
CS_UNUSED |
A pointer to a structure whose type is defined by type, or NULL. |
CS_GET |
Retrieves a specific message. |
One of the legal type values. |
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 |
CS_UNUSED |
A pointer to an integer value. |
An application that includes calls to CS-Library can handle CS-Library messages in one of two ways:
The application can call cs_config to install a CS-Library message callback, or
The application can handle CS-Library messages inline, using cs_diag.
An application can switch back and forth between the inline method and the callback method:
Installing a CS-Library message callback turns off inline message handling. Any saved messages are discarded.
Likewise, cs_diag(CS_INIT) “de-installs” an application’s CS-Library message callback. If the application has a message callback installed when cs_diag(CS_INIT) is called, the application’s first CS_GET call to cs_diag will retrieve a warning message to this effect.
If a CS-Library message callback is not installed and inline message handling is not enabled, CS-Library discards message information.
cs_diag manages inline message handling for a specific context. If an application has more than one context, it must make separate cs_diag calls for each context.
In a multithreaded application, cs_diag reports only those messages that pertain to CS-Library calls made by the thread which has called cs_diag. See the “Multithreaded Programming” topics page in the Open Client Client-Library/C Reference Manual.
cs_diag allows an application to retrieve message information into a CS_CLIENTMSG structure or a SQLCA, SQLCODE, or SQLSTATE structure. When retrieving messages, cs_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 structure must set the CS-Library context property CS_EXTRA_INF to CS_TRUE. This is because the SQL structures contain information that is not ordinarily returned by CS-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 CS-Library messages.
If cs_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, cs_diag starts saving messages again.
To initialize inline error handling, an application calls cs_diag with operation as CS_INIT.
Generally, if a context will use inline error handling, the application should call cs_diag to initialize inline error handling for the context immediately after allocating it.
To clear message information for a context, an application calls cs_diag with operation as CS_CLEAR.
cs_diag assumes that buffer points to a structure whose datatype corresponds to the value of type.
cs_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 cs_diag with operation as CS_CLEAR. Retrieving a message does not remove it from the message queue.
To retrieve message information, an application calls cs_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.
cs_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, cs_diag returns CS_NOMSG to indicate that no message is available.
See the “SQLCA Structure,” “SQLCODE Structures,” “SQLSTATE structure,” and “CS_CLIENTMSG Structure” topics pages in the Open Client Client-Library/C Reference Manual for information on these structures.
If an application runs on platforms with limited memory, you may want to limit the number of messages that CS-Library saves in that application.
To limit the number of saved messages, an application calls cs_diag with operation as CS_MSGLIMIT and type as CS_CLIENTMSG_TYPE.
When a message limit is reached, CS-Library discards any new messages.
An application cannot set a message limit that is less than the number of messages currently saved.
CS-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 cs_diag with operation as CS_STATUS and type as the CS_CLIENTMSG_TYPE.
ct_callback, ct_options
