Microsoft Word version of the Migration Guide.doc

MVS Migration Guide

Introduction.............................................................................................1Compatibility with new products................................................................1

New product names.....................................................................................1Ordering Sybase Products....................................................................................2

Available Resources.....................................................................................2Technical Support................................................................................................2Your Local Account Representative.....................................................................2Sybase Professional Services................................................................................2

1. Migration Overview..............................................................................3Migration Considerations...........................................................................3

Performance......................................................................................................... 3Year 2000 compliance.........................................................................................3Client................................................................................................................... 3Gateway............................................................................................................... 4Mainframe........................................................................................................... 4

Compatibility Features................................................................................5Database Gateway customers...............................................................................5Net Gateway customers........................................................................................5

Product Coexistence....................................................................................5Migrating your old configuration files..................................................................5Running multiple products in the same environment............................................5

New Features...............................................................................................6NetBufSize Configuration property.......................................................................6Open Server Connect 4.0 for CICS.......................................................................6Connecting to the mainframe over TCP/IP...........................................................6Service name redirection......................................................................................6Support for consolidating gateways......................................................................6Application development enhancements...............................................................7Native connectivity from PowerBuilder...............................................................7New ODBC 3.0 compliant DirectConnect drivers................................................7Systems Management...........................................................................................7

2. Migration Process................................................................................8Platforms supported....................................................................................8

Selecting a DirectConnect service for migration.........................................8Database Gateway customers...............................................................................8Net Gateway customers........................................................................................9

Getting Started............................................................................................9

Migrating from MDI Database Gateway....................................................9

Migrating from Net Gateway....................................................................10

3. Data Access Features.........................................................................11Performance...............................................................................................11

Tuning - LAN packet size..................................................................................11Adaptive Server & OmniConnect.......................................................................11

Supported Platforms and Improved Connectivity...................................12

3

Improved MVS connectivity..............................................................................12MVS Connectivity Enhancements......................................................................13

Gateway Consolidation.............................................................................14Architecture & platforms...................................................................................14Service Name Redirection..................................................................................15Using two different services in one application..................................................16

Systems Management................................................................................16DirectConnect Manager.....................................................................................16Integrated password management.......................................................................17

Application Development..........................................................................18SQL Transformation..........................................................................................18Determining a target’s capabilities.....................................................................19Transfer............................................................................................................. 19Datatype conversion...........................................................................................19Cursors............................................................................................................... 21Dynamic events.................................................................................................21ODBC drivers....................................................................................................21

4. Product Compatibility & Requirements.............................................23Product Compatibility...............................................................................23

DirectConnect for MVS.....................................................................................23MainframeConnect for DB2/MVS-CICS............................................................23Open ServerConnect..........................................................................................23Open ClientConnect...........................................................................................23

Hardware, Software & System Requirements..........................................24

LAN...........................................................................................................24DirectConnect for MVS - Windows NT.............................................................24DirectConnect for MVS – AIX...........................................................................24DirectConnect for MVS – HP.............................................................................24DirectConnect for MVS – Solaris.......................................................................25

MVS...........................................................................................................25MainframeConnect for DB2/MVS-CICS............................................................25Open ClientConnect for CICS............................................................................26Open ServerConnect for CICS...........................................................................27

5. Installation and Coexistence..............................................................29Installation Steps.......................................................................................29

Installation Checklist..........................................................................................29Installation Steps................................................................................................29Installation Tasks...............................................................................................29References......................................................................................................... 29Mainframe and Connectivity Installation............................................................29DirectConnect Server Installation......................................................................30Client Installation..............................................................................................30

Connectivity...............................................................................................31

Target Installation.....................................................................................31

MainframeConnect for DB2/MVS-CICS Installation..............................31

Open ServerConnect Installation..............................................................32

4

Open ClientConnect Installation..............................................................32

DirectConnect Server Installation.............................................................33DirectConnect Environment...............................................................................33

Client Installation......................................................................................34Open Client installation......................................................................................34DirectConnect ODBC Driver Installation...........................................................34DirectConnect Manager installation...................................................................34

Coexistence................................................................................................35Gateways...........................................................................................................35Mainframe......................................................................................................... 36

6. Configuration Migration....................................................................38Converting Old Net Gateway Configurations..........................................38

Startup parameters.............................................................................................38Configuration files.............................................................................................39

Converting Old MDI Database Gateway Configurations........................39

Access Server.............................................................................................40

Database Gateway.....................................................................................41

Open Server/Open Client customization properties.................................46

7. Migration: Client Connectivity...........................................................47Overview....................................................................................................47

Making connections...........................................................................................47

Open Client................................................................................................47Supported versions.............................................................................................47

ODBC Drivers...........................................................................................48ODBC & DirectConnect access services............................................................48ODBC & Transaction Router Service.................................................................48PowerBuilder.....................................................................................................48

Miscellaneous.............................................................................................49PeopleSoft support.............................................................................................49

8. Migration: Gateway Servers...............................................................51Database Gateway.....................................................................................51

Configuration property enhancements and changes............................................51Improved SET statements, global variables and configuration properties............53Datatypes not supported.....................................................................................54SQL transformation enhancements.....................................................................54RPC enhancements and compatibility................................................................55CSP enhancements.............................................................................................56Transfer enhancements.......................................................................................56Codeset conversion changes...............................................................................59Error messages...................................................................................................59Integrated password management enhancements................................................60

Net Gateway...............................................................................................60Mainframe Client Connect Compatibility Highlights..........................................60RPC Handling....................................................................................................60Systems Management issues...............................................................................61

5

New mainframe CSPs........................................................................................62Net Gateway 2.x Compatibility..........................................................................62

Gateway-less MVS Access.........................................................................63Open Server Connect 4.0 supports DirectConnect or "gateway-less" mainframe access.................................................................................................................63

Mainframe Client Connect........................................................................63Database Gateway Access Server replaced by MCC...........................................64

9. Migration: RSPs & Open ServerConnect..........................................67Overview....................................................................................................67

Supported Languages................................................................................67

RSP and RPC Comparison & Migration..................................................68

Open Server/Mainframe & Open ServerConnect....................................69Open Server/Mainframe v. 3.0...........................................................................69

Remote Stored Procedures (RSPs)............................................................69Migrating RSPs with full compatibility..............................................................69How RSP Processing Works...............................................................................69RPCs and Adaptive Server Enterprise................................................................70Migrating RSPs to use TRS................................................................................70Notes................................................................................................................. 71

10. Migration: CSAs & Open ClientConnect.........................................73Overview....................................................................................................73

Supported Languages.........................................................................................73

Open Client/Mainframe & Open ClientConnect......................................73

Client Services Applications (CSAs).........................................................74How CSA processing works...............................................................................74Migration considerations....................................................................................75

11. Interoperability.................................................................................77Adaptive Server Enterprise (Sybase SQL/Server)....................................77

Adaptive Server (EEO) & OmniConnect............................................................77

Adaptive Server Anywhere.......................................................................78Data access........................................................................................................78Data movement..................................................................................................78

Replication Agents.....................................................................................78

Microsoft SQL/Server...............................................................................78Data access........................................................................................................79Data movement..................................................................................................79Notes................................................................................................................. 79

InfoHub.....................................................................................................79

Migration Considerations.........................................................................80

12. Known Issues.................................................................................... 83PowerBuilder.............................................................................................83

6

Communications........................................................................................86TCP/IP Configuration Issues..............................................................................86

OmniConnect.............................................................................................87OmniConnect NUMERIC datatype translation...................................................87

7

Table of Contents

8

IntroductionThe MVS Migration Guide explains the features of new Sybase products and what you need to do to upgrade to the new product set. It identifies the common problems that you need to be aware of when migrating, explains how to make existing applications work with the new products, and how to develop and deploy new applications.

This guide is not intended to be a comprehensive description of new products. DO NOT attempt to install the new products without thoroughly reviewing the documentation for each product.

Compatibility with new productsSybase has provided backward compatibility for most of the new products. The new products and versions are backward compatible with the following:

MDI Products: Database Gateways for MVS, versions 2.03 and 2.05 MDI Access Server for MVS/CICS, versions 2.03 and 2.05

Net Gateway Products: Net Gateway, version 3.0 and 3.01 OmniSQL Access Module for DB2-CICS, version 10.5 and higher Open Server/Mainframe for CICS, version 3.1 and higher Open Client/Mainframe for CICS, version 3.1 and higher

New product namesThe following table cross-references the old and new products and product component names:

Old Name New NameOpen Server/Mainframe for CICS Open ServerConnect for CICSOpen Client/Mainframe for CICS Open ClientConnect for CICSOpen Server/Mainframe for IMS/TM Open ServerConnect for MVS and IMSOpen Client/Mainframe for IMS/TM Open ClientConnect for MVS and IMSOmniSQL Access Module for DB2 MainframeConnect for DB2/MVS-CICSNet Gateway:

Mainframe Server Gateway (MSG)

Mainframe Client Gateway (MCG)

DirectConnect for MVS: Transaction Router Service

(TRS) Mainframe Client Connect

(MCC) Database Gateway for MVS:

DB2 Gateway Database Gateway Access

Server (DGACCSRV)

DirectConnect for MVS: DB2 Access Service Mainframe Client Connect

(MCC) Access Server for MVS-CICS:

Dynamic DB2 Access (replaced by multiple products):

MainframeConnect for

1

Remote Stored Procedures

(RSPs) Client Services

Applications (CSAs)

DB2/MVS-CICS Open ServerConnect for

CICS (supporting RSPs) Open ClientConnect for

CICS (supporting CSAs)

Ordering Sybase Products

Ordering Sybase products is simplified by means of our Mainframe Connect integrated product set — which contains all of the new products listed in the previous table.

For information on our new product set and licensing and upgrade issues, refer to the Data Access Migration Site (http://www.sybase.com/products/entcon/migration_index.html).

Available Resources

Technical Support

Sybase Technical Support (call 1-800-8SYBASE) is able to help you with the following questions and activities:

Executing revenue-neutral license upgrades (upgrades that do not involve changes in platform or usage levels).

Answering technical questions not already addressed by this document or the product documents.

Giving general advice and responding to specific questions about migrating to the new product set.

Before contacting Technical Support, please review the product documentation and this document for answers to many of your questions.

Your Local Account Representative

For questions concerning pricing, maintenance changes in user levels, and/or platform changes please contact your local account representative.

Sybase Professional Services

For information about public course offerings, contact the Sybase Learning Connection (http://slc.sybase.com) or call (800) 8SYBASE. For information about custom or on-site classes, please contact your Sybase sales representative.

2

http://slc.sybase.com/

http://www.sybase.com/products/entcon/migration_index.html

1. Migration OverviewThis chapter describes information required to migrate to the new product set and provides links to the detailed information within this document. The issues are grouped into the following subject areas: Migration Considerations – summarizes issues that you must consider to migrate to

the new product set. Compatibility Features – lists the features that ensure compatibility between

DirectConnect and the legacy product sets, and explains how to use these features. Product Coexistence – summarizes the major issues surrounding running the old

and new product sets side-by-side, in test and production environments. New Features – summarizes features available to you in the new product set. Migration Process – describes a process for migrating from either a Net Gateway

or MDI environment to DirectConnect.

Migration Considerations

Performance

Performance is affected by many factors and is site-specific. In some instances, you may have to change your configuration to improve performance.

The following factors will affect your migration effort and will improve your performace:

Hardware upgrades – to more current hardware. Upgrading to the most current version (11.7) of DirectConnect

Year 2000 compliance

The new products have all been tested and certified Year 2000 compliant. For any Y2K specific issues refer to the Sybase Y2K web site at the following URL: www.sybase.com/inc/corpinfo/year2000_index.html

Client

Supported Open Client versions

Open Client is required to support client connectivity to the new gateways. The Open Client section in Chapter 7 lists the versions we support with the new product set.

Microsoft client libraries

For Database Gateway customers using Microsoft client DLLs for connectivity to the gateways, these DLLs are not supported and cannot be used with DirectConnect.

3

PowerBuilder support for DirectConnectThe most popular tool used with the gateways is PowerBuilder. There have been significant improvements using PowerBuilder with DirectConnect using a native interface driver (PBDIRxx.DLL) with DirectConnect DB2 access services and TRS services.

Powerbuilder, using an ODBC interface, is covered in the ODBC Drivers section of Chapter 7, summarizes the major issues.

Banyan Vines support discontinued

Banyan Vines networks are no longer supported.

Gateway

Codeset conversion

The a2e.dat character set conversion file is no longer supported and there have been significant changes in how character set conversion is performed. For additional information, contact Technical Support. You will find the information in the Codeset conversion changes in the Database Gateway section of Chapter 8.

Password Manager

The Password Manager features have been integrated into the DirectConnect Services (only with SNA Connectivity). See Integrated password management in the Systems Management section of Chapter 3.

Mainframe

Remote Stored Procedures

RSPs coded following the MDI Gateway documentation are supported without any changes required to the source code.

RSPs using undocumented features may require coding changes.

The only RSP functionality not supported is the use of DB2 input pipes. For additional information, see the Remote Stored Procedures (RSPs) section of Chapter 10.

4

Compatibility Features

Database Gateway customers

Database Gateway syntax supported

DirectConnect for MVS provides a "gateway compatibility" mode that supports system commands that were supported by the old gateways. See the GatewayCompatible Property under the Database Gateway section of Chapter 8 for details.

Legacy SQL transformation modes are supported

DirectConnect for MVS supports db2, tsql0, tsql1 and tsql2 SQL transformation modes.

Net Gateway customers

Support for the NOUDT flag

Support for the NOUDT flag continues for those Net Gateway customers who may have developed applications in which no user datatype was returned from the OmniSQL Access Module for DB2. See the Gateway-less MVS Connectivity section of Chapter 8 for an explanation of how we support your existing applications.

Product Coexistence

Migrating your old configuration files

Configuration is handled a little differently in the new product set. Chapter 6, Converting Configurations, shows you how to migrate from your old configurations to the new ones.

Running multiple products in the same environment

We recommend you install old and new products side-by-side for acceptance testing. The Product Coexistence section of Chapter 5, Installation & Coexistence, discusses how to setup the products for coexistence, including RSPs, mainframe Catalog Stored Procedures, and many other issues.

5

New Features

NetBufSize Configuration property

We have added a new server configuration property, NetBufSize, to help you tune LAN performance. This property allows you to set the maximum CT-Library packet size used on the network. It is recommended you set this to the smallest packet size a client will request to conserve memory. The client negotiates packet size at the time of connection. The server will allocate the full packet size and if some clients use a smaller size then that memory is wasted.

Open Server Connect 4.0 for CICS

The newest release including the latest EBF, supports several great new features:

Gateway-less MVS connectivity (TCP/IP only) Expanded network support (choice of 4 separate TCP/IP network drivers)Enhanced TCP/IP security management and tracing – new listener and transaction

user exit (with EBF I0185 or greater)

Connecting to the mainframe over TCP/IP

MDI Gateway required SNA LU6.2 connectivity to MVS-CICS. DirectConnect provides improved connectivity to MVS-CICS, with support for both APPC SNA LU 6.2 and TCP/IP connectivity. See the Installation and Connectivity section in Chapter 5 for more information.

Service name redirection

The new DirectConnect provides the ability to transparently route specific clients to specific services, based on their profile. You can use this feature to consolidate gateways, to improve customizations of the gateway for each application, and to add an extra measure of security. See Service Name Redirection in the Gateway Consolidation section of Chapter 3 for the details.

Support for consolidating gateways

DirectConnect provides a number of features that customers are using to better manage large sprawling gateway deployments (see Architecture and Platforms in the Gateway Consolidation section of Chapter 3).

6

Application development enhancements

DirectConnect now supports a variety of new capabilities you can exploit for application development, including:

New-and-improved SQL transformation (for DB2 Access Service only) sp_sqlgetinfo (for DB2 Access Service only) Several Transfer enhancements (for DB2 Access Service only) Datatype enhancements, including additional datatype conversion options,

support for incoming datatype conversion and support for new datatypes (for DB2 Access Service only)

Cursor and dynamic event support

For details on these new capabilities, see the Application Development section of Chapter 3.

Native connectivity from PowerBuilder

Native support for DirectConnect into PowerBuilder is available with DirectConnect for MVS release 11.6. See MVS Connectivity Enhancements in the Supported Platforms and Improved Connectivity section of Chapter 3 for additional information.

New ODBC 3.0 compliant DirectConnect drivers

A new set of DirectConnect ODBC drivers is available with the DirectConnect for MVS release 11.6. EBFI0211 is our latest GA (generally available) ODBC driver.

Systems Management

DirectConnect Manager provides systems management for the DirectConnect products. See Systems Management section in Chapter 3.

7

2. Migration ProcessThis section discusses a wide variety of issues surrounding migration of the Database Gateway and Net Gateway products to the new DirectConnect product set. The following topics are included:

Platforms supported Selecting a DirectConnect service for migration Getting Started Migrating from MDI Database Gateway Migrating from Net Gateway

Platforms supportedDirectConnect supports four core platforms:

AIX HP-UX Solaris Windows NT

DirectConnects will not be delivered on Sun4 OS, OS/2, AT&T UNIX, and Netware platforms.

Customers with any of the discontinued platforms are entitled to a no-charge upgrade of their licenses for DirectConnects on supported platforms.

Selecting a DirectConnect service for migration

Database Gateway customers

Database Gateway customers looking to migrate existing applications to DirectConnect should use the DB2 Access Service. The DB2 access service can be configured to behave similar to a Database Gateway.

Applications using MDI Database gateway, generally: Use Dynamic SQL to access target data Use ODBC or native interface front-end applications Access multiple, heterogeneous databases Use transfer Need to be highly-configurable to support many types of Decision Support

applications Use OmniConnect

8

Net Gateway customers

For Net Gateway customers looking to migrate existing applications to DirectConnect should use Transaction Router Service (TRS). TRS can be configured to behave similar to a Net Gateway.

Applications using Net Gateway, generally: Require handling execution of large numbers of remote mainframe

transactions Have very high performance thresholds

Getting StartedYour initial focus in migrating existing applications is to set up the new products side-by-side with the old, in order to test compatibility. To help you with this effort — Chapters 3 - 5 cover issues surrounding preparation of a test environment for the new product set, with special focus on duplicating environments. Data Access Features (Chapter 3) – covers new features and components Product Compatibility & Requirements (Chapter 4) – details hardware, software

and system requirements for the new products. Installation & Coexistence (Chapter 5) – explores issues surrounding installation of

the new products, with a focus on coexistence of old and new products in the same environment.

Specific information relating to issues for migrating from Net Gateway or MDI can be found in the following sections.

Migrating from MDI Database GatewayThe remaining chapters cover migration issues – from a feature/functionality standpoint: Configuration Migration (Chapter 6) – Converting Old MDI Database Gateway

Configurations section — describes how to create new configurations that map to your existing configurations.

Migration: Client Connectivity (Chapter 7) – covers Open Client, ODBC, PowerBuilder and other tools, and networking issues.

Migration: Gateway Servers (Chapter 8) – MDI Database Gateway section — covers gateway functionality, including Transfer, RPCs, datatype conversions, CSPs, and much more.

Migration: RSPs & Open ServerConnect (Chapter 9) – covers application compatibility, especially for RSPs.

Migration: CSAs & Open ClientConnect (Chapter 10) – covers application compatibility, especially for CSAs.

9

Interoperability (Chapter 11) – defines migration issues surrounding product interoperability.

Current Migration Issues (Chapter 12) — up-to-date migration issues that are not feature-related bugs, that may effect migration. This section will be updated regularly to provide you the latest status.

Migrating from Net GatewayThe remaining chapters cover migration issues – from a feature/functionality standpoint: Configuration Migration (Chapter 6) – Converting Old Net Gateway

Configurations section — describes how to create new configurations that map to your existing configurations.

Migration: Client Connectivity (Chapter 7) – covers Open Client, ODBC, PowerBuilder and other tools, and networking issues.

Migration: Gateway Servers (Chapter 8) – Net Gateway section — covers gateway functionality, including RPCs, datatype conversions, CSPs and much more.

Migration: RSPs & Open ServerConnect (Chapter 9) – covers application compatibility, especially for RSPs.

Migration: CSAs & Open ClientConnect (Chapter 10) – covers application compatibility, especially for CSAs.

Interoperability (Chapter 11) – defines migration issues surrounding product interoperability.

Current Migration Issues (Chapter 12) — up-to-date migration issues that are not feature-related bugs, that may effect migration. This section will be updated regularly to provide you the latest status.

10

3. Data Access Features

11

This chapter will highlight some of the new features and benefits in the new product set. We will cover the following topics:

Performance More! Better! (Targets! Platforms! Network connectivity!)Supported

Platforms and Connectivity Gateway Consolidation Systems Management Application Development (enhancements)

PerformanceTuning - LAN packet size

We have added a new server configuration property, NetBufSize, to help you tune LAN performance.

Adaptive Server & OmniConnect

Several enhancements to DirectConnect and OmniConnect have increased overall performance and provided you with the controls necessary to provide predictable performance.

SMP

OmniConnect can be configured to use multiple engines. Each thread is assigned to a single engine, executing on that engine until the thread is terminated. Load balancing is achieved by placing new threads on the engine containing the smallest number of OmniConnect threads.

QuickPass

OmniConnect examines each query involving remote tables after the query is preprocessed. If all the referenced tables reside on the same remote server, and the remote server is capable of processing all the syntax represented by the statement, the query will be passed directly to the remote server. The result set is potentially smaller and requires less processing by OmniConnect.

Split Joins

Split Joins -- A split join is a query joining data on two or more remote servers. OmniConnect improves the performance of split joins by examining the queries

12

containing two or more tables on a single remote server. If the remote tables are joined in the query, OmniConnect may be able to modify the query plan, substituting a single virtual table for the joined tables. Omni passes the join to the remote server, treating the results as a single table.

For example, if a query involves four tables, two on remote server SERVER_A and two on remote server SERVER_B, OmniConnect will process the query as though it were a two-way join. The following query:

Select * from A1, A2, B1, B2where A1.id = A2.id and A2.id = B1.id and B1.id = B2.id

Can be converted to:Select * from V1, V2 where V1.id = V2.id

V1 is a virtual table representing the results of the join between A1 and A2, and V2 is the virtual table representing the results of the join between B1 and B2.

Language event optimization

SQL requests can be sent to the remote servers in cursor, dynamic, or language requests. OmniConnect provides optimal performance by using language requests whenever possible. The use of language requests depends upon the syntax of the request and the capabilities of the remote server.

Supported Platforms and Improved ConnectivityDirectConnect supports four core platforms:

IBM RS/6000 AIX HP Solaris Windows NT

For Database Gateway customers, this represents more platforms than previously supported. This allows you to deploy on the server platform that fits your environment best while still receiving identical functionality.

Improved MVS connectivity

DirectConnect for MVS supports use of an expanded range of mainframe connectivity options. In addition to SNA LU6.2, we support both IBM and Interlink TCP/IP (Interlink support requires

13

Open ServerConnect 4.0). You can choose the appropriate protocol to meet your company standards, or to suit the particular needs of a given application. Choice of protocol does not require you to license additional Sybase products – each component (DirectConnect, Open ServerConnect, MainframeConnect) has the built-in ability to use any protocol you choose to configure. A single DirectConnect can support all three.

MVS Connectivity Enhancements

With the rapid adoption of TCP/IP as a de facto standard, many customers have requested the option to go "gateway-less" when connecting to MVS. The release of Open Server Connect 4.0 enables you to have access directly from any Open Client or jConnect client to MVS data and applications. The so-called client application may be a server: Adaptive Server, OmniConnect, Jaguar CTS, and Replication Server, as potential clients. Supported server applications include any Open Server Connect application (running on CICS, IMS or MVS), including MainframeConnect for DB2. TCP/IP connectivity will be provided across both IBM and Interlink TCP/IP stacks.

Open ClientConnect 3.2 also supports gateway-less access (over both IBM and Interlink TCP/IP stacks) to distributed client/server data from mainframe applications.

Open ServerConnect 4.0 provides two major enhancements to MVS TCP/IP security:

A vastly improved and integrated security exit Broader network support for password management

First, this release builds in robust security integration with your existing MVS security systems (RACF, ACF II and Top Secret). This approach is in contrast to IBM, which basically requires you to code your own MVS security integration into an exit.

Second, this release will extend our support for IBM’s Password Expiration Management (PEM) interface to TCP/IP networks. See Integrated password management in the Systems Management section for more information about our new integrated password management capabilities.

Gateway ConsolidationApplications built and deployed with our legacy gateways have been so successful, that many customers find themselves with

14

twenty, thirty, or more gateways supporting thousands of clients distributed throughout their enterprise. The new architecture allows you to consolidate a number of gateways on one platform.

Architecture & platforms

DirectConnect allow you to configure an unlimited number of different logical gateways to meet your application needs. Each DirectConnect "server" supports an unlimited number of DirectConnect "services". A DirectConnect server is a physical gateway that processes data access requests received on particular network ports. A DirectConnect service is a logical gateway that provides all the connectivity and configurability you expect from a Database Gateway or Net Gateway instance. One DirectConnect server can support many services; each different service can access different targets using different network connectivity and a different set of configuration properties.

Support for running services of different types (i.e. Informix and MVS) within the same DirectConnect server requires that all service types be version 11.x or later, and that you are using the most recent version of the DirectConnect server.

This architectural flexibility when combined with the broadened platform support enables you to consolidate many gateways down to a few, allowing you to do any of the following:

Consolidate gateways for multiple targets (say Informix and MVS, for example) onto a single server

Support existing applications (with services configured for backward compatibility) and new applications (leveraging new features) on a single server

Consolidate multiple gateways to fewer, larger servers Support both APPC and TCP/IP connectivity in a single server

Customers typically are replacing multiple gateway instances on the same machine with a single DirectConnect by:

Configuring the DirectConnect server to listen on the same network ports as the previous gateway instances

Configuring a DirectConnect service to match the configuration of each gateway instance

Customers have also replaced multiple gateway server hardware with larger machines, or consolidated OS/2 and Windows NT servers to larger Unix machines.

To further increase the configuration flexibility in the DirectConnect, we added a couple enhancements; Service Name Redirection and better Systems Management tools.

15

Service Name Redirection

Service Name Redirection allows you to creatively and transparently route clients to DirectConnect services, based on their particular profile. Essentially, Service Name Redirection allows the DirectConnect Server to transparently route particular client requests to particular services.

For example, consider the case of a PowerBuilder application (version 1.01) deployed to five hundred desktops. If a new version (1.02) of that application is deployed that requires a differently configured gateway, in the previous architecture your gateway administrator would have to modify client interface files to point to a different gateway at a different network location – an extremely tedious task with hundreds of desktops.

In the new architecture, the modified PowerBuilder application could be deployed without modifying any client files. The client interfaces file would continue to refer to the "PB_HR_App" service name at the same network location. When the PowerBuilder application developer creates a new version of the application, the developer would modify the application name to describe the new version. To accomplish the transparent mapping to services supporting different versions, Service Name Redirection should be employed. A Service Name Redirection File (SNRF) like the following would be used:

requested_service userid app_name assigned_service

PB_HR_App * HR_ver 1.01 PB_HR_101

PB_HR_App * HR_ver 1.02 PB_HR_102

The client’s interfaces file would remain unchanged. The client login would indicate a requested service name, the userid, as well as an application name. Keying off the application name, Service Name Redirection will route requests for the new version to the newly-configured service, while preserving the existing routing from the original application to the original service. This would allow you to gradually deploy the application over time, trusting that the proper routing will take place automatically.

Obviously, there are many other possibilities to be exploited with the Service Name Redirection File.

All requests from a particular ASE or OmniConnect could be routed to a service, specially configured to service them.

Selected power users could be singled out for routing to high-availability, high-performance services with dedicated connectivity, while routing the broader user community to more generic services.

16

Using two different services in one application

If the same application requires two differently-configured services, the application can simply open up two connections to the DirectConnect. For example, a typical scenario may be an application where a certain amount of decision support is initially done. Ad-hoc SQL against DB2 producing large result sets with heavy datatype conversions is processed using a DB2 access service. After taking a look at the data, the user is ready to make a series of structured updates to the data. Those updates might be handled through executing a number of remote Open Server transactions through the Transaction Router Service Library.

Systems Management

DirectConnect Manager

DirectConnect Manager is a Java program plug-in for Sybase Central (Java Edition) that provides systems management for the DirectConnect family of products. DirectConnect Manager offers several features that include:

Integrated management with other Sybase products through Sybase Central (Java Edition)

The ability to list and terminate specific user threads on any DirectConnect

Full GUI management of the DirectConnect Transaction Router Service Library (TRS)

DirectConnect Manager offers an enhanced interface that allows you to easily configure and manage all your data access services from your Microsoft Windows NT or Windows 95 desktop.

Manage multiple DirectConnects simultaneously

DirectConnect Manager can manage any number of DirectConnects from a single console. The DirectConnects are visually organized into a hierarchical tree view. You can start, stop, reconfigure and/or copy services across multiple DirectConnect servers.

Dynamically-reconfigure DirectConnect

DirectConnect Manager offers a set of windows that organize all configuration properties for the respective services. All configuration properties can be changed from the console; most property changes take effect immediately allowing you to reconfigure services for trouble-shooting or application development without downing the entire DirectConnect and without going to the local machine.

17

Download DirectConnect log records

DirectConnect Manager allows you to down load remote log files. The interface provides several criteria to filter precisely which records are of interest to you, so that you don’t move megabytes of data across the network.

This is a terrific trouble-shooting tool. For example, if a help desk staffer gets a call about some strange behavior from a remote user, the staffer can activate certain logging dynamically (see above) and instruct the user to try his query again. Then, the staffer can download the log records for that user, for the current date, and look through only those records to diagnose the problem. Again, because configuration properties can be changed dynamically, the staffer may be able to correct the problem remotely.

Tracking DirectConnect statistics

The DirectConnect can now be configured to log performance statistics, for each:

request connection service transfer

These statistical records can be used to size hardware and determine operational variations in performance of your applications over time.

Integrated password management

We have integrated password management "directly" into DirectConnect for MVS. This allows users, application developers and/or system administrators to transparently query status and to update mainframe passwords. With the release of Open Server Connect 4.0, this is provided for both SNA and TCP/IP networks. Integrated password management support is built into the TRS service, for SNA only.

To take advantage of this feature, we recommend you program your applications to query password status upon startup. If the status of the password suggests imminent password expiration, your application should prompt the user for a new password. For example, your application might prompt for an update if the password is within a week of its expiration date, or if there have already been two bad password entries. Many customers use this interface to create a separate password management facility for use by system administrators. For detailed information on the PEM interface, see Integrated password management enhancements in the Database Gateway section of Chapter 8.

18

Application DevelopmentWe made a number of application development enhancements that can help simplify, improve portability and add more power to your applications.

SQL Transformation

Two new SQL Transformation modes have been added to access services: passthrough mode and sybase mode.

Sybase mode supports target independence by supporting the translation of a well-defined subset of Sybase’s Transact-SQL language to its target equivalent. It is the transformation mode utilized by the DirectConnect ODBC driver and by OmniConnect.

In contrast to previous translation modes offered by the Database Gateway products, Sybase mode will pass any unrecognized statement through to the target database (e.g., DB2). This allows the application developer to mix reliance on basic SQL translation with more complex, database-specific language.

Applications written with Sybase mode have a high degree of portability to other access services and to other Sybase data servers (SQL Server and OmniConnect).

passthrough mode is very similar to tsql0 in the Database Gateway architecture. It requires the application developer to submit target-specific SQL to the DirectConnect.

Passthrough mode is used when the developer is intimately familiar with the target SQL dialect and wishes to use it exclusively.

Applications written with passthrough mode are not portable to other database targets.

Determining a target’s capabilities

The sp_sqlgetinfo stored procedure provides a wealth of information about SQL grammar, syntax, and overall capabilities for the target database. This procedure is available in all DirectConnect access services. It can be used by client applications to allow tailoring of the application to the specific target, without requiring that knowledge of the target-specifics be hard-coded in the client applications. The access service stores this information in a file that you can modify and extend as you desire. The SQLInformationFile property specifies the path and file name.

19

Transfer

In the area of Transfer, we have made the following enhancements:

Improved datatype conversion support Better error handling Broader support for Microsoft SQL Server Faster performance for gateway-to-gateway Transfers

See the chapter on "Gateway Migration" for additional details.

Datatype conversion

In DirectConnect access services, both outgoing and incoming datatype conversions have been enhanced.

Outgoing datatype conversions occur when the DirectConnect converts result sets from the target for communication to the client application.

Incoming datatype conversions occur when the DirectConnect converts incoming datatypes to their appropriate target datatype formats.

Outgoing datatype conversions

There are many additional options for conversion of target datatypes to Open Client/Server datatypes for presentation to the client.

Specific datatype conversions can be specified with the following configuration properties: BinaryResults DateResults DateTimeResults DecimalResults FloatResults GraphicResults Int2Results Int4Results RealResults TimeResults

Additionally, specific processing (including rejecting the row, inserting a null value, truncating a value or inserting a default) can be specified via the following configuration properties: CharConvertError DateTimeConvertError NumConvertError

20

If the above properties are set to default, the values configured for the following properties might be inserted: DefaultDate DefaultTime DefaultNum

Please review the DirectConnect for MVS Access Service Library documentation for detailed explanation of each option.

There is also additional functionality for conversion of "incoming" datatypes. The DirectConnect access services return both a Sybase datatype and a unique target datatype in the sp_columns result set. A client application, like OmniConnect for example, can submit the target datatype identifier to the DirectConnect as part of a cursor or dynamic event. If given this information, the access service can perform finely-tuned datatype conversions from Sybase datatypes to target-specific datatypes. For example, it could map a Sybase DateTime into a DB2 TIME field by stripping the date information from the DateTime value.

The syntax for designating the target datatype is documented in the manuals.

Incoming datatype conversions

DirectConnect has added support for very powerful and flexible "incoming" datatype conversions. This new feature will allow the application developer to request DirectConnect to perform very specific datatype conversions on data flowing from the client application through DirectConnect to the target.

Some Sybase datatypes do not directly map to target datatypes. For example, CS_DATETIME and CS_DATETIME4 do not directly map to DB2 DATE, TIME or TIMESTAMP datatypes.

When defaults are not appropriate for these conversions, the client application can specify the intended DB2 datatype using the usertype field of the CS_DATAFMT structure. The usertype value is returned to client applications from the sp_columns result set. When this usertype field is passed back to the access service with a non-zero, non-NULL value, the access service converts the Sybase datatype into the precise target datatype. Target precision, scale, and length are also specified

21

automatically. See the chapter on "Converting Open Client/Server Datatypes" in the DirectConnect Access Service User's Guide for details.

Cursors

Cursors can be used to more flexibly manipulate result sets, to increase application performance in specific cases, and to increase the accuracy and reliability of write operations. OmniConnect leverages cursors to improve its handling of long-running transactions. This release supports server-side CT-Library based cursors to all access service targets. The Transaction Router Service supports cursors. Open Server Connect now supports command-based cursors.

Dynamic events

Dynamic events allow the developer to improve performance from dynamic SQL. Dynamic events allow a PREPARE on a parameterized SQL statement with "?" placeholders for data values to be repeatedly executed with a bound plan. Dynamic events can be used for INSERTs, UPDATEs and DELETEs.

ODBC driversThe 32-bit ODBC driver is ODBC 3.0 compliant, supports use with the DirectConnect for MVS TRS service, and ships with the current DirectConnect products.

22

4. Product Compatibility & Requirements

23

This chapter provides you with the information you need to assess your environment’s suitability for the new product set. The following topics are included:

Product Compatibility Hardware, Software & System Requirements

Product Compatibility

DirectConnect for MVS

DirectConnect for MVS is compatible with: Open ServerConnect version 3.1 and higher SQL Server version 10.0.2 and higher Replication Server release 11.0 and higher CICS 4.1 and higher, and PTF UN90057 for full functionality with the

password expiration manager (PEM) feature

MainframeConnect for DB2/MVS-CICS

MainframeConnect for DB2/MVS-CICS version 11.6 and higher is compatible with the following platform and operating system configurations:

CICS version 4.1 and higher MVS/ESA DB2 4.1 and higher

Open ServerConnect

For full functionality with the current release, use these components, as available at your site:

Open ServerConnect, version 4.0 Mainframe Connect for DB2/MVS-CICS, version 11.7or

OmniSQL Access Module for DB2, release 10.1 with latest EBFs DirectConnect Transaction Router Service, version 11.1.1 DirectConnect, version 11.7 or Japanese Conversion Module, version 3.1

Open ClientConnect

For full functionality with the current release, use these components, as available at your site:

Open ClientConnect, version 4.0 Mainframe Client Connect for DB2/MVS-CICS, version 11.7

DirectConnectm version 11.7 Japanese Conversion Module, version 3.1

24

Hardware, Software & System Requirements

LAN

DirectConnect for MVS - Windows NTItem Requirements

CPU We recommend a Pentium processor. A Windows NT-compatible PC.RAM A minimum of 64MB of RAM to run Windows NT and any DirectConnect

for MVS products.Storage A minimum of 50MB, plus:

50 MB for the install tar file Space for the largest log file you expect to maintain Space for the largest trace file you expect to accommodate

Software Microsoft Windows NT Server or Microsoft Windows NT Workstation 4.0. We recommend Microsoft Windows NT Server for best performance.

Microsoft SNA Server 3.0 or higher for SNA LU6.2. Additional hardware

A CD-ROM drive for the installation CD.

Network Support For Windows NT platforms, a Windows network interface card compatible with Windows NT. We recommend a 32-bit card for best performance.

DirectConnect for MVS – AIXItem Requirements

CPU An IBM RISC System/6000RAM A minimum of 64MB of RAM to run AIX and any DirectConnect for MVS

products.Storage A minimum of 50MB, plus:

50 MB for the install tar file Space for the largest log file you expect to maintain Space for the largest trace file you expect to accommodate At least 500,000 bytes for each locale you plan to support.

Software Production version of AIX 4.1.x, 4.2, or 4.3 SNA Server for AIX 3.1.1 or 4.2

orSNA Communications Server 5.0.3.0

Note: There are known issues with IBM's SNA Communications Server version 5 and eNetworks.

Additional hardware


Network Support An interface card compatible with AIX

DirectConnect for MVS – HPItem Requirements

CPU An HP 90000(8xx).RAM A minimum of 64MB of RAM to run HP 9000(8xx) and any

DirectConnect for MVS products.Storage A minimum of 50MB, plus:

50 MB for the install tar file

25

Space for the largest log file you expect to maintain Space for the largest trace file you expect to accommodate

Software Production release of HP-UX, Release 10.10 or Release 10.20.SNA connectivity ONLY:For HP-UX 10.10 use one of the following:SNAplus-Link, Release 4.3 and SNAplus-API, Release 4.3ORSNAplus2-Link Release 5.0 and SNAplus2-API, Release 5.0For HP-UX 10.20 use:SNAplus2-Link, Release 5.1 and SNAplus2-API, Release 5.1

Additional hardware


Network Support An interface card compatible with HP 9000(8xx).

DirectConnect for MVS – SolarisItem Requirements

CPU A Sun Solaris (SPARC) system.RAM A minimum of 64MB of RAM to run Sun Solaris and any DirectConnect

for MVS products.Storage A minimum of 50MB, plus:

50 MB for the install tar file Space for the largest log file you expect to maintain Space for the largest trace file you expect to accommodate

Software Production release of Sun Solaris 2.5.1. or 2.6.1 Sunlink Peer-to-Peer 9.0 (for SNA ONLY).

Additional hardware


Network Support An interface card compatible with Sun Solaris.

MVS

MainframeConnect for DB2/MVS-CICSItem Requirements

System Requirements

The following compatible platform and operating system components: An OS/390 or MVS/ESA environment running on an IBM

System/390 mainframe adequate to support CICS and DB2. A DB2 application running on an IBM System/390 mainframe. VTAM running on an IBM System/390 mainframe. One of the following versions of NCP: NCP, Version 4.5 for 3725 and parallel session support NCP, version 5.2 for 3745 and parallel session support

Special System Requirements

The following may be required depending on your system configuration: If you are using a channel-attached 3174 model 11L (cluster

controller) and want to use parallel sessions the following requirements apply:

VTAM, version 3.4 or higher. MVS/ESA Appropriate applied RPQs. Contact IBM for details for this

configuration. Microcode Level "C". APPN LIC Feature. Contact IBM for details for this

26

configuration. If your site uses IBM RACF, make sure you have the appropriate

updates to support APPC. If your site uses ACF2 or Top Secret security packages from

Computer Associates, we strongly suggest you contact the vendor before proceeding with your LU 6.2 installation, to ensure that you have the release, user modifications, and fixes necessary to support APPC processing.

If you are using ACF2 Release 5.2, you need to obtain and apply APAR UM87688 from Computer Associates.

Performance Considerations

The line speed between DirectConnect and the mainframe is critical in determining the overall transaction throughput. Based on the type of connection:

Using SDLC: For short and simple queries, SDLC lines of 9.6K, 19.2K, and

56K bytes per second yield 2-15 concurrent transactions per second. If you choose to use SDLC consider upgrading the SDLC link speed or adding more SDLC links.

Using Token Ring: For transferring large amounts of data (over 10,000 bps), install a

Token Ring LAN connection through a 3172, 3174, or 3745, to the clients and servers.

Mainframe Access Components

Verify you have the following mainframe access components: Open Server Connect for CICS/MVS, release 3.1 or higher. Japanese Conversion Module (available upon request), release

3.1 or higher. DirectConnect for MVS, release 11.7 or higher.

Space Requirements

Disk space required for installation, 37 tracks on a 3390 disk driver.

Note: For complete software requirements, see MainframeConnect for DB2/MVS-CICS Installation and Administration Guide.

Open ClientConnect for CICSItem Requirements

Hardware IBM Mainframe: S/390 or plug compatibleIBM Front End Processor: 372x, 3745, or compatibleIBM Network Controller: 3172IBM TIC attachment or 3174 (Token Ring Gateway is used)

Space Requirements

DASD space to unload Open ClientConnect for CICS/MVS libraries from the base tape is approximately 2.7MB. The dataset sizes, by device, are as follows:

3350 - 4.5 cylinders 3380 – 3.7 cylinders 390 – 3.25 cylinders 9345 – 4.0 cylinders

DASD space to unload Open ClientConnect for CICS/MVS libraries from the API tape is approximately 6.0MB. The dataset sizes, by device, are as follows:

3350 – 11.0 cylinders 3380 – 8.5 cylinders 3390 – 7.6 cylinders 9345 – 9.0 cylinders

27

DASD space to unload RSP libraries from the base tape is approximately 10.4MB. The dataset sizes, by device, are as follows:

3350 - 17 cylinders 3380 – 14 cylinders 3390 – 12 cylinders 9345 – 15 cylinders

Software MVS/XA, ESAVTAM, Version 3.4 or higherNCP, Version 5.xCICS, Version 4.1 or higherDB2, Version 4.1 or higherIBM TCP/IP 3.1 or higherInterlink TCP/IP 3.1 or higher

For planning, installation, and configuration information, see the Open ClientConnect Installation and Administration Guide for IBM CICS/MVS.

Open ServerConnect for CICSItem Requirements

Hardware IBM Mainframe: S/390 or plug compatibleIBM Front End Processor: 372x, 3745, or compatibleIBM Network Controller: 3172IBM TIC attachment or 3174 (Token Ring Gateway is used)

Space Requirements

DASD space to unload Open ServerConnect for CICS/MVS libraries from the base tape is approximately 5.7MB. The dataset sizes, by device, are as follows:

3350 – 77 tracks 3380 – 62 tracks 390 – 52 tracks 9345 – 63 tracks

DASD space to unload Open ServeConnect for CICS/MVS libraries from the API tape is approximately 3.5MB. The dataset sizes, by device, are as follows:


DASD space to unload RSP libraries from the base tape is approximately 6.4MB. The dataset sizes, by device, are as follows:


Software MVS/XA, ESAVTAM, Version 3.4 or higherNCP, Version 5.xCICS, Version 4.1 or higherDB2, Version 3.1 or higherIBM TCP/IP 3.1 or higherInterlink TCP/IP 3.1 or higher

28

5. Installation and Coexistence

29

This section focuses on the installation steps for the new DirectConnect product set:

Installation Steps Connectivity Target Installation DirectConnect Server Installation Client Installation Coexistence

Installation StepsAll installation guides include a set of detailed installation checklists for the respective product components and should be referenced. Following is one possible scenario for installing DirectConnect that you may use as an end-to-end checklist.

It identifies the major steps for installing DirectConnect, the required tasks, reference sections within this document, and identifies the product documents that are available.

Installation Checklist

Installation Steps Installation Tasks References

Mainframe and Connectivity Installation

(for additional information refer to the Connectivity and Target Installation topics in this chapter)1. Define SNA LU6.2 or TCP/IP

configuration to allow the DirectConnect server to connect to the mainframe.

Install and configure TCP/IP or SNA. DirectConnect for MVS Connectivity Guide. For additional information refer to the appropriate vendor documentation.

2. Install Open ClientConnect and Open ServerConnect Base Tape.

Install and configure the Open ServerConnect Base Tape to enable MainframeConnect and/or Open ServerConnect.

Install and configure the Open ClientConnect Base Tape to enable Open ClientConnect.

Open ClientConnect Installation and Administration Guide for DB2/MVS-CICSOpen ServerConnect Installation and Administration Guide for DB2/MVS-CICS

3. Install MainframeConnect Mainframe Connect Installation and Administration Guide for DB2/MVS-CICS

4. Verify that MainframeConnect is running properly and connected to DB2

Type AMD2 to test the Mainframe Connect transaction.

Mainframe Connect Installation and Administration Guide for DB2/MVS-CICS

5. Install Open ServerConnect API(Install RSP libraries, if appropriate)

Open ServerConnect Installation and Administration Guide for DB2/MVS-CICS

6. Install Open ClientConnect API(Install CSA libraries, if appropriate)

Open ClientConnect Installation and Administration Guide for

30

DB2/MVS-CICS

DirectConnect Server Installation

(for additional information refer to the DirectConnect Server Installation topic, in this chapter)1. Install DirectConnect for MVS on a

test machine. Choose the option that allows

installation of a sample access service.Following your installation, make a copy of the sample service; keep the original unchanged for your reference.

DirectConnect for MVS Installation Guide (within the installation guide refer to the chapter for your platform: Windows NT, AIX, HP-UX, or Sun Solaris).For additional installation instructions refer to: http://techinfo.sybase.com:80/css/techinfo.nsf/DocID/ID=20470

2. Test the Connectivity between the DirectConnect server and the MVS mainframe.

Use the cicsping or snaping utilities to verify your connectivity.

The cicsping and snaping utilities are distributed with the DirectConnect software. Instructions and a sample can be found in the DirectConnect for MVS Installation Guide.

3. (Optional) If running on a Windows NT server, you may install DirectConnect Manager on the server.

Test connectivity using DirectConnect Manager

DirectConnect Manager for Microsoft Windows NT and Windows 95 Installation Guide.

4. Configure one DirectConnect service.Configure the Server, the DB2 access service, the TRS access service, and the service library.

If you did not install DirectConnect Manager on the server, then configure the DirectConnect Server by editing its text files.

Alter the sample access service you copied previously with any required site-specific properties

DirectConnect Server Administration GuideDirectConnect Access Service User's GuideDirectConnect Transaction Router Service User's Guide

5. Verify application connectivity between DirectConnect and the target.

Simulate a connection by using the isql utility on the DirectConnect server platform to perform this test. For example, select * from tablename

Client Installation

(for additional information refer to the Client Installation topic, in this chapter)

1. Test network connectivity to verify that the your workstation is connected to the LAN and the network protocol is configured correctly.

2. Verify or install Open Client and the ODBC driver on your workstation.

Open ClientConnect Installation and Administration Guide for DB2/MVS-CICS

3. Use the sqledit utility on the client to ping the LAN server application.

31

4. Verify application connectivity between the client and the mainframe. Use the isql utility on the client platform to perform this test.

Use the isql utility to connect to the DirectConnect server and test the connection through to the mainframe. For example, select * from tablename

Open ClientConnect Installation and Administration Guide for DB2/MVS-CICS

5. Test your applications.

6. Identify and resolve any error conditions.

7. Follow your local procedures for placing the new services into production.

Connectivity

The new architecture supports SNA LU6.2, IBM TCP/IP and Interlink TCP/IP connectivity between the LAN and the mainframe.

Target InstallationIn the new architecture, MVS-CICS installation may involve from one to three possible product installations:

Open ServerConnect for CICS Open ClientConnect for CICS MainframeConnect for DB2/MVS-CICS

You do not need to install all three products unless you require the functionality provided by each. Each product is self-contained.

Database Gateway customers must install both MainframeConnect for DB2 and Open ServerConnect API to support backward compatible execution of Remote Stored Procedures (RSPs) in the new architecture. Open ClientConnect API is required to support Client Services Applications (CSAs).

MainframeConnect for DB2/MVS-CICS InstallationMainframeConnect is composed of two libraries:

MainframeConnect Library Open ServerConnect CICS Base Tape Library

The first tape provides DB2 access; the second tape provides LAN-to-mainframe connectivity. When installed, these libraries provide everything required to provide connectivity between the DirectConnect and DB2/MVS.

32

The default transaction name for MainframeConnect release 11.7 is AMD2. The previous products used the following default names:

MDI for MDI Access Server SYRT for OmniSQL Access Module for DB2/MVS-CICS

The shipped library names are unique.

Installing Catalog Stored Procedures for TRS

If you plan to use TRS for DB2 access, you will need to install a new set of mainframe-based CSPs. These CSPs are included with MainframeConnect.

Generally, we encourage you to use the DB2 Access Service for applications that use dynamic SQL for DB2 access.

Preserving customized messages

Customized messages are a part of the AMD2 message module, AMD2CAMX. If your site has added customized messages that are not just DB2 standard messages, preserve them before installation of MainframeConnect. You can add these messages to AMD2CAMX after installing this release.

Open ServerConnect InstallationOpen ServerConnect is composed of two tapes:

Open ServerConnect API Library Open ServerConnect CICS Base Tape Library

The first tape provides the Open ServerConnect API (RSPs and RPCs) while the second tape provides the connectivity libraries. These libraries provide everything required for connectivity between the DirectConnect and Open Server applications.

Open ClientConnect InstallationOpen ClientConnect is composed of two libraries:

Open ClientConnect API Library Open ClientConnect CICS Base Tape Library

The first tape provides the Open ClientConnectAPI (CSAs) and the second the connectivity. These libraries are required to provide connectivity between MVS-CICS Open Client applications and LAN data sources. If SNA LU6.2 connectivity is employed, then Mainframe Client Connect must also be installed.

33

DirectConnect Server Installation

DirectConnect Environment

DirectConnect consists of a server and one or more service libraries. The server provides the framework for the service libraries to operate. Each Access Service library accesses data from a particular target database, such as AS/400, DB2, Informix, ODBC, and others. The Transaction Router Service library provides high-performance RPC routing to MVS, MVS/CICS and MVS/IMS environments.

A given DirectConnect service library can be used to create any number of services for access to target data and applications. A "service" is analogous to a Database Gateway or Net Gateway "instance", in that it provides a specific configuration for access to a target. Different services may transform datatypes differently, use different networks, or communicate to different target machines. However, unlike an "instance", a "service" is not a physical server, it is not a separate executable, it does not require a separate process or thread, and it does not listen on a specific network port. The DirectConnect server performs the physical functions of a server for every service you decide to configure.

An Access Service does the following: Provides configurable access to a target Transforms SQL Supports remote procedure calls (RPCs) Transfers data between targets Supports catalog stored procedures (CSPs) and system stored

procedures received from OmniConnect and/or ODBC drivers

The Transaction Router Services does the following: Provides configurable access to a target Passes SQL to DB2-compliant targets (DB2/MVS and InfoHub) Executes mainframe applications on MVS, MVS/CICS and/or

MVS/IMS Supports catalog stored procedures (CSPs) and system stored

procedures received from OmniConnect

34

Common Subdirectories

When you start the DirectConnect Server, it uses the server name you supply to locate a particular subdirectory. Within the directory tree, each server name must be unique and must identify a server instance. Thus, each server has its own context, including separate message files, service libraries, and configuration files.

A ServerName subdirectory is identified as follows: $SYBASE/econnect/ServerName

where: econnect identifies the base of the Enterprise Connect family of

products. ServerName identifies a DirectConnect subdirectory tree.

Only one econnect subdirectory can exist in a $SYBASE directory tree, but multiple DirectConnect Servers can exist within the econnect subdirectory. Within $SYBASE, all dependent components must have compatible Sybase revision levels.

The common directories installed under econnect are outlined in the following table.

The subdirectories installed under the ServerName subdirectory are outlined in the following table.

35

Directory Structure for Windows NT Platforms

The utility setup copies all DirectConnect for

DirectConnect installation components

The DirectConnect product itself is composed of several different modular components and a set of installation utilities. A series of prompts during installation allow you to control what components get installed.

When you install the DirectConnect, you install several different components:Client Installation

Several elements may be required to enable client access to DirectConnect:

Open Client installation (required) DirectConnect ODBC Driver installation (optional) DirectConnect Manager installation (optional)

Open Client installation

Sybase Open Client software provides connectivity from client platforms to the DirectConnect server platform. The environment requirements of Open Client make it easy to deploy and maintain. Open Client requires a specific

36

directory structure and specific file locations, environment variables and paths.

On a given workstation, you must install Sybase Open Client Client-Library and Net-Library before installing the DirectConnect ODBC driver.

DirectConnect ODBC Driver Installation

Currently, the DirectConnect ODBC Driver allows ODBC applications to Connect to DirectConnect access services and TRS. The driver is a Level 3 ODBC driver and supports Microsoft Windows 32-bit environments. To-date, access services exist for the following targets: AS/400 DB2/MVS Informix Microsoft SQL/Server Anywhere (ODBC)

On a given workstation, you must install Sybase Open Client Client-Library and Net-Library before installing the DirectConnect ODBC driver.

DirectConnect Manager installation

Installation of DirectConnect Manager is optional, but highly recommended. DirectConnect Manager prevents common configuration errors and provides built-in help to assist with configuration. It is a 16-bit Windows-compatible GUI application that can run on Windows95 and Windows NT machines.

Install DirectConnect Manager after you install the DirectConnect but before you finish configuring DirectConnect.

The installation process itself will let you create sample services and these should be customized for your environment using Configuration Manager.

CoexistenceOur customers typically like to install old and new products side-by-side in test environments as they work through the process of migration. Minimizing the differences between installation of old and new products as much as possible aids trouble-shooting efforts and allows side-by-side comparisons between the products. To

37

help you with both of these efforts this section will review various issues with product coexistence.

Gateways

You can easily setup older gateways and DirectConnect products on the same LAN server for testing. The gateways can share common communications configurations (the same remote and partner LU, for example) with the older products, which should help you with your testing. Gateway coexistence issues usually involve proper setup of configuration files and accommodating different server connectivity libraries.

DirectConnect & Database Gateway, v. 2.05

You should install the DirectConnect under a dedicted unique parent directory. The parent directory is the SYBASE variable value. For example, if the default directory is MDIMSV25, then the Sybase variable should be SYBASE=drive:\DC117. DirectConnect files can then be installed within the \econnect sub-directory beneath the Sybase parent directory. The resulting directory structure for the DirectConnect files, might be drive:DC117\econnect\ etc. The DirectConnect will use the Open Server libraries installed in DC117 and the ini file in DC117\ini.

DirectConnect & Database Gateway, v 2.03.x and later

Other versions of the Database Gateway were built on the Microsoft ODS infrastructure—not Open Server. Therefore, you can easily install DirectConnect and Database Gateway on the same machine as the older gateways, by using separate directory structures.

Mainframe

MainframeConnect, Open Server Connect, Open Client Connect and the Access Server 2.03.x or 2.05.x) can exist in the same CICS region. You will want to be careful about CSP and RSP coexistence.

Mainframe CSP coexistence

Net Gateway users migrating to the TRS service will be using a new set of CSPs for the new product set. These new CSPs return additional information required by OmniConnect and Adaptive Server, PowerBuilder and our ODBC drivers. However, installation of the new CSPs

38

within the same CICS region as the older CSPs will require additional steps. Therefore, we created a Technical Newsletter to help you. You can access the newsletter on the Technical Information Library Index View at

http://techinfo.sybase.com/css/techinfo.nsf/DocId/ID%3D83573

RSP coexistence

To use your existing RSPs with full backward compatibility, there are no changes required to your RSP application code. However, you will need to re-link your existing RSPs with the new RSP stub libraries. Once you have re-linked with the new stub libraries, you can run the same RSP program within the same CICS region and access it through both MainframeConnect and the Access Server. This will allow you to use the products side-by-side in development, test, and production regions.

Two specific EBFs must be installed to enable this feature: Open Server Connect v. 3.1 (EBF i0078) or later version MainframeConnect v. 11.1 (EBF i0077) or later version

39



6. Configuration MigrationAs you prepare to test existing applications with the new DirecConnect products, you will want to configure the new products as closely as possible to your existing gateway configurations. This chapter contains information to help convert your existing configuration files and parameters to those used in the new architecture.

Converting Old Net Gateway Configurations Converting Old Database Gateway Configurations OmniSQL Access Module for DB2

Converting Old Net Gateway Configurations

Startup parameters

In the new architecture, the Transaction Router replaces the Net Gateway. Because TRS is not a stand-alone component like its predecessor, its startup parameters have been migrated to DirectConnect Server and TRS Library configuration properties.

The following table indicates how to map your existing startup parameters into DirectConnect configuration properties:

Startup

ParametersNew Location New Configuration

Property

40

DirectConnect Server

TransactionRouterService

-M flag MaxServer Connections = Connections

-N flag RemoteSites = numsitehandlers

-R flag RPCInfoFile = newpath-P flag PEMDest = destsys-G Flag LogInfoFile = newpath-T and -t flags TraceTAS = long/short/no-O flag Security = yes/no-D flag DirectPrevent = yes/no-K flag Accounting=yes/no AccountFile=newpath-E flag UseDBRPC=ýes/no-V flag TruncateLV=yes/no-C flag UpperCase=yes/no-L flag ConnInfoFile=newpath-Q flag ConQTimeout=timeout-d flag DeactCon=yes/no SNATraceFile=newpath-I flag Interfaces file now defaults

to ini sub-directory of $SYBASE

-J flag Character set configured in locales.dat file

-z flag National language configured in locales.dat file

-S flag No longer needed

Configuration files

DirectConnect TRS stores the files used to maintain lists of RPCs, userids, transaction groups, etc in new locations. The file names are listed on the left of the chart and the old and the new locations are listed on the right.

File Names File Locations

PCPlatforms

UNIXPlatforms

Net-GW(Old)

DirectConnect(New)

server.tds ngtds.server $SYBASE $SYBASE/eConnect/log

server.log nglog.server $SYBASE $SYBASE/eConnect/log

server.rpc ngrpc.server $SYBASE $SYBASE/eConnect/cfg

server.reg ngreg.server $SYBASE $SYBASE/eConnect/cfg

41

server.cid ngcid.server $SYBASE $SYBASE/eConnect/cfg

server.grp nggrp.server $SYBASE $SYBASE/eConnect/cfg

server.act ngact.server $SYBASE $SYBASE/eConnect/cfg

42

Converting Old MDI Database Gateway ConfigurationsIn the new architecture, many existing configuration properties have been deleted, re-named or re-implemented. The table below lists the original configuration property, an associated release version, its new name (if any), the location where that property is now configured, and an explanation of the change.

Access ServerMany of the Access Server configuration properties are now configured at the DirectConnect or Open Server Connect. Many configuration properties have also been re-named or eliminated.

To assist your migration, the table below lists the original configuration property, its new name (if any), and comments, including the location ([ ])where that property is now configured. In the tables below we will use the following abbreviations:

N/A…Not applicable DirectConnect for MVS DB2 Access Service…DB2 Acs Svc DirectConnect server…DC Srv MainframeConnect for DB2…MFC DB2

Legacy Config Property Name

New Config Property Name

Explanation

Tuning Parameters

43

Maximum Record Size N/A Maximum Block Size N/A Maximum Request Size

N/A

Maximum Result Size MaxResultSize [DB2 Acs Svc].No. of Blocs in a Chunk

N/A Chunking is no longer supported



Explanation

Processing Parameters Temporary Storage Type

Temp storage queue type

[MFC DB2].

Force First 25 Rows? N/A [DB2 Acs Svc]. No longer supported

Allow Binary Data? DisableBinary-Results

Date Format DateResults

[DB2 Acs Svc]. Replaced by several new config props

Time Format TimeResults

[DB2 Acs Svc]. Replaced by several new config props

Catalog Refresh Location

N/A No longer supported (PC/SQL-link only)

Character Null N/A No longer supported (PC/SQL-link only)

Numeric Null N/A No longer supported (PC/SQL-link only)

Treat Empty RSP Input Pipe as Error?

N/A This property is always assumed to be TRUE

Host decimal separator translation

TargetDecimal-Separator

[DB2 Acs Svc].



Explanation

Transaction Management Parameters

Commit/Rollback Method

TransactionMode [DB2 Acs Svc].

Treat RSPs as a Unit of Work?

N/A This property is always assumed to be FALSE

Request Validation Exit Request exit name [MFC DB2].Result Validation Exit Result exit name [MFC DB2].

Legacy Config New Config Explanation

44

Property Name Property NameCatalog Access Parameters

Catalog Qualifier CSPCatalogQualifier [DB2 Acs Svc].Include System Tables CSPIncludeSystem [DB2 Acs Svc].Exclude Non-Authorized

CSPExclusions [DB2 Acs Svc].

Include Public Tables CSPExclusions [DB2 Acs Svc].Group-ID Support Group ID exit name: [MFC DB2]. Exit names designate the

security packageDB2 Parameters Default Database Name N/A No longer supported (PC/SQL-link

only)System Database Name Host Request Library [MFC DB2].System Table Qualifier CSPCatalogQualifier [DB2 Acs Svc].Return Column Labels? N/A Always NO.



Explanation

Miscellaneous Administration Password

N/A No longer supported

Activate Notification N/A No longer applicableCleanup Transaction ID N/A Fixed by Open Server

Database Gateway

Database Gateway Configuration Property

New Configuration Property

Note/Explanation

Client Connection Properties

Service Name See note [DB2 Acs Svc] A {ServiceA} heading in the DB2 Access Service Library configuration file denotesthe service name

Shareable N/A No longer supportedSocket Number See note [SQL.INI] Network addresses for

Connectivity to the DirectConnect Server are now configured in the SQL.INI file.

SPX Name/Socket See note SQL.INITCP/IP Port See note SQL.INIBanyan Street Talk Name

See note SQL.INI

Decnet Name See note SQL.INI

45



Note/Explanation

Communication Properties

Local LU Alias ConnectionSpec1 DB2 Access Service{Target Interaction}

Partner LU Alias ConnectionSpec2 DB2 Access Service{Target Interaction}

Session Mode ConnectionSpec3 DB2 Access Service{Target Interaction}

TP Name TPName DB2 Access Service{Target Interaction}

Database Name N/A InfoHub propertyAPPC Security APPCSecurity DB2 Access Service

{Target Interaction}Password Required PasswordRequired DB2 Access Service

{Target Interaction}Compression N/A No longer supportedAllocate Allocate DB2 Access Service

{Target Interaction}ASCII-EBCDIC Convert Table

No longer supported.

Database Gateway ConfigurationProperty


Note/Explanation

Gateway Parameters Autostart Database Gateway

EnableAtStartup Specifies whether an access service is enabled at the time the DC Server starts. DB2 Access Service

{Client Interaction}Maximum Number of Clients

MaxConnections Specifies the maximum number of clients that can log on to the DC Server at one time. DC Server

MaxSvcConnections Specifies the maximum number of clients that can log on to a particular DC access service at one time. DB2 Access Service

{Client Interaction}Client Idle Timeout ClientIdleTimeout DB2 Access Service

{Client Interaction}Application Validation Filename

ApplicationValidationFile DB2 Access Service{Client Interaction}

Quoted String Delimiter QuotedStringDelimiter DB2 Access Service{Target Interaction}

46

CSP Qualify by DBNAME CSPQualDBName Introduced in v 2.05. DB2 Access Service

{Catalog Stored Procedures}

CSP Include System Tables

CSPIncludeSystem DB2 Access Service{Catalog Stored Procedures}

TableTypes: System CSPIncludeSystem Introduced in v 2.05. DB2 Access Service


Table Types: View CSPIncludeView Introduced in v 2.05. DB2 Access Service


Table Types: Synonym CSPIncludeSynonym Introduced in v 2.05. DB2 Access Service


Table Types: Table CSPIncludeTable Introduced in v 2.05. DB2 Access Service


Table Types: Alias CSPIncludeAlias Introduced in v 2.05. DB2 Access Service


CSP Catalog Qualifier CSPCatalogQualifier DB2 Access Service{Catalog Stored Procedures}

CSP Include Public Tables CSPIncludePublic DB2 Access Service{Catalog Stored Procedures}

CSP Exclude Non-Authorized

CSPExclusions DB2 Access Service{Catalog Stored Procedures}



Note/Explanation

Client Parameters Maximum Number of Rows

MaxRowsReturned DB2 Access Service{Client Interaction}

Maximum Result Size MaxResultSize DB2 Access Service{Client Interaction}

Request Transform Level

SQLTransformation DB2 Access Service{Target Interaction}

Transaction Mode TransactionMode DB2 Access Service{Client Interaction}

Verbose Messages SendWarningMessages DB2 Access Service

47

{Client Interaction}Stop Condition StopCondition DB2 Access Service

{Target Interaction}Decimal Separator is Comma

ClientDecimalSeparator Introduced in v 2.05. DB2 Access Service

{Client Interaction}



Note/Explanation

Data Type Conversions ByteInt N/A SmallInt Int2Results DB2 Access Service

{Datatype Conversion}Integer Int4Results DB2 Access Service

{Datatype Conversion}Char N/A L Varchar N/A Float FloatResults DB2 Access Service

{Datatype Conversion}Decimal DecimalResults DB2 Access Service

{Datatype Conversion}Date DateResults DB2 Access Service

{Datatype Conversion}Time TimeResults DB2 Access Service

{Datatype Conversion}Timestamp DateTimeResults DB2 Access Service

{Datatype Conversion}



Note/Explanation

Data Conversion Errors

Character Conversion Errors

CharConvertError DB2 Access Service{Data Conversion Errors}

Numeric Conversion Errors

NumConvertError DB2 Access Service{Data Conversion Errors}

Date/Time Conversion Errors

DateTimeConvertError DB2 Access Service{Data Conversion Errors}

Default Date DefaultDate Default Time DefaultTime Summary Message Level

SendWarningMessages DB2 Access Service{Client Interaction}

48



Note/Explanation

Troubleshooting Parameters

There are many additional Logging & Tracing options available in the DirectConnects. Refer to the manuals for details.

Detailed Trace Options N/A Log File Name LogFileName DC ServerMax File Size LogFileSize DC ServerViewlog Pipe Name N/A Activate Trace of Host Server Files

TraceTarget DB2 Access Service{Tracing}

Display Trace on Screen

TraceToScreen DC Server

Trace Timing & Major Steps

N/A

Trace SQL Request as Received

LogReceivedSQL DB2 Access Service{Logging}

Trace SQL Request as Transformed

LogTransformedSQL DB2 Access Service{Logging}

Trace Host Communications

TraceHostCom DB2 Access Service{Tracing}

Open Server/Open Client customization propertiesInformation to customize your Open Server/Open Client environment is accomplished through executing SYCTCUST JCL.

Legacy Property New Property ExplanationACCESSCODE ACCESSCODESW DBCS Applies only to TRSDEBUGSW Applies to MFC DB2DECPOINT Configured at DC for DB2

Accesss ServiceDEFLTPROTOCOL DQUOTETRAN IMSLOGTYPE LONGVARTRUNC MVSDDNAME NATLANGUAGESRV Applies only to TRSNOUDTTRAN Send UDT [MFC DB2]. The Send UDT

option is now configured for each AMD2 transaction ID.

PARSEXITNAME PARSEXITSW ROWLIMIT

49

7. Migration: Client ConnectivityThis chapter addresses a range of migration topics surrounding client connectivity. The following reviews information about the client environment that will help you migrate your clients successfully:

Open Client ODBC drivers Front-end tools

OverviewThere have been several fundamental changes to the new gateways that have a significant effect on client connectivity DLLs and libraries. If you are not using Open Client today, you will need to add Open Client to your environment. Although your client DLLs may change, your applications will not.

The gateways are now based exclusively on Sybase’s Open Server. Using Open Server requires Open Client for client connectivity. Most previous versions of the Database Gateways utilized Microsoft client libraries for connectivity—this is no longer supported.

Making connections

To connect to a DirectConnect service—which is, remember, analogous to a Database Gateway or Net Gateway instance—you need to supply two pieces of information in the interfaces file.

The name of the interfaces file entry must map to a DirectConnect service name, either directly or through Service Name Redirection.

The address of the interfaces file entry must map to a valid DirectConnect server port.

Open Client

Supported versions

Open Client versions 10.0.4 and 11.1.1 have been tested and certified.

DirectConnect requires installation of Open Client on all desktops that access the gateway directly.

51

ODBC DriversODBC support varies according to the type of service used. Different support is provided for:

access services the Transaction Router Service

ODBC & DirectConnect access services

DirectConnect ships with 32-bit ODBC drivers. These drivers work with any DirectConnect access service. The same driver can provide connectivity to DB2, AS/400 and Informix data—any data source supported by an access service. The drivers rely on sybase SQL transformation mode and several ODBC stored procedures implemented in access services to provide transparent interoperability.

ODBC & Transaction Router Service

DirectConnect 32-bit ODBC drivers provide connectivity to the Transaction Router Service.

In general, applications that issue SQL to DB2 should use the DB2 access service and the DirectConnect ODBC Drivers for connectivity.

PowerBuilder

When migrating your existing PowerBuilder applications for use with the DirectConnect, you must take care which particular PowerBuilder interface you choose for your application. Today, this choice depends on whether you are using an access service or a TRS. Both previous gateways had their own native interfaces:

Database Gateway for MVS driver Net Gateway driver

As discussed above, Database Gateway customers should migrate their applications to a DirectConnect access service, and Net Gateway customers should migrate their applications to TRS.

To use TRS with PowerBuilder, version 6.5.1, you should use the Net Gateway native driver for connectivity. For all other DirectConnect services (access services) you should use the PowerBuilder ODBC interface along with the DirectConnect ODBC drivers. .

52

Miscellaneous

PeopleSoft support

PeopleSoft applications will not be certified with the DirectConnect.

53

8. Migration: Gateway ServersThis section discusses a wide variety of issues surrounding migration of the Database Gateway and Net Gateway products to the new DirectConnect product set. We cover the following topics:

Database Gateway enhancements & changes Net Gateway enhancements & changes

Database GatewayThe DB2 Access Service provides compatibility for customer applications written to use previous releases of the Database Gateways. To ensure compatibility, the access service:

Supports RSPs that may require code changes Supports transfer syntax Provides legacy SQL transformation modes (db2, tsql0, tsql1, and

tsql2) Offers a GatewayCompatible configuration property that supports

legacy global variables and set statements Exposes a configurable version string for sending Database Gateway

version strings to client applications that depend on it (the Version property)

The DirectConnect for MVS DB2 Access Service provides compatible functions to the Database Gateway for MVS with the exceptions listed in this document.

Configuration property enhancements and changes

This section will discuss the major configuration changes between the DB2 Access Service and the Database Gateway. These changes include several enhancements, a few discontinued features and some compatibility features.

55

For a complete set of configuration migration tables, see Chapter 6, Converting Old Configurations. The specific properties discussed below are:

Allocate ApplicationValidationFile Property Disable Binary Support Parameter Gateway Compatible property Compression Summary Messages Verbose Error Messages Parameter Version Property

Allocate

The new product set does not have any direct linkage between the way conversations are allocated and the transaction model. Specifically, the Allocate property and the TransactionMode property are independent. This allows you to explicitly control commit and rollback logic even when using Allocate On Request mode.

The DB2 access service Allocate property no longer supports chunking. If you issue a set statement to change the Allocate property to CHUNK the access service returns an error.

Client validation enhanced

The access service continues to support application validation via the ApplicationValidationFile property. We recommend using the Service Name Redirection capability instead of application validation. If you choose to use both Service Name Redirection and application validation, Service Name Redirection takes precedence. See Service name redirection in the New Features section of Chapter 2 more information.

GatewayCompatible Property

To ensure application migration, the DB2 access service can mimic the Database Gateway SET statements and global variables through the GatewayCompatible configuration property. To use the Database Gateway-compatible settings, set the access service GatewayCompatible property value to yes.

When set to yes, support for old syntax and global variable names will be preserved. The DirectConnect will map an "old syntax" request to the new syntax internally. For example, the legacy statement:

set sqltransform tsql0

will be transformed internally to:set sqltransformation passthrough

56

Note that the keyword was changed and, in this case, the argument was changed as well.

As you migrate your client applications to use the new access service configuration properties, SET statements and global variables, be sure to reset the GatewayCompatible property to no.

Convert Table property eliminated

The access service does not support the Database Gateway Convert Table parameter.

Disable Binary Support property replaced

The access service BinaryResults and GraphicResults datatype conversion properties replace the Database Gateway Disable Binary Support parameter.

LAN-to-mainframe compression eliminated

The DirectConnect does not compress data sent between LAN and mainframe. We have standardized on Sybase’s Tabular Data Stream (TDS) protocol which is inherently more efficient than the previous Database Gateway proprietary protocol.

Summary Messages property not supported

The DB2 access service does not support Summary Messages.

Verbose Error Messages property replaced

We replaced the Database Gateway Verbose error messages parameter with the DB2 access service SendWarningMessages property.

Version Property

Because some customers developed applications that use the legacy gateway version string in its logic, we have added a configurable version string for each DirectConnect service. Simply set the Version property to the desired string value to enable this feature. The system stored procedure sp_helpserver will always return the true version string in its result set.

Improved SET statements, global variables and configuration properties

To ease application development and improve portability, we made DirectConnect syntax much more consistent than the Database Gateways. For example, the keyword for setting the type of SQL transformation performed is "SQLTransformation".

57

SQLTransformation = [ passthrough | sybase ] set SQLTransformation { passthrough | sybase } select@@SQLTransformation

The keyword is reflected identically in the related configuration property, SET statement and global variable, respectively.

Datatypes not supported

IXF and COBOL data types not supported

The access service does not support the little-used IXF data format in this release. Therefore, the Set Convert All and Set Convert COBOL statements will result in errors.

SQL transformation enhancements

We have added two SQL Transformation modes with the new product set:

sybase mode passthrough mode

Support for the following prior modes of SQL Transformation are also provided:

tsql0 and db2 modes tsql1 mode tsql2 mode

We have not documented use of the tsql0, db2,tsql1 and tsql2 modes because they are provided only to support compatibility with existing applications. All new applications should use either sybase or passthrough modes.

sybase mode

The access service supports a new SQL transformation mode: sybase mode.

sybase mode provides SQL transparency to client applications, allowing the development of portable applications.

sybase mode was enhanced to pass through any unrecognized syntax directly to the target; if the statement is valid it will be processed appropriately; if not, the target will issue an error (tsql2 mode did not pass on unrecognized syntax).

OmniConnect, InfoPump and the DirectConnect ODBC drivers use sybase mode.

passthrough mode

The access service supports a new SQL transformation mode: passthrough mode.

58

passthrough mode delivers the highest performance access to the target because it does not do any SQL transformation.

For backwards compatibility, db2 and tsql0 transformation modes are mapped to passthrough mode.

passthrough mode is the new default SQL transformation mode; tsql1 is no longer the default.

The default transformation mode is now passthrough, not tsq10.

Support for legacy SQL tranformation modes db2 and tsql0 transformation modes are mapped to passthrough mode. The access service supports the tsql1 SQL transformation mode. The tsql1

mode now supports a configurable client decimal separator. The DB2 access service continues to support the tsql2 SQL transformation

mode directly.

RPC enhancements and compatibility

Several enhancements and compatibility features have been added to RPC and RSP processing in the new product set:

SQL/Server RPCs are supported RSPs are supported Parameter handling has been enhanced RPC execution syntax

Supporting SQL/Server RPCs

The access service supports execution of a SQL language statement or a Remote Stored Procedure as a SQL Server RPC. A keyword tells the access service that it is receiving a SQL Server RPC.

For purposes of backward compatibility with the Database Gateway, the DB2 access service recognizes the pcsql keyword in place of the dcon keyword.

The new RPC keyword recognized by the access service is dcon — you should use this keyword for all new applications.

Implementing Remote Stored Procedures (RSPs)

You can execute your RSPs in the DB2 access service just as you did with your Database Gateway. For full, transparent compatibility you must use the following products:

DirectConnect (the DB2 access service) MainframeConnect for DB2/MVS-CICS Open Server Connect for CICS

Existing RSP programs must be re-linked with the new Open Server libraries. In Open Server there is an RSP mapping layer that maps RSP API calls to one or more Open Server or CICS calls. This layer is very fast and does not impact performance. See Migrating RSPs with full compatibility in the Remote Stored Procedures (RSPs) section of Chapter 10 for details.

59

Support for use procedure statements

For Database Gateway compatibility, the access service also supports the following syntax:

use procedure procedure_name parm1, parm2, …

We recommend using the new access service syntax, instead.

CSP enhancements

Parameters for CSPs and system procedures

For Database Gateway compatibility, an access service supports parameter names that are preceded by either an at sign (@) or an ampersand (&). For new applications, an access service supports both positional and named parameters, but not in the same statement. The parameter should be preceded by an at sign (@).

The Database Gateway automatically converts parameter values that are not in quotes to uppercase letters. The access service does not automatically convert parameters.

Expanded sp_tables result sets

The access service sp_tables result set may return more rows and data than did the Database Gateway. The access service can query both the system catalog and the collection catalog.

Additional columns returned from sp_columns

To support a new feature – incoming datatype conversions -- sp_columns will return a few additional columns. These columns contain additional data descriptors that more precisely identify the target datatype, including scale, precision, and length. This value is used by OmniConnect and can be used by any CT-Library client application to control incoming datatype conversion.

mdi_groups replaced by sp_groups

For Database Gateway compatibility, the access service converts the name mdi_groups to the sp_groups system procedure.

Transfer enhancements

The transfer syntax has been preserved and enhanced in every DirectConnect. Most transfers are now faster, although there are a couple specific areas where transfer may be slower in your environment.

The following areas of transfer functionality have been enhanced:

60

Tighter transfer syntax control Faster transfer to other gateways More robust Destination Template Transfer Improved Transfer with Microsoft SQL/Server Bulk transfer TO, is now supported for all secondary databases

Tighter Transfer syntax control

The DirectConnect now requires the following in transfer syntax:

The first line in the transfer statement now requires all three tokens: secondaryname, userid, and password.

The first two lines of the transfer statement must be ended with a semicolon. This has always been the documented syntax, but the Database Gateway did not enforce this syntax.

DirectConnect can use three methods for performing a transfer to a target. For SQL/Server and Adaptive Server targets, DirectConnect will use a bulk interface. For transfers to another DirectConnect, dynamic events are employed. Finally, for targets that do not support dynamic events, language events are used.

Faster transfer to other gateways

Transfers will now use dynamic events to transfer data from one DirectConnect to another, from DB2 to Oracle for example. Since DirectConnect supports dynamic events, and dynamic events are faster than language events, transfers from one gateway to another are now faster.

Bulk Transfer TO is now supported to secondary databases

The MDI Database Gateway supported Bulk Transfer TO, only to the SQL Server. DirectConnect supports Bulk Transfer TO, to any secondary database or to another DirectConnect.

Improved datatype conversion when transferring between gateways

Both DirectConnect and legacy gateways understand the data types and ranges of the DBMS to which they are connected. To support target datatypes best, always implement a transfer by executing a TRANSFER FROM statement at the gateway, which is connected to the target of the transfer.

For example, if transferring data between DB2 and Microsoft SQL/Server, the following should occur:

If transferring the data into DB2, execute the transfer FROM statement through the DirectConnect for MVS.

If transferring the data into Microsoft SQL/Server, run the transfer FROM statement at the DirectConnect for Microsoft SQL Server.

61

When talking to a secondary data source, the DirectConnect always uses Open Server range-checking. You can still do transfer TO a secondary data source, but the range-checking will always use Sybase datatype ranges, which may be limiting in certain environments.

Destination Template Transfer enhancements

The DirectConnects have extended the error handling and datatype conversion features of bulk transfer to Destination Template transfer. In previous Database Gateways, the ability to count Transfer errors and the ability to take specific action when datatype conversion errors are encountered was not supported with Destination Template Transfers. However, in DirectConnects, the TransferErrorCount and the various Datatype Conversion Error properties now apply to both Bulk and Destination Template transfers.

In the Database Gateway, the syntax for Destination Template transfers allows the customer to specify that particular datatype conversions be performed en route to the target data source. When a conversion error was encountered, the default behavior was to attempt an insert/replace of the character representation of the datatype. Essentially, if an invalid datatype conversion was attempted, the gateway behaved as if the template qualifier was a ?C.

For example, if a source column was CHAR with a value of "No date" and the ?D datatype conversion specified, the gateway would pass the string "No date" to the target column. In the DirectConnect, however, it will flag this conversion as invalid and its subsequent behavior will be determined by the settings for Datatype Conversion Errors:

CharConvertError NumConvertError DatetimeConvertError DefaultDate DefaultTime DefaultNum

For example, in the above scenario, if the DatetimeConvertError was set to default then the value set in the DefaultDate property will now be inserted into the database.

62

Enhanced transfer support for Microsoft SQL Server

DirectConnect transfers into Microsoft SQL Server now optionally support the full range of SQL Server datatypes. Previous gateways used a bulk interface to load data into Microsoft SQL Server. This interface is very fast, but it does not support decimal, text and image datatypes. DirectConnect continues to support the bulk interface with the same limitation. If you would like to support decimal, text and/or image datatypes in Transfers, you can execute a transfer from a particular DirectConnect into DirectConnect for Microsoft SQL Server. This interface is slower than bulk, but does support the full range of datatypes.

Codeset conversion changes

Code set conversion is handled differently in the new architecture, depending on whether you are using an access service or the Transaction Router Service. The DirectConnect access service libraries now utilize a powerful internal engine to handle code set conversion; this engine allows DirectConnects to more effectively internationalize its products. Since we use an internal conversion engine, we no longer rely on operating system files to actually perform the conversions.

Database Gateway code sets & a2e.dat

The Database Gateways shipped with support for a non-standard codeset. All of its codeset alphanumeric characters and most of its punctuation characters map correctly to Unicode Consortium standard codesets. However, the Database Gateway EBCDIC code set contains some nonstandard extended character mappings. Therefore, if your application code depends on one or more of the unusual gateway control codes or extended character mappings, use of Unicode standard codesets may change you application’s behavior. Such cases rarely occur, so we recommend that you configure the DirectConnect to use one of the Unicode standard codesets.

If your applications do require the unique codeset supported by the Database Gateway, you can configure the access service client and target code set properties as follows:

DefaultClientCodeset=819 DefaultTargetCodeset=gwebcdic

This configuration will duplicate the standard Database Gateway codeset.

63

DirectConnect no longer uses the conversion table a2e.dat for customizing ASCII - EBCDIC conversions. Since the Unicode engine is entirely internalized, it reduces your ability to easily customize the conversions. Existing customizations can still be supported, but you will need to contact Sybase Technical Support for details.

Error messages

DirectConnect will issue different error messages than did the Database Gateway. There is no direct mapping between Database Gateway and DirectConnect error messages

Integrated password management enhancements

DirectConnect for MVS provides password management capabilities integrated right into the DirectConnect server itself (these capabilities provide the server portion of the Password Manager products used by some Database Gateway customers). Integrated password management allows you to easily query, update, and retrieve status on mainframe passwords via the Password Expiration Management (PEM) facility. If a user password is expired, you can force the user to create a new valid password.

The capabilities of the old Password Manager Server are integrated into the TRS service via a series of simple stored procedures:

1. sgw_peminfopwd, to retrieve information about an individual user’s host password expiration date and logon attempts.

2. sgw_pemchpwd to change an individual user’s host password.

PEM features are supported over TCP/IP as well as APPC with release of Open Server Connect 4.0.

You will find these procedures documented in the DirectConnect for MVS Transaction Router Service User's Guide.

Net GatewayThe TRS provides compatibility to applications written to the Net Gateway. To ensure compatibility, the TRS:

Supports interoperability with OmniConnect as both a "db2" and a "direct connect" server class.

Supports all Net Gateway systems management features.

64

Mainframe Client Connect Compatibility Highlights

Mainframe Client Connect provides compatibility to Open Client applications that use the Net Gateway’s Mainframe Client Gateway (MCG). To ensure compatibility, the Net Gateway:

Supports older TDS levels for compatibility with Open Client 2.x applications (including all mainframe Replication Agents prior to version 11.2).

Replaces use of the Database Gateway Access Server for use with CSAs.

RPC Handling

The following areas surrounding Net Gateway RPC handling should be noted:

Migrating server-to-server RPCs to the DB2 access service Server-to-Server RPCs Migrating RSPs for use with the Transaction Router

Migrating server-to-server RPCs to the DB2 access service

For purposes of backward compatibility with Net Gateway, the DB2 access service recognizes the syrt keyword and the standard dcon keyword.

Server-to-Server RPCs

The handling of RPC requests routed through Adaptive Server have been enhanced in the new products. While the older products required a separate server process for each gateway, a single DirectConnect server can route RPC requests from various Adaptive Servers to various targets. To enable this capability, requires use of the Service Name Redirection capability. Connections from an Adaptive Server to a DirectConnect always pass the name of the Adaptive Server as the requested service name. Therefore, by default, each Adaptive Server will always be routed to a single DirectConnect service unless Service Name Redirection is employed. With Service Name Redirection, you can use the userid and/or the application name to dynamically route server-to-server RPCs from a single server through multiple DirectConnect services. See Service Name Redirection in the Gateway Consolidation section of Chapter 3 for more information.

Migrating RSPs for use with the Transaction Router Service

Database Gateway customers may wish to migrate their RSPs for use with the Transaction Router Service. This will likely result in performance gains because the Transaction Router is optimized for RPC execution.

65

Systems Management issues

DirectConnect Manager works with the Transaction Router Service Library (TRS) a little differently than it does with the access service libraries. The differences are as follows:

TRS does not support configuration of multiple services using the same service library. Instead of multiple services, DirectConnect provides a utility to create multiple TRS libraries to accomplish the same purpose. See the DirectConnect for MVS TRS Guide for details.

TRS configuration properties managed by DirectConnect Manager are all static properties; most were previously implemented as startup parameters.

Administrative and monitoring RPCs used in the previous Net Gateway product continue to be supported, but are not handled within DirectConnect Manager.

New mainframe CSPs

To enhance interoperability with Adaptive Server Enterprise we provided a new set of mainframe-based CSPs with the new product set. These CSPs ship with MainframeConnect. Generally, if you are accessing DB2 with dynamic SQL, you should be using the DB2 Access Service instead. Mainframe CSPs are not required for the DB2 Access Service.

sp_columns result set

The CSP sp_columns will return additional columns in this release. The additional columns contain a 32-bit integer that specifically identifies the target datatype and associated characteristics like scale, precision and length. This value is used by OmniConnect and can be used by any CT-Library client application to control incoming datatype conversion.

New OmniConnect stored procedures

Two new and one modified stored procedures have been added to the mainframe CSPs to support interaction with OmniConnect as a remote server of class "access_server":

sp_capabilities is new sp_thread_props is new as noted previously, sp_columns has been modified

Net Gateway 2.x Compatibility

Using both Net Gateway 2.0 and 3.x Catalog Stored Procedures

Customers can use both Net Gateway 2.0 and 3.x Catalog Stored Procedures in a single DB2 subsystem in the new architecture. Here’s how to support CSP coexistence.

66

Support for User Data Types (UDTs)

We added a new configuration parameter to MainframeConnect to support legacy applications deployed with Net Gateway 2.x. It is optional, and defaults to YES. If you set it to NO, then MainframeConnect will not return a User Data Type (UDT) with the data.

This should never be used for a new application.

You should always set this value to YES wherever possible, because it will enable DirectConnect to perform datatype conversions for you. If set to NO, your own application will need to convert datatypes in client-side code.

For Net Gateway 2.0 compatibility, use the NOUDTTRAN flag. For all other uses, set Send UDT to YES.

Gateway-less MVS Access Open Server Connect 4.0 for CICS eliminates the requirement for using gateways for mainframe connectivity.

Open Server Connect 4.0 supports DirectConnect or "gateway-less" mainframe access.

To help DirectConnect customers migrate to a gateway-less architecture, certain features have been implemented on the mainframe. These include:

Conversion of Sybase RPC names to mainframe transaction names Conversion of language RPC calls to RPC invocations Connection maintenance to preserve a client’s TCP/IP connection while

no mainframe RPCs are running Invoking mainframe transactions to perform a user-requested SQL or RPC

request

Of course, you may choose to still use a DirectConnect for MVS for a number of reasons. You should note that certain functions would not be available to you when using gateway-less mode. These include the following:

Transfer SQL Transformation Customized datatype conversions Login mapping from LAN to mainframe passwords Multi-region routing Transactions and communications groups

You may also find that use of the gateway fits certain application requirements well. For instance, you may need local control over the gateway because you have unique requirements in every

67

location running a gateway. Additionally, the connection concentration function of the gateway may be the best way for you to preserve mainframe resources when supporting lots of clients. You can certainly deploy some applications that are gateway-less, and others that are gateway-based. You have the option to choose the form most appropriate for your application.

Mainframe Client ConnectMainframe Client Connect (MCC) is a LAN-based program that allows Open ClientConnect mainframe applications, coded with either the Open Client or the CSA API, to Connect to LAN servers. It performs data and protocol translation between APPC LU6.2 and the LAN network protocols.

MCC is only required when using SNA APPC LU6.2. Gateway-less connectivity is supported when using Open ClientConnect 3.2 and higher with a TCP/IP network.

Mainframe Client Connect replaces two former products: Mainframe Client Gateway (MCG) Database Gateway Access Server (DGACCSRV)

Use with mainframe Replication Agents

Mainframe Replication Agents prior to version 11.2 use a slightly older version of the Open Client software than the current release. To use the Replication Agents with Mainframe Client Connect (or the Net Gateway 3.01 MCG) you need to use the -D startup parameter. This startup parameter tells the MCG or MCC to use the older TDS version.

Database Gateway Access Server replaced by MCC

The new product component that will convert network protocols between APPC LU 6.2 and a LAN network protocol will be Mainframe Client Connect. This product replaces the current Database Gateway Access Server. The change will be transparent to all Client Services Applications (CSAs).We also support the use of CSAs over TCP/IP networks.

68

9. Migration: RSPs & Open ServerConnect

Overview

Your existing products permit you to access mainframe applications from distributed client/server and web-oriented applications. These capabilities are fully supported without requiring you to re-write your existing applications. (There is only one, very minor, exception to full backward compatibility; see DB2 input pipe support eliminated in the Notes, at the end of this chapter to make sure it does not affect you).

This chapter will tell you specifically how to migrate your existing applications with full compatibility. The new product set uses both Open ServerConnect and MainframeConnect to preserve the former capabilities of Open Server/Mainframe and the Access Server.

This chapter includes the following topics: Supported Languages – Identifies the languages supported for RPCs and

RSPs. RSP & RPC Comparison & Migration – This section outlines the

differences between RSPs and RPCs and provides suggestions on when to use each.

Open Server/Mainframe & Open ServerConnect – Documents issues when migrating from older Open Servers to Open Server Connect.

Remote Stored Procedures – Discusses how RSPs work in the new product set, and how to make them fully compatible with your existing applications.

Supported Languages

Open ServerConnect RPC language support

Open ServerConnect supports coding of RPCs in the following languages:

COBOL PL/1

RSP language support

You can write an RSP in any of the four programming languages supported by CICS:

COBOL II Assembler PL/1 C (SAS/C or IBM C/370)

RSP and RPC Comparison & MigrationRSPs and Open ServerConnect RPCs are quite similar. Both provide an API and a set of libraries that allow you to link your

69

existing mainframe applications with distributed client/server and web-oriented environments. We provide full support for both RSPs and RPCs in the new product set. Since these two similar capabilities have subtle differences, and because you have the option of using either or both, this section will offer you some guidance in making a decision.

Remote Stored Procedures (RSPs) remain a critical element of the new product set. The focus of new development will be based upon the Open ServerConnect products. Open ServerConnect has the following advantages:

Its API has been ported to MVS-native and MVS/IMS environments, in addition to MVS/CICS.

Its API is more similar to the Open Server 11.x API, making downsizing your MVS applications more straightforward.

RSP customers are encouraged to consider using the Open Server API when undertaking new development. Similarly, when new revisions of existing applications (featuring RSPs) are undertaken, you should consider re-implementing the application as an Open Server application. Continuing to use the RSP API will not be a liability for you.

The following table summarizes some of the particular cases when you might choose or be required to use RSPs or RPCs:

Feature or Capability RSP OSC RPCMap a result set to an Adaptive Server table MVS-native support MVS/IMS support MVS/CICS support Use with Transfer

Should you choose to migrate your RSPs, you will have a couple of options:

Extend the program with two very simple RSP API calls to permit invocation of the RSP directly through the TRS.

Re-write the program to use only Open Server API calls.

The first option requires less effort and is likely to increase RSP performance; it does preserve dependence on the RSP API. The second option requires more effort but may produce more portable code.

70

Open Server/Mainframe & Open ServerConnect

Open Server/Mainframe v. 3.0

Open ServerConnect v. 3.1 is compatible with Open Server 3.0 applications. You do not need to re-link your existing programs to use the new Open Server libraries.

You may need to modify your existing application if you use the Open ServerConnect API call TDINFPRM. The updated TDINFPRM call returns results a little bit differently, so you will need to re-compile your program.

Obviously, if you decide to use any API calls associated with new features – like cursors and dynamic events – you will need to re-compile your application.

Remote Stored Procedures (RSPs)A RSP is a CICS command-level program that contains the Sybase RSP calls to the RSP API.

Migrating RSPs with full compatibility

To use your existing RSPs with full backward compatibility, there are no changes required to your RSP application code. However, you will need to re-link your existing RSPs with the new RSP stub libraries.

To facilitate side-by-side testing, you can run the same RSP program within the same CICS region and access it through both MainframeConnect and the Access Server. See the section on Coexistence for detailed instructions.

How RSP Processing Works

Open ServerConnect provides an API mapping layer that converts RSP API calls into one or more Open ServerConnect and/or CICS calls. MainframeConnect provides the "traffic cop" role formerly served by the Access Server, and the DB2 access service provides function compatible with the Database Gateway. Together, this provides full backward compatibility for your existing applications and may require modifications to your existing code.

The RSP API mapping layer and the RSP Programmer’s Guide are a part of Open ServerConnect.

71

Although this may seem like a lot of layers, the actual processing that occurs is very similar to how RSPs worked with the Database Gateway and the Access Server. The only difference is that the Access Server role is shared across MainframeConnect and Open ServerConnect.

Here is how backward-compatible RSPs are processed, step-by-step:

The client requests a remote procedure call (RPC), passing the RSP name and any required arguments.

The DB2 Access Service passes the request to MainframeConnect. MainframeConnect invokes the RSP. The RSP performs the necessary processing. The RSP returns results to the DB2 Access Service DirectConnect. The RSP returns control to Open Server Connect. DirectConnect returns results to the client application.

RPCs and Adaptive Server Enterprise

With ASE, RPC requests using site handler are not supported for Gateway-less services. You must use the CIS setting in ASE to provide the Open Client connection.

Migrating RSPs to use TRS

If you are invoking RSPs directly (using the Transaction Router Service Library), you need to make the following changes:

The first API call in your program must be RPSETUP. The last API call in your program must be RPDONE. Re-link your program with the new RSP stub libraries.

See the Open ServerConnect RSP Programmer’s Guide for more details and for code samples.

Processing RSPs through the Transaction Router Service

When processing RSP requests through the Transaction Router Service, processing occurs as follows:

The client requests a remote procedure call (RPC), passing the RSP name and any required arguments.

TRS searches its catalog for the transaction name (TP name) and invokes the RSP directly.

The RSP performs the necessary processing. The RSP returns results to TRS. TRS returns results to the client application.

72

Notes

RSPs & SQL transformation

How RSPs are invoked by clients is determined by the SQL Transformation mode in effect. In the DB2 Access Service Library:

tsql0 corresponds directly to passthrough mode. tsql2 corresponds directly to sybase mode.

For these modes, the SQL issued by your client application requires no modification.

When migrating from tsql1 mode to a setting of passthrough mode, your client SQL will probably fail, since the tsql1 partial SQL conversion no longer takes place.

When migrating from tsql1 mode to a setting of sybase mode, your client SQL will most probably work, since any SQL that the parser cannot identify will be passed on to the server without change.

SPTEST utility replaced by ASPT transaction

The SPTEST utility which was used in testing RSP execution on the mainframe has been replaced by a new utility, ASPT.

DB2 input pipe support eliminated

DirectConnect no longer converts pre-formatted IXF data to DB2 format input pipes. For those few using DB2 input pipes, you must change your applications to convert your source data to ASCII for DB2 formatted input pipes.

The overwhelming majority of RSP users do not use DB2 input pipes.

All data transmitted between the RSP, DirectConnect and MainframeConnect is sent in Tabular Data Stream (TDS) format, which replaces the Integrated Exchange Format (IXF). TDS is a Sybase standard format, optimized continually over the last ten years, that automatically manages data formatting for you.

73

10. Migration: CSAs & Open ClientConnect

Overview

Your existing products permit you to access distributed client/server data from within mainframe CICS applications. These capabilities are fully supported in the new product set without requiring you to re-write your existing applications. The new product set uses Open ClientConnect to preserve the former capabilities of the Open Client/Mainframe and the Access Server. Additionally, for SNA environments, Mainframe Client Connect is required.

This chapter will tell you specifically how to migrate your existing applications with full compatibility. We cover the following topics:

Open Client/Mainframe & Open ClientConnect Migration CSA Migration

CICS customers should note that Open ClientConnect 3.2 also supports MVS/IMS and MVS-native environments. If you have applications running in these environments – batch applications, for example – you can use Open ClientConnect to request data from, or transfer data to, distributed client/server data sources. Open ClientConnect natively supports SQL/Server and Adaptive Server. Through the DirectConnect, Open ClientConnect also supports access to any data source.

Supported Languages

Open ClientConnect supports coding of RPCs in the following languages:

COBOL PL/1 C

Open ClientConnect allows you to write a CSA in any of the four programming languages supported by CICS:

COBOL II Assembler PL/1 C (SAS/C or IBM C/370)

Open Client/Mainframe & Open ClientConnectOpen ClientConnect version 3.2 and greater, supports gateway-less connectivity to distributed client/server data. This support is provided over both IBM and Interlink TCP/IP networks. Open ClientConnect continues to support use of Mainframe Client Connect with SNA and TCP/IP networks.

75

Open ClientConnect version 3.2 and greater, is compatible with Open Client 2.x and later applications. Your existing applications will need to be re-linked with new libraries if you are using Open

ClientConnect version 3.2 (with EBF 6781) or a later version.

Client Services Applications (CSAs)

How CSA processing works

A CSA is a CICS-initiated program that accesses LAN data sources. The CICS program contains calls to the CSA API.

In the new architecture, CSAs are supported by means of an API mapping layer that interprets CSA API calls to one or more Open Client and CICS calls. This provides backward compatibility for customer applications.

CSA processing occurs as follows: A CSA invokes Open ClientConnect, specifying both the server name and

the address of the request to be executed at the remote LAN data source. Open ClientConnect initiates an APPC conversation with Mainframe

Client Connect using the connection parameters specified in the server definition.

Open ClientConnect sends the request to Mainframe Client Connect. Mainframe Client Connect sends the request to the target data source. The target data source returns results to Mainframe Client Connect. Using an input pipe, Mainframe Client Connect optionally passes results

to the CSA for processing. In the case of a transfer, the CSA receives only status information and no results.

Open Client Connect/CSA Information Exchange

Information is exchanged between the CSA and Open ClientConnect using the Stored Procedure Communication Area (SPAREA) and data pipes. The CSA uses a SPAREA to communicate with Open ClientConnect. The CSA creates the SPAREA and sets values in it. Open ClientConnect sends messages to the CSA by placing the message text in a field in the SPAREA and setting a flag to indicate that a message is available. The CSA issues a GETMSG command to retrieve the message. If your CSA retrieves data, you must open a DB2 format data pipe to Open ClientConnect. The CSA data pipe can be used only for input. If your CSA receives data from an input pipe, you must also read the address of a SQLDA definition from the SPAREA.

76

Migration considerations

CSAs, Open ClientConnect and the Attachment Definition file

In the SPAREA, the Attachment Definition name SPATTACH is tested for a value. If a value exists the PCSQLSP Definition file is read. If no value exists the connection values will be taken from the SPAREA.

You must re-link your existing CSAs with the Open ClientConnect stub programs.

You can use the sample transaction ASQL, which is installed with Open ClientConnect, to ensure your environment is set up correctly.

77

11. InteroperabilityThis chapter will cover migration issues surrounding product interoperability. Specifically, we will address the following products:

Adaptive Server Enterprise (Sybase SQL/Server) Adaptive Server Anywhere Replication Server Microsoft SQL/Server InfoHub

Adaptive Server Enterprise (Sybase SQL/Server)

Adaptive Server (EEO) & OmniConnect

Setup

You can configure OmniConnect to access data on a remote server through a DirectConnect service.

OmniConnect and Transaction Router Service

The Transaction Router Service (TRS) supports configuration as a remote server of class "access_server" when used with OmniConnect. It is generally recommended, however, that you use OmniConnect with the DB2 Access Service for DB2 access.

For purposes of backward compatibility, the Transaction Router Service also continues to support configuration as a remote server of class "db2" when used with OmniConnect.

The MainframeConnect DateTime configuration property specifies the format that MainframeConnect uses to return DB2 timestamps. The default specification is DB2—this is the setting you use for the DB2 Access Service Library.

To return timestamps in a format that allows OmniConnect to communicate with the Transaction Router Service, specify the format TRO.

Server-to-server RPC configuration

To configure SQL Server for remote access, log in to SQL Server as an administrator and check the current sp_configure setting using the following command:

sp_configure ‘remote access’

If the returned value is 1, SQL Server is configured for remote access. If the returned value is 0, perform the following steps:

79

sp_configure ‘remote access’,1

Restart SQL Server when sp_configure ‘remote access’ returns a value of 1.

Adaptive Server AnywhereDirectConnect Anywhere supports access to and Transfer to/from Adaptive Server Anywhere. Simply configure DirectConnect Anywhere to use the Adaptive Server Anywhere ODBC driver and powerful and robust connectivity is enabled.

Data access

This product combination provides the following data access functionality:

With jConnect, DC Anywhere provides thin-client, Java connectivity to Adaptive Server Anywhere.

With Adaptive Server Enterprise (EEO) or OmniConnect, DC Anywhere provides location transparency and distributed join support for Adaptive Server Anywhere.

Data movement

This product combination provides the following data movement functionality:

DirectConnect Anywhere supports Transfer to/from Adaptive Server Anywhere

With Replication Server, DC Anywhere supports replication into DC Anywhere

With Open Client Connect, DC Anywhere supports batch movement of data from MVS into a consolidation Adaptive Server Anywhere database.

Replication Agents

The DirectConnect for MVS is certified to use the Sybase mainframe Replication Agents when you choose a gateway (i.e., for SNA support) to communicate between the mainframe and the LAN. The Mainframe Client Connect component of the DirectConnect provides the support for Replication Agents

Microsoft SQL/ServerDirectConnect for Microsoft SQL Server is available on four platforms: AIX, HP-UX, Solaris and Windows NT.

Data access

DirectConnect for Microsoft SQL Server provides point-to-point connectivity to Microsoft SQL Server from any Open Client or

80

jConnect client or server application, including all of the following (and many others):

Adaptive Server jConnect Open ClientConnect Open Client Jaguar CTS PowerBuilder

Using Adaptive Server, you can also provide distributed data access with Microsoft SQL Server. Adaptive Server and DirectConnect provide location transparent distributed access to Microsoft SQL Server, Sybase SQL Server, Adaptive Server and any other data source, including the ability to perform distributed joins across those data sources.

Data movement

DirectConnect for Microsoft SQL Server supports Transfer in and out of Microsoft SQL/Server. See here for more information on these capabilities. It also supports replication through interoperability with Replication Server, allowing customers to propagate changes in central Adaptive Server databases to Microsoft SQL Server.

Notes

Connecting to DirectConnect from Microsoft SQL/Server using SPX

Microsoft and Sybase use different SAP types. Therefore, Microsoft clients can not use a DirectConnects server name as the sole address identifier in the WIN.INI or registry entries. You must specify the complete network address with the port number, Mac address and network number. Similarly, Open Client users must identify Microsoft servers using the same specific network address convention.

InfoHubThe new DirectConnect architecture supports InfoHub through use of the DirectConnect for MVS TRS service. The corresponding required mainframe components:

InfoHub (OmniSQL Access Module for One or more InfoHub database interfaces Open Server Connect or MainframeConnect for DB2

Together, the above components provide everything required to access non-relational data via dynamic SQL.

81

InfoHub version 2.3, has the following major new features: Long transaction support through Adaptive Server (EEO) and

OmniConnect Support for cursors and dynamic events ADABAS access enhancements Built-in connectivity with support for operation in gateway-less mode

Connectivity to InfoHub will be enabled through Sybase protocols (via DirectConnect for MVS (TRS)).

Migration ConsiderationsDepending on your current configuration for InfoHub access, you may approach migration differently. Because of new releases that offer additional connectivity options, customers may choose different upgrade paths.

OmniConnect

If you use OmniConnect to access InfoHub, your applications are shielded from the specific MVS gateway used for connectivity. You should migrate your gateway today to use the DirectConnect for MVS. Both Database Gateway and Net Gateway customers can upgrade to DirectConnect for MVS. When the new version of InfoHub becomes available, you should update your mainframe software to the most recent version.

Net Gateway

Customers who use Net Gateway (without OmniConnect) with InfoHub should plan to migrate their gateway to the DirectConnect for MVS.

Database Gateway

If you are using the Database Gateway with InfoHub, you should migrate to InfoHub version 2.3 and DirectConnect for MVS. The new InfoHub configuration will involve new connectivity and new host code. As far as connectivity, your default migration path is to the DirectConnect for MVS. It is a no-cost upgrade to Database Gateway for MVS customers. Using DirectConnect for MVS TRS to access InfoHub is different than using a Database Gateway, and it will likely require some changes in your applications.

82

Mainframe licenses

All licensees of the InfoHub Server and the OmniSQL Access Module for InfoHub are eligible for no-cost upgrades to the new InfoHub version. For all InfoHub-related OmniSQL Access Module users the new version of InfoHub will be an automatic upgrade (using the same Product ID #s you have already licensed). Licensees of the MDI-heritage InfoHub products may convert their licenses to the new version—or the existing InfoHub-related OmniSQL Access Modules —at no-cost. See the Data Access Migration web site section on "Process & Policy" for detailed information about upgrades.

83

12. Known IssuesThis chapter lists known issues that have been identified in the following areas:

Powerbuilder Communications OmniConnect

PowerBuilderIssues have been identified in the following areas with PowerBuilder applications:

Database name and Password when using the ODBC interface driver Migrating from an MDI gateway and Powerbuilder using the MDI

interface driver Incorrect userid and password supplied to DB2 Using identifier delimiters in PowerBuilder 4.0 Using PowerBuilder in a non-DB2 environment Using Powerbuilder 5.0 in a 32-bit environment with Open Server-based

gateways

Database name and Password when using the ODBC interface driver

When creating a new profile for the DirectConnect DB2 access service using the ODBC interface driver, a DB=; and a PWD=; are added to the dbparm after the first successful connection to DirectConnect in the profile painter. This causes errors the next time powerbuilder uses that profile which occurs immediately, since you are in the select dialogue window following the profile being created.

To solve the DB=; problem, edit the profile and remove the DB=; from the dbparm.

To solve the PWD=; problem: edit the profile, remove the PWD=; from the dbparm and have the driver

prompt for the password.

OR

edit the profile and enter the correct password after the PWD=; in the dbparm parameter.

85

Migrating from an MDI gateway and Powerbuilder using the MDI interface driver

When migrating from an MDI gateway and Powerbuilder using the MDI interface driver (dbms: MDI) (pbmdi040.dll, pbmdi050.dll, pbmdi060.dll) to DirectConnect and Powerbuilder using the ODBC interface (dbms : ODBC) (pbodb040.dll, pbodb050.dll, pbodb060.dll), any datawindows with date columns that are being modified in the development environment, after migrating, will cause a -104 error in db2 when the update is sent to DB2.

To solve the problem: export the datawindow, change the date columns datatypes from datetime

back to date and import the datawindow.

OR

configure the service in DirectConnect to gateway compatible=yes, and use the MDI interface. This will only work if you are using the EBF soon to be released (version 11.1.1P2). This EBF follows EBFi0063 (version 11.1.1P1).

An incorrect userid and password supplied to DB2

When you are connecting to your database and a wrong userid and password is supplied to DB2, the following ambiguous error is returned:

[INTERSOLV][ODBC SQL server driver][SQL Server][VENDORLIB] Vendor Library Error: No error message is available.

This is the error in the DirectConnect log:Error: 30252 Severity [VENDORLIB] Vendor Library Error: No error message is available from the host. <DB2>.NETWORK ERROR:SYBLU62 ERROR INFO:,Request (recv), SubFunc (Unknown SubFunc), SYBLU^@ retCode (-7)Description (SYBLU62_ERR_INVALID_SECURITY), LU62 APIRet2 (080F6051)Description (SYBLU62_ERR_INVALID_SECURITY), LU62 APIRet2 (080F6051)Description (SNA Sense Data (080F6051),Description (Sense Category (08, Request reject),Sense Code (080F, End User or LU Not Authorized), SECURITY FAILURE).}<LocalLU=LOCAL>, <RemoteLU=DWMC141M>, <Logmode Name=MVSMODE>, <TPName=AMD2>

We are currently working on a solution to the problem.

Identifier delimiters in PowerBuilder 4.0

86

Within PowerBuilder 4.0, a default value asks PowerBuilder to put double quotes (") around table and column identifiers in the SQL statement.

For example, PB issues its SQL:SELECT "DWMK52"."AUTHORS"."AU_ID", "DWMK52"."AUTHORS"."AU_LNAME" FROM "DWMK52"."AUTHORS"

This statement worked fine through the Database Gateway. PowerBuilder’s "Database Gateway" (DB-Lib) interface has a DBParm configuration option to set Identifier Delimiters on or off. PB 4.0 documentation states the default is "No" (off), however, in reality it defaults to "Yes"(on). This worked fine with the DB Gateways, so probably very few programmers ever specifically set it to "No".

However, the DB2 Access Service does not support double-quoted delimiters. The net effect is that PB applications will have to change and potentially be re-compiled with DirectConnect.

There are two possible workarounds:1. Manually set the DBParm configuration option to "No" (off). 2. Use PowerBuilder’s ODBC interface with the DirectConnect ODBC

driver.

Using PowerBuilder in a non-DB2 environment

In PowerBuilder releases of version 4.04 and higher, changes in its error handling policy have created issues with using Powerbuilder for RPC invocation in a non-DB2 environment.

The Powerbuilder Net Gateway interface issues Catalog Stored Procedures (CSPs) at initial Connect time. In a non-DB2 (and non-InfoHub) environment, these CSPs don’t exist, however. Prior to version 4.04, the PowerBuilder interface simply digested the errors and continued processing. Beginning with the 4.04 release, PowerBuilder issues an error and closes its Connection to Net Gateway when it receives no response to the CSPs it issues.

The workaround is to provide a set of mainframe transactions that return the appropriate CSP format descriptors without any data rows. We’ve written these transactions and they are available through Sybase Technical Support. These "dummy" CSPs will be incorporated into the standard product line.

CommunicationsThe following Communications issues should be noted.

87

TCP/IP Configuration Issues

The Windows NT operating system likes to check that all referenced DLLs exist and contain all required entry points. This has created a couple of minor issues for our programs that need to use either an APPC or TCP/IP DLL for mainframe Connectivity. The issue has been addressed two ways:

Transaction Router Service Library

The DirectConnect ships two separate Transaction Router service libraries, one each for APPC and TCP/IP.

DB2 Access Service Library

The DB2 Access Service Library ships one service library and a couple stub DLLs to satisfy Windows NT.

Please follow the steps below if you are using TCP/IP Connectivity to MVS and do not have an SNA package installed. This is detectable if your installed DirectConnect application fails to run properly due to its inability to find WAPPC32.DLL:

1. In the %SYBASE%\eConnect\bin directory, copy or move the DLL named astubmsg.dll into your %systemroot%\system32 directory. This is the wappc32.dllevent log DLL.

2. In the %SYBASE%\eConnect\bindirectory, rename the DLL named appcstub.dll to wappc32.dll. This is a stubbed-out version of wappc32.dll that allows native TCP/IP customers to use the DB2 access libraries without installing SNA.

If a DB2 service is configured to use SNA, and SNA Server is not installed, the stub DLL provides the correct entry point functions, but the functions write a message to the Windows NT Application Event Log and throw an exception. This causes DirectConnect to stop and leaves an orphan copy of DIRECTC.EXE running. You must query the DirectConnect log file, find the DIRECTC process ID, and kill that process.

If you experience this behavior, reconfigure the offending service to use TCP/IP or correctly install SNA Server. If SNA Server is installed, then rename the %SYBASE%\eConnect\bin\wappc32.dll back to appcstub.dll to allow DirectConnect services to use SNA correctly.

OmniConnectFollowing is a known issues with OmniConnect and the new architecture:

88

OmniConnect NUMERIC datatype translation

If you attempt to insert data into a NUMERIC field using OmniConnect v. 10.5, and the backend database is the Transaction Router Service, the insert fails with an invalid Open Server datatype error.

As a workaround, create the table on OmniConnect using a DECIMAL(18,0) value instead of a NUMERIC value.

89

Date post:	22-Nov-2014
Category:	Documents
Upload:	tess98
View:	956 times
Download:	5 times