CS_CLIENTMSG structure

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. Table 2-11 shows the legal values for severity:

**Table 2-11: CS_CLIENTMSG severity field values**
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.

See “Sequencing long messages”.
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:

**Table 2-12: CS_CLIENTMSG status field values**
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. See “Sequencing long messages”.
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. See “Sequencing long messages”.

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.