Sends an error or informational message to the client.
% INCLUDE SYGWPLI;
01 TDPROC PTR, 01 RETCODE FIXED BIN(31), 01 MESSAGE_TYPE FIXED BIN(31), 01 MESSAGE_NUMBER FIXED BIN(31), 01 SEVERITY FIXED BIN(31), 01 ERROR_STATE FIXED BIN(31), 01 LINE_ID FIXED BIN(31), 01 TRANSACTION_ID CHAR(n), 01 TRANSACTION_ID_LENGTH FIXED BIN(31), 01 MESSAGE_TEXT CHAR(n), 01 MESSAGE_LENGTH FIXED BIN(31);
CALL TDSNDMSG (TDPROC,RETCODE, MESSAGE_TYPE, MESSAGE_NUMBER, SEVERITY, ERROR_STATE, LINE_ID, TRANSACTION_ID, TRANSACTION_ID_LENGTH, MESSAGE_TEXT, MESSAGE_LENGTH);
(I) Handle for this client/server connection. This must be the same value specified in the associated TDACCEPT call. The TDPROC handle corresponds to the connection and command handles in Open Client Client-Library.
(O) Variable where the result of function execution is returned. Its value is one of the codes listed in Table 3-40.
(I) Category of message being sent. Indicates whether it is an informational message or an error message. Assign this argument one of the following values:
TDS_INFO_MSG (1) |
Message is an informational message. |
TDS_ERROR_MSG (2) |
Message is an error message. |
(I) Message number. This value is always four bytes in length. Where possible, use Sybase-compatible error numbers.
For messages sent to Open Client programs, this value is stored in the SMSG_NO field of the Open Client CS_SERVERMSG structure.
(I) Severity level of the error. A value of 10 or less represents an informational message.
For messages sent to Open Client clients, this value is stored in the SMSG_SEV field of the Open Client CS_SERVERMSG structure.
Specify one of the following severity values:
TDS_INFO_SEV (0) |
Informational message |
TDS_ERROR_SEV (10) |
Error message |
(I) Error state number. This number provides additional information about the context of the error.
For messages sent to Open Client clients, this value is stored in the SMSG_STATE field of the Open Client CS_SERVERMSG structure.
(I) An additional identifier assigned by the program. You determine how to use this argument at your site.
For messages sent to Open Client clients, this value is stored in the SMSG_LINE field of the Open Client CS_SERVERMSG structure.
(I) Identifier of the transaction that is currently executing. The transaction ID identifies the transaction that is issuing the error message.
Under CICS: This is the TRANSID from the CICS Program Control Table (PCT).
Under IMS TM: This is the transaction name defined when the system is generated.
Under MVS: This is the APPC transaction name defined in the transaction profile.
(I) Length of the TRANSACTION_ID. For graphic datatypes, this is the number of double-byte characters; for other datatypes, it is the number of bytes.
Under CICS: For CICS Version 1.7, this value is always 4 or less. For later versions, it is the actual length of the transaction ID, which can be greater than 4.
Under IMS TM: This value is always 8 or less.
Under MVS: This is the APPC transaction name defined in the transaction profile. This value is normally 8 or less.
(I) The text of the message.
For messages sent to Open Client clients, this value is stored in the SMSG_TEXT field of the Open Client CS_SERVERMSG structure.
(I) Length of the message text. The maximum permitted length for a message is 512 bytes.
If you are using the Japanese Conversion Module (JCM), it adjusts this length to the length used by the client character set.
For messages sent to Open Client clients, this value is stored in the SMSG_TEXT_LEN field of the Open Client CS_SERVERMSG structure.
The RETCODE argument can contain any of the return values listed in Table 3-40.
Return value |
Meaning |
|---|---|
TDS_OK (0) |
Function completed successfully. |
TDS_CANCEL_RECEIVED (-12) |
Operation canceled. The remote partner issued a cancel. The current operation failed. |
TDS_CONNECTION_FAILED (-4998) |
Connection abended. The client/server connection abnormally ended (for example, the LU 6.2 session crashed or the remote transaction abended). |
TDS_CONNECTION_TERMINATED (-4997) |
Connection closed. The remote partner closed (deallocated) the client/server connection. |
TDS_ILLEGAL_REQUEST (-5) |
Illegal function. The operation failed. This code can indicate that a client application is trying to use a Gateway-Library function that is not supported for clients (for example, TDSNDROW). |
TDS_INVALID_DATA_TYPE (-171) |
Illegal datatype. A Sybase datatype supplied in the call is not supported and the conversion cannot be done. The operation failed. |
TDS_INVALID_LENGTH (-173) |
Wrong length. The length specified in the MESSAGE_LENGTH argument is too long. |
TDS_INVALID_NAMELENGTH (-179) |
Invalid name length. The length specified for the column, parameter, message, or server name is invalid. |
TDS_INVALID_PARAMETER (-4) |
Invalid parameter value. The value assigned to one or more of the arguments supplied in the call is not valid. The operation failed. |
TDS_INVALID_STATUS (-174) |
Invalid status value. The value entered in the STATUS field is invalid. |
TDS_INVALID_TDPROC (-18) |
Error in specifying a value for the TDPROC argument. |
TDS_INVALID_VAR_ADDRESS (-175) |
Specified variable address is invalid. No variable with the specified name exists. A NULL value was specified. The operation failed. |
TDS_WRONG_STATE (-6) |
This function cannot be used in the current communication state. For example, your program tried to send a reply before it read in all of the client parameters. The application was still in RECEIVE state and could not send. The operation failed. |
The following code fragment illustrates a typical use of TDSNDMSG. This example is taken from the sample program in Appendix B, “Sample RPC Application for CICS.”
/*------------------------------------------------------------------*/
SEND_ERROR_MESSAGE: PROC;
/*------------------------------------------------------------------*/
SEND_DONE = SEND_DONE_ERROR;
MSG_SEVERITY = MSG_SEVERITY_ERROR;
MSG_NR = MSG_NR_ERROR;
MSG_TYPE = TDS_ERROR_MSG;
CALL SEND_MESSAGE;
RETURN;
END SEND_ERROR_MESSAGE;
/*------------------------------------------------------------------*/
SEND_MESSAGE: PROC;
/*------------------------------------------------------------------*/
/* ------------------------------------------------------------*/
/* ensure we're in right state to send a message */
/* ------------------------------------------------------------*/
CALL TDSTATUS (GWL_PROC, GWL_RC,
GWL_STATUS_NR,
GWL_STATUS_DONE,
GWL_STATUS_COUNT,
GWL_STATUS_COMM,
GWL_STATUS_RETURN_CODE,
GWL_STATUS_SUBCODE);
IF GWL_RC = TDS_OK THEN
DO;
IF GWL_STATUS_COMM = TDS_RECEIVE THEN
CALL TDSNDMSG (GWL_PROC, GWL_RC,
MSG_TYPE, MSG_NR,
MSG_SEVERITY,
TDS_ZERO,
TDS_ZERO,
MSG_RPC, MSG_RPC_L,
MSG_TEXT, MSG_TEXT_L);
END;
RETURN;
END SEND_MESSAGE;
A server application uses this function to send an error or informational message to a remote client.
IMS TM Users: The term “message” is
used here in the narrow sense of error or informational messages
sent to the client; it is not used in the IMS TM sense of message
processing.
Errors related to the operation of the TRS are recorded in its error log, available to the TRS administrator. Errors related to the client program are passed on to the requesting client. A client handles an Open ServerConnect error message like any error returned by Adaptive Server.
Messages can be sent before a row is described or after all rows are sent. An application can call TDSNDMSG either before a TDESCRIB or after the last TDSNDROW call for the described row. No messages can be sent between a TDESCRIB and a TDSNDROW or between two TDSNDROW calls.
Your application must be in SEND state for this function to execute successfully. If it is not in SEND state, TDSNDMSG returns TDS_WRONG_STATE. Call TDRESULT to put your application in SEND state.
A transaction can send a message to a client after TDSNDDON only if the value of the TDSNDDON argument STATUS is TDS_DONE_CONTINUE, and the value of CONN_OPTIONS is TDS_FLUSH. If the value of CONN_OPTIONS is TDS_ENDRPC or TDS_ENDREPLY, no messages can be sent after the TDSNDDON call is issued.
For more information about errors and error severity levels, see Mainframe Connect Client Option and Server Option Messages and Codes.
If the Japanese Conversion Module (JCM) is used, TDSNDMSG converts the message data from the mainframe character set to the workstation character set and adjusts the message length before sending, if necessary.
Related documents
Open Client DB-Library Reference Manual (dbmsghandle)
Mainframe Connect Client Option and Server Option Messages and Codes
Mainframe Connect DirectConnect for z/OS Option User's Guide for Transaction Router Services
