Chapter 3: Functions

TDSQLLEN

Description

Determines the length of a language string received from a client.

Syntax

COPY SYGWCOB.

01 TDPROC     PIC S9(9)  USAGE COMP SYNC.
01 SQL-LENGTH PIC S9(9)  USAGE COMP SYNC.

CALL 'TDSQLLEN' USING TDPROC, SQL-LENGTH.

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.

SQL-LENGTH: (O) The length of the incoming language string. For graphic datatypes, this is the number of double-byte characters; for other datatypes, it is the number of bytes.

Returns

This function has no RETCODE argument. It returns the length of the SQL string in the SQL-LENGTH argument. If the value in SQL-LENGTH is -1, call TDRESULT, and examine its return code to determine what the problem is.

Examples

Example 1

The following code fragment illustrates the use of TDSQLLEN and TDRCVSQL to receive a language request from the client. This example is taken from the sample program in Appendix C, “Sample Language Application for CICS.”

 	*    Establish gateway environment
 
            CALL 'TDINIT' USING DFHEIBLK, GWL-RC, GWL-INIT-HANDLE.
 
       *    Turn on local tracing if not on globally or locally
 
            CALL 'TDINFLOG' USING GWL-INIT-HANDLE, GWL-RC,
                                  GWL-INFLOG-GLOBAL,
                                  GWL-INFLOG-API,
                                  GWL-INFLOG-TDS-HEADER,
                                  GWL-INFLOG-TDS-DATA,
                                  GWL-INFLOG-TRACE-ID,
                                  GWL-INFLOG-FILENAME,
                                  GWL-INFLOG-TOTAL-RECS.
 
            IF  GWL-INFLOG-GLOBAL NOT = TDS-TRACE-ALL-RPCS
            AND GWL-INFLOG-GLOBAL NOT = TDS-TRACE-SPECIFIC-RPCS THEN
                MOVE 1 TO TRACING-SET-SW
                PERFORM LOCAL-TRACING
            END-IF.
 
       *    Accept client request
 
            CALL 'TDACCEPT' USING GWL-PROC, GWL-RC, GWL-INIT-HANDLE,
                                  SNA-CONNECTION-NAME,
                                  SNA-SUBC.
 
       *    Ensure kicked off via language request
       *    (this could be handled more reasonably by TDRESULT)
 
            CALL 'TDINFPGM' USING GWL-PROC, GWL-RC,
                                  GWL-INFPGM-TDS-VERSION,
                                  GWL-INFPGM-LONGVAR,
                                  GWL-INFPGM-ROW-LIMIT,
                                  GWL-INFPGM-REMOTE-TRACE,
                                  GWL-INFPGM-CORRELATOR,
                                  GWL-INFPGM-DB2GW-OPTION,
                                  GWL-INFPGM-DB2GW-PID,
                                  GWL-INFPGM-TYPE-RPC.
            IF GWL-INFPGM-TYPE-RPC NOT = TDS-START-SQL
                MOVE MSG-NOT-LANG           TO MSG-TEXT
                MOVE LENGTH OF MSG-NOT-LANG TO MSG-TEXT-L
                PERFORM SEND-ERROR-MESSAGE
                GO TO END-PROGRAM
            END-IF.
 
       *    Prepare for receive
 
            CALL 'TDRESULT' USING GWL-PROC, GWL-RC.
 
       *    Get lenth of language text, ensure not too big for us
       *    (this could be handled without TDSQLLEN by checking
       *    LANG-ACTUAL-LEN doesn't exceed LANG-MAX-L in TDRCVSQL call)
 
            CALL 'TDSQLLEN' USING GWL-PROC, GWL-SQLLEN.
            MOVE LENGTH OF LANG-BUFFER-TEXT TO LANG-MAX-L.
 
            IF GWL-SQLLEN > LANG-MAX-L THEN
                MOVE MSG-BAD-LEN           TO MSG-TEXT
                MOVE LENGTH OF MSG-BAD-LEN TO MSG-TEXT-L
                PERFORM SEND-ERROR-MESSAGE
                GO TO END-PROGRAM
            END-IF.
 
       *    Get language text
 
            CALL 'TDRCVSQL' USING GWL-PROC, GWL-RC,
                                  LANG-BUFFER-TEXT,
                                  LANG-MAX-L,
                                  LANG-ACTUAL-L.
 
            MOVE LANG-ACTUAL-L TO LANG-BUFFER-LL.

Usage

A server application uses this function to determine the actual length of an incoming string.
Typically, an application calls TDSQLLEN after TDACCEPT and before TDRCVSQL to determine how large a storage area to allocate for the incoming string.
You can use TDSQLLEN to store incoming text in more than one variable. Read part of the text into one variable, using TDRCVSQL, then call TDSQLLEN to determine the length of the text that remains. Call TDRCVSQL again to move the remaining text into a second variable. Repeat as often as necessary.
Although this function is called TDSQLLEN, it does not differentiate between SQL strings and other language strings, such as math functions or single-byte katakana. It is up to the application to determine what kind of text is in the buffer and what to do with it.