A SERVERMSG (server message) structure contains information about an error or informational message returned by the server. This structure is defined within the application. CTBDIAG returns a message string and information about the message in this structure.
Client messages are returned to a CLIENTMSG structure, described in “CLIENTMSG structure”.
CLIENTMSG and SERVERMSG structures are part of the Mainframe ClientConnect (MCC) CTPUBLIC copybook.
This structure contains information about all messages received by the client application, including MCC messages, messages returned by the remote transactions, and messages returned by the database (such as DB2 Access Module messages and Adaptive Server messages).
A SERVERMSG structure is defined as follows:
DCL
01 SERVER-MSG,
05 SMSG_MSGNO FIXED BIN(31),
05 SMSG_STATE FIXED BIN(31),
05 SMSG_SEVERITY FIXED BIN(31),
05 SMSG_TEXT CHAR(256),
05 SMSG_TEXT_LEN FIXED BIN(31),
05 SMSG_SVRNAME CHAR(256),
05 SMSG_SVRNAME_LEN FIXED BIN(31),
05 SMSG_PROC CHAR(256),
05 SMSG_PROC_LEN FIXED BIN(31),
05 SMSG_LINE FIXED BIN(31),
05 SMSG_STATUS FIXED BIN(31);
SMSG_MSGNO is the server message number. This field corresponds to the MESSAGE_NUMBER argument of the Gateway-Library function TDSNDMSG.
SMSG_STATE is the message state. This field corresponds to the ERROR_STATE argument of the Gateway-Library function TDSNDMSG.
SMSG_SEVERITY is a symbolic value representing the severity of the message. Severity values are provided in the CTPUBLIC copybook. This field corresponds to the SEVERITY argument of the Gateway-Library function TDSNDMSG.
Table 2-9 lists the legal values for SMSG_SEVERITY.
SMSG_SEVERITY value |
Meaning |
|---|---|
CS_SV_INFORM (0) |
No error occurred. The message is informational. |
CS_SV_API_FAIL (1) |
A Client-Library routine generated an error. This error is typically caused by a bad parameter or calling sequence. The server connection is probably salvageable. |
CS_SV_RETRY_FAIL (2) |
An operation failed, but the operation can be retried. |
CS_SV_RESOURCE_FAIL (3) |
A resource error occurred. This error is typically caused by an allocation error, a lack of file descriptors, or timeout error. The server connection is probably not salvageable. |
CS_SV_CONFIG_FAIL (4) |
A configuration error occurred. |
CS_SV_COMM_FAIL (5) |
An unrecoverable error in the server communication channel occurred. The server connection is not salvageable. |
CS_SV_INTERNAL_FAIL (6) |
An internal Client-Library error occurred. |
CS_SV_FATAL (7) |
A serious error occurred. All server connections are unusable. |
SMSG_TEXT is the text of the message string. This field corresponds to the MESSAGE_TEXT argument of the Gateway-Library function TDSNDMSG.
SMSG_TEXT_LEN is the length, in bytes, of SMSG_TEXT. If there is no message text, the value of SMSG_TEXT_LEN is 0. This field corresponds to the MESSAGE_LENGTH argument of the Gateway-Library function TDSNDMSG.
SMSG_SVRNAME is the name of the server that generated the message. This is the server name from the Server Path Table.
The Server Path Table contains the information needed by Client-Library programs to route requests to a remote server, including the name of the server and connections to use to access that server. This table is part of the Connection Router, described in the Mainframe Connect Client Option Installation and Administration Guide.
SMSG_SVRNAME_LEN is the length, in bytes, of SMSG_SVRNAME.
SMSG_PROC is the name of the remote procedure or transaction that returned the message—the name of the Adaptive Server stored procedure or the transaction ID of the mainframe transaction. This field corresponds to the TRANSACTION_ID argument of the Gateway-Library function TDSNDMSG.
SMSG_MSGNO is the length, in bytes, of SMSG_PROC. This field corresponds to the TRANSACTION_ID_LENGTH argument of the Gateway-Library function TDSNDMSG.
SMSG_LINE is the line number in the called procedure or transaction where the error occurred. It may also be used for miscellaneous information. This field corresponds to the LINE_ID argument of the Gateway-Library function TDSNDMSG.
SMSG_STATUS is reserved for future use.
