Specifies the content and length of a return parameter before returning it to a remote client.
% INCLUDE SYGWPLI;
01 TDPROC PTR, 01 RETCODE FIXED BIN(31), 01 PARM_ID FIXED BIN(31), 01 HOST_VARIABLE_TYPE FIXED BIN(31), 01 HOST_VARIABLE_LENGTH FIXED BIN(31), 01 HOST_VARIABLE CHAR(n), 01 USER_DATATYPE FIXED BIN(31);
CALL TDSETPRM (TDPROC, RETCODE, PARM_ID, HOST_VARIABLE_TYPE, HOST_VARIABLE_LENGTH, HOST_VARIABLE, USER_DATATYPE);
(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-32.
(I) Number of the parameter to be returned. This must be the same parameter ID specified in the TDRCVPRM call that retrieved this parameter. Parameters are numbered sequentially in the order received, from 1 to 255.
(I) Datatype of the HOST_VARIABLE.
(I) Length of the HOST_VARIABLE.
If HOST_VARIABLE_TYPE is TDSVARYCHAR, TDSVARYBIN, or TDSVARYGRAPHIC, this length does not include the 2 bytes for the “LL” length specification. For graphic datatypes, this is the number of double-byte characters; for other datatypes, it is the number of bytes (actual length).
(I) Name of the host program variable that contains the return data.
(I) The client-specified datatype of the parameter, if any. If no user datatype is specified, code 0 for this field. Currently, this argument is ignored.
The RETCODE argument can contain any of the return values listed in Table 3-32.
Return value |
Meaning |
|---|---|
TDS_OK (0) |
Function completed successfully. |
TDS_CONNECTION_TERMINATED (-4997) |
Connection closed. The remote partner closed (deallocated) the client/server connection. |
TDS_DATE_CONVERSION_ERROR (-23) |
Error in conversion of datetime data. This can be a result of trying to convert short datetime (TDSDATETIME4) for a client using an early TDS version. TDS versions earlier than 4.2 do not support the short datetime datatype. |
TDS_DECIMAL_CONVERSION_ERROR (-24) |
Error in conversion of packed decimal data. |
TDS_ENTRY_NOT_FOUND (-8) |
The specified column number, transaction number, or parameter does not exist. |
TDS_FLOAT_CONVERSION_ERROR (-21) |
Error in conversion of float values. |
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_CONVERSION (-172) |
Incompatible datatypes. The source datatype cannot be converted into the requested result datatype. |
TDS_INVALID_LENGTH (-173) |
Wrong length. The length specified in the HOST_VARIABLE_LENGTH argument is too long. |
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_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_MONEY_CONVERSION_ERROR (-22) |
Error in conversion of TDSMONEY-type data. This can be a result of trying to convert to short money (TDSMONEY4) for a client using an early TDS version. TDS versions earlier than 4.2 do not support the short money datatype. |
TDS_TRUNCATION_ERROR (-20) |
Error occurred in truncation of data value. |
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 TDSETPRM. This example is taken from the sample program in Appendix B, “Sample RPC Application for CICS.”
/*------------------------------------------------------------------*/
GET_PARMS:
/*------------------------------------------------------------------*/
/* ------------------------------------------------------------*/
/* get return parameter information */
/* ------------------------------------------------------------*/
GWL_INFPRM_ID = 1;
CALL GET_PARM_INFO;
(IF GWL_INFPRM_STATUS ^= TDS_RETURN_VALUE AND
IF GWL_INFPRM_STATUS ^= TDS_RETURN_VALUE_NULLABLE) THEN
DO;
CALL TDINFPRM_NOT_RETURN_PARM_ERROR;
GO TO END_PROGRAM;
END;
GWL_SETPRM_USER_DATA = GWL_INFPRM_USER_DATA;
GWL_SETPRM_ID = GWL_INFPRM_ID;
GWL_SETPRM_DATA_L = GWL_INFPRM_DATA_L;
GWL_SETPRM_TYPE = GWL_INFPRM_TYPE;
/* ------------------------------------------------------------*/
/* get department id parameter number from known name */
/* ------------------------------------------------------------*/
GWL_INFPRM_NAME = '@parm2';
GWL_INFPRM_NAME_L = 6;
CALL TDLOCPRM (GWL_PROC,
GWL_INFPRM_ID,
GWL_INFPRM_NAME,
GWL_INFPRM_NAME_L);
/* ------------------------------------------------------------*/
/* get department parameter information */
/* ------------------------------------------------------------*/
CALL GET_PARM_INFO;
IF GWL_INFPRM_TYPE ^= TDSVARYCHAR THEN
DO;
CALL TDINFPRM_NOT_CHAR_PARM_ERROR;
GO TO END_PROGRAM;
END;
/* ------------------------------------------------------------*/
/* get department parameter data */
/* ------------------------------------------------------------*/
CALL TDRCVPRM (GWL_PROC, GWL_RC,
GWL_INFPRM_ID,
PARM_DEPT,
GWL_INFPRM_TYPE,
GWL_INFPRM_MAX_DATA_L,
GWL_RCVPRM_DATA_L);
/*------------------------------------------------------------------*/
END_OF_QUERY:
/*------------------------------------------------------------------*/
/* ------------------------------------------------------------*/
/* close cursor */
/* ------------------------------------------------------------*/
EXEC SQL CLOSE ECURSOR;
/* ------------------------------------------------------------*/
/* update return parameter with nr of rows fetched */
/* ------------------------------------------------------------*/
CALL TDSETPRM (GWL_PROC, GWL_RC,
GWL_SETPRM_ID,
GWL_SETPRM_TYPE,
GWL_SETPRM_DATA_L,
PARM_RETURN_ROWS,
GWL_SETPRM_USER_DATA);
GO TO END_PROGRAM;
A server application uses this function to tell TDSNDDON where to find the data for a return parameter, as well as the data length and datatype.
TDSETPRM sets the return value for a parameter but does not actually send it to the client. All return parameters, whether their return values were changed by TDSETPRM or not, are sent to the client when TDSNDDON is called.
TDSETPRM is the only way to change the content or the length of a return parameter. When you call TDSNDDON, any return parameters with values that were not changed by a TDSETPRM call contain the same data they contained when received from the client.
A return parameter must be identified as such in the PARM_STATUS argument of TDINFPRM. If you try to change the return value for a parameter that was not invoked as a return parameter, an error occurs.
A valid return parameter has the PARM_STATUS field set to TDS_RETURN_VALUE (X'01') or TDS_RETURN_VALUE_NULLABLE(X'33') and a parameter ID of 1 or greater. Any other PARM_STATUS and a PARM_ID of 0 indicate that the parameter is not a return parameter.
A server program may specify its own datatype for a parameter. To specify the datatype for the return value, assign it to the USER_DATATYPE argument.
If the variable datatype is TDSVARYCHAR, TDSVARYBIN, or TDSVARYGRAPHIC, the length does not include the 2 bytes for the “LL” specification. The length specified in “LL” is ignored unless a -1 is coded as the length argument, in which case the length specified in the “LL” is used.
When converting from char or packed decimal datatype to the client numeric or Sybase decimal datatype, use TDSETBCD before TDSETPRM to set precision and scale of the client datatype.
When sending data to a client, TDSETPRM converts many datatypes from the Gateway-Library (source) datatype to the client (result) datatype. Table 3-33 shows what conversions are possible.
Source datatype: Gateway-Library |
Result datatype: Open Client |
Notes |
|---|---|---|
TDSCHAR TDSCHAR TDSVARYCHAR TDSVARYCHAR TDSLONGVARCHAR TDSLONGVARCHAR TDSMONEY TDSMONEY |
TDSVARYCHAR TDSLONGVARCHAR TDSCHAR TDSLONGVARCHAR TDSCHAR TDSVARYCHAR TDSCHAR TDSVARYCHAR |
Does EBCDIC to ASCII conversion. For Japanese characters, converts to workstation datatype. Pads TDSCHAR fields with blanks. |
TDSFLT8 TDSFLT8 TDSFLT8 TDSFLT4 TDSFLT4 TDSFLT4 |
TDSFLT4 TDSMONEY TDSMONEY4 TDSFLT8 TDSMONEY TDSMONEY4 |
Truncates low order digits. |
TDSCHAR TDSVARYCHAR |
TDSMONEY TDSMONEY |
|
TDS_PACKED_DECIMAL TDS_PACKED_DECIMAL TDS_PACKED_DECIMAL TDS_PACKED_DECIMAL |
TDSCHAR TDSVARYCHAR TDSFLT8 TDSMONEY |
When converting packed decimal to character values, change the length to allow for unpacking, leading or trailing zeros, the sign and the decimal point. |
TDSGRAPHIC TDSGRAPHIC TDSVARYGRAPHIC TDSVARYGRAPHIC |
TDSCHAR TDSVARYCHAR TDSCHAR TDSVARYCHAR |
Used with Japanese double-byte character sets. Pads TDSCHAR fields with blanks. |
TDSDATETIME TDSDATETIME4 |
TDSCHAR TDSCHAR |
|
TDSCHAR TDSCHAR |
TDSNUMERIC TDS_SYBASE_DECIMAL |
Use TDSETBCD to set Sybase numeric and decimal precision and scale before TDSETPRM. |
TDS_PACKED_DECIMAL TDS_PACKED_DECIMAL |
TDSNUMERIC TDS_SYBASE_DECIMAL |
Use TDSETBCD to set Sybase numeric and decimal precision and scale before TDSETPRM. |
Related functions
