Client-Library message numbers

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-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 and Open 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:

**Table 2-12: Client-Library message severities**
Severity	Explanation	User action
CS_SV_INFORM	No error has occurred. The message is informational.	No action is required.
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.	Raise an error so that the application’s end user can correct the problem.
CS_SV_RETRY_FAIL	An operation has failed, but the operation may be retried. An example of this type of operation is a network read that times out.	The return value from an application’s client message callback determines whether or not Client-Library retries the operation. If the client message callback returns CS_SUCCEED, Client-Library retries the operation. If the client message callback returns CS_FAIL, Client-Library does not retry the operation and marks the connection as dead. In this case, call ct_close(CS_FORCE_CLOSE) to close the connection and then reopen it by calling ct_connect.
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.	Call ct_cancel(CS_CANCEL_ALL) to clean up the connection. If ct_cancel(CS_CANCEL_ALL) returns CS_SUCCEED, the server connection is unharmed. It is illegal to perform this type of cancel from within a client message callback routine.
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.	Call ct_close(CS_FORCE_CLOSE) to close the server connection and then reopen it, if desired, by calling ct_connect. It is illegal to make these calls from within a client message callback routine.
CS_SV_COMM_FAIL	An unrecoverable error in the server communication channel has occurred. The server connection is not usable.	Call ct_close(CS_FORCE_CLOSE) to close the server connection and then re-open it, if desired, by calling ct_connect. It is illegal to make these calls from within a client message callback routine.
CS_SV_INTERNAL_FAIL	An internal Client-Library error has occurred.	Call ct_exit(CS_FORCE_EXIT) to exit Client-Library, and then exit the application. It is illegal to call ct_exit from within a client message callback routine.
CS_SV_FATAL	A serious error has occurred. All server connections are unusable.	Call ct_exit(CS_FORCE_EXIT) to exit Client-Library, and then exit the application. It is illegal to call ct_exit from within a client message callback routine.

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.

**Table 2-13: Client-Library errors**
Severity	Number	Origin	Layer	Cause
CS_SV_RETRY_FAIL	63	2	1	A read from the server timed out. See “Handling timeout errors”.
CS_SV_CONFIG_FAIL	8	3	5	The interfaces file (or platform equivalent) was not found. See “Location of the interfaces file”.
CS_SV_CONFIG_FAIL	3	3	5	The server name is not found in the interfaces file or the connection’s directory source.
CS_SV_COMM_FAIL	4	3	4	The connection attempt failed because a login dialog could not be established with the remote server. This error occurs when the remote server is down.
CS_SV_COMM_FAIL	131	3	5	ct_init failed because Net-Library drivers could not be initialized. The client message callback is not called for this error—Client-Library prints a message to the stderr device. The most likely cause of this error is a misconfigured [DRIVER] section in the libtcl.cfg file. See the Open Client and Open Server Configuration Guide for details on how Client-Library loads Net-Library drivers.
CS_SV_API_FAIL	132	4	1	The bind of a result item resulted in truncation while fetching the data. This error occurs when calling ct_fetch if a destination variable (bound with ct_bind) is too small for the data to be received. If column indicators are used, the application checks the indicator values to see which column(s) were truncated.