Retrieves parameter type, datatype, and length information about a specified RPC parameter.
%INCLUDE SYGWPLI;
01 TDPROC PTR, 01 RETCODE FIXED BIN(31), 01 PARM_ID FIXED BIN(31), 01 DATATYPE FIXED BIN(31), 01 ACTUAL_DATA_LENGTH FIXED BIN(31), 01 MAX_DATA_LENGT FIXED BIN(31), 01 PARM_STATU FIXED BIN(31), 01 PARM_NAME CHAR(30), 01 PARM_NAME_LENGTH FIXED BIN(31), 01 USER_DATATYP FIXED BIN(31);
CALL TDINFPRM (TDPROC, RETCODE, PARM_ID, DATATYPE,
ACTUAL_DATA_LENGTH, MAX_DATA_LENGTH,
PARM_STATUS, PARM_NAME,
PARM_NAME_LENGTH, 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-18.
(I) Number of the parameter with the information that is requested. Parameters are numbered sequentially; the first parameter is number 1.
(O) Variable where the Open Client datatype of the parameter is returned. The datatype is specified by the client.
(O) Variable where the actual length of the parameter data is returned. For TDSVARYCHAR, TDSVARYBIN, and TDSVARYGRAPHIC parameters, this value does not include the 2 bytes for the “LL” length specification.
(O) Variable where the maximum length allowed for the parameter’s data is returned. This value is specified by the client in the parameter definition. For TDSVARYCHAR, TDSVARYBIN, and TDSVARYGRAPHIC parameters, this value does not include the 2 bytes for the “LL” length specification.
(O) Variable where the parameter’s status is returned. This argument indicates whether or not the named parameter is a return parameter. It returns one of the following values, depending on the TDS version you are using:
TDS 4.6:
TDS_INPUT_VALUE (0) |
Parameter is not a return parameter. |
TDS_RETURN_VALUE (1) |
Parameter is a return parameter. |
TDS 5.0:
TDS_INPUT_VALUE_NULLABLE (32) |
Parameter is a nullable non-return parameter. |
TDS_RETURN_VALUE_NULLABLE (33) |
Parameter is a nullable return parameter. |
The client specifies the value of this argument.
(O) Variable where the name of the incoming parameter is stored. This is the name given to the parameter by the client.
(O) Variable where the length of the parameter name is returned. The name length is specified by the client when the RPC is sent.
(O) Variable where the user-assigned datatype for this parameter is stored. This argument is used for return parameters only.
The RETCODE argument can contain any of the return values listed in Table 3-18.
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_ENTRY_NOT_FOUND (-8) |
The specified column number, transaction number, or parameter does not exist. |
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_NO_PARM_PRESENT (103) |
No incoming parameters present. TDRCVPRM cannot retrieve a parameter because no more parameters were accepted. 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 TDINFPRM. 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);
/*------------------------------------------------------------------*/
GET_PARM_INFO: PROC;
/*------------------------------------------------------------------*/
CALL TDINFPRM (GWL_PROC, GWL_RC,
GWL_INFPRM_ID,
GWL_INFPRM_TYPE,
GWL_INFPRM_DATA_L,
GWL_INFPRM_MAX_DATA_L,
GWL_INFPRM_STATUS,
GWL_INFPRM_NAME,
GWL_INFPRM_NAME_L,
GWL_INFPRM_USER_DATA);
RETURN;
END GET_PARM_INFO;
A server application uses this function to retrieve type and length information about a parameter before it retrieves it. This can be any supported type of parameter including cursor parameters.
An application can request information about parameters in any order, by specifying the parameter in the PARM_ID argument.
The maximum number of parameters that can be retrieved is 255.
Unless you already know the length and datatype of the incoming parameter, you must issue a TDINFPRM call before each TDRCVPRM call. TDRCVPRM needs to know the appropriate datatype and length to properly set up for the incoming data.
An application uses TDINFPRM only when the client request is an RPC or a cursor command. Language requests do not have parameters.
A server program can modify the data length of a parameter by calling TDSETPRM before passing results back to the client.
Each parameter has an actual data length and a maximum data length. For standard fixed-length datatypes that do not allow nulls, both lengths are the same. For variable-length fields, the lengths may vary.
For example, a TDSVARYCHAR parameter with a declared length of 30 may have data that is only 10 bytes long. In this case, the parameter’s actual data length is 10 and its maximum data length is 30.
A value of TDSVOID in the DATATYPE argument indicates a NULL parameter (for example, an empty parameter).
Related functions
