Chapter 3: Functions

TDSETSOI

Description

Set the Shift Out/Shift In (“SO/SI”) processing options for a column or parameter.

This function is used with the Japanese Conversion Module (JCM).

Syntax

COPY SYGWCOB.


01   TDPROC        PIC S9(9)  USAGE COMP SYNC.
01   RETCODE       PIC S9(9)  USAGE COMP SYNC.
01   OBJECT-TYPE   PIC S9(9)  USAGE COMP SYNC.
01   OBJECT-NUMBER PIC S9(9)  USAGE COMP SYNC.
01   STRIP-SOSI    PIC S9(9)  USAGE COMP SYNC.

CALL 'TDSETSOI' USING TDPROC, RETCODE, OBJECT-TYPE, 
                 OBJECT-NUMBER, STRIP-SOSI.

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.

RETCODE: (O) Variable where the result of function execution is returned. Its value is one of the codes listed in Table 3-35.

OBJECT-TYPE

(I) Indicator for the type of object being set. This argument indicates whether the object being described is a column in a return row or a return parameter.

Assign this argument one of the following values:

TDS-OBJECT-COL (1)	Object is a column in a return row.
TDS-OBJECT-PARM (2)	Object is a return parameter.

OBJECT-NUMBER

(I) Number of the column or parameter being set.

If the object is a column, this is the number of the column with the SO/SI option that is being set. Columns are numbered sequentially; the first column in a row is number 1.

If the object is a parameter, this is the number of the parameter with the SO/SI option that is being set. All parameters are counted, whether or not they are return parameters. Parameters are numbered sequentially; the first parameter is number 1.

STRIP-SOSI

(I) The SO/SI processing option being set for this column or parameter.

Assign STRIP-SOSI one of the following values:

TDS-STRIP-SOSI (0)	SO/SI codes are stripped at the host before being sent to the client. This is the default.
TDS-BLANK-SOSI (1)	SO/SI codes are converted to blanks before being sent to the client. The length of the object does not change.

Returns

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

**Table 3-35: TDSETSOI return values**
Return value	Meaning
TDS-OK (0)	Function completed successfully.
TDS-ENTRY-NOT-FOUND (-8)	The specified column number, transaction number, or parameter does not exist.
TDS-INVALID-FLAGS (-176)	Invalid padding option for a field.
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.

Examples

Example 1

The following code fragment uses TDSETSOI to replace SO/SI codes with blanks before retrieving parameters and again before returning data to the client. This example is not included on the Open ServerConnect API tape, but is available to Japanese customers on the Japanese Conversion Module tape.

 *****************************************************************
  PROCEDURE DIVISION.
 *****************************************************************
 *
      CALL ‘TDINIT’   USING DFHEIBLK, GWL-RC, GWL-INIT-HANDLE.
 *
      CALL ‘TDACCEPT’ USING GWL-PROC, GWL-RC, GWL-INIT-HANDLE,
                            SNA-CONNECTION-NAME,
                            SNA-SUBC.
 *
      CALL ‘TDINFRPC’ USING GWL-PROC, GWL-RC, GWL-REQ-TYPE,
                           GWL-RPC-NAME,GWL-COMM-STATE.

 *    get the information of so-so

     MOVE TDS-OBJECT-PARM  TO PRM-01-OBJ-TYPE.
      MOVE PRM-01-ID        TO PRM-01-OBJ-ID.
      CALL ‘TDGETSOI’ USING GWL-PROC, GWL-RC,
                            PRM-01-OBJ-TYPE,
                            PRM-01-OBJ-ID,
                            PRM-01-STRIP-SOSI.
 *
      IF PRM-01-STRIP = TDS-STRIP-SOSI
      THEN

*    specify the embedded blanks to the parameter

     MOVE TDS-BLANK-SOSI   TO PRM-01-STRIP-SOSI

     CALL ‘TDSETSOI’ USING GWL-PROC, GWL-RC,
                            PRM-01-OBJ-TYPE,
                            PRM-01-OBJ-ID,
                            PRM-01-STRIP-SOSI
      END-IF
*
      MOVE TDSCHAR          TO PRM-01-HOST-TYPE.
 *
      MOVE LENGTH OF PRM-01-DATA TO PRM-01-MAX-LEN.
 *
      CALL ‘TDRCVPRM’ USING GWL-PROC, GWL-RC,
                            PRM-01-ID,
                            PRM-01-AREA,
                            PRM-01-HOST-TYPE,
                            PRM-01-MAX-LEN,
                            PRM-01-ACT-LEN.
*
      CALL ‘TDESCRIB’ USING GWL-PROC, GWL-RC,
                            COL-01-NUM,
                            COL-01-HOST-TYPE,
                            COL-01-HOST-LEN,
                            COL-01-AREA,
                            COL-01-NULL-INDICATOR,
                            TDS-FALSE,
                            COL-01-CLIENT-TYPE,
                            COL-01-CLIENT-LEN,
                            COL-01-NAME,
                            COL-01-NAME-LEN.

*    get the information of sosi

     MOVE TDS-OBJECT-COL   TO COL-01-OBJ-TYPE.
      MOVE COL-01-NUM       TO COL-01-OBJ-ID.
      CALL ‘TDGETSOI’ USING GWL-PROC, GWL-RC,
                            COL-01-OBJ-TYPE,
                            COL-01-OBJ-ID,
                            COL-01-STRIP-SOSI.
 *
      IF COL-01-STRIP-SOSI = TDS-STRIP-SOSI
      THEN
 *
 *    specify the embedded blanks to the column

           MOVE TDS-BLANK-SOSI TO COL-01-STRIP-SOSI
            CALL ‘TDSETSOI’ USING  GWL-PROC, GWL-RC,
                                   COL-01-OBJ-TYPE,
                                   COL-01-OBJ-ID,
                                   COL-01-STRIP-SOSI
      END-IF
       PERFORM FETCH-AND-SEND-ROWS UNTIL ALL-DONE.

Usage

Use TDSETSOI to specify whether SO/SI codes are stripped or converted to blanks for a specified column or parameter before results are returned to the client.
SO/SI codes are inserted around double-byte character strings when the client request is received by the Gateway-Library program. The TDSETSOI setting determines what happens to those codes when the string is returned to the client.
If a program uses TDSETSOI to handle SO/SI codes when there are no SO/SI codes or blanks surrounding kanji characters, the TDSETSOI setting is ignored.
SO/SI codes are used with character datatypes. Graphic datatypes do not use SO/SI codes.
Replacing SO/SI codes with blanks maintains the length of the string. Otherwise, if SO/SI codes are stripped, the result length is shorter than the source length. Unless you know in advance how many pairs of SO/SI codes are in the source string, it is difficult to know what the result length will be.
For a discussion of Shift Out and Shift In codes, read “Character sets” and “Processing Japanese client requests”.