Converts the data in a variable from a mainframe datatype to a datatype that can be used by an Open Client program.
TDCONVRT converts SBCS. Do not use
it with DBCS.
%INCLUDE SYGWPLI;
01 TDPROC PTR, 01 RETCODE FIXED BIN(31), 01 NUM_DECIMAL_PLACES FIXED BIN(31), 01 SOURCE_TYPE FIXED BIN(31), 01 SOURCE_LENGTH FIXED BIN(31), 01 SOURCE_VARIABLE CHAR(n), 01 RESULT_TYPE FIXED BIN(31), 01 RESULT_LENGTH FIXED BIN(31), 01 RESULT_VARIABLE CHAR(n), 01 OUTLEN BIN(31);
CALL TDCONVRT (TDPROC, RETCODE, NUM_DECIMAL_PLACES, SOURCE_TYPE, SOURCE_LENGTH, SOURCE_VARIABLE, RESULT_TYPE, RESULT_LENGTH, RESULT_VARIABLE, OUTLEN);
(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-3.
(I) Number of digits after the decimal point (scale) in the SOURCE_VARIABLE. This value must not be a negative number. When converting packed decimal to or from numeric or Sybase-decimal, or when converting packed decimal, numeric, or Sybase decimal to or from character format, TDCONVRT uses this information to ensure that the decimal point is correctly placed. For all other datatypes, it ignores this argument.
(I) Datatype of the SOURCE_VARIABLE.
(I) Actual length of the SOURCE_VARIABLE. This value must not be a negative number. For TDSVARYCHAR or TDSVARYBIN this value does not include two bytes for "LL" specifications. For Sybase numeric or decimal, it is actual length not a maximum length (35).
(I) Host program variable that contains the data to be converted. This is the variable described in the previous two arguments.
(I) DB-Library or Client-Library datatype of the RESULT_VARIABLE.
(I) Actual length of the RESULT_VARIABLE. This value must be greater than zero and must not be a negative number. For fixed-length datatypes, this argument is ignored. Always use 35 as a result length for numeric and Sybase decimal data.
(O) Variable that contains the converted data. This is the variable described in the previous two arguments.
(O) Optional, returns actual length for numeric or Sybase decimal result.
The RETCODE argument can contain any of the return values listed in Table 3-3.
Return value |
Meaning |
|---|---|
TDS_OK (0) |
Function completed successfully. |
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_FLOAT_CONVERSION_ERROR (-21) |
Error in conversion of float values. |
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 RESULT_LENGTH argument is too short. |
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. |
The following code fragment uses TDCONVRT to convert data from the DB2 datatypes to DB-Library datatypes. 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;
A server application uses this function to convert from a mainframe datatype to a datatype that can be used by a DB-Library or Client-Library client. See “Datatypes” for more information about particular datatypes and datatype conversions. For details about DB-Library datatypes, see the Open Client DB-Library Reference Manual. For details about Client-Library datatypes, see the Open Client Client-Library Reference Manual.
Most Gateway-Library-to-Client-Library datatype conversions
can be done more efficiently with TDESCRIB and TDSETPRM,
which perform automatic data conversions. For more information,
see TDESCRIB and TDSETPRM.
This function converts a single variable each time it executes.
If several columns in a single result row will be converted, an application must issue a separate TDCONVRT call for each column that will be converted before it sends the row to a client. If several rows of data are sent to the client, the application must issue a separate TDCONVRT call for every column that needs conversion in each row, before it issues a TDSNDROW call for that row.
If TDESCRIB follows TDCONVRT, be sure that the TDESCRIB HOST_VARIABLE_NAME argument corresponds to the TDCONVRT RESULT_VARIABLE rather than the SOURCE_VARIABLE.
Table 3-4 lists the conversions you can perform with TDCONVRT.
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 if precision=scale for leading zero. 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 if precision=scale for leading zero. |
WARNING! The results of decimal-to-character type conversions are no longer formatted in SQL Processor Using File Input (SPUFI) style. See “Converting packed decimal to character data” for an explanation of how the results now handle leading and trailing zeroes.
For VARCHAR strings:
Treat VARCHAR strings as TDSVARYCHAR. You can safely convert these strings to DB-library VARYCHAR or CHAR.
For 255-byte LONG VARCHAR strings:
Treat these strings as TDSVARYCHAR. TDSVARYCHAR strings can be up to 255 bytes in length. You can safely convert these strings to DB-library VARYCHAR or CHAR.
For longer LONG VARCHAR strings (256 or more bytes):
Treat these strings as TDSLONGVARCHAR. When converting long varchar data to a client datatype, you have three options:
If the client program supports TEXT datatypes, you can convert the string to TDSTEXT before sending it to the client. TDSTEXT is a variable-length datatype containing up to 2,147,483,647 bytes.
If the client is an Open Client 10.0 program, you can send the data as TDSLONGVARCHAR. The Client-Library datatype CS_LONGCHAR has a maximum length of 2,147,483,647 bytes.
If the truncation option is set during customization, you can send the string as TDSVARYCHAR. If you choose this option, the data is truncated. However, if the truncation option is not set, and you try to convert these strings to TDSVARYCHAR, an error is returned.
For binary strings:
If the client program supports IMAGE datatypes, you can convert the string to TDSIMAGE before sending it to the client. TDSIMAGE is a variable-length datatype containing up to 2,147,483,647 bytes.
If the client is a Client-Library 10.0 program, you can send the data as TDSLONGVARBIN. The Client-Library datatype CS_LONGBINARY has a maximum length of 2,147,483,647 bytes.
Related functions
Related topics
