release bulletin open serverconnect™ for cics version 12 · serverconnect for cics yes no...

Copyright 1989-2002 by Sybase, Inc. All rights reserved. Sybase, the Sybase logo, Data Workbench, InfoMaker, PowerBuilder, Powersoft, SQL Advantage, SQL Debug, Transact-SQL, Adaptive Server, Adaptive Server Any-where, Adaptive Server Enterprise, Adaptive Server Enterprise Monitor, Adaptive Server IQ, AnswerBase, Any-where Studio, Backup Server, ClearConnect, Client-Library, DB-Library, dbQueue, DirectConnect, Embedded SQL, Enterprise Client/Server, EnterpriseConnect, Financial Fusion Server, InformationConnect, Jaguar CTS, jConnect, KnowledgeBase, MainframeConnect, MAP, Net-Gateway, Net-Library, ObjectConnect, OmniConnect, OmniSQL Access Module, Open Client, Open ClientConnect, Open Client/Server, Open Gateway, Open Server, Open Server-Connect, PC DB-Net, PowerDesigner, Replication Agent, Replication Driver, Replication Server, Replication Server Manager, RW-Library, Secure SQL Server, Security Guardian, SQL Remote, SQL Server, SQL Server Manager, SQL Toolset, Sybase Central, Sybase SQL Desktop, Sybase SQL Workgroup, System 10, System 11, Watcom SQL, Web.SQL, WorkGroup SQL Server, XA-Library, XA-Server, and XP Server are trademarks of Sybase, Inc. Other product names used herein may be trademarks or registered trademarks of Sybase or other companies. 11/01

Release BulletinOpen ServerConnect™ for CICS

Version 12.5

Document ID: 75200-01-1250-01

Last revised: December 7, 2001

Table of Contents Page

1. Accessing current release bulletin information 2

2. Product summary 3

2.1 Hardware and software requirements 3

2.2 Product media 3

2.3 Product documentation 4

3. Special installation instructions 5

3.1 New JCL jobs 5

3.2 Running Open ServerConnect and Open ClientConnect in a common CICS region

6

4. Special upgrade instructions 6

4.1 SYOSRDO 6

5. Added functionality in this version 6

5.1 TCP/IP listener security 7

5.2 Text and image data 7

6. Known problems 19

6.1 Transaction isolation with Interlink TCP/IP 19

6.2 Below-the-line memory 19

6.3 Packet configuration not working with TRS 19

6.4 Cannot change expired password 19

6.5 Configurable packet size 19

1. Accessing current release bulletin information Open ServerConnect for CICS Version 12.5

2 Release Bulletin for CICS

1. Accessing current release bulletin informationA more recent version of this release bulletin may be available on the World Wide Web. To check for critical product or document information added after the release of the product CD, use the Sybase Technical Library Product Manuals Web site.

❖ To access release bulletins at the Technical Library Product Manuals Web site:

1 Go to Product Manuals at http://www.sybase.com/support/manuals/.

2 Follow the links to the appropriate Sybase product.

3 Select the “Platform-Specific” collection for the product version you are interested in.

4 From the list of individual documents, select the link to the release bulletin for your platform. You can either download the PDF version or browse the document online.

6.6 Delayed Interlink error message data for logon failure 19

6.7 Interlink 5.2 20

6.8 TDSNDTXT and TDSNDROW capacity 20

7. Product compatibilities 20

8. Documentation updates and clarifications 21

8.1 Open ServerConnect for CICS library members 21

8.2 RDO definitions for sp_mda 21

8.3 MODELRSP sample 21

8.4 Enhanced TDS functionality 22

8.5 TDCANCEL 22

9. Technical support 24

10. Other sources of information 24

10.1 Sybase certifications on the Web 24

Table of Contents Page

Open ServerConnect for CICS Version 12.5 2. Product summary

Release Bulletin for CICS 3

2. Product summaryEnclosed is Sybase Open ServerConnect for CICS version 12.5, which is a programming environment enabling user development of mainframe applications that Sybase client applications can execute. Open ServerConnect applications can retrieve and update data stored on an IBM mainframe in any mainframe resource, such as VSAM files, TD queues, TS queues, and DL/1 databases, as well as in DB2 databases and other database management systems (DBMSs).

Open ServerConnect is available for CICS, IMS TM, and native MVS. Open ServerConnect runs on IBM System/390 or plug-compatible mainframe computers. It uses a host transaction processor, such as CICS, as a communications front end and uses the LU 6.2 or TCP/IP (IBM or Interlink) communications protocol.

2.1 Hardware and software requirementsThe following hardware and software are compatible with Open ServerConnect for CICS version 12.5:

• Hardware:

• IBM mainframe: S/390 or plug-compatible

• IBM front-end processor: 372x, 3745, or compatible

• IBM network controller: 3172

• IBM TIC attachment or 3174 (Token Ring Gateway is used)

• Software:

• IBM OS/390 version 2.9 or later

• Transaction Server 1.1 or later

• DB2 version 6.1 or later

• IBM TCP/IP

• Interlink TCP/IP version 5.2

For planning, installation and configuration information, see the Installation and Administration Guide for Open ServerConnect for CICS.

2.2 Product media

2. Product summary Open ServerConnect for CICS Version 12.5


Open ServerConnect for CICS consists of two tapes and the Technical Library CD.

EBFs for this product must be downloaded from the Web. See “Sybase certifications on the Web” for instructions.

Note For directory and file information, see Appendix A, “Open ServerConnect for CICS Tape Libraries” in the Installation and Administration Guide for Open ServerConnect for CICS.

The following table lists the media for Open ServerConnect for CICS version 12.5.

Table 1: Open ServerConnect for CICS version 12.5 media

2.3 Product documentationThe following table lists all the documentation for Open ServerConnect for CICS version 12.5. Although not all documents are shipped in paper copy, all documents are provided online in the shipped Technical Library CD and are also available on the Web.

Table 2: Open ServerConnect for CICS version 12.5 documentation

MediaShipped with product Product ID

Open ServerConnect Base Tape for CICS version 12.5

Yes 68120-33-1250-01

Open ServerConnect API Tape for CICS version 12.5

Yes 68100-33-1250-01

Technical Library CD Yes 94880-55-1250-01

Document title

Paper copy shipped with product

On Technical Library CD shipped with product Document ID

Installation and Administration Guide for Open ServerConnect for CICS

Yes No 36510-01-1250-01

Programmer’s Reference for Open ServerConnect for PL/1

No Yes 36560-01-0400-02

Programmer’s Reference for Open ServerConnect for COBOL

No Yes 36520-01-0400-02

Open ServerConnect for CICS Version 12.5 3. Special installation instructions


3. Special installation instructionsThis section describes special installation issues for this release.

3.1 New JCL jobsIf you are upgrading Open ServerConnect for CICS from a previous release, run the SYOSRRPC job in the JCL library. This job will do the following:

1 Back up your SYRPCFIL VSAM file

2 Delete your existing SYRPCFIL VSAM file and define a new file with a larger record size (from 65 bytes to 80 bytes)

3 Use the IDCAMS REPRO command to copy the SYRPCFIL file you backed up in step 1 to a new file

If you are installing Open ServerConnect for CICS for the first time, you must run the following two JCL jobs:

• SYOSVRPC – This job defines the SYRPCFIL VSAM file with an 80-byte LRCEL. The SYRPCFIL is used by the SYRP transaction to map RPC names to CICS transaction names.

• SYOSCRPC – Run this job to REPRO your default RPC data into your SYRPCFIL RPC file.

Programmer’s Reference for Open ServerConnect for RSPs

No Yes 35605-01-0400-01

Messages and Codes for Open ServerConnect and Open ClientConnect

No Yes 36450-01-0400-02

Release Bulletin for Open ServerConnect for CICS

Yes No 75200-01-1250-01

Document title

Paper copy shipped with product

On Technical Library CD shipped with product Document ID

4. Special upgrade instructions Open ServerConnect for CICS Version 12.5


3.2 Running Open ServerConnect and Open ClientConnect in a common CICS region

If you are planning to run Open ServerConnect for CICS applications in the same CICS region with Open ClientConnect for CICS applications, Sybase recommends that you run only the SYLSCFG job to configure TCP/IP. If you intend to run only Open ClientConnect for CICS, you should run the SYCTTCP job instead.

For installation instructions, see the Installation and Administration Guide for Open ServerConnect for CICS.

4. Special upgrade instructionsThis section documents special upgrade instructions for Open ServerConnect for CICS.

4.1 SYOSRDOIf you are upgrading from a previous release of Open ServerConnect for CICS, follow the instructions in the JCL for the SYOSRDO job in the JCL library. The SYOSRDO job copies the supplied Open ServerConnect group(s) to a backup group before defining the new resources.

Note All Open ClientConnect and Open ServerConnect applications can run in transaction isolation mode, but not with Interlink TCP/IP. Applications accompanying Open ClientConnect and Open ServerConnect version 12.5 are configured for transaction isolation by default in the JCL to set up the RDO.

For information on configuring and using transaction isolation, refer to the appropriate IBM documentation for CICS. For information on defining Open ServerConnect resources to CICS, see the Open ServerConnect Installation and Administration Guide for CICS.

5. Added functionality in this versionThis section lists the significant product changes for version 12.5 of Open ServerConnect for CICS. This version includes:

• Enhanced Tabular Data Stream (TDS) functionality – Modified Gateway-Library functions have additional return values and fields.

Open ServerConnect for CICS Version 12.5 5. Added functionality in this version


• Support for wide tables – New and larger limits to table size are supported. The old limit of 250 columns per table has been extended to 1000 columns per table.

• Text and image data – To enable streaming of text and image data, Open ServerConnect has three new API function calls: TDINFTXT, TDGETTXT, and TDSNDTXT.

• Transaction isolation – Open ServerConnect now functions in a CICS transaction isolation environment.

• Metadata availability – sp_mda is a new Open ServerConnect CSP that returns metadata from either a DB2 table or a VSAM file to client applications using jConnect.

• TCP/IP security – TCP/IP listeners can be configured to implement security in Open ServerConnect for CICS.

5.1 TCP/IP listener securityThe configuration CSECT SYLSCFG contains a new parameter for configuring listener security, LSECR. This parameter is useful only with SEC=YES in the CICS SIT.

The LSECR parameter has three values:

• Y – This setting allows the user to attempt to execute a query, even with an invalid user ID or password. The user must submit a query to determine if the connection has been refused. This may be a problem for some client applications that must execute a query before discovering access has not been achieved.

• N – Turns security off for the listener. No security check is performed.

• H – This setting will not allow the user to log on with an invalid user ID or password. The user cannot attempt to execute a query if an invalid user ID or password has been provided.

5.2 Text and image dataClient applications send text and image data to Open ServerConnect in a writetext stream. To process writetext stream data, an Open ServerConnect application cannot employ functions normally used to process parameter data. Instead, an Open ServerConnect application must use special text and image functions.

5. Added functionality in this version Open ServerConnect for CICS Version 12.5


An Open ServerConnect application can send text or image data to a client application in either of the following ways:

• data stream – If the row of returned data contains one column of text or image data, the row may be sent as a data stream. Then length of the data is between 0 and 2 gigabytes.

• describe/send row – If the row of returned data contains columns in addition to a text or image column, the text or image data may be sent using the describe/send row method. The length of the data cannot exceed 32 KB.

The following subsections describe text and image issues for Open ServerConnect:

• CS_IODESC structure

• Retrieving data from a client

• Returning data to a client

• Text and image functions

5.2.1 CS_IODESC structure

The CS_IODESC structure describes text or image data and is used to pass information between an Open ServerConnect application and the API functions that process this data.

The general structure for a CS_IODESC, regardless of programming language, is shown in Table 3.

Table 3: CS_IODESC structure

This field Contains this information

IOTYPE Indicates the type of input or output to perform. For text and image operations, IOTYPE always has the value CS_IODATA.

DATATYPE The datatype of the data object. The only legal values for DATATYPE are TDSTEXT and TDSIMAGE.

LOCALE Not used in Open ServerConnect. Set this to NULL.

USERTYPE Not used in Open ServerConnect.

TOTAL_TXTLEN The total length, in bytes, of the text or image value.

OFFSET Reserved for future use.

LOG_ON_UPDATE Determines whether the update to this text or image value should be logged. This field is not used by Open ServerConnect.

NAME The name of the text or image column.

NAMELEN The length, in bytes, of NAME.



The CS_IODESC structure is defined in the SYGWCOB copy book for COBOL (under the name CS-IODESC) and in the SYGWPLI INCLUDE member for PL/1.

When receiving text or image data from a client application, an Open ServerConnect application invokes the TDINFTXT function with the ACTION parameter set to TDS_GET. The Open ServerConnect application must provide the correct text or image DATATYPE field value before TDINFTXT is invoked so that Open ServerConnect can translate incoming text data. Only the value of the TOTAL_TXTLEN field is provided by TDINFTXT here.

When sending text or image data to a client application, the Open ServerConnect application also invokes the TDINFTXT function with the ACTION parameter set to TDS_SET. The Open ServerConnect application must describe the text or image data to be sent to the client by providing values for the appropriate CS_IODESC fields before TDINFTXT is invoked.

5.2.2 Retrieving data from a client

A writetext stream retrieved from a client application is handled as bulk data by the Open ServerConnect application.

An application processes incoming text or image data in two steps:

1 The TDINFTXT function retrieves a description of the text or image data and places the description in a CS_IODESC structure. The TDINFTXT function call returns information including the total length of incoming data. This length enables the Open ServerConnect application to determine whether the data should be retrieved in one unit or in sections. The Open ServerConnect application also determines the size of the buffer that must be allocated to store the incoming data. TDINFTXT is invoked with the ACTION parameter set to TDS_GET. The DATATYPE field of the CS_IODESC structure must be provided by the Open ServerConnect application before TDINFTXT is invoked. See “TDINFTXT” for details on this function.

TIMESTAMP The text timestamp of the column. A text timestamp marks the time of the last modification to a text or image column.

TIMESTAMPLEN Not used by Open ServerConnect.

TEXTPTR A text pointer to a table row ID.

TEXTPTRLEN The length, in bytes, of TEXTPTR. This length is currently set at 16.

This field Contains this information



2 The TDGETTXT function retrieves the incoming text and image data from the client application in the specified section size and stores the data in the specified buffer. See “TDGETTXT” for details on the TDGETTXT function.

Note A call to TDINFTXT must always precede a call to TDGETTXT. The TDGETTXT routine must be called until all text has been read from the client.

Table 4 illustrates the sequence of API function calls for retrieving text or image bulk data from the client.



Table 4: API function call sequence for data retrieval

5.2.3 Returning data to a client

An Open ServerConnect application sends text or image data to a client application in one of two ways, depending on the number of columns in the data row.

If there is one text or image column in the row to be sent, the Open ServerConnect application proceeds as follows:

1 Using the TDESCRIB function, the Open ServerConnect application describes the format in which the client receives the text or image column.

2 Optionally use the TDSETUDT function to set the user-defined datatype for the text or image column.

Function Action performed

TDSQLLEN Determines the length of the incoming writetext string

TDSRCVSQL Retrieves a writetext string. The TDSRCVSQL function call receives a writetext bulk command, which indicates that text or image bulk data follows. The writetext bulk command occurs in the following format:

writetext bulk <object_name> <text_pointer> timestamp = <time_stamp> [with log | without log]

The parameters of the writetext bulk command are as follows:

• <object_name> is the name of the object name to which data is to be sent.

• <text_pointer> is a text pointer.

• <time_stamp> indicates the value of the timestamp parameter.

• The text with log or without log is not used by Open ServerConnect.

For example:

writetext bulk SYBASE.au_txt.TXT 0xa1a0bbd014a6d005060e016a20400100 timestamp = 0x0000000000000000 with log

The manner in which the writetext bulk parameters are used depends on the Open ServerConnect application and on the destination of the incoming text and image data.

TDSNDDON Notifies the sender that the SQL string has been received. Use the connection option of TDS_ENDREPLY to change the communication state from send to receive.

TDINFTXT(using TDS_GET)

Returns the length of the entire text or image data stream. Open ServerConnect translates incoming data based on the value of the DATATYPE field in the CS_IODESC structure.

TDGETTXT Retrieves a section of the text or image data stream. TDGETTXT is invoked in a loop until all incoming data is retrieved.

TDSNDDON Notifies the sender that all data has been received.



3 The Open ServerConnect application invokes the TDINFTXT function with the ACTION parameter set to TDS_SET to indicate the total length of the returning data.

4 The Open ServerConnect application invokes the TDSNDTXT function to send the data to the client in sections.

Table 5 illustrates the sequence of API function calls for sending text or image bulk data to the client.

Table 5: API function call sequence for sending bulk data only

If there are other columns in addition to the text and image data in the row to be sent, the Open ServerConnect application proceeds as follows:

1 Using the TDESCRIB function, the Open ServerConnect application describes the format in which the client receives a column of data. The Open ServerConnect application invokes the TDESCRIB function once for each column of data.

2 The Open ServerConnect application invokes the TDINFTXT function with the ACTION parameter set to TDS_SET to provide text pointer and timestamp information. The Open ServerConnect application invokes the TDINFTXT function once for each text or image column in a row.

3 The Open ServerConnect application transfers the data to the client application using the TDSNDROW function, which is invoked once for each row of data. The text or image column size must not exceed 32KB.

Table 5 illustrates the sequence of API function calls for sending rows in which there are other columns in addition to the text or image data column(s).


TDESCRIB Describes the text or image column to be sent to the client.

TDSETUDT(optional)

Sets the user-defined datatype for the column.

TDINFTXT(using TDS_SET)

Describes the text or image column to Open ServerConnect. The Open ServerConnect application provides values for the CS_IODESC fields before invoking the TDINFTXT function. The TDINFTXT function is invoked once for every row that is to be sent to the client.

TDSNDTXT Sends a section of the text or image data stream. The TDSNDTXT function is invoked in a loop until all the data for a given row is sent to the client.

TDSNDDON Notifies the client that all data has been sent.



Table 6: API function call sequence for sending row data of varied column datatypes

5.2.4 Text and image functions

Open ServerConnect provides three new functions: TDINFTXT, TDGETTXT, and TDSNDTXT. These functions can be invoked from within an Open ServerConnect application written in COBOL or PL/1. The TDINFTXT, TDGETTXT, and TDSNDTXT functions are described in the following sections using COBOL syntax.

TDINFTXT

Function Set or get a description of text or image data.

Syntax 01 TDPROC PIC S9(9) USAGE COMP SYNC.01 RETCODE PIC S9(9) USAGE COMP SYNC.01 ACTION PIC S9(9) USAGE COMP SYNC.01 ITEM-NUMBER PIC S9(9) USAGE COMP SYNC.01 CS-IODESC FROM SYGWCOB

CALL ’TDINFTXT’ USING TDPROC, RETCODE, ACTION, ITEM-NUMBER, CS-IODESC.

Arguments TDPROC

(I) Handle for the client/server connection. The value here must be the same value specified in the associated TDACCEPT function call. The TDPROC handle corresponds to the connection and command handles in Open Client Client-Library.

RETCODE


TDESCRIB Describes a column to be sent to the client. The TDESCRIB function is invoked once for each column of data to be sent to the client.

TDINFTXT(using TDS_SET)

Describes a text or image column to Open ServerConnect. The Open ServerConnect application provides values for the CS_IODESC fields before invoking the TDINFTXT function. The TDINFTXT function is invoked in two nested loops, once for every text or image column in a row to be sent to the client, and once for every row to be sent to the client.

TDSNDROW Sends a row of data to the client. The TDSNDROW function is invoked in a loop for every row of data to be sent to the client and preceded by a number of TDINFTXT calls describing the text and image columns in a row.

TDSNDDON Notifies the client that all data has been sent.



(O) Variable to which the result of function execution is returned. The value of this variable is one of the codes listed below under “Returns”.

ACTION

(I) Action to be taken by this call. ACTION is an integer variable that indicates the purpose of this call.

Assign ACTION one of the following symbolic values:

ITEM-NUMBER

(I) The column number of the column being described. The first column in a row is column 1. This parameter is ignored when ACTION is TDS_GET.

CS-IODESC

(I) A pointer to the CS-IODESC for the application.

Comments • TDINFTXT is used to describe text or image columns for sending a result row or retrieving a parameter.

• If ACTION is TDS_GET, TDINFTXT must be called prior to the first or only call to TDGETTXT for a row.

• If ACTION is TDS_SET, TDINFTXT must be called for each text or image datatype column in a row before TDSNDTXT or TDSNDROW is called.

• Text and image data is transferred to the client using either TDSNDTXT or TDSNDROW.

Returns The RETCODE argument can contain any of the following values:

• TDS_OK (0)

• TDS_INVALID_PARAMETER (-4)

TDS_GET (1) Open ServerConnect updates the CS_IODESC structure with the total length of the text or image data to be read from the client. Typically, this is followed by a call to the TDGETTXT function. The Open ServerConnect application must set the DATATYPE field in the CS-IODESC structure to TDSTEXT or TDSIMAGE before invoking TDGETTXT.

TDS_SET (2) Open ServerConnect sets internal Server-Library structures to describe a text or image data object. The TDINFTXT call updates a text or image column with the information contained in CS-IODESC. The Open ServerConnect application must describe the column using TDESCRIB before TDINFTXT is invoked.



• TDS_INVALID_DATA_TYPE (-171)

• TDS_ILLEGAL_REQUEST (-5)

• TDS_INVALID_LENGTH (-173)

• TDS_RESULTS_COMPLETE (500)

• TDS_WRONG_STATE (-6)

• TDS_CONNECTION_FAILED (-4998)

• TDS_CONNECTION_TERMINATED (-4997)

See also Related functions:

• TDSNDTXT

• TDGETTXT

TDSNDTXT

Function Send a subsequent part of the text or image data stream to the client.

Syntax 01 TDPROC PIC S9(9) USAGE COMP SYNC.01 RETCODE PIC S9(9) USAGE COMP SYNC.01 HOST-VARIABLE-NAME PIC X(n).01 BUFLEN PIC S9(9) USAGE COMP SYNC.

CALL ‘TDSNDTXT’ USING TDPROC, RETCODE, HOST-VARIABLE-NAME, BUFLEN.

Arguments TDPROC


RETCODE


HOST-VARIABLE-NAME

(I) Application program variable that contains data for this column.

BUFLEN

(I) The size in bytes of the buffer containing the data.



Comments • TDSNDTXT is used when sending a single column of text or image data to the client.

• The Open ServerConnect application must always call TDINFTXT prior to the first call to TDSNDTXT for the data stream, in order to set the total length of the data to be sent. The application then calls TDSNDTXT to send a part of the data. TDSNDTXT is called as many times as there are sections of data in the data stream.

• The item being sent to the client must have previously been described using TDESCRIB.

• An Open ServerConnect application can also write text and image data to a client using TDSNDROW. TDSNDTXT allows the application to send the data in sections, whereas the standard TDSNDROW method requires that all the data in the column be sent in one piece.

• A column sent with TDSNDTXT must be of type text or image.

• Open ServerConnect treats text and image data streams identically except for character set conversion, which is only performed on text data.


• TDS_OK (0)


• TDS_INVALID_VAR_ADDRESS (-175)

• TDS_CANCEL_RECEIVED (-12)





• TDGETTXT

• TDINFTXT



TDGETTXT

Function Read a subsequent part of a text or image datastream from the client.

Syntax 01 TDPROC PIC S9(9) USAGE COMP SYNC.01 RETCODE PIC S9(9) USAGE COMP SYNC.01 HOST-VARIABLE-NAME PIC X(n).01 BUFLEN PIC S9(9) USAGE COMP SYNC.01 OUTLEN PIC S9(9) USAGE COMP SYNC.

CALL ’TDSNDTXT’ USING TDPROC, RETCODE, HOST-VARIABLE NAME, BUFLEN.

Arguments TDPROC


RETCODE


HOST-VARIABLE-NAME

(I) Application program variable to receive a subsequent part of the incoming text or image client data.

BUFLEN

(I) The size in bytes of the buffer containing the data.

OUTLEN

(O) The length in bytes of the data received.



Comments • TDGETTXT is used to read bulk data from the client. The bulk data can be of type text or image.

• TDGETTXT must be called until all of the bulk data has been read from a client. The Open ServerConnect application must keep track of the data that remains to be read.

• A column read with TDGETTXT must be of type text or image.

• An Open ServerConnect application must call TDINFTXT prior to the first call to TDGETTXT for the data stream. The application then calls TDGETTXT to retrieve a section of data. TDGETTXT is called as many times as are necessary to read in the whole stream.

• The Open ServerConnect application must set the CS_IODESC DATATYPE field to TDSTEXT or TDSIMAGE before invoking the TDINFTXT and TDGETTXT functions. In the case in which DATATYPE is set to TDSTEXT, Open ServerConnect translates the character set for the client data before sending the data to the Open ServerConnect application.


• TDS_OK (0)

• TDS_INVALID_VAR_ADDRESS (-175)






• TDSNDTXT

• TDINFTXT

Open ServerConnect for CICS Version 12.5 6. Known problems


6. Known problemsThis section explains known problems with Open ServerConnect for CICS version 12.5.

6.1 Transaction isolation with Interlink TCP/IPAll Open ServerConnect and Open ClientConnect applications can run in transaction isolation mode, but not with Interlink TCP/IP. To run applications in transaction isolation mode with TCP/IP, you must use IBM TCP/IP.

6.2 Below-the-line memoryOpen ServerConnect for CICS objects no longer use below-the-line memory storage. This may give rise to compatibility issues with non-Sybase products that do use below-the-line memory.

6.3 Packet configuration not working with TRSOpen ServerConnect for CICS applications might abend with client requests exceeding 1024KB in a three-tier, gateway-enabled environment using DirectConnect TRS when the packet size is set by the client application.

6.4 Cannot change expired passwordExpired RACF passwords cannot be changed using the sgw_chgpw RPC from isql. You must either change RACF passwords before they expire or use some other means to change the password once it has expired.

6.5 Configurable packet sizeConfigurable packet size functionality does not work properly in a three-tier environment with the DirectConnect DB2 access service in which code page translation is performed on the gateway instead of on the mainframe.

6.6 Delayed Interlink error message data for logon failureThe configuration CSECT SYLSCFG contains a new parameter for listener security, LSECR. When LSECR=H, error messages indicating connection failure using the Interlink TCP/IP listener, ICSLSTNR, may be significantly

7. Product compatibilities Open ServerConnect for CICS Version 12.5


delayed before writing to the CICS MSGUSR log. However, there is no error message delay after connection failures for the IBM TCP/IP listener, IBMLSTNR.

For more information on the LSECR parameter in the SYLSCFG configuration CSECT, see “TCP/IP listener security”.

6.7 Interlink 5.2The ICSLSTNR Interlink listener, version 5.2, will abend unless the RENTPGM, TRANISO, and STGPROT parameters are set in your CICS SIT as follows:

• RENTPGM=NOPROTECT

• TRANISO=NO

• STGPROT=YES

6.8 TDSNDTXT and TDSNDROW capacityWhen sending data from one text or image column using the TDSNDTXT function, the text or image column can be as large as 2GB in size. However, this capacity has not been fully tested.

When sending data from a text or image column in addition to other selected columns using the TDSNDROW function, the row size must not exceed 32KB in size.

For information on sending text and image data, see “Returning data to a client”.

7. Product compatibilitiesFor full functionality with the current release, use these Sybase components, as available at your site:

Table 7: Sybase product release compatibility

Component Release level

Open ClientConnect for CICS 12.5

MainframeConnect for DB2 UDB 12.5

DirectConnect Transaction Router Service 12.5

Japanese Conversion Module 12.5

Open ServerConnect for CICS Version 12.5 8. Documentation updates and clarifications


8. Documentation updates and clarificationsThe section contains documentation updates and clarifications for Open ServerConnect for CICS version 12.5.

8.1 Open ServerConnect for CICS library membersThe following library members are absent from Appendix A, “Tape Libraries,” in the Open ServerConnect Installation and Administration Guide for CICS:

Table 8: Base tape library contents

Table 9: API tape RSP library contents

Table 10: API tape Open ServerConnect for CICS library contents

8.2 RDO definitions for sp_mdaBefore installing sp_mda, you must decide which format you wish to use to store and access metadata: a DB2 table or a VSAM data set. To use sp_mda for DB2, you must un-comment the TRANS definition in the RDO. For example, to use DB2 tables, un-comment the following lines in the RDO:

DEFINE DB2ENTRY(SPMDACSP) GROUP(SYAPGRP) TR(SYJC) AUTHT(USERID) PLAN(SPMDACSP) PRI(EQUAL) THREADW(POOL)

This example replaces the example found under “Installing and using sp_mda” in Chapter 4, “Installing CICS Libraries from the API Tape” of the Open ServerConnect Installation and Administration Guide for CICS.

8.3 MODELRSP sampleThe Open ServerConnect Programmer’s Guide for Remote Stored Procedures shows sample code for the MODELRSP remote stored procedure. Code samples for this remote stored procedure show the length range of char and varchar as 1-256 bytes. This should instead show the range 1-255 bytes.

Library Member Descriptions

LOADLIB SYBCLOS Close listener ports


MACLIB SPAREAA Stored procedure communication area for Assembler programs


COPY DCLSPMDA COBOL record structure for sp_mda DB2 table columns

8. Documentation updates and clarifications Open ServerConnect for CICS Version 12.5


8.4 Enhanced TDS functionalityIn addition to the three new API function calls created to ensure streaming of text and image data and large objects, existing APIs have been enhanced. While existing APIs have been enhanced to accommodate larger data streams, the format of the fields and return values have not changed.

8.5 TDCANCELThis section describes the TDCANEL Open ServerConnect Gateway-Library function using PL/1 syntax.

Function Cancel the current request.

Warning! This function cannot be used with the IMS LU 6.2 Adapter for LU 6.1.

Syntax %INCLUDE SYGWPLI;

01 TDPROC PTR,

01 RETCODE FIXED BIN(31);

CALL TDCANCEL (TDPROC, RETCODE);

Arguments TDPROC – (I) Handle for this client-server connection. This must be the same value specified in the associated TDACCEPT call.

RETCODE – (O) Variable where the result of function execution is returned. Its value is one of the codes listed under “Returns” in this section.

Comments • A server application uses TDCANCEL to tell the client that an error has been detected, and that the current request has been canceled and purged. Any pending return rows are discarded.

• A server application must be in Receive state for TDCANCEL to execute successfully.

• When TDCANCEL completes, it leaves the application in Send state. Calling TDCANCEL is one way to switch a server application from Receive state into Send state.

• A server application should follow a TDCANCEL with a message (TDSNDMSG) explaining why the cancel occurred, then issue a TDSNDDON call.

Open ServerConnect for CICS Version 12.5 8. Documentation updates and clarifications


Example The following code fragment illustrates the use of TDCANCEL to put the server application in Send state. This example is in PL/1.

/*------------------------------------------------------------------*/SEND_MESSAGE: PROC;/*------------------------------------------------------------------*/

/* ------------------------------------------------------------*//* Ensure server is in SEND state, so it can send a message. *//* ------------------------------------------------------------*/

CALL TDSTATUS (GWL_PROC, GWL_RC,GWL_STATUS_NR,GWL_STATUS_DONE,GWL_STATUS_COUNT,GWL_STATUS_COMM,GWL_STATUS_RETCODE,GWL_STATUS_SUBCODE);

IF GWL_RC = TDS_OK THENDO;

IF GWL_STATUS_COMM = TDS_RECEIVE THENDO;

CALL TDCANCEL (GWL_PROC, GWL_RC);END;

CALL TDSNDMSG (GWL_PROC, GWL_RC,MSG_TYPE, MSG_NR,MSG_SEVERITY,TDS_ZERO,TDS_ZERO,MSG_RPC, MSG_RPC_L,MSG_TEXT, MSG_TEXT_L);

END;RETURN;

END SEND_MESSAGE;


• TDS_OK (0)




• TDS_INVALID_PARAMETER (-4)

9. Technical support Open ServerConnect for CICS Version 12.5


• TDS_INVALID_TDPROC (-18)


9. Technical supportEach Sybase installation that has purchased a support contract has one or more designated people who are authorized to contact Sybase Technical Support. If you have any questions about this installation or if you need assistance during the installation process, ask the designated person to contact Sybase Technical Support or the Sybase subsidiary in your area.

10. Other sources of informationUse the Sybase Technical Library CD and the Technical Library Product Manuals Web site to learn more about your product:

• Technical Library CD contains product manuals and is included with your software. The DynaText browser (downloadable from Product Manuals at http://www.sybase.com/detail/1,3693,1010661,00.html) allows you to access technical information about your product in an easy-to-use format.

Refer to the Technical Library Installation Guide in your documentation package for instructions on installing and starting the Technical Library.

• Technical Library Product Manuals Web site is an HTML version of the Technical Library CD that you can access using a standard Web browser. In addition to product manuals, you will find links to the Technical Documents Web site (formerly known as Tech Info Library), the Solved Cases page, and Sybase/Powersoft newsgroups.

To access the Technical Library Product Manuals Web site, go to Product Manuals at http://www.sybase.com/support/manuals/.

10.1 Sybase certifications on the WebTechnical documentation at the Sybase Web site is updated frequently.

❖ For the latest information on product certifications

1 Point your Web browser to Technical Documents at http://www.sybase.com/support/techdocs/.

2 Select Products from the navigation bar on the left.

Open ServerConnect for CICS Version 12.5 10. Other sources of information


3 Select a product name from the product list.

4 Select the Certification Report filter, specify a time frame, and click Go.

5 Click a Certification Report title to display the report.

❖ For the latest information on EBFs and Updates


2 Select EBFs/Updates. Enter user name and password information, if prompted (for existing Web accounts) or create a new account (a free service).

3 Specify a time frame and click Go.

4 Select a product.

5 Click an EBF/Update title to display the report.

❖ To create a personalized view of the Sybase Web site (including support pages)

Set up a MySybase profile. MySybase is a free service that allows you to create a personalized view of Sybase Web pages.


2 Click MySybase and create a MySybase profile.

10. Other sources of information Open ServerConnect for CICS Version 12.5
