Home

	Expand Search

Open Client Client-Library/C Reference Manual

Chapter 2 Topics

Client-Library and SQL Structures

CS_CLIENTMSG structure

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. The legal values for severity are:

  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:

  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.

Client-Library message numbers are represented by a CS_INT value that encodes four byte-size components.

Decoding a message number

Client-Library provides the following macros for decoding a message number so that each component is displayed separately:

• CS_LAYER - unpacks the layer number that identifies the Client-Library layer that generated the message.

• CS_ORIGIN - unpacks the message's origin, which indicates whether the error occurred internal or external to Client-Library.

• CS_SEVERITY - unpacks the severity of the message. See "Client-Library message severities" for a list of severity codes and their meanings.

• CS_NUMBER - unpacks the layer-specific message number that (together with severity, layer, and origin) identifies the message.

These macros are defined in the header file cstypes.h (which is included in ctpublic.h).

A typical application uses these macros to split a message number into four parts, which it then displays separately. For examples that demonstrates the use of these macros, see "Client message callback example" and "Handling timeout errors".

Client-Library and CS-Library use the message number components layer, origin, and number as keys for building a localized message string from text retrieved from the library's locales file. The localized message strings are then passed to the application as the msgstring field of the CS_CLIENTMSG structure.

See the Open Client/Server Configuration Guide for the Sybase localization file structure on your platform.

The error message text is composed from the components as follows:

routine: layer: origin: description

where:

• routine is the name of the library routine where the error occurred.

• layer is a layer description retrieved from either the [cslayer] section of cslib.loc (for CS-Library errors) or the [ctlayer] section of ctlib.loc (for Client-Library errors).

• origin is a phrase retrieved from either the [csorigin] section of cslib.loc (for CS-Library errors) or the [ctorigin] section of ctlib.loc (for Client-Library errors).

• description is an error description retrieved from the appropriate layer-specific section of the file.

The following is a U.S. English error string as it might be printed by a typical client message callback routine:

Client Library error(16843066):

 severity(1) number(58) origin(1) layer(1)

 ct_bind(): user api layer: external error: The format

field of the CS_DATAFMT structure must be CS_FMT_UNUSED

if the datatype field is int.

Client-Library message severities

Table 2-12 lists Client-Library message severities:

Handling specific Client-Library messages

Most Client-Library messages represent a coding error in the program, and the error description tells you the problem. These errors are best handled by either displaying the message or logging it to an application error file.

In other cases, the program may want to recognize the error and take specific action. For example:

• If a read from the server times out, then the program may decide to cancel the command that is being processed.

• For configuration errors, the program may want to recognize the specific problem and display an application-defined message that gives specific instructions to the application end user.

Errors are uniquely described by the four components of the error. A macro such as the ERROR_SNOL example below is useful for recognizing message numbers:

/*

 ** ERROR_SNOL(error_numb, severity, number, origin, layer)

 **

 **   Error comparison for Client-Library or CS-Library errors.

 **   Breaks down a message number and compares it to the given 

 **   constants for severity, number, origin, and layer. Returns

 **   non-zero if the error number matches the 4 components.

 */

 #define ERROR_SNOL (e, s, n, o, l) \

   ( (CS_SEVERITY(e) == s) && (CS_NUMBER(e) == n) \

    && (CS_ORIGIN(e) == o) && (CS_LAYER(e) == l ) )

Table 2-13 lists the error codes for some Client-Library messages. These errors are either recoverable, or they represent a configuration problem either on the client machine or the remote server machine.