TDSETPRM

Description

Specifies the content and length of a return parameter before returning it to a remote client.

Syntax

% 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);

Parameters

TDPROC

(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.

RETCODE

(O) Variable where the result of function execution is returned. Its value is one of the codes listed in Table 3-32.

PARM_ID

(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.

HOST_VARIABLE_TYPE

(I) Datatype of the HOST_VARIABLE.

HOST_VARIABLE_LENGTH

(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).

HOST_VARIABLE

(I) Name of the host program variable that contains the return data.

USER_DATATYPE

(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.

Returns

The RETCODE argument can contain any of the return values listed in Table 3-32.

Examples

Example 1

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;

Usage

TDSETPRM

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.

Datatype conversions

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.

See also

Related functions

• TDINFPRM

• TDRCVPRM

• TDSNDDON

Copyright © 2005. Sybase Inc. All rights reserved.

View this book as PDF