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