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_CHAR];

     CS_INT      svrnlen;

/*

     ** If the error involved a stored procedure,

     ** the following fields contain information

     ** about the procedure:

*/

     CS_CHAR     proc[CS_MAX_CHAR];

     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 Enterprise 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 Enterprise 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.

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. Table 2-18 lists the values that can be present in status:

**Table 2-18: CS_SERVERMSG status field values**
Symbolic value	Meaning
CS_HASEED	Extended error data is included with the message. 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.