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:

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.

NoteSee the Open Client and Open Server Configuration Guide for Microsoft Windows or the Open Client and Open Server Configuration Guide for UNIX, to view the Sybase localization file structure on your platform.

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

routine: layer: origin: description

where:

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-13 lists Client-Library message severities:

Table 2-13: 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:

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-14 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-14: 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 Microsoft Windows or Open Server Configuration Guide for UNIX, to view 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.