TDESCRIB

COPY SYGWCOB.

01 TDPROC                  PIC S9(9) USAGE COMP SYNC.
01 RETCODE                 PIC S9(9) USAGE COMP SYNC.
01 COLUMN-NUMBER           PIC S9(9) USAGE COMP SYNC.
01 HOST-VARIABLE-TYPE      PIC S9(9) USAGE COMP SYNC.
01 HOST-VARIABLE-MAXLEN    PIC S9(9) USAGE COMP SYNC.
01 HOST-VARIABLE-NAME      PIC X(n).
01 NULL-INDICATOR-VARIABLE PIC S9(4) USAGE COMP SYNC.
01 NULLS-ALLOWED           PIC S9(9) USAGE COMP SYNC.
01 COLUMN-TYPE             PIC S9(9) USAGE COMP SYNC.
01 COLUMN-MAXLEN           PIC S9(9) USAGE COMP SYNC.
01 COLUMN-NAME             PIC X(n).
01 COLUMN-NAME-LENGTH      PIC S9(9) USAGE COMP SYNC.

CALL 'TDESCRIB’ USING 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. 

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

COLUMN-NUMBER

(I) Number of the column that is being described. Columns are numbered sequentially. The first column in a row is number 1.

HOST-VARIABLE-TYPE

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

HOST-VARIABLE-MAXLEN

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

HOST-VARIABLE-NAME

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

NULL-INDICATOR-VARIABLE

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

NULLS-ALLOWED – (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.

COLUMN-TYPE

(I) Open Client datatype of the column. This is the datatype used by the client application.

COLUMN-MAXLEN

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

COLUMN-NAME

(I) Name of the column with the data that is being returned.

COLUMN-NAME-LENGTH

(I) Actual length of the column name.

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

The following code fragment illustrates a typical use of TDESCRIB. This example is taken from the sample program, SYCCSAR2, in Appendix B, “Sample RPC Application for CICS.”

*	 Here we let TDESCRIB convert from DB2 varchar (TDSVARYCHAR)
*	 to DBCHAR.

 
	 CALL 'SYGETAD' USING DB-DESCRIBE-HV-PTR, EMPLOYEE-ED.
	 CALL 'SYGETAD' USING DB-COLUMN-NAME-HV-PTR, CN-ED.
	 MOVE LENGTH OF EMPLOYEE-ED TO WRKLEN1.
	 MOVE LENGTH OF CN-ED       TO WRKLEN2.
      MOVE TDSINT2               TO DB-HOST-TYPE.
      MOVE TDSINT2               TO DB-CLIENT-TYPE.
      PERFORM DESCRIBE-COLUMN.

 *    Get the user defined datatype of EMPLOYEE-ED column.
 
      CALL 'TDINFUDT' USING GWL-PROC, GWL-RC, CTR-COLUMN,
                            GWL-INFUDT-USER-TYPE.
 
 *    Set the user defined datatype of EMPLOYEE-ED column.
 
      CALL 'TDSETUDT' USING GWL-PROC, GWL-RC, CTR-COLUMN,
                            GWL-INFUDT-USER-TYPE.
 *-----------------------------------------------------------------
  DESCRIBE-COLUMN.
 *-----------------------------------------------------------------
      SET ADDRESS OF LK-DESCRIBE-HV    TO DB-DESCRIBE-HV-PTR.
      SET ADDRESS OF LK-COLUMN-NAME-HV TO DB-COLUMN-NAME-HV-PTR.
      ADD 1                            TO CTR-COLUMN.
 
      CALL 'TDESCRIB' USING GWL-PROC, GWL-RC, CTR-COLUMN,
                            DB-HOST-TYPE, WRKLEN1, LK-DESCRIBE-HV,
                            DB-NULL-INDICATOR, TDS-FALSE,
                            DB-CLIENT-TYPE, WRKLEN1,
	 LK-COLUMN-NAME-HV, WRKLEN2.

Usage

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

• You must use a separate TDESCRIB call for each column in a row. Thus, if a row has 12 columns of data, you must call TDESCRIB 12 times, once for each column.

• Columns can be described in any order.

• The maximum number of columns that can be returned to a client is 255.

  Applications should check the return code after each TDESCRIB to see whether any data conversion errors occurred. This is especially important with applications that convert decimal or floating point data before returning it to the client.

• There can be only one TDESCRIB call for each column. If you try to describe the same column twice, the operation fails and returns TDS-DUPLICATE-ENTRY.

• After all the columns in a row are described, the server application calls TDSNDROW once for each row of data to be sent to the client.

  Each TDSNDROW call retrieves the data from every variable named in the HOST-VARIABLE-NAME arguments of the preceding TDESCRIB calls, and returns that data to the client in the associated columns. Do not call TDSNDROW until all columns in the row are associated with a variable, using TDESCRIB.

• An application can only call TDESCRIB before it sends rows to a client. Do not call TDESCRIB once your program starts to send rows.

• The length of columns with datatypes that have “VARY” in the name (TDSVARYCHAR, TDSVARYBIN, TDSVARYGRAPHIC) is derived from the 2-byte “LL” length specification in the named variable structure.

  TDSLONGVARCHAR columns do not have “LL” length specifications.

  Always specify a column length of 35 when describing Sybase numeric and decimal columns.

• TDESCRIB automatically converts some mainframe datatypes to Open Client datatypes before returning data to a Sybase client. TDESCRIB sets up the conversion and then performs the conversion when the row is sent to the client by TDSNDROW.

  TDESCRIB pads binary-type columns with zeros and character-type columns with blanks; no default padding is set for columns of other datatypes.

  You can perform additional datatype conversions (to text and image datatypes, for example) by calling TDCONVRT.

• TDS versions earlier than 4.2 do not support short float (TDSFLT4), short money (TDSMONEY4), or short datetime (TDSDATETIME4) datatypes. Gateway-Library automatically converts short float and money values to TDSFLT8 and TDSMONEY before returning data to a client using earlier versions of TDS. Gateway-Library does not convert short datetime datatypes.

  TDINFPGM returns the version of TDS in use.

Datatype conversions

Table 3-7 shows which conversions are performed automatically when TDESCRIB is called.

• Table 3-7: Datatype conversions performed by TDESCRIB

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

For Japanese users

• When converting Japanese characters, TDESCRIB changes the length of the column name to the length required by the client character set, which may be different from the length of the column name at the mainframe.

  To learn more, see the discussion of length considerations in “Processing Japanese client requests”.

See also

• TDCONVRT

• TDSNDROW

Related topics

• “Datatypes”

• “Processing Japanese client requests”

---

Copyright © 2007. Sybase Inc. All rights reserved.

View this document as PDF