Open Client Client-Library/C Reference Manual

Home

Open Client Client-Library/C Reference Manual

Chapter 2 Topics

Client-Library and SQL Structures

CS_SERVERMSG structure

A CS_SERVERMSG structure contains information about a server error or informational message.

Client-Library uses a CS_SERVERMSG structure in two ways:

For connections using the callback method to handle messages, a CS_SERVERMSG is the third parameter that Client-Library passes to the connection's server message callback.
For connections handling messages inline, ct_diag returns information in a CS_SERVERMSG.

For information on error and message handling, see "Error handling".

A CS_SERVERMSG structure is defined as follows:

/*

 ** CS_SERVERMSG

 ** The Client-Library server message structure.

*/

typedef struct _cs_servermsg

     CS_MSGNUM   msgnumber;

     CS_INT      state;

     CS_INT      severity;

     CS_CHAR     text[CS_MAX_MSG];

     CS_INT      textlen;

     CS_CHAR     svrname[CS_MAX_NAME];

     CS_INT      svrnlen;

/*

     ** If the error involved a stored procedure,

     ** the following fields contain information

     ** about the procedure:

*/

     CS_CHAR     proc[CS_MAX_NAME];

     CS_INT      proclen;

     CS_INT      line;

/*

     ** Other information.

*/

     CS_INT      status;

     CS_BYTE     sqlstate[CS_SQLSTATE_SIZE];

     CS_INT      sqlstatelen;

} CS_SERVERMSG;

where:

msgnumber is the server message number. For a list of Adaptive Server messages, execute the Transact-SQL command:
```
select * from sysmessages
```
state is the server error state.
severity is the severity of the message. For a list of Adaptive Server message severities, execute the Transact-SQL command:
```
select distinct severity from sysmessages
```
text is the text of the server message.
If an application is not sequencing messages, text is guaranteed to be null-terminated, even if it has been truncated.
If an application is sequencing messages, text is null-terminated only if it is the last chunk of a sequenced message.
For more information on sequenced messages, see "Sequencing long messages ".
textlen is the length, in bytes, of text. This is always the actual length, never the symbolic value CS_NULLTERM.
svrname is the name of the server that generated the message. This is the name of the server as it appears in the interfaces file. svrname is a null-terminated string.
svrnlen is the length, in bytes, of svrname.
proc is the name of the stored procedure that caused the message, if any. proc is a null-terminated string.
proclen is the length, in bytes, of proc.
line is the line number, if any, of the line that caused the message. line may be a line number in a stored procedure or a line number in a command batch.

status is a bitmask used to indicate various types of information, such as whether or not extended error data is included with the message. The following table lists the values that can be present in status:

CS_SERVERMSG status field values
Symbolic value	Meaning
CS_HASEED	Extended error data is included with the message. For more information on extended error data, see "Extended error data".
CS_FIRST_CHUNK	The message text contained in text is the first chunk of the message. If CS_FIRST_CHUNK and CS_LAST_CHUNK are both on, then text contains the entire message. If neither CS_FIRST_CHUNK nor CS_LAST_CHUNK is on, then text contains a middle chunk of the message. See "Sequencing long messages ".
CS_LAST_CHUNK	The message text contained in text is the last chunk of the message. If CS_FIRST_CHUNK and CS_LAST_CHUNK are both on, then text contains the entire message. If neither CS_FIRST_CHUNK nor CS_LAST_CHUNK is on, then text contains a middle chunk of the message. See "Sequencing long messages ".

sqlstate is a byte string describing the error.
Not all server 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.


	Expand Search