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 the section “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 (for example, DB2 Access Module messages and Adaptive Server messages).
A SERVERMSG structure is defined as follows:
01 SERVER-MSG 05 SMSG-MSGNO PIC S9(9) COMP SYNC. 05 SMSG-STATE PIC S9(9) COMP SYNC. 05 SMSG-SEVERITY PIC S9(9) COMP SYNC. 05 SMSG-TEXT PIC X(256). 05 SMSG-TEXT-LEN PIC S9(9) COMP SYNC. 05 SMSG-SVRNAME PIC X(256). 05 SMSG-SVRNAME-LEN PIC S9(9) COMP SYNC. 05 SMSG-PROC PIC X(256). 05 SMSG-PROC-LEN PIC S9(9) COMP SYNC. 05 SMSG-LINE PIC S9(9) COMP SYNC. 05 SMSG-STATUS PIC S9(9) COMP SYNC.
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-PROC-LEN 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.
