A CS_CLIENTMSG structure contains information about a Client-Library error or informational message.
Client-Library uses a CS_CLIENTMSG structure in two ways:
For connections using the callback method to handle messages, a CS_CLIENTMSG is the third parameter that Client-Library passes to an application’s client message callback routine.
For connections handling messages inline, ct_diag returns information in a CS_CLIENTMSG.
For information on how to handle Client-Library error handling and server message handling, see “Error handling”.
A CS_CLIENTMSG structure is defined as follows:
/*
** CS_CLIENTMSG
** The Client-Library client message structure.
*/
typedef struct _cs_clientmsg
{
CS_INT severity;
CS_MSGNUM msgnumber;
CS_CHAR msgstring[CS_MAX_MSG];
CS_INT msgstringlen;
/*
** If the error involved the operating
** system, the following fields contain
** operating-system-specific information:
*/
CS_INT osnumber;
CS_CHAR osstring[CS_MAX_MSG];
CS_INT osstringlen;
/*
** Other information:
*/
CS_INT status;
CS_BYTE sqlstate[CS_SQLSTATE_SIZE];
CS_INT sqlstatelen;
} CS_CLIENTMSG;
where:
severity is a symbolic value representing the severity of the message. The legal values for severity are:
Severity |
Explanation |
---|---|
CS_SV_INFORM |
No error has occurred. The message is informational. |
CS_SV_CONFIG_FAIL |
A Sybase configuration error has been detected. Configuration errors include missing localization files, a missing interfaces file, and an unknown server name in the interfaces file. |
CS_SV_RETRY_FAIL |
An operation has failed, but can be retried. An example of this type of operation is a network read that times out. |
CS_SV_API_FAIL |
A Client-Library routine generated an error. This error is typically caused by a bad parameter or calling sequence. The server connection is probably usable. |
CS_SV_RESOURCE_FAIL |
A resource error has occurred. This error is typically caused by a malloc failure or lack of file descriptors. The server connection is probably not usable. |
CS_SV_COMM_FAIL |
An unrecoverable error in the server. The server connection is not usable. |
CS_SV_INTERNAL_FAIL |
An internal Client-Library error has occurred. |
CS_SV_FATAL |
A serious error has occurred. All server connections are unusable. |
msgnumber is the Client-Library message number. See “Client-Library message numbers”.
msgstring is the null-terminated Client-Library message string.
If an application is not sequencing messages, msgstring is guaranteed to be null-terminated, even if it has been truncated.
If an application is sequencing messages, msgstring is null-terminated only if it is the last chunk of a sequenced message.
msgstringlen is the length, in bytes, of msgstring. This is always the actual length, never the symbolic value CS_NULLTERM.
osnumber is the operating system error number, if any. Client-Library sets osnumber to 0 if no operating system error has occurred.
osstring is the null-terminated operating system error string, if any.
osstringlen is the length of osstring. This is always the actual length, never the symbolic value CS_NULLTERM.
status is a bitmask that indicates various types of information, such as whether or not this is the first, a middle, or the last chunk of an error message. The values that can be present in status include:
Symbolic value |
Meaning |
---|---|
CS_FIRST_CHUNK |
The message text contained in msgstring is the first chunk of the message. If CS_FIRST_CHUNK and CS_LAST_CHUNK are both on, then msgstring contains the entire message. If neither CS_FIRST_CHUNK nor CS_LAST_CHUNK is on, then msgstring contains a middle chunk of the message. |
CS_LAST_CHUNK |
The message text contained in msgstring is the last chunk of the message. If CS_FIRST_CHUNK and CS_LAST_CHUNK are both on, then msgstring contains the entire message. If neither CS_FIRST_CHUNK nor CS_LAST_CHUNK is on, then msgstring contains a middle chunk of the message. |
sqlstate is a byte string describing the error.
Not all client messages have SQL state values associated with them. If no SQL state value is associated with a message, sqlstate has the value “ZZZZZ”.
sqlstatelen is the length, in bytes, of the sqlstate string.