Converts the data in a variable from a mainframe datatype to a datatype that can be used by an Open Client program.
TDCONVRT converts single-byte character
sets. Do not use it with double-byte character sets.
COPY SYGWCOB.
01 TDPROC PIC S9(9) USAGE COMP SYNC.
01 RETCODE PIC S9(9) USAGE COMP SYNC.
01 NUM-DECIMAL-PLACES PIC S9(9) USAGE COMP SYNC.
01 SOURCE-TYPE PIC S9(9) USAGE COMP SYNC.
01 SOURCE-LENGTH PIC S9(9) USAGE COMP SYNC.
01 SOURCE-VARIABLE PIC X(n).
01 RESULT-TYPE PIC S9(9) USAGE COMP SYNC.
01 RESULT-LENGTH PIC S9(9) USAGE COMP SYNC.
01 RESULT-VARIABLE PIC X(n).
01 OUTLEN PIC S9(9) USAGE COMP SYNC.
(optional)
CALL 'TDCONVRT' USING 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 and 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. The length must be greater than zero. |
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 shows two methods of converting datatypes. One method uses TDESCRIB to convert data from the DB2 datatype DECIMAL (TDSDECIMAL) to TDSFLT8. The other method uses TDCONVRT to convert data from the DB2 datatype DECIMAL (TDSDECIMAL) to the DB-Library datatype DBMONEY (TDSMONEY).
This example is taken from the sample program, SYCCSAR2, in Appendix B, “Sample RPC Application for CICS” which runs under CICS.
* Here we let TDESCRIB convert from TDSDECIMAL to TDSFLT8.
CALL 'SYGETAD' USING DB-DESCRIBE-HV-PTR, EMPLOYEE-JC. CALL 'SYGETAD' USING DB-COLUMN-NAME-HV-PTR, CN-JC. MOVE LENGTH OF EMPLOYEE-JC TO WRKLEN1. MOVE LENGTH OF CN-JC TO WRKLEN2.
MOVE TDSDECIMAL TO DB-HOST-TYPE. MOVE TDSFLT8 TO DB-CLIENT-TYPE. PERFORM DESCRIBE-COLUMN.
* We must inform the Server Library how many decimal places
* are in the EMPLOYEE-JC column.
CALL 'TDSETBCD' USING GWL-PROC, GWL-RC, TDS-OBJECT-COL,
CTR-COLUMN, TDS-DEFAULT-LENGTH,
GWL-SETBCD-SCALE.
* Demonstrate getting decimal column information.
A server application uses this function to convert from a mainframe datatype to a datatype that can be used by an Open Client 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.
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 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 zeros. |
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. PadsTDSCHAR fields with blanks. |
TDSLONGVARBIN |
TDSIMAGE |
|
TDSNUMERIC TDSNUMERIC |
TDSCHAR TDSPACKED-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 S9(10) v9(5). |
TDS-PACKED-DECIMAL TDS-PACKED-DECIMAL TDS-PACKED-DECIMAL TDS-PACKED-DECIMAL TDS-PACKED-DECIMAL TDS-PACKED-DECIMAL TDS-PACKED-DECIMAL |
TDS-CHAR 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 TDSPACKED-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:
Option 1: 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.
Option 2: 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.
Option 3: 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 long 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
Related documents
Open Client DB-Library Reference Manual
