Describes a column in a result row and the mainframe server program variable where it is stored.
%INCLUDE SYGWPLI;
01 TDPROC PTR, 01 RETCODE FIXED BIN(31), 01 COLUMN_NUMBER FIXED BIN(31), 01 HOST_VARIABLE_TYPE FIXED BIN(31), 01 HOST_VARIABLE_MAXLEN FIXED BIN(31), 01 HOST_VARIABLE_NAME CHAR(n), 01 NULL_INDICATOR_VARIABLE FIXED BIN(15) INIT(0), 01 NULLS_ALLOWED FIXED BIN(31), 01 COLUMN_TYPE FIXED BIN(31), 01 COLUMN_MAXLEN FIXED BIN(31), 01 COLUMN_NAME CHAR(n), 01 COLUMN_NAME_LENGTH FIXED BIN(31);
CALL TDESCRIB (TDPROC, RETCODE, COLUMN_NUMBER, HOST_VARIABLE_TYPE,
HOST_VARIABLE_MAXLEN,
HOST_VARIABLE_NAME,
NULL_INDICATOR_VARIABLE, NULLS_ALLOWED,
COLUMN_TYPE, COLUMN_MAXLEN,
COLUMN_NAME, COLUMN_NAME_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-6.
(I) Number of the column that is being described. Columns are numbered sequentially. The first column in a row is number 1.
(I) Datatype of HOST_VARIABLE_NAME, the host program variable where the data for this column is stored. If you use TDCONVRT to convert from one datatype to another, this is the RESULT_TYPE.
(I) Maximum length of the host program variable. This is the value of (n) in the definition statement for HOST_VARIABLE_NAME.
For TDSVARYCHAR, TDSVARYBIN, and TDSVARYGRAPHIC variables, 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 actual length.
(I) Host program variable that contains the data for this column.
You must name a different variable for each column to be described.
If you use TDCONVRT to convert from one datatype to another, this is the RESULT_VARIABLE. If the datatype is TDSVARYCHAR, TDSVARYBIN, or TDSVARYGRAPHIC, this is the name of a structure that includes the “LL” length specification.
(I) Host program variable that contains the NULL indicator for this column. When the value in this variable is negative, TDSNDROW sends a NULL value for this column. Note that this variable is a halfword.
If NULLS_ALLOWED is TDS_FALSE, this argument is ignored.
(I) Null permission indicator. Indicates whether NULLs are allowed for this column. Assign this argument one of the following values:
TDS_TRUE (1) |
NULLs are allowed. |
TDS_FALSE (0) |
NULLs are not allowed. |
NULLs are typically used with DB2.
(I) Open Client datatype of the column. This is the datatype used by the client application.
(I) Maximum length of the column data. For variable-length datatypes, this argument represents the maximum length for a value of that datatype. For fixed-length datatypes (TDSINTn, TDSFLTn), this argument is ignored.
See “Comments” in this section for cautions about converting packed decimal datatypes and Japanese double-byte characters.
(I) Name of the column with the data that is being returned.
(I) Actual length of the column name.
The RETCODE argument can contain any of the return values listed in Table 3-6.
Return value |
Meaning |
|---|---|
TDS_OK (0) |
Function completed successfully. |
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_DUPLICATE_ENTRY (-9) |
Duplicate column description. You attempted to describe the same column twice with a TDESCRIB statement. The operation failed. |
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_DATA_TYPE (-171) |
Illegal datatype. A sybase datatype supplied in the call is not supported and the conversion can not be completed. |
TDS_INVALID_ID_VALUE (-10) |
The specified column or parameter number is greater than the system maximum. Sybase allows as many columns per table result and parameters per RPC as the system maximum. |
TDS_INVALID_LENGTH (-173) |
Wrong length. The length specified in the COLUMN_MAXLEN argument is too short. |
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_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 TDESCRIB to describe a column in a return row. This example is taken from the sample program in Appendix B, “Sample RPC Application for CICS.”
/*------------------------------------------------------------------*/
SETUP_REPLY_COLUMNS:
/*------------------------------------------------------------------*/
DB_DESCRIBE_HV_PTR = ADDR(EMPLOYEE_FNM);
DB_COLUMN_NAME_HV_PTR = ADDR(CN_FNM);
WRKLEN1 = STG(EMPLOYEE_FNM)-2;
WRKLEN2 = STG(CN_FNM);
DB_HOST_TYPE = TDSVARYCHAR;
DB_CLIENT_TYPE = TDSVARYCHAR;
CALL DESCRIBE_COLUMN;
/* ------------------------------------------------------------*/
/* Here we let TDESCRIB convert from DB2 varchar (TDSVARYCHAR) */
/* to DBCHAR. */
/* ------------------------------------------------------------*/
DB_DESCRIBE_HV_PTR = ADDR(EMPLOYEE_LNM);
DB_COLUMN_NAME_HV_PTR = ADDR(CN_LNM);
WRKLEN1 = STG(EMPLOYEE_LNM)-2;
WRKLEN2 = STG(CN_LNM);
DB_HOST_TYPE = TDSVARYCHAR;
DB_CLIENT_TYPE = TDSCHAR;
CALL DESCRIBE_COLUMN;
DB_DESCRIBE_HV_PTR = ADDR(EMPLOYEE_ED);
DB_COLUMN_NAME_HV_PTR = ADDR(CN_ED);
WRKLEN1 = STG(EMPLOYEE_ED);
WRKLEN2 = STG(CN_ED);
DB_HOST_TYPE = TDSINT2;
DB_CLIENT_TYPE = TDSINT2;
CALL DESCRIBE_COLUMN;
/* ------------------------------------------------------------*/
/* Get the user defined datatype of EMPLOYEE_ED column. */
/* ------------------------------------------------------------*/
CALL TDINFUDT (GWL_PROC, GWL_RC,
CTR_COLUMN,
GWL_INFUDT_USER_TYPE);
/* ------------------------------------------------------------*/
/* Set the user defined datatype of EMPLOYEE_ED column. */
/* ------------------------------------------------------------*/
CALL TDSETUDT (GWL_PROC, GWL_RC,
CTR_COLUMN,
GWL_INFUDT_USER_TYPE);
/* ------------------------------------------------------------*/
/* Here we let TDESCRIB convert from TDSDECIMAL to TDSFLT8. */
/* ------------------------------------------------------------*/
DB_DESCRIBE_HV_PTR = ADDR(EMPLOYEE_JC);
DB_COLUMN_NAME_HV_PTR = ADDR(CN_JC);
WRKLEN1 = STG(EMPLOYEE_JC);
WRKLEN2 = STG(CN_JC);
DB_HOST_TYPE = TDSDECIMAL;
DB_CLIENT_TYPE = TDSFLT8;
CALL DESCRIBE_COLUMN;
/* ------------------------------------------------------------*/
/* We must inform the Server Library how many decimal places */
/* are in the EMPLOYEE_JC column. */
/* ------------------------------------------------------------*/
CALL TDSETBCD (GWL_PROC, GWL_RC,
TDS_OBJECT_COL,
CTR_COLUMN,
TDS_DEFAULT_LENGTH,
GWL_SETBCD_SCALE);
/* ------------------------------------------------------------*/
/* Demonstrate getting decimal column information. */
/* ------------------------------------------------------------*/
CALL TDINFBCD (GWL_PROC, GWL_RC,
TDS_OBJECT_COL,
CTR_COLUMN,
GWL_INFBCD_LENGTH,
GWL_INFBCD_SCALE);
/* ------------------------------------------------------------*/
/* Here we intend to use TDCONVRT to convert from TDSDECIMAL to*/
/* TDSMONEY, so we point TDESCRIB to the output of TDCONVRT, */
/* rather than the original input. */
/* ------------------------------------------------------------*/
DB_DESCRIBE_HV_PTR = ADDR(WRK_EMPLOYEE_SAL);
DB_COLUMN_NAME_HV_PTR = ADDR(CN_SAL);
WRKLEN1 = STG(WRK_EMPLOYEE_SAL);
WRKLEN2 = STG(CN_SAL);
DB_HOST_TYPE = TDSMONEY;
DB_CLIENT_TYPE = TDSMONEY;
CALL DESCRIBE_COLUMN;
/*------------------------------------------------------------------*/
SEND_ROWS:
/*------------------------------------------------------------------*/
DO WHILE(^ ALL_DONE);
CALL FETCH_AND_SEND_ROWS;
END;
/*------------------------------------------------------------------*/
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;
/*------------------------------------------------------------------*/
FETCH_AND_SEND_ROWS: PROC;
/*------------------------------------------------------------------*/
EXEC SQL FETCH ECURSOR INTO :EMPLOYEE_FIELDS;
IF SQLCODE = 0 THEN
DO;
/* --------------------------------------------------------*/
/* Convert from DB2 decimal (TDSDECIMAL) to dblib MONEY. */
/* --------------------------------------------------------*/
WRKLEN1 = STG(EMPLOYEE_SAL);
WRKLEN2 = STG(WRK_EMPLOYEE_SAL);
CALL TDCONVRT (GWL_PROC, GWL_RC,
GWL_CONVRT_SCALE,
TDSDECIMAL,
WRKLEN1,
EMPLOYEE_SAL,
TDSMONEY,
WRKLEN2,
WRK_EMPLOYEE_SAL);
/* --------------------------------------------------------*/
/* Do not send trailing blanks of EMPLOYEE_LNM */
/* --------------------------------------------------------*/
WRKLEN1 = LENGTH(EMPLOYEE_LNM);
CTR_COLUMN = 2;
WRK_BLANKS_SS = 1;
LOOP: DO WHILE(WRK_BLANKS_SS <= WRKLEN1);
IF SUBSTR(EMPLOYEE_LNM, WRK_BLANKS_SS, 1) = ' ' THEN DO;
LEAVE LOOP;
END;
WRK_BLANKS_SS = WRK_BLANKS_SS + 1;
END LOOP;
IF (WRK_BLANKS_SS <= WRKLEN1) THEN DO;
CALL TDSETLEN (GWL_PROC, GWL_RC,
CTR_COLUMN,
WRK_BLANKS_SS - 1);
END;
/*--------------------------------------------------------------*/
/* send a row to the client */
/*--------------------------------------------------------------*/
CALL TDSNDROW (GWL_PROC, GWL_RC);
PARM_RETURN_ROWS = PARM_RETURN_ROWS + 1;
IF GWL_RC = TDS_CANCEL_RECEIVED THEN
DO;
ALL_DONE = ALL_DONE_YES;
END;
END;
ELSE IF SQLCODE = +100 THEN
DO;
ALL_DONE = ALL_DONE_YES;
END;
ELSE IF SQLCODE < 0 THEN
DO;
ALL_DONE = ALL_DONE_YES;
CALL FETCH_ERROR;
END;
RETURN;
END FETCH_AND_SEND_ROWS;
/*------------------------------------------------------------------*/
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;
/*------------------------------------------------------------------*/
DESCRIBE_COLUMN: PROC;
/*------------------------------------------------------------------*/
CTR_COLUMN = CTR_COLUMN +1;
CALL TDESCRIB (GWL_PROC, GWL_RC,
CTR_COLUMN,
DB_HOST_TYPE,
WRKLEN1,
DB_DESCRIBE_HV,
DB_NULL_INDICATOR,
TDS_FALSE,
DB_CLIENT_TYPE,
WRKLEN1,
DB_COLUMN_NAME_HV,
WRKLEN2);
RETURN;
END DESCRIBE_COLUMN;
A server application uses this function to describe a column that is returned to the client and the host program variable where the column data is stored. A server application uses this function to describe a column that is returned to the client and the host program variable where the column data is stored.
A server application uses this function to describe a column that is returned to the client and the host program variable where the column data is stored.
Table 3-7 shows which conversions are performed automatically when TDESCRIB is called.
Source datatype |
Result datatype |
Notes |
|---|---|---|
TDSCHAR TDSCHAR TDSCHAR TDSCHAR TDSCHAR TDSCHAR TDSVARYCHAR TDSVARYCHAR TDSVARYCHAR TDSLONGVARCHAR TDSLONGVARCHAR TDSLONGVARCHAR |
TDSVARYCHAR TDSLONGVARCHAR TDSMONEY TDSNUMERIC TDS_SYBASE_DECIMAL TDS_PACKED_DECIMAL TDSCHAR TDSLONGVARCHAR TDSMONEY TDSCHAR TDSTEXT TDSVARYCHAR |
Performs EBCDIC and ASCII conversion. Pads TDSCHAR fields with blanks. When converting TDSCHAR to Sybase numeric and decimal, specify 35 as destination length. OUTLEN shows the actual length. |
TDSDATETIME TDSDATETIME4 |
TDSCHAR TDSCHAR |
|
TDSFLT4 TDSFLT4 TDSFLT4 |
TDSFLT8 TDSMONEY TDSMONEY4 |
Pads with zeroes. |
TDSFLT8 TDSFLT8 TDSFLT8 |
TDSFLT4 TDSMONEY TDSMONEY4 |
Truncates low order digits. |
TDSGRAPHIC TDSGRAPHIC TDSVARYGRAPHIC TDSVARYGRAPHIC |
TDSCHAR TDSVARYCHAR TDSCHAR TDSVARYCHAR |
Used with Japanese double-byte character sets. Pads TDSCHAR fields with blanks. |
TDSLONGVARBIN |
TDSIMAGE |
|
TDSNUMERIC TDSNUMERIC |
TDSCHAR TDS_PACKED_DECIMAL |
When converting Sybase numeric and decimal to char, specify destination length as precision + 2, or precision +3 when precision=scale. When converting from numeric to TDS_PACKED_DECIMAL the destination should supply the same precision and scale as the source. For numeric (15,5) specify destination as FIXED DEC (15,5). |
TDS_PACKED_DECIMAL TDS_PACKED_DECIMAL TDS_PACKED_DECIMAL TDS_PACKED_DECIMAL TDS_PACKED_DECIMAL TDS_PACKED_DECIMAL TDS_PACKED_DECIMAL |
TDSCHAR TDSVARYCHAR TDSMONEY TDSNUMERIC TDSFLT4 TDSFLT8 TDS_SYBASE_DECIMAL |
When converting packed decimal to character values, change the length to allow for unpacking, leading or trailing zeros, the sign and the decimal point. When converting TDS_PACKED_DECIMAL to Sybase numeric and decimal, specify 35 as the destination length. OUTLEN shows the actual length of the numeric field. |
TDS_SYBASE_DECIMAL TDS_SYBASE_DECIMAL |
TDSCHAR TDS_PACKED_DECIMAL |
When converting Sybase numeric and decimal to char, specify destination length as precision + 2, or precision +3 when precision=scale (for leading zero). |
When converting packed decimal data, the COLUMN_MAXLEN must allow for:
Unpacking
Leading and trailing zeros
Sign and decimal point
A suggested formula for unpacking is:
Result Length = (2 * Source Length) - 1.
Always use TDSETBCD when describing Sybase decimal and numeric columns. Assign the following:
Precision to BCD_LENGTH
Scale to BCD_NUMBER_DECIMAL_PLACES
See “Datatypes” for more information about datatypes supported by Gateway-Library.
The Japanese Conversion Module (JCM) automatically converts column names from the character set used at the mainframe server to that specified by the client in the login packet.
When converting Japanese characters, TDESCRIB changes the length of the column name to the length required by the client character set, which can be different from the length of the column name at the mainframe.
For example, the length of a hankaku katakana character is 1 in the mainframe character set, IBM-Kanji, and 2 in the workstation character set, eucjis.
To learn more, see the discussion of length considerations in “Processing Japanese client requests”.
Related functions
Related topics
