Oracle Database Gateway for IMS, VSAM, and Adabas Installation and Configuration Guide, 11g Release 2 (11.2) for AIX 5L Based Systems (64-Bit), HP-UX Itanium, Solaris Operating System (SPARC 64-Bit), Linux x86, and Linux x86-64

11g Release 2 (11.2)

E12076-03

Contents

Title and Copyright Information

Preface

- Audience

- Documentation Accessibility

- Related Documents

- Conventions

Part I Getting Started with Oracle Database Gateways

1 Getting Started with Oracle Database Gateway

- Overview

- Oracle Heterogeneous Services

- Oracle Database Gateways

- Gateway Architecture

- Gateway Process Flow

- Setup Flow

Part II Installing and Configuring Oracle Database Gateway for VSAM

2 Configuring Access to VSAM Data

- Setting Up Access to a Computer Running Oracle Connect for IMS, VSAM, and Adabas Gateways

- Setting Up a VSAM Data Source

- Defining the VSAM Data Source Connection

- Defining the VSAM (CICS) Data Source Connection

- Configuring the VSAM or VSAM (CICS) Data Source Properties

- VSAM Data Source Parameters

- VSAM (CICS) Data Source Parameters

- Setting Up the Metadata of the VSAM Data Source

- Import the COBOL Copybooks

- Apply Filters

- Select Tables

- Manipulate the Imported Tables

- Create VSAM Indexes

- Select the Metadata Model

- Import the Metadata

- Setting Up the Metadata of the VSAM (CICS) Data Source

- Import the COBOL Copybooks

- Apply Filters

- Select Tables

- Manipulate the Imported Tables

- Assign File Names

- Assign Index File Names

- Select the Metadata Model

- Import the Metadata

3 Installing Oracle Database Gateway for VSAM

- Overview of Oracle Database Gateway for VSAM

- System Requirements for Oracle Database Gateway for VSAM

- Hardware Requirements for Oracle Database Gateway for VSAM

- Software Requirements for Oracle Database Gateway for VSAM

- Gateway Installation Configurations

- Gateway Installation Methods

- Interactive Installation Method

- Automated Installation Method Using Response Files

- Gateway Installation Considerations

- Release Notes

- Hardware and Software Certification

- Multiple ORACLE_HOME Directories

- Installing the Software on a System with an Existing Oracle Installation

- Upgrades

- Accessing the Installation Software

- Downloading Oracle Software from the Oracle Technology Network Web Site

- Downloading the Installation Files

- Extracting the Installation Files

- Copying the Gateway Software to a Hard Disk

- Mounting the Installation Media

- Copying the Oracle Database Gateway Software to a Hard Disk

- Running the Oracle Universal Installer

4 Configuring Oracle Database Gateway for VSAM

- Configuring the Gateway

- Choose a System Identifier for the Gateway

- Customize the Initialization Parameter File

- Configuring Oracle Net Services Listener for the Gateway

- Configure Oracle Net Services Oracle Net Listener for the Gateway

- Example of Address to Listen On in listener.ora File

- Example of Gateway to Start in listener.ora File

- Stop and Start the Oracle Net Listener for the Gateway

- Configuring the Oracle Database for Gateway Access

- Configuring Oracle Net Services for the Oracle Database

- Configuring tnsnames.ora

- Creating Database Links

- Gateway Password Encryption Tool

- Configuring the Gateway for Multiple VSAM Databases

- Multiple Databases Example: Configuring the Gateway

- Multiple Databases Example: Configuring Oracle Net Services Listener

- Multiple Databases Example: Stopping and Starting the Oracle Net Listener

- Multiple Databases Example: Configuring the Oracle Database for Gateway Access

- Configuring Oracle Net Services on the Oracle Database for Multiple Gateway Instances

- Multiple Databases Example: Accessing VSAM Data

- Performing Configuration Tasks

- Configuring for Global Transactions

- Enabling Automatic Recovery

- Testing the VSAM Data Source

- Sample Log File

Part III Installing and Configuring Oracle Database Gateway for IMS

5 Configuring Access to IMS Data

- Setting Up Access to a Computer Running Oracle Connect for IMS, VSAM, and Adabas Gateways

- Setting Up an IMS Data Source

- Defining the IMS-DLI Data Source

- Setting Up the Daemon Workspace

- Defining the IMS-DLI Data Source Connection

- Configuring the IMS/DB DLI Data Source Properties

- Defining the IMS/DB DBCTL Data Source

- Define the IMS/DB DBCTL Data Source Connection

- Configure the IMS/DB DBCTL Data Source Properties

- Accessing IMS/DB Data under CICS

- Defining the IMS/DB DBDC Data Source

- Define the IMS/DB DBDC Data Source Connection

- Configure the IMS/DB DBDC Data Source Properties

- Access IMS/DB Data under IMS/TM

- Setting Up the IMS/DB Data Source Metadata

- Select the Input Files

- Apply Filters

- Select Tables

- Match DBD to COBOL

- Manipulate the Imported Records

- Select the Metadata Model

- Import the Metadata

6 Installing Oracle Database Gateway for IMS

- Overview of Oracle Database Gateway for IMS

- System Requirements for Oracle Database Gateway for IMS

- Hardware Requirements for Oracle Database Gateway for IMS

- Software Requirements for Oracle Database Gateway for IMS

- Gateway Installation Configurations

- Gateway Installation Methods

- Interactive Installation Method

- Automated Installation Method Using Response Files

- Gateway Installation Considerations

- Release Notes

- Hardware and Software Certification

- Multiple ORACLE_HOME Directories

- Installing the Software on a System with an Existing Oracle Installation

- Upgrades

- Accessing the Installation Software

- Downloading Oracle Software from the Oracle Technology Network Web Site

- Downloading the Installation Files

- Extracting the Installation Files

- Copying the Gateway Software to a Hard Disk

- Mounting the Installation Media

- Copying the Oracle Database Gateway Software to a Hard Disk

- Running the Oracle Universal Installer

7 Configuring Oracle Database Gateway for IMS

- Configuring the Gateway

- Choose a System Identifier for the Gateway

- Customize the Initialization Parameter File

- Configuring Oracle Net Services Listener for the Gateway

- Configure Oracle Net Services Oracle Net Listener for the Gateway

- Example of Address to Listen On in listener.ora File

- Example of Gateway to Start in listener.ora File

- Stop and Start the Oracle Net Listener for the Gateway

- Configuring the Oracle Database for Gateway Access

- Configuring Oracle Net Services for the Oracle Database

- Configuring tnsnames.ora

- Creating Database Links

- Gateway Password Encryption Tool

- Configuring the Gateway for Multiple IMS Databases

- Multiple Databases Example: Configuring the Gateway

- Multiple Databases Example: Configuring Oracle Net Services Listener

- Multiple Databases Example: Stopping and Starting the Oracle Net Listener

- Multiple Databases Example: Configuring the Oracle Database for Gateway Access

- Configuring Oracle Net Services on the Oracle Database for Multiple Gateway Instances

- Multiple Databases Example: Accessing IMS Data

- Performing Configuration Tasks

- Configuring for Global Transactions

- Enabling Automatic Recovery

- Testing the IMS Data Source

- Sample Log File

Part IV Installing and Configuring Oracle Database Gateway for Adabas

8 Configuring Access to Adabas Data

- Setting Up Access to a Computer Running Oracle Connect for IMS, VSAM, and Adabas Gateways

- Setting Up an Adabas Data Source

- Define the Adabas Data Source Connection

- Configure the Adabas Data Source Properties

- Setting Up Adabas Data Source Metadata

- Import Oracle Metadata from DDM Files

- Export Predict Metadata into Adabas ADD

9 Installing Oracle Database Gateway for Adabas

- Overview of Oracle Database Gateway for Adabas

- System Requirements for Oracle Database Gateway for Adabas

- Hardware Requirements for Oracle Database Gateway for Adabas

- Software Requirements for Oracle Database Gateway for Adabas

- Gateway Installation Configurations

- Gateway Installation Methods

- Interactive Installation Method

- Automated Installation Method Using Response Files

- Gateway Installation Considerations

- Release Notes

- Hardware and Software Certification

- Multiple ORACLE_HOME Directories

- Installing the Software on a System with an Existing Oracle Installation

- Upgrades

- Accessing the Installation Software

- Downloading Oracle Software from the Oracle Technology Network Web Site

- Downloading the Installation Files

- Extracting the Installation Files

- Copying the Gateway Software to a Hard Disk

- Mounting the Installation Media

- Copying the Oracle Database Gateway Software to a Hard Disk

- Running the Oracle Universal Installer

10 Configuring Oracle Database Gateway for Adabas

- Configuring the Gateway

- Choose a System Identifier for the Gateway

- Customize the Initialization Parameter File

- Configuring Oracle Net Services Listener for the Gateway

- Configure Oracle Net Services Oracle Net Listener for the Gateway

- Example of Address to Listen On in listener.ora File

- Example of Gateway to Start in listener.ora File

- Stop and Start the Oracle Net Listener for the Gateway

- Configuring the Oracle Database for Gateway Access

- Configuring Oracle Net Services for the Oracle Database

- Configuring tnsnames.ora

- Creating Database Links

- Gateway Password Encryption Tool

- Configuring the Gateway for Multiple Adabas Databases

- Multiple Databases Example: Configuring the Gateway

- Multiple Databases Example: Configuring Oracle Net Services Listener

- Multiple Databases Example: Stopping and Starting the Oracle Net Listener

- Multiple Databases Example: Configuring the Oracle Database for Gateway Access

- Configuring Oracle Net Services on the Oracle Database for Multiple Gateway Instances

- Multiple Databases Example: Accessing Adabas Data

- Performing Configuration Tasks

- Configuring for Global Transactions

- Enabling Automatic Recovery

- Testing the Adabas Data Source

Part V Installing and Working with Oracle Studio for IMS, VSAM, and Adabas Gateways

11 Installing Oracle Studio for IMS, VSAM, and Adabas Gateways

- System Requirements for Oracle Studio for IMS, VSAM, and Adabas Gateways

- Hardware Requirements for Oracle Studio for IMS, VSAM, and Adabas Gateways

- Software Requirements for Oracle Studio for IMS, VSAM, and Adabas Gateways

- Installing Oracle Studio for IMS, VSAM, and Adabas Gateways on Linux (SH Installation)

12 Working with the Oracle Studio for IMS, VSAM, and Adabas Gateways Workbench

- Using Workbench Parts

- Main Screen

- Main Menu Bar

- Working with Views

- Customizing Views

- Properties View

- Error Log View

- Configuration View

- Metadata View

- Working with Perspectives

- Design Perspective

- Runtime Perspective

- Selecting a Perspective

- Setting Oracle Studio for IMS, VSAM, and Adabas Gateways Preferences

- Studio

- Configuration

- Metadata

- Runtime Manager

- Keys

- Default Keyboard Shortcuts

13 Configuring Oracle Connect through Oracle Studio for IMS, VSAM, and Adabas Gateways

- Starting and Stopping Daemons

- Starting a Daemon

- Enabling Automatic Startup

- Manually Starting a Daemon on z/OS Platforms

- Starting Multiple Daemons

- Stopping a Daemon

- Shutting Down a Daemon Using Oracle Studio for IMS, VSAM, and Adabas Gateways

- Shutting Down a Daemon Using the Command Line

- Disabling a Workspace

- Checking the Daemon

- Managing Daemon Configurations

- Daemon Configuration Groups

- Adding and Editing Daemon Configurations

- Configuring Logging

- Adding and Editing Workspaces

- Adding a Workspace

- Editing a Workspace

- WS Info

- WS Server

- WS Logging

- WS Security

- WS Governing

- Managing Binding Configurations

- Server Binding

- Client Binding

- Binding Syntax

- <remoteMachines> Statement

- <datasources> Statement

- Sample Binding

- Environment Properties

- Sample Environment Properties

14 Managing Security for Oracle Connect for IMS, VSAM, and Adabas Gateways

- Managing Design Time Security

- Setting Up the Password Caching Policy in Oracle Studio for IMS, VSAM, and Adabas Gateways

- Setting Up Administration Access to a Machine

- Assigning Design Roles

- Assigning Authorization Rights to a Workspace

- Setting Up a Master Password for a User Profile

- Managing Runtime Security

- Granting Daemon Administration Rights to Users

- Granting Workspace Administration Rights to Users

- Granting Workspace Access Rights to a User

- Accessing a Server through a Firewall

- Specifying a Port Range for Workspace Servers

- Accessing a Server Using Fixed NAT

- Encrypting Network Communications

- Transport Encryption

- Setting an Encryption Protocol on the Gateway Side

- Specifying the Encryption Key on the Server Machine

- Setting Up Impersonation

Part VI Appendixes

A Using Response Files for Non-Interactive Installation

- Introduction

- Installation Overview

- Creating the oraInst.loc File

- Preparing a Response File

- Editing a Response File Template

- Recording a Response File

- Running Oracle Universal Installer in Silent or Suppressed Mode

B Initialization Parameters

- Initialization Parameter File Syntax

- HS_DB_DOMAIN

- HS_DB_INTERNAL_NAME

- HS_DB_NAME

- HS_DESCRIBE_CACHE_HWM

- HS_LANGUAGE

- Character Sets

- Language

- Territory

- HS_LONG_PIECE_TRANSFER_SIZE

- HS_OPEN_CURSORS

- HS_RPC_FETCH_REBLOCKING

- HS_RPC_FETCH_SIZE

- HS_TRANSACTION_MODEL

- IFILE

- HS_FDS_CONNECT_INFO

- HS_FDS_PARSER_TOKEN_SIZE

- HS_FDS_RECOVERY_ACCOUNT

- HS_FDS_RECOVERY_PWD

- HS_FDS_TRACE_LEVEL

- HS_NLS_NCHAR

- HS_NLS_NUMERIC_CHARACTER

- HS_FDS_DATASOURCE_NAME

- HS_FDS_ACCESS_METHOD

C Oracle Database Gateway Troubleshooting

- Verify Requirements

- What to do if an Installation Error Occurs

- Reviewing the Log of an Installation Session

- Silent Mode Response File Error Handling

- Cleaning Up after a Failed Installation

Index

Oracle® Database Gateway

for IMS, VSAM, and Adabas Installation and Configuration Guide

11g Release 2 (11.2) for AIX 5L Based Systems (64-Bit), HP-UX Itanium, Solaris Operating System (SPARC 64-Bit), Linux x86, and Linux x86-64

E12076-03

October 2010

Oracle Database Gateway for IMS, VSAM, and Adabas Installation and Configuration Guide, 11g Release 2 (11.2) for AIX 5L Based Systems (64-Bit), HP-UX Itanium, Solaris Operating System (SPARC 64-Bit), Linux x86, and Linux x86-64

E12076-03

Copyright © 2008, 2010, Oracle and/or its affiliates. All rights reserved.

Primary Author:  Jeanne Wiegelmann

Contributing Author:  Maitreyee Chaliha, Sami Zeitoun, Oussama Mkaabal

Contributor:  Vira Goorah, Peter Wong

This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited.

The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing.

If this software or related documentation is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, the following notice is applicable:

U.S. GOVERNMENT RIGHTS Programs, software, databases, and related documentation and technical data delivered to U.S. Government customers are "commercial computer software" or "commercial technical data" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, the use, duplication, disclosure, modification, and adaptation shall be subject to the restrictions and license terms set forth in the applicable Government contract, and, to the extent applicable by the terms of the Government contract, the additional rights set forth in FAR 52.227-19, Commercial Computer Software License (December 2007). Oracle USA, Inc., 500 Oracle Parkway, Redwood City, CA 94065.

This software is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications which may create a risk of personal injury. If you use this software in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure the safe use of this software. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software in dangerous applications.

Oracle is a registered trademark of Oracle Corporation and/or its affiliates. Other names may be trademarks of their respective owners.

This software and documentation may provide access to or information on content, products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services.

Preface

This manual describes the installation and configuration of Oracle Database Gateway for IMS, VSAM, and Adabas, which enables Oracle client applications to access IMS, VSAM, and Adabas data through Structured Query Language (SQL). The gateway, with the Oracle Database, creates the appearance that all data is located on a local Oracle Database, even though the data can be widely distributed.

Audience

This manual is intended for Oracle database administrators who perform the following tasks:

- Installing the components of the Oracle Database Gateway for IMS, VSAM, and Adabas

- Configuring the components of the Oracle Database Gateway for IMS, VSAM, and Adabas

- Diagnosing gateway errors

Note:

You should understand the fundamentals of database gateways before using this guide to install or administer the gateway.

Documentation Accessibility

Our goal is to make Oracle products, services, and supporting documentation accessible to all users, including users that are disabled. To that end, our documentation includes features that make information available to users of assistive technology. This documentation is available in HTML format, and contains markup to facilitate access by the disabled community. Accessibility standards will continue to evolve over time, and Oracle is actively engaged with other market-leading technology vendors to address technical obstacles so that our documentation can be accessible to all of our customers. For more information, visit the Oracle Accessibility Program Web site at http://www.oracle.com/accessibility/.

Accessibility of Code Examples in Documentation

Screen readers may not always correctly read the code examples in this document. The conventions for writing code require that closing braces should appear on an otherwise empty line; however, some screen readers may not always read a line of text that consists solely of a bracket or brace.

Accessibility of Links to External Web Sites in Documentation

This documentation may contain links to Web sites of other companies or organizations that Oracle does not own or control. Oracle neither evaluates nor makes any representations regarding the accessibility of these Web sites.

Access to Oracle Support

Oracle customers have access to electronic support through My Oracle Support. For information, visit http://www.oracle.com/support/contact.html or visit http://www.oracle.com/accessibility/support.html if you are hearing impaired.

Related Documents

For more information, see the following documents in the Oracle Database Gateway 11g Release 2 (11.2) documentation set:

- Oracle Database New Features

- Oracle Call Interface Programmer's Guide

- Oracle Enterprise Manager Administrator's Guide

- Oracle Database Administrator's Guide

- Oracle Application Developer's Guide - Fundamentals

- Oracle Database Concepts

- Oracle Database Performance Tuning Guide and Reference

- Oracle Database Performance Planning

- Oracle Database Error Messages

- Oracle Database Globalization Support Guide

- Oracle Database Reference

- Oracle SQL Reference

- Oracle Net Services Administrator's Guide

- SQL*Plus User's Guide and Reference

- Oracle Database Heterogeneous Connectivity User's Guide

- Oracle 2 Day DBA

- Oracle Database Security Guide

Conventions

The following text conventions are used in this document:

Convention

Meaning

boldface

Boldface type indicates graphical user interface elements associated with an action, or terms defined in text or the glossary.

italic

Italic type indicates book titles, emphasis, or placeholder variables for which you supply particular values.

monospace

Monospace type indicates commands within a paragraph, URLs, code in examples, text that appears on the screen, or text that you enter.

Part I

Getting Started with Oracle Database Gateways

Part I, "Getting Started with Oracle Database Gateways," contains the following chapters:

Chapter 1, "Getting Started with Oracle Database Gateway"

1 Getting Started with Oracle Database Gateway

This chapter contains the following sections:

- Overview

- Oracle Heterogeneous Services

- Oracle Database Gateways

- Gateway Architecture

- Gateway Process Flow

- Setup Flow

Overview

Heterogeneous data access is a problem that affects a lot of companies. A lot of companies run several different database systems. Each of these systems stores data and has a set of applications that run against it. Consolidation of this data in one database system is often hard—in large part because many of the applications that run against one database may not have an equivalent that runs against another. Until such time as migration to one consolidated database system is made feasible, it is necessary for the various heterogeneous database systems to interoperate.

Oracle Database Gateways provide the ability to transparently access data located in a non-Oracle system from an Oracle environment. This transparency eliminates the need for application developers to customize their applications to access data from different non-Oracle systems, thus decreasing development efforts and increasing the mobility of the application. Applications can be developed using a consistent Oracle interface for both Oracle and VSAM, IMS, or Adabas.

Gateway technology is composed of two parts: a component that has the generic technology to connect to a non-Oracle system, which is common to all the non-Oracle systems, called Heterogeneous Services, and a component that is specific to the non-Oracle system that the gateway connects to. Heterogeneous Services, in conjunction with the Database Gateway agent and Oracle Connect for IMS, VSAM, and Adabas Gateways, enables transparent access to non-Oracle systems from an Oracle environment.

Oracle Heterogeneous Services

Heterogeneous Services provides the generic technology for connecting to non-Oracle systems. As an integrated component of the database, Heterogeneous Services can exploit features of the database, such as the powerful SQL parsing and distributed optimization capabilities.

Heterogeneous Services extends the Oracle SQL engine to recognize the SQL and procedural capabilities of the remote non-Oracle system and the mappings required to obtain necessary data dictionary information. Heterogeneous Services provides two types of translations: the ability to translate Oracle SQL into the proper dialect of the non-Oracle system and the ability to handle data dictionary translations so that the metadata of the non-Oracle system is displayed in the local format. For situations where no translations are available, native SQL can be issued to the non-Oracle system using the pass-through feature of Heterogeneous Services.

Heterogeneous Services also maintains the transaction coordination between Oracle and the remote non-Oracle system, such as providing the global transaction protocol to ensure distributed transaction integrity, even for non-Oracle systems that do not natively support global transactions.

See Also:

Oracle Database Heterogeneous Connectivity User's Guide for more information about Heterogeneous Services.

Oracle Database Gateways

Oracle Database Gateways for IMS, VSAM, and Adabas allow Oracle client applications to access IMS, VSAM, and Adabas data through Structured Query Language (SQL). The gateway, with the Oracle database server, creates the appearance that all data resides on a local Oracle database server, even though data might be widely distributed. If data is moved from these data sources to an Oracle database, no changes in the client application's design or function are needed because the gateway handles all differences in data types or SQL functions between the applications and the database.

Using Oracle SQL, Oracle client applications can access data sources such as IMS, VSAM, and Adabas as if the data was stored in an Oracle table. A single SQL statement can access data residing in Oracle and VSAM, IMS, or Adabas data sources, performing heterogeneous joins and subselects. This means that you can develop one set of portable applications to use against Oracle and these non-relational data sources. You can continue to develop new information systems without losing your investment in existing data and applications.

Transactions updating Oracle and these non-relational data sources are automatically protected by the Oracle global transactions feature. Use of synonyms is another Oracle feature. By setting up synonyms in the Oracle database server that point to database links to VSAM, IMS, or Adabas files, the physical location of the data is transparent to the client application. This allows future migration of data from the VSAM, IMS, or Adabas data source to Oracle to be transparent to the client applications.

The gateway requires the Oracle database server, Oracle Connect for IMS, VSAM, and Adabas Gateways, and Oracle Studio for IMS, VSAM, and Adabas Gateways. All other Oracle products are optional. However, using other Oracle products with the gateway can greatly extend the gateway's capabilities.

The gateway can be installed on a computer where the Oracle database is installed, or on a second, standalone machine. Each configuration has its advantages and disadvantages. The issues to consider when you determine where to install the gateway are network traffic, availability of the operating system platform, hardware resources, and storage.

Oracle Connect for IMS, VSAM, and Adabas Gateways must be installed on the z/OS system where the VSAM, IMS, or Adabas data source is installed. To be able to configure and manage Oracle Connect for IMS, VSAM, and Adabas Gateways, you need to install Oracle Studio for IMS, VSAM, and Adabas Gateways on a computer running Windows or Linux.

Gateway Architecture

The gateway is invoked by the listener. The gateway is not multi-threaded and cannot support shared database links. Each gateway session spawns a separate gateway process, and connections cannot be shared.

The gateway is located on a Windows or UNIX computer. The non-relational data source resides on a computer running IBM z/OS. The Oracle database server can reside on the same system as the gateway or on another system.

The gateway interacts with the Oracle database server to interface between client applications and the VSAM, IMS, or Adabas data source, as shown in Figure 1-1.

Note:

The non-Oracle system in Figure 1-1 and Figure 1-2 represents the VSAM, IMS, or Adabas data source.

Figure 1-1 Gateway Processing

- Client applications, such as Developer, connect to the Oracle database server by using Oracle Net.

- The Oracle database server, which includes Heterogeneous Services and the database itself, resides on a single system. This Oracle database server also stores definitions of database links for the non-Oracle system.

- The gateway to VSAM, IMS, and Adabas resides on a second system.

- The VSAM, IMS, or Adabas data source, together with Oracle Connect for IMS, VSAM, and Adabas Gateways, resides on a third system, which is an IBM z/OS platform.

- Oracle Studio for IMS, VSAM, and Adabas Gateways, which is used to configure Oracle Connect for IMS, VSAM, and Adabas Gateways, resides on a fourth system, which can be running a Windows or Linux operating system.

- The Oracle database server on the first system uses Oracle Net to connect directly to the VSAM, IMS, or Adabas gateway on the second system. The gateway itself uses the Oracle Connect for IMS, VSAM, and Adabas Gateways protocol to connect to Oracle Connect for IMS, VSAM, and Adabas Gateways, which then connects to the non-Oracle system using the same protocol.

The Oracle database server and the gateway work together to present the appearance of a single Oracle database to the client. All data accessed by the client appears to reside in a single Oracle database. The client application sends a request to the Oracle database server, and the Oracle database server sends the request to the gateway.

For the first transaction in a session, the gateway logs into the VSAM, IMS, or Adabas data source using a username and password that is valid in the respective data source. The gateway converts the SQL statement to a native VSAM, IMS, or Adabas statement, and the VSAM, IMS, or Adabas data source performs the request. The gateway converts the retrieved data to a format compatible with the Oracle database server and returns the results to the Oracle database server, which returns the results to the client application.

Gateway Process Flow

Figure 1-2 shows a typical gateway process flow. The steps explain the sequence of the events that occurs when a client application queries the VSAM, IMS, or Adabas data source through the gateway.

Figure 1-2 Gateway Process Flow

1. The client application sends a query over Oracle Net to the Oracle database server.

2. The Oracle database server sends the query over to the gateway, again using Oracle Net.

3. The gateway passes the query on to Oracle Connect for IMS, VSAM, and Adabas Gateways.

4. For the first transaction in a session, Oracle Connect for IMS, VSAM, and Adabas Gateways logs into the VSAM, IMS, or Adabas data source using a user name and password that is valid in the respective data source.

5. Oracle Connect for IMS, VSAM, and Adabas Gateways converts the Oracle SQL statement into a data access operation understood by the data source.

6. Oracle Connect for IMS, VSAM, and Adabas Gateways retrieves the data.

7. Oracle Connect for IMS, VSAM, and Adabas Gateways converts the retrieved data into a format compatible with the Oracle database server.

8. Oracle Connect for IMS, VSAM, and Adabas Gateways passes the data to the gateway using the Oracle Connect for IMS, VSAM, and Adabas Gateways protocol.

9. The gateway returns the query results to the Oracle database server, again using Oracle Net.

10. The Oracle database server passes the query results to the client application by using Oracle Net. The database link remains open until the gateway session is finished or the database link is explicitly closed.

Setup Flow

To be able to access VSAM, IMS, or Adabas data, you need to perform the tasks described in the following list, in the specified order. Each step in the list directs you to the relevant manual or chapter.

1. Install Oracle Connect for IMS, VSAM, and Adabas Gateways

See:

Oracle Connect for IMS, VSAM, and Adabas Gateways Installation and Configuration Guide for IBM z/OS for information on installing Oracle Connect for IMS, VSAM, and Adabas Gateways

2. Install Oracle Studio for IMS, VSAM, and Adabas Gateways

See:

Chapter 11, "Installing Oracle Studio for IMS, VSAM, and Adabas Gateways" for information on installing Oracle Studio for IMS, VSAM, and Adabas Gateways

3. Configure Oracle Connect for IMS, VSAM, and Adabas Gateways

See:

Chapter 13, "Configuring Oracle Connect through Oracle Studio for IMS, VSAM, and Adabas Gateways" for information on configuring Oracle Connect for IMS, VSAM, and Adabas Gateways

4. Set up the connection to Oracle Connect for IMS, VSAM, and Adabas Gateways

See:

Relevant topic in any of the following chapters:

- Chapter 2, "Configuring Access to VSAM Data"

- Chapter 5, "Configuring Access to IMS Data"

- Chapter 8, "Configuring Access to Adabas Data"

5. Set up the VSAM, IMS, or Adabas data source

See:

Relevant topic in any of the following chapters:

- Chapter 2, "Configuring Access to VSAM Data"

- Chapter 5, "Configuring Access to IMS Data"

- Chapter 8, "Configuring Access to Adabas Data"

6. Set up the data source metadata

See:

- Chapter 2, "Configuring Access to VSAM Data"

- Chapter 5, "Configuring Access to IMS Data"

- Chapter 8, "Configuring Access to Adabas Data"

7. Install Oracle Database Gateway for VSAM, IMS, or Adabas

See:

- Chapter 3, "Installing Oracle Database Gateway for VSAM"

- Chapter 6, "Installing Oracle Database Gateway for IMS"

- Chapter 9, "Installing Oracle Database Gateway for Adabas"

8. Configure Oracle Database Gateway for VSAM, IMS, or Adabas

See:

- Chapter 4, "Configuring Oracle Database Gateway for VSAM"

- Chapter 7, "Configuring Oracle Database Gateway for IMS"

- Chapter 10, "Configuring Oracle Database Gateway for Adabas"

Part II

Installing and Configuring Oracle Database Gateway for VSAM

Before performing any of the tasks described in this part, you should read Part I, "Getting Started with Oracle Database Gateways" to get an overview of the technology, the architecture, and the process involved in installing and configuring Oracle Database Gateway for VSAM.

To be able to access VSAM data, you need to perform the tasks described in the following list, in the specified order. Each step in the list directs you to the relevant manual or chapter.

By now, you should have completed tasks 1 – 3. This part describes how to perform tasks 4 – 8.

1. Install Oracle Connect for IMS, VSAM, and Adabas Gateways
See Oracle Connect for IMS, VSAM, and Adabas Gateways Installation and Configuration Guide for IBM z/OS for information on installing Oracle Connect for IMS, VSAM, and Adabas Gateways.

2. Install Oracle Studio for IMS, VSAM, and Adabas Gateways
See Chapter 11, "Installing Oracle Studio for IMS, VSAM, and Adabas Gateways" for information on installing Oracle Studio for IMS, VSAM, and Adabas Gateways.

3. Configure Oracle Connect for IMS, VSAM, and Adabas Gateways
See Chapter 13, "Configuring Oracle Connect through Oracle Studio for IMS, VSAM, and Adabas Gateways" for information on configuring Oracle Connect for IMS, VSAM, and Adabas Gateways.

4. Set up the connection to Oracle Connect for IMS, VSAM, and Adabas Gateways
See Chapter 2, "Configuring Access to VSAM Data" for information on setting up the connection to Oracle Connect for IMS, VSAM, and Adabas Gateways.

5. Set up the VSAM data source
See Chapter 2, "Configuring Access to VSAM Data" for information on setting up the VSAM data source.

6. Set up the VSAM metadata
See Chapter 2, "Configuring Access to VSAM Data" for information on setting up the VSAM metadata.

7. Install Oracle Database Gateway for VSAM
See Chapter 3, "Installing Oracle Database Gateway for VSAM" for information on installing Oracle Database Gateway for VSAM.

8. Configure Oracle Database Gateway for VSAM
Chapter 4, "Configuring Oracle Database Gateway for VSAM" for information on configuring Oracle Database Gateway for VSAM

Part II, "Installing and Configuring Oracle Database Gateway for VSAM," describes how to configure access to the VSAM data source and install and configure Oracle Database Gateway for VSAM.

It contains the following chapters:

- Chapter 2, "Configuring Access to VSAM Data"

- Chapter 3, "Installing Oracle Database Gateway for VSAM"

- Chapter 4, "Configuring Oracle Database Gateway for VSAM"

2 Configuring Access to VSAM Data

This chapter explains how to configure access to VSAM data by using Oracle Studio for IMS, VSAM, and Adabas Gateways. It contains the following sections:

- Setting Up Access to a Computer Running Oracle Connect for IMS, VSAM, and Adabas Gateways

- Setting Up a VSAM Data Source

- Setting Up the Metadata of the VSAM Data Source

- Setting Up the Metadata of the VSAM (CICS) Data Source

Setting Up Access to a Computer Running Oracle Connect for IMS, VSAM, and Adabas Gateways

To be able to access VSAM data, you must have a working connection to Oracle Connect for IMS, VSAM, and Adabas Gateways, which is installed on the IBM z/OS computer where your VSAM files are located. You establish this connection by using Oracle Studio for IMS, VSAM, and Adabas Gateways.

Whenever needed, you can also use Oracle Studio for IMS, VSAM, and Adabas Gateways to configure Oracle Connect for IMS, VSAM, and Adabas Gateways.

Note:

The following task assumes that you have permission to access the IBM z/OS platform and that the Oracle Connect for IMS, VSAM, and Adabas Gateways daemon is running on this computer. Check with the system administrator to ensure these requirements are fulfilled.

Perform the following steps to set up access to a computer that runs Oracle Connect for IMS, VSAM, and Adabas Gateways.

1. From the Start menu, select Programs, point to Oracle, and select Studio. Oracle Studio for IMS, VSAM, and Adabas Gateways opens.

2. In the Design perspective's Configuration view, right-click the Machines folder and select Add Machines.
The Add machine screen opens, as shown in Figure 2-1.

Figure 2-1 Add Machine Screen.

Enter the following information in each field:

- Host name/IP address: Enter the name of the computer on the network or click Browse, to browse all the systems running a daemon listener on the specified port currently accessible over the network.

- Port: Enter the port number where the daemon is running. The default port is 2551.

- Display name: Enter an alias used to identify the system when different from the host name (optional).

- User name: Enter the system administrator's user name.

Note:

You indicate the system administrator when the system is installed or by using the NAV_UTIL utility ADD_ADMIN operation. For details, see Oracle Connect for IMS, VSAM, and Adabas Gateways Installation and Configuration Guide for IBM z/OS.

- Password: Enter the system administrator's password. This is the password for the user entered in the User name field. If no password is necessary to access this system, do not enter anything.

- Connect via NAT with fixed IP address: Select this if the system uses the NAT (Network Address Translation) firewall protocol, with a fixed configuration, mapping each external IP to one internal IP, regardless of the port specified.

3. Click Finish.
The computer is displayed in the Configuration view, in the Machine folder. You can edit the system's login information, or configure bindings, daemons, and users for each system.

Setting Up a VSAM Data Source

Oracle Connect for IMS, VSAM, and Adabas Gateways supports the following types of VSAM data sources:

- VSAM (CICS): The VSAM under CICS data source accesses VSAM by making calls from the external CICS interface (EXCI) to a CICS program that is provided as part of the Oracle Connect for IMS, VSAM, and Adabas Gateways installation. This CICS program does the actual VSAM reads and writes from within CICS.
When you access VSAM data using this data source, the following restrictions apply:

- SQL DELETE operations are not supported for ESDS files.

- Using an alternate index to access an entry sequenced data set (ESDS) file is not supported.

- A non-unique alternate index for a key sequenced data set (KSDS) file is not supported.

- VSAM/Batch: This data source connects directly to the VSAM data and is limited if the VSAM files are managed by CICS. In this case, it is recommended to use this data source for read-only access to VSAM files. However, this may not give you adequate read integrity if some changes are buffered by CICS. Another alternative is to use the VSAM under CICS data source.
When you access VSAM data using the VSAM data source, the following restrictions apply:

- Transactions are not supported when you access VSAM directly. When you access VSAM under CICS, global transactions are supported.

- Locking is not supported.

- You cannot update an array value (a child record in a hierarchical table) when the parent record is included in the SQL in a subquery.

- SQL DELETE operations are not supported for ESDS files.

- An relative record data set (RRDS) file cannot have an alternate index.

- The primary key of a KSDS file must be one segment only (however, it can be several consecutive fields). You cannot modify the primary key value of a KSDS file.

This section describes how to set up a VSAM data source using Oracle Studio for IMS, VSAM, and Adabas Gateways. It includes the following tasks:

- Defining the VSAM Data Source Connection or Defining the VSAM (CICS) Data Source Connection

- Configuring the VSAM or VSAM (CICS) Data Source Properties

- Setting Up the Metadata of the VSAM Data Source

Defining the VSAM Data Source Connection

Perform the following steps to define the connection to the VSAM data source.

1. In Oracle Studio for IMS, VSAM, and Adabas Gateways, in the Configuration view of the Design perspective, open the binding of the system where the data is located.

2. Right-click Data Source and select New Data Source.
The New Data Source screen opens, as shown in Figure 2-2.

Figure 2-2 New Data Source Screen

3. Specify a name for the data source in the Name field.

Note:

The name you assign to each data source that you define must be noted and used consistently throughout all phases of the gateway configuration.

4. From the Type list, select VSAM and click Next.
Click Next.

5. Specify the connect string as follows:

- Data HLQ: The high-level qualifier where the data files are located.

- Disk Volume Name: The high-level qualifier (volume) where the data is located.
The values specified are used in the Data File field in the Oracle Studio for IMS, VSAM, and Adabas Gateways Design Perspective Metadata tab. For tables created using the CREATE TABLE statement, the values specified are used to create the data files. If values are not specified, then data files are written to the DEF high-level qualifier under the high-level qualifier where Oracle Connect for IMS, VSAM, and Adabas Gateways is installed.

When SMS is used to manage the volumes, leave this value empty and set the newFileSMSStorageClass and newFileSMSDataClass properties as described in VSAM Data Source Parameters.

6. Click Finish.

Defining the VSAM (CICS) Data Source Connection

Perform the following steps to define the connection to the VSAM (CICS) data source:

1. In Oracle Studio for IMS, VSAM, and Adabas Gateways, in the Configuration view of the Design perspective, open the binding of the system where the data is located.

2. Right-click Data Source and select New Data Source.
The New Data Source screen opens, as shown in Figure 2-3.

Figure 2-3 New Data Source Screen

3. Specify a name for the data source in the Name field.

4. From the Type list, select VSAM (CICS) and click Next.
The Data Source Connect String screen is displayed.

5. Specify the connect string as follows:

- CICS Application ID: The VTAM applied of the CICS target system. The default value is CICS. This parameter is used when updating VSAM data. You can determine this value by activating the CEMT transaction on the target CICS system. In the bottom right corner of the screen appears the legend APPLID=target_system.

- Transaction ID: The mirror transaction within CICS that receives control through MRO, which transfers the transaction from the Oracle Connect for IMS, VSAM, and Adabas Gateways environment to CICS. The default value is EXCI.

- VTAM Netname: The VTAM netname of the specific connection being used by EXCI (and MRO) to relay the program call to the CICS target system. For example, if you issue the following command to CEMT:
CEMT INQ CONN

Then you see on the display screen that the netname is BATCHCLI (this is the default connection supplied by IBM upon the installation of CICS). The default value is ATYCLIEN.

If you plan to use the IBM defaults, specify BATCHCLI as the VTAM_netname parameter, otherwise define a specific connection (with EXCI protocol) and use the netname you provided there for this parameter.

- Oracle provides a netname, ATYCLIEN that can be used after the following procedure is followed:
Either, use the JCL in the NAVROOT.USERLIB(CICSCONF) member to submit the DFHCSDUP batch utility program to add the resource definitions to the DFHCSD dataset (see the IBM CICS Resource Definition Guide for further details).

or:

Use the instream SYSIN control statements in the NAVROOT.USERLIB(CICSCONF) member as a guide to defining the resources online using the CEDA facility.

- After the definitions have been added (through batch or using the CEDA facility), logon to CICS and issue the following command to install the resource definitions under CICS:
CEDA INST GROUP(ATYI)

Henceforth, specify ATYCLIEN as the NETNAME.

- Program Name: The UPDTRNS program that is supplied with Oracle Connect for IMS, VSAM, and Adabas Gateways to enable updating VSAM data. To use the UPDTRNS program, copy the program from NAVROOT.LOAD to a CICS DFHRPL library (such as CICS.USER.LOAD) and then define the UPDTRNS program under CICS using any available group:
CEDA DEF PROG(UPDTRNS) G(group_name) LANG(C) DA(ANY) DE(ATTUNIT VSAM UPDATE PROG)

NAVROOT is the high-level qualifier where Oracle Connect for IMS, VSAM, and Adabas Gateways is installed.

After defining the UPDTRNS program, install it as follows:

CEDA IN G(group_name)

- Trace Queue: The name of the queue for output that is defined under CICS when tracing the output of the UPDTRNS program. When not defined, the default CICS queue is used.

6. Click Finish.

Configuring the VSAM or VSAM (CICS) Data Source Properties

After defining the connection to the VSAM (CICS) data source, perform the following steps to configure the data source properties.

1. In Oracle Studio for IMS, VSAM, and Adabas Gateways, in the Configuration view of the Design perspective, right-click the data source and select Edit Data Source.

2. In the editor, on the Properties tab, configure the data source parameters as required. For a description of the available parameters, see "VSAM Data Source Parameters" or "VSAM (CICS) Data Source Parameters".

3. If you want to configure VSAM (CICS) to support rollback, on the Advanced tab, from the Transaction type list, select 1PC or 2PC, depending on the data source usage.
If you do not use 2PC, see the Oracle Database Heterogeneous Connectivity User's Guide for configuration information.

4. On the Advanced tab, configure how arrays will be handled by selecting the relevant check boxes in the Virtual View Policy section. The following options are available:

- Generate sequential view: Select this option if you want to map a non-relational file to a single table.

- Generate virtual views: Select this option if you want to have an individual table created for every array in the non-relational file.

- Include row number column: Select this option if you want to include a column that specifies the row number in the virtual or sequential view.

- Inherit all parent columns: Select this option if you want the virtual views to include all the columns of the parent record.

5. Save your settings.

VSAM Data Source Parameters

The following parameters can be configured for VSAM data sources in the Properties tab of the Configuration Properties screen:

- disableExplicitSelect=true|false: When set to true, this parameter disables the ExplicitSelect ADD attribute; every field is returned by a SELECT * FROM... statement.

- filepoolCloseOnTransaction=true|false: This parameter specifies that all files in the file pool for this data source close at each end of transaction (commit or rollback).

- filepoolSize=n: This parameter specifies how many instances of a file from the file pool may be open concurrently.

- newFileLocation=string: This parameter is the Data HLQ in the connect string that specifies the high-level qualifier for the file.

- newFileSMSStorageClass=string: This parameter specifies the storage class when SMS is used to manage volumes.

- newFileSMSDataClass=string: This parameter specifies the data class when SMS is used to manage volumes.

- newFileVolume=string: This parameter specifies the file volume where the file is catalogued (data disk in the connect string).

- useGlobalFilepool=true|false: This parameter specifies whether or not a global file pool that can span more than one session is used.

VSAM (CICS) Data Source Parameters

The following parameters can be configured for VSAM (CICS) data sources in the Properties tab of the Configuration Properties screen:

- allowUpdateKey=true|false: When set to true, this parameter specifies that the key is updatable.

- cicsProgname=string: The ProgramName in the connect string, this parameter specifies the UPDTRNS program that is supplied with Oracle Connect for IMS, VSAM, and Adabas Gateways to enable updating VSAM data.

- cicsTraceQueue=string: The TraceQueue in the connect string, this parameter indicates the name of queue for output that is defined under CICS when tracing the output of the UPDTRNS program. When not defined, the default CICS queue is used.

- disableExplicitSelect=true|false: When set to true, this parameter disables the ExplicitSelect ADD attribute; every field is returned by a SELECT * FROM... statement.

- exciTransid=string: The Transaction ID in the connect string, this parameter indicates the CICS TRANSID. This value must be EXCI or a copy of this transaction.

- targetSystemApplid=string: The CICS Application ID in the connect string, this parameter specifies the VTAM applid of the CICS target system.

- TransactionType=true|false: When set to true, this parameter specifies that the key is updatable.

- vtamNetname=string: The VTAM Netname in the connect string, this parameter specifies the connection being used by EXCI (and MRO) to relay the program call to the CICS target system.

Setting Up the Metadata of the VSAM Data Source

Defining VSAM metadata by using the Import Manager of Oracle Studio for IMS, VSAM, and Adabas Gateways requires a COBOL copybook that contains the COBOL definition of the VSAM records.

If the metadata is provided in a number of COBOL copybooks with different filter settings, such as whether the first 6 columns are ignored or not (see Apply Filters), first import the metadata from copybooks with the same settings, and then import the metadata from the other copybooks.

The import process includes the following tasks:

1. Import the COBOL Copybooks

2. Apply Filters

3. Select Tables

4. Manipulate the Imported Tables

5. Create VSAM Indexes

6. Assign Index File Names

7. Select the Metadata Model

8. Import the Metadata

Import the COBOL Copybooks

This section describes the steps required to import the COBOL copybooks that will be used to generate the metadata. You can import new copybooks or use copybooks that you already imported earlier.

To import new copybooks, perform the following procedure.

1. In the Configuration view, right-click the data source and select Edit Metadata.
The Metadata tab is displayed with the data source displayed in the Metadata view.

2. Right-click the Imports node under the data source and select New Import.
The Metadata Import screen opens, as shown in Figure 2-4:

Figure 2-4 Metadata Import Screen

3. Enter a name for the import. The name can contain letters, numbers and the underscore character.

4. Select VSAM Import Manager or VSAM Under CICS Import Manager as the import type as required.

5. Click Finish.
The Metadata import wizard opens with the Get Input Files screen, as shown in Figure 2-5:

Figure 2-5 The Get Input Files Screen

6. Click Add.
The Add Resource screen opens, as shown in Figure 2-6:

Figure 2-6 Add Resource Screen

7. If the files are located on another computer, do any of the following:

- Right-click My FTP Sites and select Add.
The Add FTP Site screen opens, as shown in the following figure.

- Enter the server name where the COBOL copybooks are located and, if not using an anonymous connection, enter a valid username and password to access the computer. The username is then used as the high-level qualifier.

- Click OK. After accessing the remote computer, you can change the high-level qualifier by right-clicking the system in the Add Resource screen and selecting Change Root Directory.

- Select the files to import and click Finish to start the file transfer. When complete, the selected files are displayed in the Get Input Files screen.
To remove any of these files, select the required file and click Remove.

8. Click Next.
The Apply Filters screen opens (see Apply Filters).

To use copybooks that you imported earlier, perform the following procedure.

1. In the Configuration view, right-click the data source and select Edit Metadata.
The Metadata tab is displayed with the data source displayed in the Metadata view.

2. Expand the Imports node under the data source, right-click the existing import, and select Open.
The Metadata import wizard opens with the Get Input Files screen, showing the copybooks that you imported.

3. Click Next.
The Apply Filters screen opens (see Apply Filters).

Apply Filters

This section describes the steps required to apply filters on the COBOL copybooks used to generate the Metadata. It continues the Import the COBOL Copybooks procedure. Perform the following procedure.

1. Expand all nodes in the Apply Filters screen.

Figure 2-7 Apply Filters Screen

2. Apply the required filter attributes to the COBOL copybooks.
The following table describes the available filters.

Table 2-1 Metadata Filters

Filter

Description

COMP_6 switch

The MicroFocus COMP-6 compiler directive. Specify either COMP-6'1' to treat COMP-6 as a COMP data type or COMP-6'2' to treat COMP-6 as a COMP-3 data type.

Compiler source

z/OS

Storage mode

The MicroFocus Integer Storage Mode. Specify one of the following:

- NOIBMCOMP for byte storage mode.

- IBMCOMP for word storage mode.

Ignore after column 72

When set to true, ignores columns 73 to 80 in the COBOL copybook.

IgnoreFirst6

When set to true, ignores the first six columns in the COBOL copybook.

Replace hyphens (-) in record and field names with underscores (_)

When set to true, replaces all hyphens in either the record or field names in the metadata generated from the COBOL with underscore characters.

Prefix nested columns

When set to true, prefix all nested columns with the previous level heading.

Case sensitive

Specifies whether to be sensitive to the search string case.

Find

Searches for the specified value.

Replace with

Replaces the value specified for Find with the value specified here

3. Click Next.
The Select Tables screen opens (see Select Tables).

Select Tables

This section describes the steps required to select the tables from the COBOL copybooks. The import manager identifies the names of the records in the COBOL copybooks that will be imported as tables.

This task continues the Apply Filters task. Perform these steps to select the required tables.

1. From the Select Tables screen, select the tables that you want to access. To select all tables, click Select All. To clear the selection, click Unselect All.

Figure 2-8 Select Tables Screen

2. Click Next.
The Import Manipulation screen opens (see Manipulate the Imported Tables).

Manipulate the Imported Tables

If required, you can now manipulate the imported tables. This is an optional task.

This section describes the operations available for manipulating the imported tables. It continues the Select Tables task.

The import manager identifies 01 level names in the copybooks that will be imported as tables. You can manipulate the general table data in the Import Manipulation Screen.

Perform the following steps to manipulate the table metadata.

1. In the Data Location column, click the browse button to specify the data file location. The Select Resources dialog box opens.

2. In the File Name box, enter the location of the data file and click Finish.

3. From the Import Manipulation screen (for details, see Import Manipulation Screen), right-click the table record marked with a validation error and select the relevant operation. Table 2-2 describes the available operations.

4. Repeat step 1 for all tables marked with a validation error. You resolve the issues in the Import Manipulation Screen.
Once all the validation error issues have been resolved, the Import Manipulation screen is displayed with no error indicators.

5. Click Next to continue to the Create VSAM Indexes.

Import Manipulation Screen

Figure 2-9 shows the Import Manipulation screen.

Figure 2-9 Import Manipulation Screen

The upper area of the screen lists the table names and their validation status. The metadata source specifies the copybook in which the table is defined.

The Validation tab at the lower area of the screen displays information about what needs to be resolved to validate the tables and fields generated from the COBOL. The Log tab displays a log of what has been performed (such as renaming a table or specifying a data location).

The following operations are available in the Import Manipulation screen:

- Resolving table names, where tables with the same name are generated from different files during the import.

- Selecting the physical location for the data.

- Selecting table attributes.

- Manipulating the fields generated from the COBOL, as follows:

- Merging sequential fields into one (for simple fields).

- Resolving variants by either marking a selector field or specifying that only one case of the variant is relevant.

- Adding, deleting, hiding, or renaming fields.

- Changing a data type.

- Setting the field size and scale.

- Changing the order of the fields.

- Setting a field as nullable.

- Selecting a counter field for array for fields with dimensions (arrays). You can select the array counter field from a list of potential fields.

- Setting column-wise normalization for fields with dimensions (arrays). You can create new fields instead of the array field where the number of generated fields will be determined by the array dimension.

- Creating arrays and setting the array dimension.

The following table describes the available operations when you right-click a table entry.

Table 2-2 Table Manipulation Options

Option

Description

Fields Manipulation

Customizes the field definitions, using the Field Manipulation screen. You can also access this screen by double-clicking the required table record.

Rename

Renames a table. This option is used especially when more than one table with the same name is generated from the COBOL.

Set data location

Sets the physical location of the data file for the table.

Set table attributes

Sets the table attributes.

XSL manipulation

Specifies an XSL transformation or JDOM document that is used to transform the table definitions.

Remove

Removes the table record.

You can manipulate the data in the table fields in the Field Manipulation Screen. Double-click a line in the Import Manipulation Screen to open the Field Manipulation Screen.

Field Manipulation Screen

The Field Manipulation screen lets you make changes to fields in a selected table. You get to the Field Manipulation screen by double-clicking a table in the Import Manipulation Screen. The Field Manipulation screen is shown in Figure 2-10.

Figure 2-10 Field Manipulation Screen

The values displayed in the table on the Field Manipulation screen are calculated by the import process.

You can carry out all of the available tasks in this screen through the menu or toolbar. You can also right-click anywhere in the screen and select any of the options available in the main menus from a shortcut menu. The following table describes the tasks that are done in this screen. If a toolbar button is available for a task, it is pictured in the table.

The following table describes the commands that are available in the Field Manipulation screen.

Table 2-3 Field Manipulation Screen Commands

Command

Description

General menu

Undo

Click to undo the last change made in the Field Manipulation screen.

Select fixed offset

The offset of a field is usually calculated dynamically by the server at run time according to the offset and size of the proceeding column. Select this option to override this calculation and specify a fixed offset at design time. This can happen if there is a part of the buffer that you want to skip.

When you select a fixed offset you pin the offset for that column. The indicated value is used at run time for the column instead of a calculated value. Note that the offset of following columns that do not have a fixed offset are calculated from this fixed position.

Test import tables

Select this table to create an SQL statement to test the import table. You can base the statement on the Full table or Selected columns. When you select this option, the following screen opens with an SQL statement based on the table or column entered at the bottom of the screen.

Enter the following in this screen:

- Data file name: Enter the name of the file that contains the data you want to query.

- Limit query results: Select this if you want to limit the results to a specified number of rows. Enter the amount of rows you want returned in the following field. 100 is the default value.

- Define Where Clause: Click Add to select a column to use in a Where clause. In the table below, you can add the operator, value and other information. Click on the columns to make the selections. To remove a Where Clause, select the row with the Where Clause you want t remove and then click Remove.

The resulting SQL statement with any Where Clauses that you added are displayed at the bottom of the screen.

Click OK to send the query and test the table.

Attribute menu

Change data type

Select Change data type from the Attribute menu to activate the Type column, or click the Type column and select a new data type from the list.

Create array

This command allows you to add an array dimension to the field. Select this command to open the Create Array screen.

Enter a number in the Array Dimension field and click OK to create the array for the column.

Hide/Reveal field

Select a row from the Field manipulation screen and select Hide field to hide the selected field from that row. If the field is hidden, you can select Reveal field.

Set dimension

Select this to change or set a dimension for a field that has an array. Select Set dimension to open the Set Dimension screen.

Edit the entry in the Array Dimension field and click OK to set the dimension for the selected array.

Set field attribute

Select a row to set or edit the attributes for the field in the row. Select Set field attribute to open the Field Attribute screen.

Click in the Value column for any of the properties listed and enter a new value or select a value from a list.

Nullable/Not nullable

Select Nullable to activate the Nullable column in the Field Manipulation screen. You can also click in the column.

Select the check box to make the field Nullable. Clear the check box to make the field Not Nullable.

Set scale

Select this to activate the Scale column or click in the column and enter the number of places to display after the decimal point in a data type.

Set size

Select this to activate the Size column or click in the column and enter the number of total number of characters for a data type.

Field menu

Add

Select this command or use the button to add a field to the table. If you select a row with a field (not a child of a field), you can add a child to that field. Select Add Field or Add Child to open the following screen:

Enter the name of the field or child, and click OK to add the field or child to the table.

Delete field

Select a row and then select Delete Field or click the Delete Field button to delete the field in the selected row.

Move up or down

Select a row and use the arrows to move it up or down in the list.

Rename field

Select Rename field to make the Name field active. Change the name and then click outside of the field.

Structures menu

Columnwise Normalization

Select Columnwise Normalization to create new fields instead of the array field where the number of generated fields will be determined by the array dimension.

Combining sequential fields

Select Combining sequential fields to combine two or more sequential fields into one simple field. The following dialog box opens:

Enter the following information in the Combining sequential fields screen:

- First field name: Select the first field in the table to include in the combined field

- End field name: Select the last field to be included in the combined field. Make sure that the fields are sequential.

- Enter field name: Enter a name for the new combined field.

Flatten group

Select Flatten Group to flatten a field that is an array. This field must be defined as Group for its data type. When you flatten an array field, the entries in the array are spread into a new table, with each entry in its own field. The following screen provides options for flattening.

Do the following in this screen:

- Select Recursive operation to repeat the flattening process on all levels. For example, if there are multiple child fields in this group, you can place the values for each field into the new table when you select this option.

- Select Use parent name as prefix to use the name of the parent field as a prefix when creating the new fields. For example, if the parent field is called Car Details and you have a child in the array called Color, when a new field is created in the flattening operation it will be called Car Details_Color.

Mark selector

Select Mark selector to select the selector field for a variant. This is available only for variant data types. Select the Selector field form the following screen.

Replace variant

Select Replace variant to replace a variant's selector field.

Select counter field

Select Counter Field opens a screen where you select a field that is the counter for an array dimension.

Create VSAM Indexes

Oracle Studio for IMS, VSAM, and Adabas Gateways automatically creates the VSAM indexes from the physical data file. Click Next to continue to the Select the Metadata Model task.

Note:

Oracle Studio for IMS, VSAM, and Adabas Gateways does not create any indexes for design systems.

Select the Metadata Model

This screen allows you to generate virtual and sequential views for tables containing arrays. In addition, you can configure the properties of the generated views.

This screen continues the Create VSAM Indexes procedure.

In the Metadata Model Selection screen, you can select default values that apply to all tables or set specific settings per table. This screen inherits its default settings from the settings that you defined for the virtual view policy when you configured the data source properties (see Configuring the VSAM or VSAM (CICS) Data Source Properties).

Note:

Selecting the Default values for all tables check box discards any table-specific settings that you set.

Perform the following steps to select the metadata model.

1. Select from the following:

- Default values for all tables: Select this option if you want to apply the same values to all tables to be imported.

- Generate sequential view: Select this option if you want to map a non-relational file to a single table.

- Generate virtual views: Select this option if you want to have an individual table created for every array in the non-relational file.

- Virtual views include row number: Select this option if you want to include a column that specifies the row number in the virtual or sequential view.

- Virtual views inherit all parent columns: Select this option if you want the virtual views to include all the columns of the parent record.

- Specific virtual array view settings per table: Select this option if you want to apply different values to the tables to be imported. Then select the relevant check boxes.

Note:

After importing a table, you can change these settings on the Modeling tab of the table editor.

2. Click Next to continue to the Import the Metadata task.

Figure 2-11 shows the Metadata Model Selection screen.

Figure 2-11 Metadata Model Selection Screen

Import the Metadata

This section describes the steps required to import the metadata to the target computer. It continues the Assign Index File Names task.

You can now import the metadata to the computer where the data source is located, or import it later (in case the target computer is not available).

Perform the following steps to import the metadata.

1. Specify Yes to transfer the metadata to the target computer or No to transfer the metadata later.

2. Click Finish.

If you specified Yes, the metadata is imported to the target computer immediately.

Figure 2-12 shows the Import Metadata screen.

Figure 2-12 Import Metadata Screen

Setting Up the Metadata of the VSAM (CICS) Data Source

Defining VSAM metadata by using the Import Manager of Oracle Studio for IMS, VSAM, and Adabas Gateways requires a COBOL copybook that contains the COBOL definition of the VSAM records.

If the metadata is provided in a number of COBOL copybooks with different filter settings, such as whether the first 6 columns are ignored or not (see Apply Filters), first import the metadata from copybooks with the same settings, and then import the metadata from the other copybooks.

The import process includes the following tasks:

1. Import the COBOL Copybooks

2. Apply Filters

3. Select Tables

4. Manipulate the Imported Tables

5. Create VSAM Indexes

6. Assign Index File Names

7. Select the Metadata Model

8. Import the Metadata

Import the COBOL Copybooks

This section describes the steps required to import the COBOL copybooks that will be used to generate the metadata. You can import new copybooks or use copybooks that you already imported earlier.

To import new copybooks, perform the following procedure.

1. In the Configuration view, right-click the data source and select Edit Metadata.
The Metadata tab is displayed with the data source displayed in the Metadata view.

2. Right-click the Imports node under the data source and select New Import.
The Metadata Import screen opens, as shown in Figure 2-4:

Figure 2-13 Metadata Import Screen

3. Enter a name for the import. The name can contain letters, numbers and the underscore character.

4. Select VSAM Import Manager or VSAM Under CICS Import Manager as the import type as required.

5. Click Finish.
The Metadata import wizard opens with the Get Input Files screen, as shown in Figure 2-5:

Figure 2-14 The Get Input Files Screen

6. Click Add.
The Add Resource screen opens, as shown in Figure 2-6:

Figure 2-15 Add Resource Screen

7. If the files are located on another computer, do any of the following:

- Right-click My FTP Sites and select Add.
The Add FTP Site screen opens, as shown in the following figure.

- Enter the server name where the COBOL copybooks are located and, if not using an anonymous connection, enter a valid username and password to access the computer. The username is then used as the high-level qualifier.

- Click OK. After accessing the remote computer, you can change the high-level qualifier by right-clicking the system in the Add Resource screen and selecting Change Root Directory.

- Select the files to import and click Finish to start the file transfer. When complete, the selected files are displayed in the Get Input Files screen.
To remove any of these files, select the required file and click Remove.

8. Click Next.
The Apply Filters screen opens (see Apply Filters).

To use copybooks that you imported earlier, perform the following procedure.

1. In the Configuration view, right-click the data source and select Edit Metadata.
The Metadata tab is displayed with the data source displayed in the Metadata view.

2. Expand the Imports node under the data source, right-click the existing import, and select Open.
The Metadata import wizard opens with the Get Input Files screen, showing the copybooks that you imported.

3. Click Next.
The Apply Filters screen opens (see Apply Filters).

Apply Filters

This section describes the steps required to apply filters on the COBOL copybooks used to generate the Metadata. It continues the Import the COBOL Copybooks procedure. Perform the following procedure.

1. Expand all nodes in the Apply Filters screen.

Figure 2-16 Apply Filters Screen

2. Apply the required filter attributes to the COBOL copybooks.
The following table describes the available filters.

Table 2-4 Metadata Filters

Filter

Description

COMP_6 switch

The MicroFocus COMP-6 compiler directive. Specify either COMP-6'1' to treat COMP-6 as a COMP data type or COMP-6'2' to treat COMP-6 as a COMP-3 data type.

Compiler source

z/OS

Storage mode

The MicroFocus Integer Storage Mode. Specify one of the following:

- NOIBMCOMP for byte storage mode.

- IBMCOMP for word storage mode.

Ignore after column 72

When set to true, ignores columns 73 to 80 in the COBOL copybook.

IgnoreFirst6

When set to true, ignores the first six columns in the COBOL copybook.

Replace hyphens (-) in record and field names with underscores (_)

When set to true, replaces all hyphens in either the record or field names in the metadata generated from the COBOL with underscore characters.

Prefix nested columns

When set to true, prefix all nested columns with the previous level heading.

Case sensitive

Specifies whether to be sensitive to the search string case.

Find

Searches for the specified value.

Replace with

Replaces the value specified for Find with the value specified here

3. Click Next.
The Select Tables screen opens (see Select Tables).

Select Tables

This section describes the steps required to select the tables from the COBOL copybooks. The import manager identifies the names of the records in the COBOL copybooks that will be imported as tables.

This task continues the Apply Filters task. Perform these steps to select the required tables.

1. From the Select Tables screen, select the tables that you want to access. To select all tables, click Select All. To clear the selection, click Unselect All.

Figure 2-17 Select Tables Screen

2. Click Next.
The Import Manipulation screen opens (see Manipulate the Imported Tables).

Manipulate the Imported Tables

If required, you can now manipulate the imported tables. This is an optional task.

This section describes the operations available for manipulating the imported tables. It continues the Select Tables task.

The import manager identifies 01 level names in the copybooks that will be imported as tables. You can manipulate the general table data in the Import Manipulation Screen.

Perform the following steps to manipulate the table metadata.

1. From the Import Manipulation screen (for details, see Import Manipulation Screen), right-click the table record marked with a validation error and select the relevant operation. Table 2-2 describes the available operations.

2. Repeat step 1 for all tables marked with a validation error. You resolve the issues in the Import Manipulation Screen.
Once all the validation error issues have been resolved, the Import Manipulation screen is displayed with no error indicators.

3. Click Next to continue to the Create VSAM Indexes.

Import Manipulation Screen

Figure 2-9 shows the Import Manipulation screen.

Figure 2-18 Import Manipulation Screen

The upper area of the screen lists the table names and their validation status. The metadata source specifies the copybook in which the table is defined.

The Validation tab at the lower area of the screen displays information about what needs to be resolved to validate the tables and fields generated from the COBOL. The Log tab displays a log of what has been performed (such as renaming a table or specifying a data location).

The following operations are available in the Import Manipulation screen:

- Resolving table names, where tables with the same name are generated from different files during the import.

- Selecting the physical location for the data.

- Selecting table attributes.

- Manipulating the fields generated from the COBOL, as follows:

- Merging sequential fields into one (for simple fields).

- Resolving variants by either marking a selector field or specifying that only one case of the variant is relevant.

- Adding, deleting, hiding, or renaming fields.

- Changing a data type.

- Setting the field size and scale.

- Changing the order of the fields.

- Setting a field as nullable.

- Selecting a counter field for array for fields with dimensions (arrays). You can select the array counter field from a list of potential fields.

- Setting column-wise normalization for fields with dimensions (arrays). You can create new fields instead of the array field where the number of generated fields will be determined by the array dimension.

- Creating arrays and setting the array dimension.

The following table describes the available operations when you right-click a table entry.

Table 2-5 Table Manipulation Options

Option

Description

Fields Manipulation

Customizes the field definitions, using the Field Manipulation screen. You can also access this screen by double-clicking the required table record.

Rename

Renames a table. This option is used especially when more than one table with the same name is generated from the COBOL.

Set data location

Sets the physical location of the data file for the table.

Set table attributes

Sets the table attributes.

XSL manipulation

Specifies an XSL transformation or JDOM document that is used to transform the table definitions.

Remove

Removes the table record.

You can manipulate the data in the table fields in the Field Manipulation Screen. Double-click a line in the Import Manipulation Screen to open the Field Manipulation Screen.

Field Manipulation Screen

The Field Manipulation screen lets you make changes to fields in a selected table. You get to the Field Manipulation screen by double-clicking a table in the Import Manipulation Screen. The Field Manipulation screen is shown in Figure 2-10.

Figure 2-19 Field Manipulation Screen

The values displayed in the table on the Field Manipulation screen are calculated by the import process.

You can carry out all of the available tasks in this screen through the menu or toolbar. You can also right-click anywhere in the screen and select any of the options available in the main menus from a shortcut menu. The following table describes the tasks that are done in this screen. If a toolbar button is available for a task, it is pictured in the table.

The following table describes the commands that are available in the Field Manipulation screen.

Table 2-6 Field Manipulation Screen Commands

Command

Description

General menu

Undo

Click to undo the last change made in the Field Manipulation screen.

Select fixed offset

The offset of a field is usually calculated dynamically by the server at run time according to the offset and size of the proceeding column. Select this option to override this calculation and specify a fixed offset at design time. This can happen if there is a part of the buffer that you want to skip.

When you select a fixed offset you pin the offset for that column. The indicated value is used at run time for the column instead of a calculated value. Note that the offset of following columns that do not have a fixed offset are calculated from this fixed position.

Test import tables

Select this table to create an SQL statement to test the import table. You can base the statement on the Full table or Selected columns. When you select this option, the following screen opens with an SQL statement based on the table or column entered at the bottom of the screen.

Enter the following in this screen:

- Data file name: Enter the name of the file that contains the data you want to query.

- Limit query results: Select this if you want to limit the results to a specified number of rows. Enter the amount of rows you want returned in the following field. 100 is the default value.

- Define Where Clause: Click Add to select a column to use in a Where clause. In the table below, you can add the operator, value and other information. Click on the columns to make the selections. To remove a Where Clause, select the row with the Where Clause you want t remove and then click Remove.

The resulting SQL statement with any Where Clauses that you added are displayed at the bottom of the screen.

Click OK to send the query and test the table.

Attribute menu

Change data type

Select Change data type from the Attribute menu to activate the Type column, or click the Type column and select a new data type from the list.

Create array

This command allows you to add an array dimension to the field. Select this command to open the Create Array screen.

Enter a number in the Array Dimension field and click OK to create the array for the column.

Hide/Reveal field

Select a row from the Field manipulation screen and select Hide field to hide the selected field from that row. If the field is hidden, you can select Reveal field.

Set dimension

Select this to change or set a dimension for a field that has an array. Select Set dimension to open the Set Dimension screen.

Edit the entry in the Array Dimension field and click OK to set the dimension for the selected array.

Set field attribute

Select a row to set or edit the attributes for the field in the row. Select Set field attribute to open the Field Attribute screen.

Click in the Value column for any of the properties listed and enter a new value or select a value from a list.

Nullable/Not nullable

Select Nullable to activate the Nullable column in the Field Manipulation screen. You can also click in the column.

Select the check box to make the field Nullable. Clear the check box to make the field Not Nullable.

Set scale

Select this to activate the Scale column or click in the column and enter the number of places to display after the decimal point in a data type.

Set size

Select this to activate the Size column or click in the column and enter the number of total number of characters for a data type.

Field menu

Add

Select this command or use the button to add a field to the table. If you select a row with a field (not a child of a field), you can add a child to that field. Select Add Field or Add Child to open the following screen:

Enter the name of the field or child, and click OK to add the field or child to the table.

Delete field

Select a row and then select Delete Field or click the Delete Field button to delete the field in the selected row.

Move up or down

Select a row and use the arrows to move it up or down in the list.

Rename field

Select Rename field to make the Name field active. Change the name and then click outside of the field.

Structures menu

Columnwise Normalization

Select Columnwise Normalization to create new fields instead of the array field where the number of generated fields will be determined by the array dimension.

Combining sequential fields

Select Combining sequential fields to combine two or more sequential fields into one simple field. The following dialog box opens:

Enter the following information in the Combining sequential fields screen:

- First field name: Select the first field in the table to include in the combined field

- End field name: Select the last field to be included in the combined field. Make sure that the fields are sequential.

- Enter field name: Enter a name for the new combined field.

Flatten group

Select Flatten Group to flatten a field that is an array. This field must be defined as Group for its data type. When you flatten an array field, the entries in the array are spread into a new table, with each entry in its own field. The following screen provides options for flattening.

Do the following in this screen:

- Select Recursive operation to repeat the flattening process on all levels. For example, if there are multiple child fields in this group, you can place the values for each field into the new table when you select this option.

- Select Use parent name as prefix to use the name of the parent field as a prefix when creating the new fields. For example, if the parent field is called Car Details and you have a child in the array called Color, when a new field is created in the flattening operation it will be called Car Details_Color.

Mark selector

Select Mark selector to select the selector field for a variant. This is available only for variant data types. Select the Selector field form the following screen.

Replace variant

Select Replace variant to replace a variant's selector field.

Select counter field

Select Counter Field opens a screen where you select a field that is the counter for an array dimension.

Assign File Names

This section describes the steps required to specify the physical file name and the corresponding logical CICS file name for each VSAM table. It continues the Manipulate the Imported Tables task.

Perform the following to assign file names.

1. In the Assign File Names screen, enter the name of an existing physical VSAM file for each table listed.
Oracle Studio for IMS, VSAM, and Adabas Gateways needs the physical VSAM file name to be able to create a list of its alternate indexes in the Assign Index File Names task.

2. Specify the CICS logical file name for each physical file.

3. Click Next to continue to the Assign Index File Names task.
The Assign Index File Names screen opens.

Figure 2-20 shows the Assign File Names screen.

Figure 2-20 Assign File Names Screen

Assign Index File Names

This section describes the steps required to specify the logical CICS names of the alternate indexes. It continues the Create VSAM Indexes task.

To assign the logical CICS index names

1. Specify the logical CICS alternate index name for each alternate index listed.

2. Click Next to continue to the Select the Metadata Model task.
The Import Metadata screen opens.

Figure 2-21 shows the Assign Index File Names screen.

Figure 2-21 Assign Index File Names Screen

Select the Metadata Model

This screen allows you to generate virtual and sequential views for tables containing arrays. In addition, you can configure the properties of the generated views.

This screen continues the Assign Index File Names procedure.

In the Metadata Model Selection screen, you can select default values that apply to all tables or set specific settings per table. This screen inherits its default settings from the settings that you defined for the virtual view policy when you configured the data source properties (see Configuring the VSAM or VSAM (CICS) Data Source Properties).

Note:

Selecting the Default values for all tables check box discards any table-specific settings that you set.

Perform the following steps to select the metadata model.

1. Select from the following:

- Default values for all tables: Select this option if you want to apply the same values to all tables to be imported.

- Generate sequential view: Select this option if you want to map a non-relational file to a single table.

- Generate virtual views: Select this option if you want to have an individual table created for every array in the non-relational file.

- Virtual views include row number: Select this option if you want to include a column that specifies the row number in the virtual or sequential view.

- Virtual views inherit all parent columns: Select this option if you want the virtual views to include all the columns of the parent record.

- Specific virtual array view settings per table: Select this option if you want to apply different values to the tables to be imported. Then select the relevant check boxes.

Note:

After importing a table, you can change these settings on the Modeling tab of the table editor.

2. Click Next to continue to the Import the Metadata task.

Figure 2-11 shows the Metadata Model Selection screen.

Figure 2-22 Metadata Model Selection Screen

Import the Metadata

This section describes the steps required to import the metadata to the target computer. It continues the Assign Index File Names task.

You can now import the metadata to the computer where the data source is located, or import it later (in case the target computer is not available).

Perform the following to import the mentadata.

1. Select Yes to transfer the metadata to the target computer or No to transfer the metadata later.

2. Click Finish.

If you selected Yes, the metadata is imported to the target computer immediately.

Figure 2-12 shows the Import Metadata screen.

Figure 2-23 Import Metadata Screen

The script content on this page is for navigation purposes only and does not alter the content in any way.

3 Installing Oracle Database Gateway for VSAM

This chapter guides you through the installation procedure of Oracle Database Gateway for VSAM.

To install the gateway, follow these steps:

1. Ensure that the system meets all of the hardware and software requirements specified in "System Requirements for Oracle Database Gateway for VSAM".

2. Run the Oracle Universal Installer.
See "Running the Oracle Universal Installer" for more information about running the Oracle Universal Installer.

Oracle Universal Installer is a menu-driven utility that guides you through the installation of the gateway by prompting you with action items. The action items and the sequence in which they appear depend on your platform.

3. Configure the gateway.
Chapter 4, "Configuring Oracle Database Gateway for VSAM" provides information on how to configure the gateway.

Overview of Oracle Database Gateway for VSAM

Oracle Database Gateway for VSAM consists of the following components:

- Oracle Studio for IMS, VSAM, and Adabas Gateways, a GUI-based tool that lets you configure the Oracle Connect for IMS, VSAM, and Adabas Gateways servers in your system. Oracle Studio for IMS, VSAM, and Adabas Gateways runs on Windows and Linux platforms.

- Oracle Connect for IMS, VSAM, and Adabas Gateways, which is natively located on the data server to provide standard, service-oriented integration to VSAM data. Oracle Connect for IMS, VSAM, and Adabas Gateways runs on z/OS platforms.

- Oracle Database Gateway, which provides the capabilities, SQL mappings, data type conversions, and interface to the remote non-Oracle system. The gateway interacts with Heterogeneous Services to provide the transparent connectivity between Oracle and non-Oracle systems.
The gateway must be installed on a Windows or UNIX computer. This can be the same system as the Oracle database server or a second, standalone system.

System Requirements for Oracle Database Gateway for VSAM

This section provides information about the hardware and software requirements for the gateway. It contains the following sections:

- Hardware Requirements for Oracle Database Gateway for VSAM

- Software Requirements for Oracle Database Gateway for VSAM

Hardware Requirements for Oracle Database Gateway for VSAM

Table 3-1 lists the hardware requirements for Oracle Database Gateway for VSAM on UNIX.

Table 3-1 Hardware Requirements for Oracle Database Gateway for VSAM

Requirement

IBM AIX

HP-UX Itanium (64-bit Itanium)

Sun Solaris (SPARC) 64-bit

Linux x86

Linux x86 64-bit

Temporary disk space

700 MBFoot 1

700 MB

700 MB

700 MB

700 MB

Disk space

1.5 GB

1.5 GB

750 MB

750 MB

750 MB

Physical memory

512 MB

512 MB

512 MB

512 MB

512 MB

Swap space

1 GB

1 GB

1 GB

1 GB

1 GB

Processor

IBM RS/6000 AIX-based system processor

HP chipset sx2000 processor for HP-UX 11i v2

Sun Solaris (SPARC) processor

Processor chips that adhere to the x86 32-bit architecture

Processor chips that adhere to the x86 64-bit architecture

Footnote 1 This temporary disk space requirement assumes you download the software. The temporary disk space is less than 300 MB if you install from CD or DVD media.

Software Requirements for Oracle Database Gateway for VSAM

Oracle Database Gateway for VSAM is supported on the UNIX operating systems specified in table Table 3-2.

Table 3-2 Software Requirements for Oracle Database Gateway for VSAM

Operating System

Version

Linux x86 (32-bit)

- Asianux 2.0 and 3.0

- Red Hat Enterprise Linux 4.0 and 5.0

- Oracle Linux 4.0 and 5.0

- SUSE Linux Enterprise Server 10.0

Linux x86 64-bit

- Red Hat Enterprise Linux 4.0 and 5.0

- Oracle Linux 4.0 and 5.0

Sun Solaris Sparc 64-bit

- Solaris 10

HP-UX Itanium 64-bit

- HP-UX 11.31 or higher

IBM AIX 5L 64-bit

- Version 5.3, Maintenance Level 02 or later

Gateway Installation Configurations

You can install the gateway in either of the following configurations:

- On the same computer as an existing Oracle database but in a different ORACLE_HOME directory.

- On a system with no Oracle database.

- On the same computer as the Oracle database and in the same ORACLE_HOME directory. Note that in this case, the Oracle database and the gateway must be at the same release level.

Gateway Installation Methods

You can choose different installation methods to install the gateway, as follows:

- Interactive Installation Method

- Automated Installation Method Using Response Files

Interactive Installation Method

When you use the interactive method to install the gateway, Oracle Universal Installer displays a series of screens that enable you to specify all of the required information to install the gateway software.

Automated Installation Method Using Response Files

By creating a response file and specifying this file when you start Oracle Universal Installer, you can automate some or all of the gateway installation steps. These automated installation methods are useful if you need to perform multiple installations on similarly configured systems or if the system where you want to install the software does not have X Window system software installed.

When you use a response file, you can run Oracle Universal Installer in the following modes, depending on whether you specify all of the required information or not:

- Silent Mode: Oracle Universal Installer runs in silent mode if you use a response file that specifies all required information. None of the Oracle Universal Installer screens are displayed.

- Suppressed Mode: Oracle Universal Installer runs in suppressed mode if you do not specify all required information in the response file. Oracle Universal Installer displays only the screens that prompt for the information that you did not specify.

See Appendix A, "Using Response Files for Non-Interactive Installation" for more information about this method and about how to complete an installation using response files.

Gateway Installation Considerations

This section contains information that you should consider before installing this product. It contains the following sections:

- Release Notes

- Hardware and Software Certification

- Multiple ORACLE_HOME Directories

Release Notes

Read the release notes for the product before installing it. The release notes are available on the Oracle Database 11g Release 2 (11.2) installation media. The latest version of the release notes is also available on the Oracle Technology Network (OTN) Web site:

http://www.oracle.com/technology/documentation/index.html

Hardware and Software Certification

The platform-specific hardware and software requirements included in this installation guide were current at the time this guide was published. However, because new platforms and operating system software versions might be certified after this guide is published, review the certification matrix on the OracleMetaLink Web site for the most up-to-date list of certified hardware platforms and operating system versions. The OracleMetaLink Web site is available at the following Web site:

http://metalink.oracle.com

If you do not have a current Oracle Support Services contract, then you can access the same information at the following Web site:

http://www.oracle.com/technology/support/metalink/content.html

Multiple ORACLE_HOME Directories

This product supports multiple ORACLE_HOME directories. This means that you can install this release or previous releases of the software more than once on the same system, in different ORACLE_HOME directories.

Installing the Software on a System with an Existing Oracle Installation

You must install this product in a new ORACLE_HOME directory. You cannot install products from one release of the gateway into an ORACLE_HOME directory of a different release.

Upgrades

Upgrades are not supported for Oracle Database Gateways.

Accessing the Installation Software

You can access and install the gateway by using the following methods:

- Downloading Oracle Software from the Oracle Technology Network Web Site

- Copying the Gateway Software to a Hard Disk

Downloading Oracle Software from the Oracle Technology Network Web Site

This section describes how to download the installation files and extract them on your hard disk. It contains the following topics:

- Downloading the Installation Files

- Extracting the Installation Files

Downloading the Installation Files

To download the installation files from the Oracle Technology Network (OTN):

1. Use any browser to access the software download page on OTN:
http://www.oracle.com/technology/software

2. Navigate to the download page for the product that you want to install.

3. On the download page, identify the required disk space by adding the file sizes for each required file.
The file sizes are listed next to the file names.

4. Select a file system with enough free space to store and expand the archive files.
In most cases, the available disk space must be at least twice the size of each compressed file.

5. On the file system that you selected in step 4, create a parent directory for each product, for example, dg4vsam, to hold the installation directories.

6. Download all of the installation archive files to the directory that you created in step 5.

7. Verify that the files you downloaded are the same size as the corresponding files on OTN.

Extracting the Installation Files

To extract the installation files:

1. If necessary, change directory to the directory that contains the downloaded installation archive files.

2. To extract each file, enter the gunzip command.
For example:

$ gunzip filename.cpio.gz

This command creates files with names similar to the following:

filename.cpio

3. To extract the installation files, enter the cpio command.
For example:

$ cpio -idmv < filename.cpio

Note:

Refer to the download page for information about the correct options to use with the cpio command. Some browsers extract files while downloading them, but leave the .gz file extension. If these steps do not work, remove the .gz extension from the files and repeat step 3.

For each file, this command creates a subdirectory named Diskn, where n is either 1 or the disk number identified in the file name.

Copying the Gateway Software to a Hard Disk

Before installing the gateway, you might want to copy the software to the hard disk. This enables the installation process to run faster. Before copying the installation media content to the hard disk, you must mount the installation media.

Mounting the Installation Media

On most Sun Solaris operating systems, the disc mounts automatically when you insert it into the disc drive. If the disc does not mount automatically, perform the following steps to mount it:

1. Enter the following command to switch user to root:
$ su - root

2. If necessary, enter a command similar to one of the following to eject the currently mounted disc, then remove the disc from the drive:
On Sun Solaris (SPARC):

# eject

On IBM AIX:

# umount /cdrom

On HP-UX Itanium:

# /usr/sbin/umount /SD_CDROM

In these examples, /cdrom and /SD_CDROM are the mount point directories for the disc drive.

3. Insert the appropriate disc into the disc drive.

4. To verify that the disc mounted automatically, enter a command similar to the following, depending on your platform:
Sun Solaris (SPARC):

# ls /cdrom/cdrom0

5. If this command fails to display the contents of the disc, enter a command similar to the following to mount it, depending on your platform:
Sun Solaris (SPARC):

# /usr/sbin/mount -r -F hsfs /dev/dsk/cxtydzs2 /cdrom

In this example, /cdrom is the disc mount point directory and /dev/dsk/cxtydzs2 is the device name for the disc device, for example /dev/dsk/c0t2d0s2.

6. If Oracle Universal Installer displays the Disk Location dialog box, enter the disk mount point directory path, for example:
/mnt/cdrom

After you have the Oracle Gateway shiphome image, Oracle Connect for IMS, VSAM, and Adabas Gateways software is located in the following directory:

/gateways/legacy/Connect/Connect.zip

Copying the Oracle Database Gateway Software to a Hard Disk

To copy the contents of the disc to a hard disk:

1. Create a directory on the hard disk to hold the Oracle software:
$ mkdir Ora10g

2. Change directory to the directory you created in step 1:
$ cd Ora10g

3. Create subdirectories for each installation disc with names similar to the following, where n is the disc number:
$ mkdir Diskn

4. Copy the contents of the mounted disc to the corresponding new subdirectory as follows:
$ cp -R /directory_path Diskn

In this example, n is the disc number and /directory_path is the installation media mount point directory. The mount point directory is /cdrom.

5. If necessary, mount the next disc and repeat step 4.

Running the Oracle Universal Installer

Start the Installer and install the software, as follows:

1. If you are installing the software from disc, then mount the disc if it is not already mounted.
Some platforms automatically mount discs when you insert them into the drive.

2. If necessary, log in as the Oracle software owner user (oracle) and set the DISPLAY environment variable.

3. To start the Installer, enter the following commands where directory_path is the CD-ROM mount point directory or the path of the dg directory on the DVD-ROM.
directory_path/runInstaller

4. Follow the instruction displayed in the Installer window.

Caution:

The Oracle Universal Installer automatically installs the Oracle-supplied version of the Java Runtime Environment (JRE). This version is required to run Oracle Universal Installer and several Oracle assistants. Do not modify the JRE except by using a patch provided by Oracle Support Services.

Table 3-3 describes the installation procedure for Oracle Database Gateway for VSAM.

Note:

- When the Installer prompts you to run a script with root privileges, enter a command similar to the following in a terminal where you are logged in as the root user, then click Continue or OK:
# /script_path/script_name

- On Tru64 UNIX, when prompted for the JDK home directory, specify the location of JDK 1.4.2 on your system.
To determine the JDK home directory, enter the following command:

# /usr/sbin/setld -i JAVA142 | more

The default location is /usr/opt/java142.

Table 3-3 The Oracle Universal Installer: Steps for Installing the Gateway

Screen

Response

Oracle Universal Installer: Welcome

Click Next.

Oracle Universal Installer: Specify Home Details

The Path field in the Specify Home Details screen is where you specify the destination for your installation. You need not edit the path specification in the Path field. The default setting for this field points to ORACLE_HOME. After you set the fields in the Specify Home Details screen as necessary, click Next to continue. After loading the necessary information from the installation, the Oracle Universal Installer displays the Available Products screen.

Oracle Universal Installer: Available Product Components

Select Oracle Database Gateway for VSAM 11.2.0.

Click Next.

Oracle Database Gateway for VSAM

Oracle Connect for IMS, VSAM, and Adabas Gateways Host Name: Specify the host name of the system running Oracle Connect for IMS, VSAM, and Adabas Gateways on z/OS.

Oracle Connect for IMS, VSAM, and Adabas Gateways Port number: Specify the port number Oracle Connect for IMS, VSAM, and Adabas Gateways listens on.Click Next to continue.

Oracle Universal Installer: Summary

The Installation Summary screen enables you to review a tree list of options and components for this installation.

Click Install to display the Installation Status screen.

Oracle Net Configuration Assistant: Welcome

Click Cancel.

Oracle Net Configuration Assistant:

Click Yes.

Oracle Universal Installer: Configuration Tools

When Oracle Universal Installer confirms that the installation is complete, verify that the installation procedure was successful. To do this, read the contents of the installation log file, which is located in the following directory:

[designated_inventory_location]\OraInventory\logs

The default file name is InstallActionsYYYY-MM-DD_HH-mm-SS-AM/PM.log, where:

YYYY is year

MM is month

DD is day

HH is hour

mm is minute

SS is seconds

AM/PM is daytime or evening

Each of these variables in the log file name represents the date and time the product was installed.

When you finish configuring, click Exit.

Exit

Click Exit.

If you need additional information, click Help.

If you encounter errors while installing or linking the software, then see Appendix C, "Oracle Database Gateway Troubleshooting" for information about troubleshooting.

4 Configuring Oracle Database Gateway for VSAM

After installing the gateway, perform the following tasks to configure the gateway for VSAM:

- Configuring the Gateway

- Configuring Oracle Net Services Listener for the Gateway

- Configuring the Oracle Database for Gateway Access

- Creating Database Links

- Gateway Password Encryption Tool

- Configuring the Gateway for Multiple VSAM Databases

- Performing Configuration Tasks

- Testing the VSAM Data Source

Configuring the Gateway

Perform the following tasks to configure Oracle Database Gateway for VSAM:

1. Choose a System Identifier for the Gateway

2. Customize the Initialization Parameter File

Choose a System Identifier for the Gateway

Choosing a system identifier is the first task in configuring Oracle Database Gateway for VSAM. The gateway system identifier (SID) is an alphanumeric character string that identifies a gateway instance. If you want to connect simultaneously to different VSAM data sources, you need one gateway instance, and therefore one gateway SID, for each VSAM data source. The SID name is used as part of the file name for the initialization parameter file. The default SID is dg4vsam.

The HS_FDS_DATASOURCE_NAME parameter takes on the gateway SID as the default value. This means that the data source matches the gateway SID by default. However, you can specify the value of the HS_FDS_DATASOURCE_NAME parameter to match the data source that you want to access. See "HS_FDS_DATASOURCE_NAME" for more information.

If you have one VSAM data source and want to access it sometimes with one set of gateway parameter settings, and other times with a different set of gateway parameter settings, you can define two different data sources and define the matching SIDs accordingly.

Customize the Initialization Parameter File

Customizing the initialization parameter file is the second task in configuring Oracle Database Gateway for VSAM. The initialization parameter file must be available when the gateway is started. During installation, the following default initialization parameter file is created:

$ORACLE_HOME/dg4vsam/admin/initdg4vsam.ora

Where $ORACLE_HOME is the directory in which the gateway is installed.

The name of the parameter file is init[SID].ora, where SID is the gateway SID. If you are not using dg4vsam as the gateway SID, you must rename the initialization parameter file using the SID you chose in Task 1. This default initialization parameter file is sufficient for starting the gateway, verifying a successful installation, and running the demonstration scripts.

In the initialization parameter file, specify the VSAM connection as follows:

- If you use the default workspace:

HS_FDS_CONNECT_INFO="address:port"

- If you use a workspace other than the default:

HS_FDS_CONNECT_INFO="address='host' port='port' workspace='workspace'"

Where:

- host: The name of the mainframe computer on which Oracle Connect for IMS, VSAM, and Adabas Gateways runs.

- port: The port number to listen to.

- workspace: The VSAM data source workspace name (optional).

HS_FDS_ACCESS_METHOD must be set to VSAM-CICS for VSAM (CICS) data sources. See Appendix B, "Initialization Parameters" for details.

A number of initialization parameters can be used to modify the gateway behavior. You may want to change the initialization parameter file later to meet system requirements.

See Also:

The Oracle Database Heterogeneous Connectivity Administrator's Guide for more information about customizing the initialization parameter file.

Configuring Oracle Net Services Listener for the Gateway

The gateway requires Oracle Net Services to provide transparent data access. After configuring the gateway, configure Oracle Net Services to work with the gateway.

1. Configure Oracle Net Services Oracle Net Listener for the Gateway

2. Stop and Start the Oracle Net Listener for the Gateway

Configure Oracle Net Services Oracle Net Listener for the Gateway

Oracle Net Services uses the Oracle Net Listener to receive incoming connections from a Oracle Net Services client. The Oracle Net Listener and the gateway must reside on the same system.

The Oracle Net Listener listens for incoming requests from the Oracle Database. For the Oracle Net Listener to listen for the gateway, information about the gateway must be added to the Oracle Net Listener configuration file, listener.ora. This file is located in the following directory:

$ORACLE_HOME/network/admin

where $ORACLE_HOME is the directory in which the gateway is installed.

Note:

If Oracle Net Services is reinstalled, the original listener.ora file is renamed and a new listener.ora file is put into the same directory.

The following entries must be added to the listener.ora file:

- A list of Oracle Net Services addresses on which the Oracle Net Listener listens.

- The gateway that the Oracle Net Listener starts in response to incoming connection requests.

Example of Address to Listen On in listener.ora File

The Oracle Database accesses the gateway using Oracle Net Services and the TCP/IP protocol adapter. The following is the syntax of the connect descriptor entry in the listener.ora file:

LISTENER =
(DESCRIPTION_LIST =
(DESCRIPTION =
(ADDRESS_LIST =
(ADDRESS = (PROTOCOL = IPC)(KEY = EXTPROC))
)
(ADDRESS_LIST =
(ADDRESS = (PROTOCOL = TCP)(HOST = host_name)(PORT = 1552))
)
)
)

Where:

Table 4-1 Parameters for listener.ora File

Variable

Description

host_name

The name of the system on which the gateway is installed.

port

The port number used by the Oracle Net Listener. If you have other listeners running on host_name, the value of port_number must be different from the other listeners' port numbers.

Example of Gateway to Start in listener.ora File

To direct the Oracle Net Listener to start the gateway in response to incoming connection requests, add an entry to the listener.ora file as follows.

Use the following syntax for Linux platforms:

SID_LIST_LISTENER =
(SID_LIST =
.
.
(SID_DESC=
(SID_NAME=gateway_sid)
(ORACLE_HOME=ORACLE_HOME_directory)
(PROGRAM=dg4vsam)
(ENVS=LD_LIBRARY_PATH=$ORACLE_HOME/lib)
)
)

Note:

The executable dg4vsam is valid for both VSAM and VSAM CICS.

Where:

Table 4-2 Parameters for listener.ora File

Variable

Description

sid_name

The SID of the gateway and matches the gateway SID specified in the connect descriptor entry in the tnsnames.ora file. The Oracle Net Listener uses the SID name to locate the relevant <sid_name>.ora file. It needs to access this file to check which access method is used (VSAM-BATCH or VSAM-CICS).

ORACLE_HOME

The Oracle home directory where the gateway is located.

The following table specifies which ENVS parameter value to use for the different platforms:

Platform

ENVS Parameter Value

Sun Solaris, 64-bit

LD_LIBRARY_PATH=$ORACLE_HOME/lib

HP-UX Itanium 64-bit

SHLIB_PATH=$ORACLE_HOME/lib

IBM AIX 64-bit

LIBPATH=$ORACLE_HOME/lib

Linux 32-bit

LD_LIBRARY_PATH=$ORACLE_HOME/lib

Linux 64-bit

LD_LIBRARY_PATH=$ORACLE_HOME/lib

See Also:

Oracle Net Services Administrator's Guide for information about changing the listener.ora file.

Stop and Start the Oracle Net Listener for the Gateway

The Oracle Net Listener must be started to initiate the new settings, as follows:

1. Set the PATH environment variable to access the commands in the following directory:

$ORACLE_HOME/bin

If you have the Bourne or Korn Shell, enter the following:

$ PATH=$ORACLE_HOME/bin:$PATH;export PATH
$ LD_LIBRARY_PATH=$ORACLE_HOME/lib:$LD_LIBRARY_PATH; export LD_LIBRARY_PATH

If you have the C Shell, enter the following:

$ setenv PATH $ORACLE_HOME/bin:$PATH
$ setenv LD_LIBRARY_PATH $ORACLE_HOME/lib:$LD_LIBRARY_PATH

where $ORACLE_HOME is the directory where the gateway is installed.

The following table specifies which path to use for the different platforms.

Platform

Path to be Used

Linux, 32-bit and 64-bit

LD_LIBRARY_PATH

Sun solaris

LD_LIBRARY_PATH

HP-UX

SHLIB_PATH

IBM AIX

LIBPATH

2. If the listener is already running, use the lsnrctl command to stop the listener and then start it with the new settings, as follows:

$ lsnrctl stop
$ lsnrctl start

3. Check the status of the listener with the new settings, as follows:

$ lsnrctl status

The following is an example of output from a lsnrctl status check:

LSNRCTL for SOLARIS: Version 11.2.0 - Production on 01-JUN-2009 09:16:17

Copyright (c) 1991, 2009, Oracle. All rights reserved.

Connecting to (ADDRESS=(PROTOCOL=TCP)(HOST=204.179.99.15)(PORT=11201))
STATUS of the LISTENER
----------------------
Alias                    listener
Version                  TNSLSNR for SOLARIS: Version 11.2.0 - Production
Start Date               31-May-2009 10:16:17
Uptime                   0 days 18 hr. 5 min. 13 sec
Trace Level              off
Security                 OFF
SNMP                     OFF
Listener Parameter File  /users/oracle/gateway/network/admin/listener.ora
Listener Log File        /users/oracle/gateway/network/log/listener.log
Listening Endpoints Summary...
(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=204.179.99.15)(PORT=11201)))
Services Summary...
Service "dg4vsam" has 1 instance(s).
Instance "dg4vsam", status UNKNOWN, has 1 handler(s) for this service...
The command completed successfully

In this example, dg4vsam is the default SID value assigned during installation. You can use any valid ID for the SID, or keep the default.

Note:

You must use the same SID value in the tnsnames.ora file and the listener.ora file.

Configuring the Oracle Database for Gateway Access

Before you can use the gateway to access VSAM data, you must configure the Oracle Database to enable communication with the gateway over Oracle Net Services.

Perform the following tasks to configure the Oracle Database accordingly:

Configuring Oracle Net Services for the Oracle Database

Configuring Oracle Net Services for the Oracle Database

To configure the server you add connect descriptors to the tnsnames.ora file. You cannot use the Oracle Net Services Assistant or the Oracle Net Services Easy Config tools to configure the tnsnames.ora file. You must edit the file manually.

See Also:

Oracle Database Administrator's Guide for information about editing the tnsnames.ora file.

For the Oracle Database to access the gateway, it needs a service name entry or a connect descriptor name entry in the tnsnames.ora file to tell the Oracle Database where to make connections.

By default, this file is located in the directory $ORACLE_HOME/network/admin, where $ORACLE_HOME is the directory in which the Oracle Database is installed. The tnsnames.ora file is required by the Oracle Database accessing the gateway, but not by the gateway.

Configuring tnsnames.ora

Edit the tnsnames.ora file to add a connect descriptor for the gateway. The following is the syntax of the Oracle Net Services entries using TCP/IP protocol needed for the Oracle Database to access the gateway:

connect_descriptor =
(DESCRIPTION =
(ADDRESS_LIST =
(ADDRESS = (PROTOCOL = TCP)(HOST = host_name)(PORT = port_number))
)
(CONNECT_DATA =
(SID=gateway_sid)
)
(HS = OK)
)

Where:

Table 4-3 Parameters for tnsnames.ora File

Variable

Description

connect_descriptor

The description of the object to connect to as specified when creating the database link, such as dg4vsam.

Check the sqlnet.ora file for the following parameter setting:

names.directory_path = (TNSNAMES)

Note: The sqlnet.ora file is typically stored in $ORACLE_HOME/network/admin.

host_name

Specifies the system where the gateway is running.

port_number

Matches the port number used by the Oracle Net Services Oracle Net Listener that is listening for the gateway. The Oracle Net Listener's port number can be found in the listener.ora file used by the Oracle Net Listener. See "Example of Address to Listen On in listener.ora File".

gateway_sid

Specifies the SID of the gateway and matches the SID specified in the listener.ora file of the Oracle Net Listener that is listening for the gateway. See "Configure Oracle Net Services Oracle Net Listener for the Gateway" for more information.

For example:

connect_descriptor=
vsam =
(DESCRIPTION =
(ADDRESS_LIST =
(ADDRESS = (PROTOCOL = TCP)(HOST = host_name)(PORT = port_number))
)
(CONNECT_DATA =
(SID = gateway_sid)
)
(HS = OK)
)

Creating Database Links

Any Oracle client connected to the Oracle Database can access VSAM data through the gateway. The Oracle client and the Oracle Database can reside on different systems. The gateway accepts connections only from the Oracle Database.

A connection to the gateway is established through a database link when it is first used in an Oracle session. In this context, a connection refers to the connection between the Oracle Database and the gateway. The connection remains established until the Oracle session ends. Another session or user can access the same database link and get a distinct connection to the gateway and VSAM data source.

Database links are active for the duration of a gateway session. If you want to close a database link during a session, you can do so with the ALTER SESSION CLOSE DATABASE LINK dblink statement. The database and application administrators of a distributed database system are responsible for managing the necessary database links that define paths to the VSAM data source.

See Also:

Oracle Database Administrator's Guide and Oracle Database Heterogeneous Connectivity User's Guide for more information about using database links.

Gateway Password Encryption Tool

The gateway uses userids and passwords to access the information in the remote database. Some userids and passwords must be defined in the Gateway Initialization File to handle functions such as resource recovery. In the current security conscious environment, having plain-text passwords that are accessible in the Initialization File is considered insecure. The dg4pwd encryption utility has been added as part of Heterogeneous Services' generic connectivity to help make this more secure. This utility is accessible by this gateway. The initialization parameters that contain sensitive values can be stored in an encrypted form.

See Also:

Oracle Database Heterogeneous Connectivity User's Guide for more information about using this utility.

Configuring the Gateway for Multiple VSAM Databases

The tasks for configuring the gateway to access multiple VSAM data sources are similar to the tasks for configuring the gateway for a single database. The configuration example assumes the following:

- The gateway is installed and configured with the default SID of dg4vsam.

- The ORACLE_HOME environment variable is set to the directory where the gateway is installed.

- The gateway is configured for one VSAM data source named dg4vsam.

- Two VSAM data sources named dg4vsam2 and dg4vsam3 on a server named mvs5 with port number 2551 are added.

Configuring the gateway for additional VSAM data sources is similar to configuring it for one database, and involves the following:

- Configuring the gateway.

- Configuring Oracle Net Services for the gateway and the Oracle Database.

Multiple Databases Example: Configuring the Gateway

Choose Two System IDs for Each VSAM Database

A separate instance of the gateway accesses the different VSAM data sources. Each instance needs its own gateway System ID (SID). For this example, the gateway SIDs for the instances that access the VSAM data sources are named as follows:

- dg4vsam2 for the gateway accessing data source dg4vsam2.

- dg4vsam3 for the gateway accessing data source dg4vsam3.

Create Two Initialization Parameter Files

Create an initialization parameter file for each instance of the gateway by copying the original initialization parameter file twice, naming one with the gateway SID for dg4vsam2 and the other with the gateway SID for dg4vsam3:

$ cd $ORACLE_HOME/dg4vsam/admin$ cp initdg4vsam.ora initdg4vsam2.ora$ cp initdg4vsam.ora initdg4vsam3.ora

Note:

The library $ORACLE_HOME/dg4vsam/admin is valid both for VSAM and VSAM CICS.

Change the value of the HS_FDS_CONNECT_INFO parameter in the new files.

For initdg4vsam2.ora, enter the following:

HS_FDS_CONNECT_INFO="mvs5:2551"

For initdg4vsam3.ora, enter the following:

HS_FDS_CONNECT_INFO="mvs5:2551"

Note:

If you have multiple gateway SIDs for the same VSAM data source because you want to use different gateway parameter settings at different times, follow the same procedure. You create several initialization parameter files, each with different SIDs and different parameter settings.

Multiple Databases Example: Configuring Oracle Net Services Listener

Add Entries to listener.ora

Add two new entries to the Oracle Net Listener configuration file, listener.ora. You must have an entry for each gateway instance, even when multiple gateway instances access the same database.

The following example shows the entry for the original installed gateway first, followed by the new entries:

SID_LIST_LISTENER=
(SID_LIST=
(SID_DESC=
(SID_NAME=dg4vsam)
(ORACLE_HOME=ORACLE_HOME_directory)
(PROGRAM=dg4vsam)
)
(SID_DESC=
(SID_NAME=dg4vsam2)
(ORACLE_HOME=ORACLE_HOME_directory)
(PROGRAM=dg4vsam)
)
(SID_DESC=
(SID_NAME=dg4vsam3)
(ORACLE_HOME=ORACLE_HOME_directory)
(PROGRAM=dg4vsam)
)
)

Multiple Databases Example: Stopping and Starting the Oracle Net Listener

If the listener is already running, use the lsnrctl command to stop the listener and then start it with the new settings, as follows:

$ lsnrctl stop$ lsnrctl start

Multiple Databases Example: Configuring the Oracle Database for Gateway Access

This section describes the required procedures to configure the Oracle Database for the gateway access.

Configuring Oracle Net Services on the Oracle Database for Multiple Gateway Instances

Add two connect descriptor entries to the tnsnames.ora file. You must have an entry for each gateway instance, even if the gateway instances access the same database.

The following VSAM example shows the entry for the original installed gateway first, followed by the two entries for the new gateway instances:

old_db_using=(DESCRIPTION=
(ADDRESS=
(PROTOCOL=TCP)
(PORT=1541)
(HOST=gtwhost))
(CONNECT_DATA=
(SID=dg4vsam))
(HS=OK))
new_vsam2_using=(DESCRIPTION=
(ADDRESS=
(PROTOCOL=TCP)
(PORT=1541)
(HOST=gtwhost))
(CONNECT_DATA=
(SID=dg4vsam2))
(HS=OK))
new_vsam3_using=(DESCRIPTION=
(ADDRESS=
(PROTOCOL=TCP)
(PORT=1541)
(HOST=gtwhost))
(CONNECT_DATA=
(SID=dg4vsam3))
(HS=OK))

The value for PORT is the TCP/IP port number of the Oracle Net Listener that is listening for the gateway. The number can be found in the listener.ora file used by the Oracle Net Listener. The value for HOST is the name of the system on which the gateway is running. The name also can be found in the listener.ora file used by the Oracle Net Listener.

Multiple Databases Example: Accessing VSAM Data

Enter the following to create a database link for the dg4vsam2 gateway:

SQL> CREATE PUBLIC DATABASE LINK VSAM2 CONNECT TO
2  user2 IDENTIFIED BY password2 USING 'new_vsam2_using';

Enter the following to create a database link for the dg4vsam3 gateway:

SQL> CREATE PUBLIC DATABASE LINK VSAM3 CONNECT TO
2  user3 IDENTIFIED BY password3 USING 'new_vsam3_using';

Note:

To encrypt the initialization parameters that would normally be stored in the initialization file in plain text, you must use the dg4pwd utility, as described in Oracle Database Heterogeneous Connectivity User's Guide.

After the database links are established you can query the new VSAM data sources, as in the following:

SQL> SELECT * FROM ALL_TABLES@VSAM2;

or:

SQL> SELECT * FROM ALL_TABLES@VSAM3;

Performing Configuration Tasks

You can perform the following configuration tasks:

- Configuring for Global Transactions

- Enabling Automatic Recovery

Configuring for Global Transactions

The VSAM/Batch data source supports auto-commit mode only. This means that you cannot roll back, or undo, any changes that you made.

The gateway supports the following transaction capabilities:

- READ_ONLY

- SINGLE_SITE (default)

See the Oracle Database Heterogeneous Connectivity User's Guide for configuration information.

By default, the VSAM (CICS) data source supports global transactions.

If the VSAM (CICS) data source is configured differently in Oracle Studio for IMS, VSAM, and Adabas Gateways, see the Oracle Database Heterogeneous Connectivity User's Guide for information about configuring for global transactions.

If the VSAM (CICS) data source is configured for global transactions, the gateway becomes the commit point site when the VSAM (CICS) data source is updated by a transaction. The Oracle database commits the unit of work in the VSAM (CICS) data source after verifying that all Oracle databases in the transaction have successfully prepared the transaction. Only one gateway can participate in an Oracle global transaction as the commit point site.

See Also:

Oracle Database Heterogeneous Connectivity User's Guide for information about the global transaction process.

Enabling Automatic Recovery

For the gateway to recover distributed transactions, a recovery account and password must be provided. By default, both the user name of the account and the password are RECOVER. The name of the account can be changed with the gateway initialization parameter HS_FDS_RECOVERY_ACCOUNT. The account password can be changed with the gateway initialization parameter HS_FDS_RECOVERY_PWD.

Note:

Oracle Corporation recommends that you do not use the default value RECOVER for the user name and password. Moreover, storing plain text as user name and password in the initialization file is not a good security policy. There is now a utility called dg4pwd that should be used for encryption. Refer to Chapter 4, "Encrypting Initialization parameters" in Oracle Heterogeneous Connectivity Administration Guide for details.

To change the default user name or the password, in the initialization parameter file, set the following gateway initialization parameters:

- HS_FDS_RECOVERY_ACCOUNT to the mainframe account name.
This account can be the same account that is used to access the VSAM data source. If you use another account, then it must have the same permissions as the account that is used to access the VSAM data source.

- HS_FDS_RECOVERY_PWD to the password of the account.

See Also:

"Customize the Initialization Parameter File" for information about editing the initialization parameter file and Appendix B, "Initialization Parameters" for information about the HS_FDS_RECOVERY_ACCOUNT and HS_FDS_RECOVERY_PWD initialization parameters.

Testing the VSAM Data Source

You can perform the following tests on the VSAM data source:

- Connection test: This tests the physical connection to the data source.

- Query test: This test runs an SQL SELECT query against the data source.

These tests are described in the following procedures.

See Also:

Setting Up a VSAM Data Source for information on how to add a data source.

Perform the following to test the physical connection to the data source.

1. Open Oracle Studio for IMS, VSAM, and Adabas Gateways.

2. Expand the node of the required computer.

3. Expand the node of the required binding.

4. Expand the Data sources node.

5. Right-click the required data source entity, and select Test.
The Test Wizard screen opens.

6. Select Navigator from the Active Workspace Name list and click Next.
The system now tests the connection to the data source, and returns the test result status.

7. Click Finish to exit the Test wizard.

Perform the following to test the VSAM data source by query.

1. Open Oracle Studio for IMS, VSAM, and Adabas Gateways.

2. Expand the node of the required computer.

3. Expand the node of the required binding.

4. Expand the Data sources node.

5. Right-click the required data source entity, and select Query Tool.
The Query Tool opens in the Editor pane, with the Build Query tab displayed (see Figure 4-1).

6. Select Navigator and click OK.

7. Select the required query type from the Query Type list. The default is a SELECT-type query.

8. Locate and expand the node of the required data source entity.
The data source tables are listed.

9. Select the required table and move it to the Table column by using the arrow button.

Figure 4-1 The Query Tool Screen

10. Click Execute query.
The Query Result tab opens, displaying the results of the query.

11. Close the Query Tool in the Editor pane.

Sample Log File

Log files are used for troubleshooting and error handling. The log file is generated when the driverTrace debug binding parameter is set to True.

The log file includes various information concerning the functions used or called by the driver, queries executed, data sources accessed, etc.

First, you need to create the log file. Perform the following procedure.

1. Open Oracle Studio for IMS, VSAM, and Adabas Gateways.

2. From the main menu, click Windows, Preferences.
The Preferences screen is displayed.

Figure 4-2 Studio Preferences

3. In the left pane, click the Studio node.

4. Click the Advanced tab.

5. Select the Show advanced environment parameters check box.

6. Click OK.

7. In the Design Perspective Configuration view, right-click the binding under which the Oracle data source is located and select Edit Binding.

8. From the Category list, select Debug.

9. Set the driverTrace and generalTrace parameters to TRUE.

Figure 4-3 Binding Properties

10. Execute the following query: Select * from upd_dt limit to 3 rows

The following is a sample log file output:

Example 4-1 Sample VSAM Log File

ORACLE CONNECT Log (V10.1.3.1, MVS) Started at 2006-11-21T17:25:13
Licensed by Oracle Corporation on 28-SEP-2006 (001001610)
Licensed to ORACLE for <all providers> on <all machines> (<all platforms>
o: 586 9862924 fopen >>> filename=TEST.OR5000A.DEF.NOSBB.SYS,mode=rb, typ
e=record, lrecl=8208
o: 275 0 flocate >>> stream=9862924,key=98A9830,key_len=4,options=3
o: 292 8208 fread >>> buffer=98AA310, size=1, count=8208,stream=9862924
o: 424 0 fclose >>> stream=9862924
o: 275 0 flocate >>> stream=98613F4,key=984FFD0,key_len=100,options=5
o: 292 2048 fread >>> buffer=984F7C8, size=1, count=2048,stream=98613F4
o: 275 0 flocate >>> stream=9861024,key=984FFD0,key_len=4,options=5
o: 292 2048 fread >>> buffer=984F7C8, size=1, count=2048,stream=9861024
o: 275 0 flocate >>> stream=98613F4,key=984FFD0,key_len=100,options=5
o: 292 2048 fread >>> buffer=984F7C8, size=1, count=2048,stream=98613F4
o: 275 0 flocate >>> stream=9861024,key=984FFD0,key_len=4,options=5
o: 292 2048 fread >>> buffer=984F7C8, size=1, count=2048,stream=9861024
o: 275 0 flocate >>> stream=98613F4,key=984FFD0,key_len=100,options=5
o: 292 2048 fread >>> buffer=984F7C8, size=1, count=2048,stream=98613F4
o: 275 0 flocate >>> stream=9861024,key=984FFD0,key_len=4,options=5
o: 292 2048 fread >>> buffer=984F7C8, size=1, count=2048,stream=9861024
o: 586 98B7424 fopen >>> filename=TEST.OR5000A.DEF.NOSBB.SYS,mode=rb, typ
e=record, lrecl=8208
o: 275 0 flocate >>> stream=98B7424,key=98C2820,key_len=4,options=3
o: 292 8208 fread >>> buffer=98C3300, size=1, count=8208,stream=98B7424
o: 424 0 fclose >>> stream=98B7424
o: 275 0 flocate >>> stream=98613F4,key=984FFD0,key_len=100,options=5
o: 292 2048 fread >>> buffer=984F7C8, size=1, count=2048,stream=98613F4
o: 275 0 flocate >>> stream=9861024,key=984FFD0,key_len=4,options=5
o: 292 2048 fread >>> buffer=984F7C8, size=1, count=2048,stream=9861024
IRprc (6695): ; Client 194.90.22.131:3130 (No. 1, NAVXML CLIENT) has connected
o: 275 0 flocate >>> stream=98613F4,key=984FFD0,key_len=100,options=5
o: 292 2048 fread >>> buffer=984F7C8, size=1, count=2048,stream=98613F4
o: 275 0 flocate >>> stream=9861024,key=984FFD0,key_len=4,options=5
o: 292 2048 fread >>> buffer=984F7C8, size=1, count=2048,stream=9861024
o: 586 98B7424 fopen >>> filename=TEST.OR5000A.DEF.NOSBB.SYS,mode=rb, typ
e=record, lrecl=8208
o: 275 0 flocate >>> stream=98B7424,key=98FEA80,key_len=4,options=3
o: 292 8208 fread >>> buffer=9901040, size=1, count=8208,stream=98B7424
o: 424 0 fclose >>> stream=98B7424
o: 275 0 flocate >>> stream=98613F4,key=984FFD0,key_len=100,options=5
o: 292 2048 fread >>> buffer=984F7C8, size=1, count=2048,stream=98613F4
o: 275 0 flocate >>> stream=9861024,key=984FFD0,key_len=4,options=5
o: 292 2048 fread >>> buffer=984F7C8, size=1, count=2048,stream=9861024
nvOUT (PROD.AC10131.NAV(QP#SQTXT) 89): SELECT * FROM VSAM:UPD_DT LIMIT TO 100 R
nvRETURN (PROD.AC10131.NAV(QPSYNON) 1140): -1
o: 586 98B7424 fopen >>> filename=TEST.OR5000A.DEF.NOS.VSAM,mode=rb, type
=record, lrecl=2048
o: 393 0 fclose >>> stream=98613F4
o: 424 0 fclose >>> stream=9861024
o: 586 Calling ENQ for TEST.OR5000A.DEF.NOS.SYS .
o: 586 Successful exclusive enqueue retCode=0
o: 586 98B77F4 fopen >>> filename=TEST.OR5000A.DEF.NOS.SYS,mode=rb+, type
=record
o: 627 98B7BC4 fopen >>> filename=TEST.OR5000A.DEF.NOS.SYS.I2.PATH,mode=r
b, type=record, lrecl=2048
o: 275 0 flocate >>> stream=98B7BC4,key=9981F00,key_len=100,options=5
o: 292 2048 fread >>> buffer=99816F8, size=1, count=2048,stream=98B7BC4
o: 393 0 fclose >>> stream=98B7BC4
o: 424 0 fclose >>> stream=98B77F4
o: 424 Calling DEQ for TEST.OR5000A.DEF.NOS.SYS
o: 424 Successful dequeue retCode=0
o: 627 98B77F4 fopen >>> filename=TEST.OR5000A.DEF.NOS.VSAM.I2.PATH,mode=
rb, type=record, lrecl=2048
o: 275 0 flocate >>> stream=98B77F4,key=98BF0C0,key_len=100,options=5
o: 292 2048 fread >>> buffer=98BE8B8, size=1, count=2048,stream=98B77F4
o: 275 0 flocate >>> stream=98B7424,key=98BF0C0,key_len=4,options=5
o: 292 2048 fread >>> buffer=98BE8B8, size=1, count=2048,stream=98B7424
o: 586 98B8BF4 fopen >>> filename=TEST.OR5000A.DEF.NOSBB.VSAM,mode=rb, ty
pe=record, lrecl=8208
o: 275 0 flocate >>> stream=98B8BF4,key=9982850,key_len=4,options=3
o: 292 8208 fread >>> buffer=9983330, size=1, count=8208,stream=98B8BF4
o: 424 0 fclose >>> stream=98B8BF4
<<<<<<<<<<<<<<<<<<< Execution Strategy Begin <<<<<<<<<<<<<<<<<<<<<<<<<<<<
Original SQL:
SELECT * FROM VSAM : UPD_DT LIMIT TO 100 ROWS
Accessing file 'UPD_DT' from 'VSAM' Database
Fetch strategy: scan
>>>>>>>>>>>>>>>>>>>> Execution Strategy End >>>>>>>>>>>>>>>>>>>>>>>>>>>>
FilePool Init(DB=VSAM)
FilePool Get(DB=VSAM, File=TEST.VSAM.DATA.UPDDT015, Mode=0, FilePool Size=0)
o: 586 98B8BF4 fopen >>> filename=TEST.VSAM.DATA.UPDDT015,mode=rb, type=r
ecord, lrecl=116
o: 292 116 fread >>> buffer=9984628, size=1, count=116,stream=98B8BF4
o: 292 116 fread >>> buffer=9984628, size=1, count=116,stream=98B8BF4
o: 292 0 fread >>> buffer=9984628, size=1, count=116,stream=98B8BF4

Part III

Installing and Configuring Oracle Database Gateway for IMS

Before performing any of the tasks described in this part, you should read Part I, "Getting Started with Oracle Database Gateways" to get an overview of the technology, the architecture, and the process involved in installing and configuring Oracle Database Gateway for IMS.

To be able to access IMS data, you need to perform the tasks described in the following list, in the specified order. Each step in the list directs you to the relevant manual or chapter.

By now, you should have completed tasks 1 – 3. This part describes how to perform tasks 4 – 8.

1. Install Oracle Connect for IMS, VSAM, and Adabas Gateways
See Oracle Connect for IMS, VSAM, and Adabas Gateways Installation and Configuration Guide for IBM z/OS for information on installing Oracle Connect for IMS, VSAM, and Adabas Gateways.

2. Install Oracle Studio for IMS, VSAM, and Adabas Gateways
See Chapter 11, "Installing Oracle Studio for IMS, VSAM, and Adabas Gateways" for information on installing Oracle Studio for IMS, VSAM, and Adabas Gateways.

3. Configure Oracle Connect for IMS, VSAM, and Adabas Gateways
See Chapter 13, "Configuring Oracle Connect through Oracle Studio for IMS, VSAM, and Adabas Gateways" for information on configuring Oracle Connect for IMS, VSAM, and Adabas Gateways.

4. Set up the connection to Oracle Connect for IMS, VSAM, and Adabas Gateways
See Chapter 5, "Configuring Access to IMS Data" for information on setting up the connection to Oracle Connect for IMS, VSAM, and Adabas Gateways.

5. Set up the IMS data source
See Chapter 5, "Configuring Access to IMS Data" for information on setting up the IMS data source.

6. Set up the IMS metadata
See. Chapter 5, "Configuring Access to IMS Data" for information on setting up the IMS metadata.

7. Install Oracle Database Gateway for IMS
See Chapter 6, "Installing Oracle Database Gateway for IMS" for information on installing Oracle Database Gateway for IMS.

8. Configure Oracle Database Gateway for IMS
See Chapter 7, "Configuring Oracle Database Gateway for IMS" for information on configuring Oracle Database Gateway for IMS.

Part III, "Installing and Configuring Oracle Database Gateway for IMS," describes how to install and configure Oracle Database Gateway for IMS.

It contains the following chapters:

- Chapter 5, "Configuring Access to IMS Data"

- Chapter 6, "Installing Oracle Database Gateway for IMS"

- Chapter 7, "Configuring Oracle Database Gateway for IMS"

5 Configuring Access to IMS Data

This chapter explains how to configure access to IMS data by using Oracle Studio for IMS, VSAM, and Adabas Gateways. It contains the following sections:

- Setting Up Access to a Computer Running Oracle Connect for IMS, VSAM, and Adabas Gateways

- Setting Up an IMS Data Source

- Setting Up the IMS/DB Data Source Metadata

Setting Up Access to a Computer Running Oracle Connect for IMS, VSAM, and Adabas Gateways

To be able to access IMS data, you must have a working connection to Oracle Connect for IMS, VSAM, and Adabas Gateways, which is installed on the IBM z/OS computer where your IMS files are located. You establish this connection by using Oracle Studio for IMS, VSAM, and Adabas Gateways.

Whenever needed, you can also use Oracle Studio for IMS, VSAM, and Adabas Gateways to configure Oracle Connect for IMS, VSAM, and Adabas Gateways.

Note:

The following task assumes that you have permission to access the IBM z/OS platform and that the Oracle Connect for IMS, VSAM, and Adabas Gateways daemon is running on this computer. Check with the system administrator to ensure these requirements are fulfilled.

Perform the following steps to set up access to a computer that runs Oracle Connect for IMS, VSAM, and Adabas Gateways.

1. From the Start menu, select Programs, point to Oracle, and select Studio. Oracle Studio for IMS, VSAM, and Adabas Gateways opens.

2. In the Design perspective's Configuration view, right-click the Machines folder and select Add Machines.
The Add machine screen opens, as shown in Figure 5-1.

Figure 5-1 Add Machine Screen.

Enter the following information in each field:

- Host name/IP address: Enter the name of the computer on the network or click Browse, to browse all the systems running a daemon listener on the specified port currently accessible over the network.

- Port: Enter the port number where the daemon is running. The default port is 2551.

- Display name: Enter an alias used to identify the system when different from the host name (optional).

- User name: Enter the system administrator's user name.

Note:

You indicate the system administrator when the system is installed or by using the NAV_UTIL utility ADD_ADMIN operation. For details, see Oracle Connect for IMS, VSAM, and Adabas Gateways Installation and Configuration Guide for IBM z/OS.

- Password: Enter the system administrator's password. This is the password for the user entered in the User name field. If no password is necessary to access this system, do not enter anything.

- Connect via NAT with fixed IP address: Select this if the system uses the NAT (Network Address Translation) firewall protocol, with a fixed configuration, mapping each external IP to one internal IP, regardless of the port specified.

3. Click Finish.
The computer is displayed in the Configuration view, in the Machine folder. You can edit the system's login information, or configure bindings, daemons, and users for each system.

Setting Up an IMS Data Source

Oracle Connect for IMS, VSAM, and Adabas Gateways supports SQL data access to IMS/DB data in the following three IMS/DB environments:

- IMS-DLI: Batch access. The dedicated Oracle Connect for IMS, VSAM, and Adabas Gateways server, running as IMS batch process, issues DLI commands to retrieve IMS/DB data. This data source can be used when the accessed database is not currently opened under CICS or IMS/TM.
The IMS-DLI data source does not support transaction processing.

- IMS-DBCTL: This data source is suited to users employing CICS as their primary application platform for accessing IMS/DB data. All Oracle Connect for IMS, VSAM, and Adabas Gateways servers communicate with an Oracle Connect for IMS, VSAM, and Adabas Gateways-supplied CICS program. This program accepts requests for scheduling PSBs and retrieving data through DBCTL services.

- IMS-DBDC: This data source is suited to users employing IMS/TM as their primary application platform for accessing IMS/DB data. All Oracle Connect for IMS, VSAM, and Adabas Gateways servers communicate with an Oracle Connect for IMS, VSAM, and Adabas Gateways-supplied IMS/TM program. This program accepts requests from Oracle Connect for IMS, VSAM, and Adabas Gateways servers and performs the DLI requests on their behalf.
The IMS-DBDC data source does not support transaction processing.

IMS/DB data sources support IMS/DB hierarchical structures, provided there exists a unique sequence field for all the segments within the hierarchy.

IMS/DB data sources do not support secondary indexes.

This section describes how to set up an IMS data source using Oracle Studio for IMS, VSAM, and Adabas Gateways. Each IMS/DB data source has its own considerations. Therefore, perform the procedure relevant for the data source you use, as follows:

- Defining the IMS-DLI Data Source

- Defining the IMS/DB DBCTL Data Source

- Defining the IMS/DB DBDC Data Source

After you defined the data source, proceed to the following task:

Setting Up the IMS/DB Data Source Metadata

Defining the IMS-DLI Data Source

The process of defining an IMS/DB DLI data source consists of the following tasks:

- Setting Up the Daemon Workspace

- Defining the IMS-DLI Data Source Connection

- Configuring the IMS/DB DLI Data Source Properties

Setting Up the Daemon Workspace

Configure a special daemon workspace to use an NVIMSSRV started task. In this workspace, set the server type to IMS and the startup script to NVIMSSRV.XY.

All other settings are the same settings as those of the Navigator workspace provided with the Oracle Connect for IMS, VSAM, and Adabas Gateways installation.

See Adding a Workspace for information on adding a new workspace.

Note:

- The suffix for the startup script enables instances of the server process for the workspace. Any suffix can be used, and Oracle Connect for IMS, VSAM, and Adabas Gateways automatically extends the suffix for each instance. You can use different suffixes in different started tasks to distinguish between the running servers.

- The remote system specification in the binding setting for the IMS-DLI data source on the client must include the workspace name as part of the <remoteMachine> statement.

Defining the IMS-DLI Data Source Connection

The IMS-DLI data source connection is set using the Design Perspective Configuration view in Oracle Studio for IMS, VSAM, and Adabas Gateways. Perform the following steps to define the IMS-DLI data source connection.

1. In Oracle Studio for IMS, VSAM, and Adabas Gateways, in the Configuration view of the Design perspective, open the binding of the system where the data is located.

2. Right-click Data Source and select New Data Source.
The New Data Source screen opens, as shown in Figure 5-2.

Figure 5-2 New Data Source Screen

3. Specify a name for the data source in the Name field.

4. Select IMS-DLI from the Type list.

5. Click Next.
The Data Source Connect String screen opens.

6. Click Finish.

Configuring the IMS/DB DLI Data Source Properties

After defining the connection, you can set the data source properties.

The following properties can be configured for the IMS/DCB DLI data source on the Properties tab of the Configuration Properties screen:

disableExplicitSelect=true|false: When set to true, this parameter disables the explicitSelect ADD attribute; every field is returned by a SELECT * FROM... statement.

Perform the following steps to configure the IMS/DB DLI data source.

1. Right-click the data source and select Edit Data Source.
The Configuration Properties screen opens.

2. On the Properties tab, configure the data source parameters as required.

3. On the Advanced tab, configure how arrays will be handled by selecting the relevant check boxes in the Virtual View Policy section. The following options are available:

- Generate sequential view: Select this option if you want to map a non-relational file to a single table.

- Generate virtual views: Select this option if you want to have an individual table created for every array in the non-relational file.

- Include row number column: Select this option if you want to include a column that specifies the row number in the virtual or sequential view.

- Inherit all parent columns: Select this option if you want the virtual views to include all the columns of the parent record.

4. Save your settings.

Defining the IMS/DB DBCTL Data Source

The process of defining an IMS/DB DBCTL data source consists of the following tasks:

- Define the IMS/DB DBCTL Data Source Connection

- Configure the IMS/DB DBCTL Data Source Properties

- Accessing IMS/DB Data under CICS

Define the IMS/DB DBCTL Data Source Connection

The IMS/DB DBCTL data source connection is set using the Design Perspective Configuration view in Oracle Studio for IMS, VSAM, and Adabas Gateways.

To define the data source connection

1. In Oracle Studio for IMS, VSAM, and Adabas Gateways, in the Configuration view of the Design perspective, open the binding of the system where the data is located.

2. Right-click Data Source and select New Data Source.
The New Data Source screen opens, as shown in Figure 5-3.

Figure 5-3 New Data Source Screen

3. Specify a name for the data source in the Name field.

4. Select IMS-DBCTL from the Type list.

5. Click Next.
The Data Source Connect String screen opens.

6. Specify the IMS-DBCTL connect string as follows:

- PSB Name: Specify the name of the PSB file that contains details of all the IMS/DB databases that you want to access.

- Target System: Specify the VTAM APPLID of the CICS target system. The default value is CICS. This parameter is used when updating VSAM data. You can determine this value by activating the CEMT transaction on the target CICS system. The legend APPLID=target_system appears in the bottom right corner of the screen.

- VTAM NetName: The VTAM netname of the specific connection being used by EXCI (and MRO) to relay the program call to the CICS target system. For example, if you issue the following command to CEMT:
CEMT INQ CONN

You see on the display screen that the netname is BATCHCLI (this is the default connection supplied by IBM upon the installation of CICS). The default value is ATYCLIEN.

7. Click Finish.

Configure the IMS/DB DBCTL Data Source Properties

After defining the connection, you can set the data source properties.

The following properties can be configured for the IMS/DB DBCTL data source in the Properties tab of the Configuration Properties screen:

- cicsProgname=ATYDBCTL: This parameter specifies the ATYDBCTL program that is supplied with Oracle Connect for IMS, VSAM, and Adabas Gateways to enable updating VSAM data.

- cicsTraceQueue=string: This parameter specifies the e name of queue for output that is defined under CICS when tracing the output of the ATYDBCTL program. When not defined, the default CICS queue is used.

- disableExplicitSelect=true|false: When set to true, this parameter disables the explicitSelect ADD attribute; every field is returned by a SELECT * FROM... statement.

- exciTransid=string: This parameter specifies the CICS TRANSID. This value must be EXCI or a copy of this transaction.

- pbsName=string: The PSB Name in the connect string, this parameter contains details of all the IMS/DB databases that you want to access.

- targetSystemApplid=string: The Target System in the connect string, this parameter specifies the VTAM applied of the CICS target system. The default value is CICS. This parameter is used when updating VSAM data. You can determine this value by activating the CEMT transaction on the target CICS system. The legend APPLID=target_system appears in the bottom right corner of the screen.

- vtamNetname=string: The VTAM NetName in the connect string, this parameter specifies the connection being used by EXCI (and MRO) to relay the program call to the CICS target system. The default value is ATYCLIEN.

Perform the following steps to configure the IMS/DB DBCTL data source.

1. Right-click the data source and select Edit Data Source.

2. On the Properties tab, configure the data source parameters as required.

3. To support rollback, on the Advanced tab, from the Transaction type list, select 1PC or 2PC, depending on the data source usage.
If you do not use 2PC, see the Oracle Database Heterogeneous Connectivity User's Guide for configuration information.

4. On the Advanced tab, configure how arrays will be handled by selecting the relevant check boxes in the Virtual View Policy section. The following options are available:

- Generate sequential view: Select this option if you want to map a non-relational file to a single table.

- Generate virtual views: Select this option if you want to have an individual table created for every array in the non-relational file.

- Include row number column: Select this option if you want to include a column that specifies the row number in the virtual or sequential view.

- Inherit all parent columns: Select this option if you want the virtual views to include all the columns of the parent record.

5. Save your settings.

Accessing IMS/DB Data under CICS

The IMS/DB DBCTL data source accesses IMS/DB data under CICS.

To access IMS/DB data under CICS, perform the following steps.

1. Copy the ATYDBCTL member from NAVROOT.LOAD to a CICS DFHRPL library (such as CICS.USER.LOAD) and then define the ATYDBCTL program under CICS using any available group such as the ATY group:
CEDA DEF PROG(ATYDBCTL) G(ATY) LANG(C) DA(ANY) DE(ATY IMSDB CICS PROGRAM)

NAVROOT is the high-level qualifier where the Oracle Connect for IMS, VSAM, and Adabas Gateways is installed.

2. After assigning the ATYDBCTL program to a group, install it as follows:
CEDA IN G(ATY)

3. Under CICS, run the CDBC transaction and select the first option (Connection). Provide the startup table suffix and DBCTL ID override value.

Defining the IMS/DB DBDC Data Source

The process of defining an IMS/DB DBDC data source consists of the following tasks:

- Define the IMS/DB DBDC Data Source Connection

- Configure the IMS/DB DBDC Data Source Properties

- Access IMS/DB Data under IMS/TM

Define the IMS/DB DBDC Data Source Connection

The IMS/DB DBDC data source connection is set using the Design Perspective Configuration view in Oracle Studio for IMS, VSAM, and Adabas Gateways.

To define the data source connection

1. In Oracle Studio for IMS, VSAM, and Adabas Gateways, in the Configuration view of the Design perspective, open the binding of the system where the data is located.

2. Right-click Data Source and select New Data Source.
The New Data Source screen opens, as shown in Figure 5-4.

Figure 5-4 New Data Source Screen

3. Specify a name for the data source in the Name field.

4. Select IMS-DBDC from the Type list.

5. Click Next.
The Data Source Connect String screen opens.

6. Specify the IMS-DBDC connect string as follows:

- XCF Group: Specify the Cross System Coupling Facility collection of XCF members to which the connection belongs. A group may consist of up to eight characters, and may span between multiple systems.

- XCF server: Specify the Cross System Coupling Facility group member.

- TPipe prefix: Specify the transaction pipe prefix used to associate between the transaction and the transaction pipe it is using. The default value is ATTU.

- User name: Specify the security facility user identification (for example, the RACF user identification).

- Group name: Specify the security facility group identification (for example, the RACF group identification).

7. Click Finish.

Configure the IMS/DB DBDC Data Source Properties

After defining the connection, you can set the data source properties.

The following properties can be configured for the IMS/DCB DBDC data source in the Properties tab of the Configuration Properties screen:

- disableExplicitSelect=true|false: When set to true, this parameter disables the explicitSelect ADD attribute; every field is returned by a SELECT * FROM... statement.

- imsTransname=string: This parameter specifies the name of the IMS transaction that points to the program that is used to access the PSB used to access the IMS/DB data. The default name of the transaction is ATYIMSTM.

- maxSessions=n: This parameter specifies the maximum number of sessions allowed. The default value is 5.

- racfGroupId=string: This parameter specifies the security facility group identification (for example, the RACF group identification).

- racfUserId=string: This parameter specifies the security resource user name.

- tpipePrefix=string: The TPipe prefix in the connect string, this parameter is used to associate between the transaction and the transaction pipe it is using. The default is ATTU.

- xcfClient=string: This parameter specifies the client name for the Cross System Coupling Facility to which the connection belongs.

- xcfGroup=string: The XCF group in the connect string, this parameter specifies the Cross System Coupling Facility collection of XCF members the connection belongs to. A group may consist of up to eight characters, and may span between multiple systems.

- xcflmsMember=string: This parameter specifies the Cross System Coupling Facility group member.

- xcfServer=string: The XCF server in the connect string, this parameter specifies the Cross System Coupling Facility group member.

- userName=string: The user name in the connect string, this parameter specifies the security facility user identification (for example, the RACF user identification).

Perform the following steps to configure the IMS/DB DBDC data source.

1. Right-click the data source and select Edit Data Source.

2. On the Properties tab, configure the data source parameters as required.

3. On the Advanced tab, from the Transaction type list, select 0PC.

4. On the Advanced tab, configure how arrays will be handled by selecting the relevant check boxes in the Virtual View Policy section. The following options are available:

- Generate sequential view: Select this option if you want to map a non-relational file to a single table.

- Generate virtual views: Select this option if you want to have an individual table created for every array in the non-relational file.

- Include row number column: Select this option if you want to include a column that specifies the row number in the virtual or sequential view.

- Inherit all parent columns: Select this option if you want the virtual views to include all the columns of the parent record.

5. Save your settings.

Access IMS/DB Data under IMS/TM

The IMS/DB DBCTL data source accesses IMS/DB data under IMS/TM.

To access IMS/DB data under IMS/TM

1. Copy the ATYDBDC program from NAVROOT.LOAD to an IMS/TM program library (such as IMS.PGMLIB) with the name of the PSB used to access the IMS/DB data.

2. Define an IMS transaction to point to the program, using statements similar to the following:
APPLCTN PSB=ATYDBDC,SCHDTYP=PARALLELTRANSACT CODE=ATYIMSTM,PRTY=(7,10,2),INQUIRY=NO,MODE=SNGL,EDIT=ULC

The default transaction name is ATYIMSTM. If you use a different transaction, the transaction name must be less than or equal to eight characters and you must specify this value in the imsTransname data source property in the binding.

3. Set up OTMA, as described in the Oracle Connect for IMS, VSAM, and Adabas Gateways Installation and Configuration Guide for IBM z/OS.

Setting Up the IMS/DB Data Source Metadata

The IMS/DB data sources requires Oracle metadata.

Setting up the metadata in Oracle Connect for IMS, VSAM, and Adabas Gateways to enable working with IMS/DB is the same for all the IMS/DB data sources.

The mapping of IMS/DB metadata to Oracle metadata format has the following rules:

- Segments are defined as tables within <table> elements.

- Tables inherit the key fields of their ancestors.

- Tables have indexes for their full hierarchical paths.

- Additional information is defined in dbCommand attributes specified within the <table> and <field> elements.

If COBOL copybooks describing the data source records are available, you can import the metadata by running the metadata import in the Oracle Studio for IMS, VSAM, and Adabas Gateways Design Perspective Metadata tab. If the metadata is provided in a number of COBOL copybooks, with different filter settings (such as whether the first 6 columns are ignored or not), import the metadata from copybooks with the same settings and later import the metadata from the other copybooks.

If COBOL copybooks that describe the IMS/DB records do not exist, you must manually define the metadata.

To import the metadata, you need to perform the following tasks:

1. Select the Input Files

2. Apply Filters

3. Select Tables

4. Match DBD to COBOL

5. Manipulate the Imported Records

6. Select the Metadata Model

7. Import the Metadata

Select the Input Files

This section describes the steps required to select the input files that will be used to generate the metadata. The IMS/DB data source requires three types of files, DBD files, COBOL copybooks, and PSB source files. See Select the Input Files for an explanation of these files.

Perform the following task to enter the input files.

1. In the Configuration view, right-click the data source and select Edit Metadata.
The Metadata tab is displayed with the data source displayed in the Metadata view.

2. Right-click the Imports node under the data source and select the New Import menu option.

3. Enter a name for the import. The name can contain letters, numbers and the underscore character.

4. Select IMS/DB Import Manager as the import type.

5. Click Finish. The Metadata Import Wizard is displayed.

6. Click Add in the Import Wizard to add DBD files. The Add Resource screen opens, providing the option of selecting files from the local system or copying the files from another system.
Figure 5-5 shows the Add Resource screen.

Figure 5-5 Add Resource Screen

7. If the files are located on a UNIX or Windows computer, do the following:

- Right-click My FTP Sites and select Add.
The Add FTP Site screen opens, as shown in the following figure.

- Enter the server name where the COBOL copybooks are located and, if not using an anonymous connection, enter a valid username and password to access the computer. The username is then used as the high-level qualifier.

- Click OK. After accessing the remote computer, you can change the high-level qualifier by right-clicking the system in the Add Resource screen and selecting Change Root Directory.

- Select the files to import and click Finish to start the file transfer. When complete, the selected files are displayed in the Get Input Files screen.
To remove any of these files, select the required file and click Remove.

8. Repeat the procedure for COBOL copybooks.
The format of the COBOL copybooks must be the same. For example, you cannot import a COBOL copybook that uses the first six columns together with a COBOL copybook that ignores the first six columns. In this type of case, repeat the import process.

You can import the metadata from one COBOL copybook and later add to this metadata by repeating the import using different COBOL copybooks.

9. Click Add in the Import wizard to add a PSB source file, if necessary.
The selected files are displayed in the Get Input Files screen, as shown in Figure 5-6.

Figure 5-6 Get Input Files Screen

10. Click Next to go to the Apply Filters task.

Apply Filters

This section describes the steps required to apply filters on the COBOL Copybook files used to generate the Metadata. It continues the Select the Input Files task.

Perform the following task to apply filters.

1. Click Next.
The Apply Filters screen opens in the editor, as shown in Figure 5-7.

Figure 5-7 Apply Filters Wizard

2. Apply filters to the copybooks, as needed.
The following COBOL filters are available:

- COMP_6 switch: The MicroFocus COMP-6 compiler directive. Specify either COMP-6'1' to treat COMP-6 as a COMP data type or COMP-6'2' to treat COMP-6 as a COMP-3 data type.

- Compiler source: The compiler vendor.

- Storage mode: The MicroFocus Integer Storage Mode. Specify either NOIBMCOMP for byte storage mode or IBMCOMP for word storage mode.

- Ignore after column 72: Ignore columns 73 to 80 in the COBOL copybooks.

- Ignore first 6 columns: Ignore the first six columns in the COBOL copybooks.

- Prefix nested column: Prefix all nested columns with the previous level heading.

- Replace hyphens (-) in record and field names with underscores (_): A hyphen, which is an invalid character in Oracle metadata, is replaced with an underscore.

- Case sensitive: Specifies whether to consider case sensitivity or not.

- Find: Searches for the specified value.

- Replace with: Replaces the value specified for in the Find field with the value specified here.

The following DBD filters are available:

- Ignore after column 72: Ignore columns 73 to 80 in the COBOL copybooks.

- Ignore first 6 columns: Ignore the first six columns in the COBOL copybooks.

- Ignore labels: Ignore labels in the DBD files.

The following PSB filters are available:

- Ignore after column 72: Ignore columns 73 to 80 in the COBOL copybooks.

- Ignore first 6 columns: Ignore the first six columns in the COBOL copybooks.

3. Click Next to go to the Select Tables task.

Select Tables

This section describes the steps required to select the tables from the COBOL Copybooks.

The following task continues the Apply Filters task.

1. From the Select Tables screen, select the tables that you want to access. To select all tables, click Select All. To clear all the selected tables, click Unselect All.
Figure 5-8 shows the Select Tables screen.

Figure 5-8 Select Tables Screen

The import manager identifies the names of the segments in the DBD files that will be imported as tables.

2. Click Next to continue to the Match DBD to COBOL task.
The Import Manipulation screen open.

Match DBD to COBOL

This step lets you match the DBD file to your COBOL copybook. It is a continuation of the Select Tables task. Figure 5-9 shows the DBD to COBOL task that is displayed in the Editor.

Figure 5-9 Match DBD to COBOL Screen

1. Match each table selected from the DBD file with the COBOL copybook that contains the relevant table structure. Select the files and tables from the lists for each DBD entry.

2. Click Next to continue to the Manipulate the Imported Records task.
The Import Manipulation screen opens.

Manipulate the Imported Records

If required, you can now manipulate the imported records. This is an optional task.

This section describes the operations available for manipulating the imported records (tables). It continues the Select Tables task.

The import manager identifies the names of the records in the DDM Declaration files that will be imported as tables. You can manipulate the general table data in the Import Manipulation Screen.

Perform the following steps to manipulate the table metadata.

1. From the Import Manipulation screen (see Import Manipulation Screen figure), right-click the table record marked with a validation error, and select the relevant operation. See the Table Manipulation Options table, for the available operations.

2. Repeat step 1 for all table records marked with a validation error. You resolve the issues in the Import Manipulation Screen.
Once all the validation error issues have been resolved, the Import Manipulation screen is displayed with no error indicators.

3. Click Next to continue to the Select the Metadata Model task.

Import Manipulation Screen

Figure 5-10 shows the Import Manipulation screen.

Figure 5-10 Import Manipulation Screen

The upper area of the screen lists the DDM Declaration files and their validation status. The metadata source and location are also listed.

The Validation tab at the lower area of the screen displays information about what needs to be resolved in order to validate the tables and fields generated from the COBOL. The Log tab displays a log of what has been performed (such as renaming a table or specifying a data location).

The following operations are available in the Import Manipulation screen:

- Resolving table names, where tables with the same name are generated from different files during the import.

- Selecting the physical location for the data.

- Selecting table attributes.

- Manipulating the fields generated from the COBOL, as follows:

- Merging sequential fields into one (for simple fields).

- Resolving variants by either marking a selector field or specifying that only one case of the variant is relevant.

- Adding, deleting, hiding, or renaming fields.

- Changing a data type.

- Setting the field size and scale.

- Changing the order of the fields.

- Setting a field as nullable.

- Selecting a counter field for array for fields with dimensions (arrays). You can select the array counter field from a list of potential fields.

- Setting column-wise normalization for fields with dimensions (arrays). You can create new fields instead of the array field where the number of generated fields will be determined by the array dimension.

- Creating arrays and setting the array dimension.

The following table describes the available operations when you right-click a table entry.

Table 5-1 Table Manipulation Options

Option

Description

Fields Manipulation

Customizes the field definitions, using the Field Manipulation screen. You can also access this screen by double-clicking the required table record.

Rename

Renames a table. This option is used especially when more than one table with the same name is generated from the COBOL.

Set data location

Sets the physical location of the data file for the table.

Set table attributes

Sets the table attributes.

XSL manipulation

Specifies an XSL transformation or JDOM document that is used to transform the table definitions.

Remove

Removes the table record.

You can manipulate the data in the table fields in the Field Manipulation Screen. Double-click a line in the Import Manipulation Screen to open the Field Manipulation screen.

Field Manipulation Screen

The Field Manipulation screen lets you make changes to fields in a selected table. You get to the Field Manipulation screen through the Import Manipulation Screen. Figure 5-11 shows the Field Manipulation screen.

Figure 5-11 Field Manipulation Screen

The values displayed in the table on the Field Manipulation screen are calculated by the import process.

You can use the Primary Key Column column to define the primary key of the table and of the virtual views created for the table's arrays. When you select the Primary Key Column check box of array members, these columns form the primary key of the virtual view, together with the selected primary key columns of the parent.

You can carry out all of the available tasks in this screen through the menu or toolbar. You can also right click anywhere in the screen and select any of the options available in the main menus from a shortcut menu.

See Field Manipulation Screen Commands describes the commands that are available in the Field Manipulation screen. If a toolbar button is available for a task, it is pictured in the table.

Select the Metadata Model

This screen allows you to generate virtual and sequential views for tables containing arrays. In addition, you can configure the properties of the generated views.

This screen continues the Manipulate the Imported Records procedure.

In the Metadata Model Selection screen, you can select default values that apply to all tables or set specific settings per table. This screen inherits its default settings from the settings that you defined for the virtual view policy when you configure the data source properties (see Configuring the IMS/DB DLI Data Source Properties, Configure the IMS/DB DBCTL Data Source Properties, or Configure the IMS/DB DBDC Data Source Properties).

Note:

Selecting the Default values for all tables check box discards any table-specific settings that you set.

Perform the following steps to select the metadata model.

1. Select from the following:

- Default values for all tables: Select this option if you want to apply the same values to all tables to be imported.

- Generate sequential view: Select this option if you want to map a non-relational file to a single table.

- Generate virtual views: Select this option if you want to have an individual table created for every array in the non-relational file.

- Virtual views include row number: Select this option if you want to include a column that specifies the row number in the virtual or sequential view.

- Virtual views inherit all parent columns: Select this option if you want the virtual views to include all the columns of the parent record.

- Specific virtual array view settings per table: Select this option if you want to apply different values to the tables to be imported. Then select the relevant check boxes.

Note:

After importing a table, you can change these settings on the Modeling tab of the table editor.

2. Click Next to continue to the Import the Metadata task.

Figure 5-12 shows the Metadata Model Selection screen.

Figure 5-12 Metadata Model Selection Screen

Import the Metadata

This section describes the steps required to import the metadata to the target computer. It continues the Select the Metadata Model step.

You can now import the metadata to the computer where the data source is located, or import it later (in case the target computer is not available).

Perform the following steps to transfer the metadata.

1. Select Yes to transfer the metadata to the target computer immediately or No to transfer the metadata later.

2. Click Finish.

Figure 5-13 shows the Import Metadata screen.

Figure 5-13 Import Metadata Screen

The script content on this page is for navigation purposes only and does not alter the content in any way.

6 Installing Oracle Database Gateway for IMS

This chapter guides you through the installation procedure of Oracle Database Gateway for IMS.

To install the gateway, follow these steps:

1. Ensure that the system meets all of the hardware and software requirements specified in "System Requirements for Oracle Database Gateway for IMS".

2. Run the Oracle Universal Installer.
See "Running the Oracle Universal Installer" for more information about running the Oracle Universal Installer.

Oracle Universal Installer is a menu-driven utility that guides you through the installation of the gateway by prompting you with action items. The action items and the sequence in which they appear depend on your platform.

3. Configure the gateway.
Chapter 7, "Configuring Oracle Database Gateway for IMS" provides information on how to configure the gateway.

Overview of Oracle Database Gateway for IMS

Oracle Database Gateway for IMS consists of the following components:

- Oracle Studio for IMS, VSAM, and Adabas Gateways, a GUI-based tool that lets you configure the Oracle Servers in your system. Oracle Studio for IMS, VSAM, and Adabas Gateways runs on Windows and Linux platforms.

- Oracle Connect for IMS, VSAM, and Adabas Gateways, which is natively located on the data server to provide standard, service-oriented integration to IMS data. Oracle Connect for IMS, VSAM, and Adabas Gateways runs on z/OS platforms.

- Oracle Database Gateway, which provides the capabilities, SQL mappings, data type conversions, and interface to the remote non-Oracle system. The gateway interacts with Heterogeneous Services to provide the transparent connectivity between Oracle and non-Oracle systems.
The gateway must be installed on a Windows or UNIX computer. This can be the same system as the Oracle database server or a second, standalone system.

System Requirements for Oracle Database Gateway for IMS

This section provides information about the hardware and software requirements for the gateway. It contains the following sections:

- Hardware Requirements for Oracle Database Gateway for IMS

- Software Requirements for Oracle Database Gateway for IMS

Hardware Requirements for Oracle Database Gateway for IMS

Table 6-1 lists the hardware requirements for Oracle Database Gateway for IMS on UNIX.

Table 6-1 Hardware Requirements for Oracle Database Gateway for IMS

Requirement

IBM AIX

HP-UX Itanium (64-bit Itanium

Sun Solaris (SPARC) 64-bit

Linux x86

Linux x86 64-bit

Temporary disk space

700 MBFoot 1

700 MB

700 MB

700 MB

700 MB

Disk space

1.5 GB

1.5 GB

750 MB

750 MB

750 MB

Physical memory

512 MB

512 MB

512 MB

512 MB

512 MB

Swap space

1 GB

1 GB

1 GB

1 GB

1 GB

Processor

IBM RS/6000 AIX-based system processor

HP chipset sx2000 processor for HP-UX 11i v2

Sun Solaris (SPARC) processor

Processor chips that adhere to the x86 32-bit architecture

Processor chips that adhere to the x86 64-bit architecture

Footnote 1 This temporary disk space requirement assumes you download the software. The temporary disk space is less than 300 MB if you install from CD or DVD media.

Software Requirements for Oracle Database Gateway for IMS

Oracle Database Gateway for IMS is supported on the UNIX operating systems specified in table Table 6-2.

Table 6-2 Software Requirements for Oracle Database Gateway for IMS

Operating System

Version

Linux x86 (32-bit)

- Red Hat Enterprise Linux AS/ES 3.0 (Update 4 or later)

- Red Hat Enterprise Linux 4.0

- Enterprise Linux 4.0

Linux x86 64-bit

- Red Hat Enterprise Linux AS/ES 3.0 (Update 4 or later)

- Red Hat Enterprise Linux AS/ES 4.0 (Update 1 or later)

- Enterprise Linux 4.0

Sun Solaris 64-bit

- Solaris 9 (Update 6 or later)

- Solaris 10

HP Itanium 64-bit

- HP-UX 11i v2

- HP-UX 11i v2

IBM AIX 5L 64-bit

Version 5.3, Maintenance Level 02 or later

Gateway Installation Configurations

You can install the gateway in either of the following configurations:

- On the same computer as an existing Oracle database but in a different ORACLE_HOME directory.

- On a system with no Oracle database.

- On the same computer as the Oracle database and in the same ORACLE_HOME directory. Note that in this case, the Oracle database and the gateway must be at the same release level.

Gateway Installation Methods

You can choose different installation methods to install the gateway, as follows:

- Interactive Installation Method

- Automated Installation Method Using Response Files

Interactive Installation Method

When you use the interactive method to install the gateway, Oracle Universal Installer displays a series of screens that enable you to specify all of the required information to install the gateway software.

Automated Installation Method Using Response Files

By creating a response file and specifying this file when you start Oracle Universal Installer, you can automate some or all of the gateway installation steps. These automated installation methods are useful if you need to perform multiple installations on similarly configured systems or if the system where you want to install the software does not have X Window system software installed.

When you use a response file, you can run Oracle Universal Installer in the following modes, depending on whether you specify all of the required information or not:

- Silent Mode: Oracle Universal Installer runs in silent mode if you use a response file that specifies all required information. None of the Oracle Universal Installer screens are displayed.

- Suppressed Mode: Oracle Universal Installer runs in suppressed mode if you do not specify all required information in the response file. Oracle Universal Installer displays only the screens that prompt for the information that you did not specify.

See Appendix A, "Using Response Files for Non-Interactive Installation" for more information about this method and about how to complete an installation using response files.

Gateway Installation Considerations

This section contains information that you should consider before installing this product. It contains the following sections:

- Release Notes

- Hardware and Software Certification

- Multiple ORACLE_HOME Directories

Release Notes

Read the release notes for the product before installing it. The release notes are available on the Oracle Database 11g Release 2 (11.2) installation media. The latest version of the release notes is also available on the Oracle Technology Network (OTN) Web site:

http://www.oracle.com/technology/documentation/index.html

Hardware and Software Certification

The platform-specific hardware and software requirements included in this installation guide were current at the time this guide was published. However, because new platforms and operating system software versions might be certified after this guide is published, review the certification matrix on the OracleMetaLink Web site for the most up-to-date list of certified hardware platforms and operating system versions. The OracleMetaLink Web site is available at the following Web site:

http://metalink.oracle.com

If you do not have a current Oracle Support Services contract, then you can access the same information at the following Web site:

http://www.oracle.com/technology/support/metalink/content.html

Multiple ORACLE_HOME Directories

This product supports multiple ORACLE_HOME directories. This means that you can install this release or previous releases of the software more than once on the same system, in different ORACLE_HOME directories.

Installing the Software on a System with an Existing Oracle Installation

You must install this product in a new ORACLE_HOME directory. You cannot install products from one release of the gateway into an ORACLE_HOME directory of a different release.

Upgrades

Upgrades are not supported for Oracle Database Gateways.

Accessing the Installation Software

You can access and install the gateway by using the following methods:

- Downloading Oracle Software from the Oracle Technology Network Web Site

- Copying the Gateway Software to a Hard Disk

Downloading Oracle Software from the Oracle Technology Network Web Site

This section describes how to download the installation files and extract them on your hard disk. It contains the following topics:

- Downloading the Installation Files

- Extracting the Installation Files

Downloading the Installation Files

To download the installation files from the Oracle Technology Network (OTN):

1. Use any browser to access the software download page on OTN:
http://www.oracle.com/technology/software

2. Navigate to the download page for the product that you want to install.

3. On the download page, identify the required disk space by adding the file sizes for each required file.
The file sizes are listed next to the file names.

4. Select a file system with enough free space to store and expand the archive files.
In most cases, the available disk space must be at least twice the size of each compressed file.

5. On the file system that you selected in step 4, create a parent directory for each product, for example, dg4ims, to hold the installation directories.

6. Download all of the installation archive files to the directory that you created in step 5.

7. Verify that the files you downloaded are the same size as the corresponding files on OTN.

Extracting the Installation Files

To extract the installation files:

1. If necessary, change directory to the directory that contains the downloaded installation archive files.

2. To extract each file, enter the gunzip command.
For example:

$ gunzip filename.cpio.gz

This command creates files with names similar to the following:

filename.cpio

3. To extract the installation files, enter the cpio command.
For example:

$ cpio -idmv < filename.cpio

Note:

Refer to the download page for information about the correct options to use with the cpio command. Some browsers extract files while downloading them, but leave the .gz file extension. If these steps do not work, remove the .gz extension from the files and repeat step 3.

For each file, this command creates a subdirectory named Diskn, where n is either 1 or the disk number identified in the file name.

Copying the Gateway Software to a Hard Disk

Before installing the gateway, you might want to copy the software to the hard disk. This enables the installation process to run faster. Before copying the installation media content to the hard disk, you must mount the installation media.

Mounting the Installation Media

On most Sun Solaris operating systems, the disc mounts automatically when you insert it into the disc drive. If the disc does not mount automatically, perform the following steps to mount it:

1. Enter the following command to switch user to root:
$ su - root

2. If necessary, enter a command similar to one of the following to eject the currently mounted disc, then remove the disc from the drive:
On Sun Solaris (SPARC):

# eject

On IBM AIX:

# umount /cdrom

On HP-UX Itanium:

# /usr/sbin/umount /SD_CDROM

In these examples, /cdrom and /SD_CDROM are the mount point directories for the disc drive.

3. Insert the appropriate disc into the disc drive.

4. To verify that the disc mounted automatically, enter a command similar to the following, depending on your platform:
Sun Solaris (SPARC):

# ls /cdrom/cdrom0

5. If this command fails to display the contents of the disc, enter a command similar to the following to mount it, depending on your platform:
Sun Solaris (SPARC):

# /usr/sbin/mount -r -F hsfs /dev/dsk/cxtydzs2 /cdrom

In this example, /cdrom is the disc mount point directory and /dev/dsk/cxtydzs2 is the device name for the disc device, for example /dev/dsk/c0t2d0s2.

6. If Oracle Universal Installer displays the Disk Location dialog box, enter the disk mount point directory path, for example:
/mnt/cdrom

Copying the Oracle Database Gateway Software to a Hard Disk

To copy the contents of the disc to a hard disk:

1. Create a directory on the hard disk to hold the Oracle software:
$ mkdir Ora10g

2. Change directory to the directory you created in step 1:
$ cd Ora10g

3. Create subdirectories for each installation disc with names similar to the following, where n is the disc number:
$ mkdir Diskn

4. Copy the contents of the mounted disc to the corresponding new subdirectory as follows:
$ cp -R /directory_path Diskn

In this example, n is the disc number and /directory_path is the installation media mount point directory. The mount point directory is /cdrom.

5. If necessary, mount the next disc and repeat step 4.

Running the Oracle Universal Installer

Start the Installer and install the software, as follows:

1. If you are installing the software from disc, then mount the disc if it is not already mounted.
Some platforms automatically mount discs when you insert them into the drive.

2. If necessary, log in as the Oracle software owner user (oracle) and set the DISPLAY environment variable.

3. To start the Installer, enter the following commands where directory_path is the CD-ROM mount point directory or the path of the dg directory on the DVD-ROM.
directory_path/runInstaller

4. Follow the instruction displayed in the Installer window.

Caution:

The Oracle Universal Installer automatically installs the Oracle-supplied version of the Java Runtime Environment (JRE). This version is required to run Oracle Universal Installer and several Oracle assistants. Do not modify the JRE except by using a patch provided by Oracle Support Services.

Table 6-3 describes the installation procedure for Oracle Database Gateway for IMS.

Note:

- When the Installer prompts you to run a script with root privileges, enter a command similar to the following in a terminal where you are logged in as the root user, then click Continue or OK:
# /script_path/script_name

- On Tru64 UNIX, when prompted for the JDK home directory, specify the location of JDK 1.4.2 on your system.
To determine the JDK home directory, enter the following command:

# /usr/sbin/setld -i JAVA142 | more

The default location is /usr/opt/java142.

Table 6-3 The Oracle Universal Installer: Steps for Installing the Gateway

Screen

Response

Oracle Universal Installer: Welcome

Click Next.

Oracle Universal Installer: Specify Home Details

The Path field in the Specify Home Details screen is where you specify the destination for your installation. You need not edit the path specification in the Path field. The default setting for this field points to ORACLE_HOME. After you set the fields in the Specify Home Details screen as necessary, click Next to continue. After loading the necessary information from the installation, the Oracle Universal Installer displays the Available Products screen.

Oracle Universal Installer: Available Product Components

Select Oracle Database Gateway for IMS 11.2.0.

Click Next.

Oracle Database Gateway for IMS

Oracle Connect for IMS, VSAM, and Adabas Gateways Host Name: Specify the host name of the system running Oracle Connect for IMS, VSAM, and Adabas Gateways on z/OS.

Oracle Connect for IMS, VSAM, and Adabas Gateways Port number: Specify the port number Oracle Connect for IMS, VSAM, and Adabas Gateways listens on.Click Next to continue.

Oracle Universal Installer: Summary

The Installation Summary screen enables you to review a tree list of options and components for this installation.

Click Install to display the Installation Status screen.

Oracle Net Configuration Assistant: Welcome

Click Cancel.

Oracle Net Configuration Assistant:

Click Yes.

Oracle Universal Installer: Configuration Tools

When Oracle Universal Installer confirms that the installation is complete, verify that the installation procedure was successful. To do this, read the contents of the installation log file, which is located in the following directory:

[designated_inventory_location]\OraInventory\logs

The default file name is InstallActionsYYYY-MM-DD_HH-mm-SS-AM/PM.log, where:

YYYY is year

MM is month

DD is day

HH is hour

mm is minute

SS is seconds

AM/PM is daytime or evening

Each of these variables in the log file name represents the date and time the product was installed.

When you finish configuring, click Exit.

Exit

Click Exit.

If you need additional information, click Help.

If you encounter errors while installing or linking the software, then see Appendix B for information about troubleshooting.

7 Configuring Oracle Database Gateway for IMS

After installing the gateway, perform the following tasks to configure the gateway for IMS:

- Configuring the Gateway

- Configuring Oracle Net Services Listener for the Gateway

- Configuring the Oracle Database for Gateway Access

- Creating Database Links

- Gateway Password Encryption Tool

- Configuring the Gateway for Multiple IMS Databases

- Performing Configuration Tasks

- Testing the IMS Data Source

Configuring the Gateway

Perform the following tasks to configure Oracle Database Gateway for IMS:

1. Choose a System Identifier for the Gateway

2. Customize the Initialization Parameter File

Choose a System Identifier for the Gateway

Choosing a system identifier is the first task in configuring Oracle Database Gateway for IMS. The gateway system identifier (SID) is an alphanumeric character string that identifies a gateway instance. If you want to connect simultaneously to different IMS data sources, you need one gateway instance, and therefore one gateway SID, for each IMS database you are accessing. The SID name is used as part of the file name for the initialization parameter file. The default SID is dg4ims.

The HS_FDS_DATASOURCE_NAME parameter takes on the gateway SID as the default value. This means that the data source matches the gateway SID by default. However, you can specify the value of the HS_FDS_DATASOURCE_NAME parameter to match the data source that you want to access. See "HS_FDS_DATASOURCE_NAME" for more information.

If you have one IMS data source and want to access it sometimes with one set of gateway parameter settings, and other times with different gateway parameter settings, you can do that by defining two different data sources and defining the matching SID s accordingly.

Customize the Initialization Parameter File

Customizing the initialization parameter file is the second task in configuring Oracle Database Gateway for IMS. The initialization parameter file must be available when the gateway is started. During installation, the following default initialization parameter file is created:

$ORACLE_HOME/dg4ims/admin/initdg4ims.ora

Where $ORACLE_HOME is the directory in which the gateway is installed.

The name of the parameter file is init[SID].ora, where SID is the gateway SID. If you are not using dg4ims as the gateway SID, you must rename the initialization parameter file using the SID you chose in Task 1. This default initialization parameter file is sufficient for starting the gateway, verifying a successful installation, and running the demonstration scripts.

In the initialization parameter file, specify the IMS connection as follows:

In the initialization parameter file, specify the VSAM connection as follows:

- If you use the default workspace:

HS_FDS_CONNECT_INFO="address:port"

- If you use a workspace other than the default:

HS_FDS_CONNECT_INFO="address='host' port='port' workspace='workspace'"

Where:

- host: The name of the mainframe computer on which Oracle Connect for IMS, VSAM, and Adabas Gateways runs.

- port: The port number to listen to.

- workspace: The IMS data source workspace name. (optional except for the IMS/DB DLI data source)

HS_FDS_ACCESS_METHOD must be set to IMS-DBCTL for IMS/DB DBCTL data sources and to IMS/DBDC for the IMS/DB DBDC data sources. See Appendix B, "Initialization Parameters" for details.

A number of initialization parameters can be used to modify the gateway behavior. You may want to change the initialization parameter file later to meet system requirements.

See Also:

The Oracle Database Heterogeneous Connectivity Administrator's Guide for more information about customizing the initialization parameter file.

Configuring Oracle Net Services Listener for the Gateway

The gateway requires Oracle Net Services to provide transparent data access. After configuring the gateway, configure Oracle Net Services to work with the gateway.

1. Configure Oracle Net Services Oracle Net Listener for the Gateway

2. Stop and Start the Oracle Net Listener for the Gateway

Configure Oracle Net Services Oracle Net Listener for the Gateway

Oracle Net Services uses the Oracle Net Listener to receive incoming connections from a Oracle Net Services client. The Oracle Net Listener and the gateway must reside on the same system.

The Oracle Net Listener listens for incoming requests from the Oracle Database. For the Oracle Net Listener to listen for the gateway, information about the gateway must be added to the Oracle Net Listener configuration file, listener.ora. This file is located in the following directory:

$ORACLE_HOME/network/admin

Note:

If Oracle Net Services is reinstalled, the original listener.ora file is renamed and a new listener.ora file is put into the same directory.

The following entries must be added to the listener.ora file:

- A list of Oracle Net Services addresses on which the Oracle Net Listener listens.

- The gateway that the Oracle Net Listener starts in response to incoming connection requests.

Example of Address to Listen On in listener.ora File

The Oracle Database accesses the gateway using Oracle Net Services and the TCP/IP protocol adapter. The following is the syntax of the connect descriptor entry in the listener.ora file:

LISTENER =
(DESCRIPTION_LIST =
(DESCRIPTION =
(ADDRESS_LIST =
(ADDRESS = (PROTOCOL = IPC)(KEY = EXTPROC))
)
(ADDRESS_LIST =
(ADDRESS = (PROTOCOL = TCP)(HOST = host_name)(PORT = 1552))
)
)
)

Where:

Table 7-1 Parameters for listener.ora File

Variable

Description

host_name

is the name of the system on which the gateway is installed.

port

specifies the port number used by the Oracle Net Listener. If you have other listeners running on host_name, the value of port_number must be different from the other listeners' port numbers.

Example of Gateway to Start in listener.ora File

To direct the Oracle Net Listener to start the gateway in response to incoming connection requests, add an entry to the listener.ora file as follows.

Use the following syntax for Linux platforms:

SID_LIST_LISTENER =
(SID_LIST =
.
.
(SID_DESC=
(SID_NAME=gateway_sid)
(ORACLE_HOME=ORACLE_HOME_directory)
(PROGRAM=dg4ims)
(ENVS=LD_LIBRARY_PATH=$ORACLE_HOME/lib)
)
)

Note:

The executable dg4ims is valid for IMS, IMS CICS, and IMS/TM

Where:

Table 7-2 Parameters for listener.ora File

Variable

Description

sid_name

The SID of the gateway and matches the gateway SID specified in the connect descriptor entry in the tnsnames.ora file. The Oracle Net Listener uses the SID name to locate the relevant <sid_name>.ora file. It needs to access this file to check that access method is used (IMS-BATCH, IMS-DBCTL, or IMS-DBDC).

ORACLE_HOME

The Oracle home directory where the gateway is located.

The following table specifies which ENVS parameter value to use for the different platforms:

Platform

ENVS Parameter Value

Sun Solaris 64-bit

LD_LIBRARY_PATH=$ORACLE_HOME/lib

HP-UX Itanium 64-bit

SHLIB_PATH=$ORACLE_HOME/lib

IBM AIX 64-bit

LIBPATH=$ORACLE_HOME/lib

Linux32-bit

LD_LIBRARY_PATH=$ORACLE_HOME/lib

Linux 64-bit

LD_LIBRARY_PATH=$ORACLE_HOME/lib

See Also:

Oracle Net Services Administrator's Guide for information about changing the listener.ora file.

Stop and Start the Oracle Net Listener for the Gateway

The Oracle Net Listener must be started to initiate the new settings, as follows:

1. Set the PATH environment variable to access the commands in the following directory:

$ORACLE_HOME/bin

If you have the Bourne or Korn Shell, enter the following:

$ PATH=$ORACLE_HOME/bin:$PATH;export PATH
$ LD_LIBRARY_PATH=$ORACLE_HOME/lib:$LD_LIBRARY_PATH; export LD_LIBRARY_PATH

If you have the C Shell, enter the following:

$ setenv PATH $ORACLE_HOME/bin:$PATH
$ setenv LD_LIBRARY_PATH $ORACLE_HOME/lib:$LD_LIBRARY_PATH

where $ORACLE_HOME is the directory where the gateway is installed.

2. If the listener is already running, use the lsnrctl command to stop the listener and then start it with the new settings, as follows:

$ lsnrctl stop
$ lsnrctl start

3. Check the status of the listener with the new settings, as follows:

$ lsnrctl status

The following is an example of output from a lsnrctl status check:

LSNRCTL for SOLARIS: Version 11.2.0 - Production on 01-JUN-2009 09:16:17

Copyright (c) 1991, 2009, Oracle. All rights reserved.

Connecting to (ADDRESS=(PROTOCOL=TCP)(HOST=204.179.99.15)(PORT=11201))
STATUS of the LISTENER
----------------------
Alias                    listener
Version                  TNSLSNR for SOLARIS: Version 11.2.0 - Production
Start Date               31-May-2009 10:16:17
Uptime                   0 days 18 hr. 5 min. 13 sec
Trace Level              off
Security                 OFF
SNMP                     OFF
Listener Parameter File  /users/oracle/gateway/network/admin/listener.ora
Listener Log File        /users/oracle/gateway/network/log/listener.log
Listening Endpoints Summary...
(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=204.179.99.15)(PORT=11201)))
Services Summary...
Service "dg4ims" has 1 instance(s).
Instance "dg4ims", status UNKNOWN, has 1 handler(s) for this service...
The command completed successfully

In this example, dg4ims is the default SID value assigned during installation. You can use any valid ID for the SID, or keep the default.

Note:

You must use the same SID value in the tnsnames.ora file, and the listener.ora file.

Configuring the Oracle Database for Gateway Access

Before you can use the gateway to access IMS data, you must configure the Oracle Database to enable communication with the gateway over Oracle Net Services.

Perform the following tasks to configure the Oracle Database accordingly:

Configuring Oracle Net Services for the Oracle Database

Configuring Oracle Net Services for the Oracle Database

To configure the server you add connect descriptors to the tnsnames.ora file. You cannot use the Oracle Net Services Assistant or the Oracle Net Services Easy Config tools to configure the tnsnames.ora file. You must edit the file manually.

See Also:

Oracle Database Administrator's Guide for information about editing the tnsnames.ora file.

For the Oracle Database to access the gateway, it needs a service name entry or a connect descriptor name entry in the tnsnames.ora file to tell the Oracle Database where to make connections.

By default, this file is in $ORACLE_HOME/network/admin, where $ORACLE_HOME is the directory in which the Oracle Database is installed. The tnsnames.ora file is required by the Oracle Database accessing the gateway, but not by the gateway.

Configuring tnsnames.ora

Edit the tnsnames.ora file to add a connect descriptor for the gateway. The following is an example of the Oracle Net Services entries using TCP/IP protocol needed for the Oracle Database to access the gateway:

connect_descriptor=
vsam =
(DESCRIPTION =
(ADDRESS_LIST =
(ADDRESS = (PROTOCOL = TCP)(HOST = host_name)(PORT = port_number))
)
(CONNECT_DATA =
(SID = gateway_sid)
)
(HS = OK)
)

Where:

Table 7-3 Parameters for tnsnames.ora File

Variable

Description

connect_descriptor

The description of the object to connect to as specified when creating the database link, such as dg4ims.

Check the sqlnet.ora file for the following parameter setting:

names.directory_path = (TNSNAMES)

Note: The sqlnet.ora file is typically stored in $ORACLE_HOME/network/admin.

host_name

Specifies the system where the gateway is running.

port_number

Matches the port number used by the Oracle Net Services Oracle Net Listener that is listening for the gateway. The Oracle Net Listener's port number can be found in the listener.ora file used by the Oracle Net Listener. See "Example of Address to Listen On in listener.ora File".

gateway_sid

Specifies the SID of the gateway and matches the SID specified in the listener.ora file of the Oracle Net Listener that is listening for the gateway. See "Configure Oracle Net Services Oracle Net Listener for the Gateway" for more information.

For example:

connect_descriptor=
IMS =
(DESCRIPTION =
(ADDRESS_LIST =
(ADDRESS = (PROTOCOL = TCP)(HOST = host_name)(PORT = port_number))
)
(CONNECT_DATA =
(SID = gateway_sid)
)
(HS = OK)
)

Creating Database Links

Any Oracle client connected to the Oracle Database can access IMS data through the gateway. The Oracle client and the Oracle Database can reside on different systems. The gateway accepts connections only from the Oracle Database.

A connection to the gateway is established through a database link when it is first used in an Oracle session. In this context, a connection refers to the connection between the Oracle Database and the gateway. The connection remains established until the Oracle session ends. Another session or user can access the same database link and get a distinct connection to the gateway and IMS database.

Database links are active for the duration of a gateway session. If you want to close a database link during a session, you can do so with the ALTER SESSION CLOSE DATABASE LINK dblink statement. The database and application administrators of a distributed database system are responsible for managing the necessary database links that define paths to the IMS database.

See Also:

Oracle Database Administrator's Guide and Oracle Database Heterogeneous Connectivity User's Guide for more information about using database links.

Gateway Password Encryption Tool

The gateway uses userids and passwords to access the information in the remote database. Some userids and passwords must be defined in the Gateway Initialization File to handle functions such as resource recovery. In the current security conscious environment, having plain-text passwords that are accessible in the Initialization File is considered insecure. The dg4pwd encryption utility has been added as part of Heterogeneous Services' generic connectivity to help make this more secure. This utility is accessible by this gateway. The initialization parameters that contain sensitive values can be stored in an encrypted form.

See Also:

Oracle Database Heterogeneous Connectivity User's Guide for more information about using this utility.

Configuring the Gateway for Multiple IMS Databases

The tasks for configuring the gateway to access multiple IMS databases are similar to the tasks for configuring the gateway for a single database. The configuration example assumes the following:

- The gateway is installed and configured with the default SID of dg4ims.

- The ORACLE_HOME environment variable is set to the directory where the gateway is installed.

- The gateway is configured for one IMS database named dg4ims.

- Two IMS databases named dg4ims2 and dg4ims3 on a server named mvs5 with port number 2551 are added.

Configuring the gateway for additional IMS databases is similar to configuring it for one database, and involves the following:

- Configuring the gateway.

- Configuring Oracle Net Services for the gateway and the Oracle Database.

Multiple Databases Example: Configuring the Gateway

Choose Two System IDs for Each IMS Database

A separate instance of the gateway accesses the different IMS databases. Each instance needs its own gateway System ID (SID). For this example, the gateway SIDs for the instances that access the IMS databases are named as follows:

- dg4ims2 for the gateway accessing data source dg4ims2.

- dg4ims3 for the gateway accessing data source dg4ims3.

Create Two Initialization Parameter Files

Create an initialization parameter file for each instance of the gateway by copying the original initialization parameter file twice, naming one with the gateway SID for dg4ims2 and the other with the gateway SID for dg4ims3:

$ cd $ORACLE_HOME/dg4ims/admin$ cp initdg4ims.ora initdg4ims2.ora$ cp initdg4ims.ora initdg4ims3.ora

Note:

The library $ORACLE_HOME/dg4ims/admin is valid for IMS, IMS CICS, and IMS/TM.

Change the value of the HS_FDS_CONNECT_INFO parameter in the new files.

For initdg4ims2.ora, enter the following:

HS_FDS_CONNECT_INFO="mvs5:2551"

For initdg4ims3.ora, enter the following:

HS_FDS_CONNECT_INFO="mvs5:2551"

Note:

If you have multiple gateway SIDs for the same IMS database because you want to use different gateway parameter settings at different times, follow the same procedure. You create several initialization parameter files, each with different SIDs and different parameter settings.

Multiple Databases Example: Configuring Oracle Net Services Listener

Add Entries to listener.ora

Add two new entries to the Oracle Net Listener configuration file, listener.ora. You must have an entry for each gateway instance, even when multiple gateway instances access the same database.

The following example shows the entry for the original installed gateway first, followed by the new entries:

SID_LIST_LISTENER=
(SID_LIST=
(SID_DESC=
(SID_NAME=dg4ims)
(ORACLE_HOME=ORACLE_HOME_directory)
(PROGRAM=dg4ims)
)
(SID_DESC=
(SID_NAME=dg4ims2)
(ORACLE_HOME=ORACLE_HOME_directory)
(PROGRAM=dg4ims)
)
(SID_DESC=
(SID_NAME=dg4ims3)
(ORACLE_HOME=ORACLE_HOME_directory)
(PROGRAM=dg4ims)
)
)

Multiple Databases Example: Stopping and Starting the Oracle Net Listener

If the listener is already running, use the lsnrctl command to stop the listener and then start it with the new settings, as follows:

$ lsnrctl stop$ lsnrctl start

Multiple Databases Example: Configuring the Oracle Database for Gateway Access

This section describes the required procedures to configure the Oracle Database for the gateway access.

Configuring Oracle Net Services on the Oracle Database for Multiple Gateway Instances

Add two connect descriptor entries to the tnsnames.ora file. You must have an entry for each gateway instance, even if the gateway instances access the same database.

The following IMS example shows the entry for the original installed gateway first, followed by the two entries for the new gateway instances:

old_db_using=(DESCRIPTION=
(ADDRESS=
(PROTOCOL=TCP)
(PORT=1541)
(HOST=gtwhost))
(CONNECT_DATA=
(SID=dg4ims))
(HS=OK))
new_IMS2_using=(DESCRIPTION=
(ADDRESS=
(PROTOCOL=TCP)
(PORT=1541)
(HOST=gtwhost))
(CONNECT_DATA=
(SID=dg4ims2))
(HS=OK))
new_IMS3_using=(DESCRIPTION=
(ADDRESS=
(PROTOCOL=TCP)
(PORT=1541)
(HOST=gtwhost))
(CONNECT_DATA=
(SID=dg4ims3))
(HS=OK))

The value for PORT is the TCP/IP port number of the Oracle Net Listener that is listening for the gateway. The number can be found in the listener.ora file used by the Oracle Net Listener. The value for HOST is the name of the system on which the gateway is running. The name also can be found in the listener.ora file used by the Oracle Net Listener.

Multiple Databases Example: Accessing IMS Data

Enter the following to create a database link for the dg4ims2 gateway:

SQL> CREATE PUBLIC DATABASE LINK IMS2 CONNECT TO
2  user2 IDENTIFIED BY password2 USING 'new_IMS2_using';

Enter the following to create a database link for the dg4ims3 gateway:

SQL> CREATE PUBLIC DATABASE LINK IMS3 CONNECT TO
2  user3 IDENTIFIED BY password3 USING 'new_IMS3_using';

Note:

To encrypt the initialization parameters that would normally be stored in the initialization file in plain text, you must use the dg4pwd utility, as described in Oracle Database Heterogeneous Connectivity User's Guide.

After the database links are established you can query the new IMS databases, as in the following:

SQL> SELECT * FROM ALL_TABLES@IMS2;

Or

SQL> SELECT * FROM ALL_TABLES@IMS3;

Performing Configuration Tasks

You can perform the following configuration tasks:

- Configuring for Global Transactions

- Enabling Automatic Recovery

Configuring for Global Transactions

The IMS/DLI and IMS/DBDC data sources support auto-commit mode only. This means that you cannot roll back, or undo, any changes that you made.

The gateway supports the following transaction capabilities:

- READ_ONLY

- SINGLE_SITE (default)

See the Oracle Database Heterogeneous Connectivity User's Guide for configuration information.

By default, the IMS/DBCTL data source supports global transactions. If the IMS/DBCTL data source is configured differently in Oracle Studio for IMS, VSAM, and Adabas Gateways, see the Oracle Database Heterogeneous Connectivity User's Guide for information about configuring for global transactions.

If the IMS/DBCTL data source is configured for global transactions, the gateway becomes the commit point site when the IMS/DBCTL data source is updated by a transaction. The Oracle database commits the unit of work in the IMS/DBCTL data source after verifying that all Oracle databases in the transaction have successfully prepared the transaction. Only one gateway can participate in an Oracle global transaction as the commit point site.

See Also:

Oracle Database Heterogeneous Connectivity User's Guide for information about the global transaction process.

Enabling Automatic Recovery

For the gateway to recover distributed transactions, a recovery account and password must be provided. By default, both the user name of the account and the password are RECOVER. The name of the account can be changed with the gateway initialization parameter HS_FDS_RECOVERY_ACCOUNT. The account password can be changed with the gateway initialization parameter HS_FDS_RECOVERY_PWD.

Note:

Oracle Corporation recommends that you do not use the default value RECOVER for the user name and password. Moreover, storing plain text as user name and password in the initialization file is not a good security policy. There is now a utility called dg4pwd that should be used for encryption. Refer to Chapter 4, "Encrypting Initialization parameters" in Oracle Heterogeneous Connectivity Administration Guide for details.

To change the default user name or the password, in the initialization parameter file, set the following gateway initialization parameters:

- HS_FDS_RECOVERY_ACCOUNT to the mainframe account name.
This account can be the same account that is used to access the IMS/DB data source. If you use another account, then it must have the same permissions as the account that is used to access the IMS/DB data source.

- HS_FDS_RECOVERY_PWD to the password of the account.

See Also:

"Customize the Initialization Parameter File" for information about editing the initialization parameter file and Appendix B, "Initialization Parameters" for information about the HS_FDS_RECOVERY_ACCOUNT and HS_FDS_RECOVERY_PWD initialization parameters.

Testing the IMS Data Source

You can perform the following tests on the IMS data source:

- Connection test: This tests the physical connection to the data source.

- Query test: This test runs an SQL SELECT query against the data source.

These tests are described in the following procedures.

See Also:

Setting Up an IMS Data Source for information on how to add a data source.

1. Open Oracle Studio for IMS, VSAM, and Adabas Gateways.

2. Expand the node of the required computer.

3. Expand the node of the required binding.

4. Expand the Data sources node.

5. Right-click the required data source entity, and select Test.
The Test Wizard screen opens.

6. Select Navigator from the Active Workspace Name list, and click Next.
The system now tests the connection to the data source, and returns the test result status.

7. Click Finish to exit the Test wizard.

Perform the following procedure to test the IMS data source by query:

1. Open Oracle Studio for IMS, VSAM, and Adabas Gateways.

2. Expand the node of the required computer.

3. Expand the node of the required binding.

4. Expand the Data sources node.

5. Right-click the required data source entity, and select Query Tool.
The Select Workspace screen opens.

6. Select Navigator and click OK.
The Query Tool opens in the Editor pane, with the Build Query tab displayed (see Figure 7-1).

7. Select the required query type from the Query Type list. The default is a SELECT-type query.

8. Locate and expand the node of the required data source entity.
The data source tables are listed.

9. Select the required table and move it to the Table column by using the arrow button.

Figure 7-1 The Query Tool screen

10. Click Execute query.
The Query Result tab opens, displaying the results of the query.

11. Close the Query Tool in the Editor pane.

Sample Log File

Log files are used for troubleshooting and error handling. The log file is generated when the driverTrace debug binding parameter is set to True.

The log file includes various information concerning the functions used or called by the driver, queries executed, data sources accessed, etc.

First, you need to create the log file. Perform the following procedure.

1. Open Oracle Studio for IMS, VSAM, and Adabas Gateways.

2. From the main menu, click Windows, Preferences.
The Preferences screen is displayed.

Figure 7-2 Studio Preferences

3. In the left pane, click the Studio node.

4. Click the Advanced tab.

5. Click the Show advanced environment parameters check box.

6. Click OK.

7. In the Design Perspective Configuration view, right-click the binding under which the data source is located, and select Edit Binding.

8. In the Category combo box, select Debug.

9. Set the driverTrace and generalTrace parameters to TRUE.

Figure 7-3 Binding Properties

10. Execute the following query: Select * from nation limit to 3 rows.

The following is a sample log file output:

Example 7-1 Sample IMS Log File

ORACLE CONNECT Log (V10.1.3.1, MVS) Started at 2006-12-04T17:57:33
Licensed by Oracle Corporation on 28-SEP-2006 (001001610)
Licensed to ORACLE for <all providers> on <all machines> (<all platforms>)

o: 586 9991834 fopen >>> filename=TEST.OR5000A.DEF.NOSBB.SYS,mode=rb, typ
e=record, lrecl=8208
o: 275 0 flocate >>> stream=9991834,key=99CA6C8,key_len=4,options=3
o: 292 8208 fread >>> buffer=99CB1A8, size=1, count=8208,stream=9991834
o: 424 0 fclose >>> stream=9991834
o: 275 0 flocate >>> stream=997C3F4,key=9974ED0,key_len=100,options=5
o: 292 2048 fread >>> buffer=99746C8, size=1, count=2048,stream=997C3F4
o: 275 0 flocate >>> stream=997C024,key=9974ED0,key_len=4,options=5
o: 292 2048 fread >>> buffer=99746C8, size=1, count=2048,stream=997C024
o: 275 0 flocate >>> stream=997C3F4,key=9974ED0,key_len=100,options=5
o: 292 2048 fread >>> buffer=99746C8, size=1, count=2048,stream=997C3F4
o: 275 0 flocate >>> stream=997C024,key=9974ED0,key_len=4,options=5
o: 292 2048 fread >>> buffer=99746C8, size=1, count=2048,stream=997C024
SYSBASE (699): ; REGENTP(db_ims_d) returned 0
SYSBASE (640): ; dllload(NVDBIMS) returned 8ED5A67
SYSBASE (650): ; dllqueryfn(8ED5A67, db_ims_dli_get_functions) returned 8ED5A90
<IMSDB DP> >>> CONNECT                 connect=''
<IMSDB DP> <<< CONNECT                 0
<IMSDB DP> >>> SET CONNECT  transaction type ==  '0'
<IMSDB DP> <<< SET CONNECT                 0
nvOUT (PROD.AC10131.NAV(QP#SQTXT) 89): SELECT TABLE_NAME, TABLE_TYPE FROM NAV_PROC:SP_TABLES('ims', '%', '%', 'TABLE,SYSTEM TABLE,
VIEW,SYNONYM', 0)
nvRETURN (PROD.AC10131.NAV(QPSYNON) 1140): -1
<<<<<<<<<<<<<<<<<<<  Execution Strategy Begin <<<<<<<<<<<<<<<<<<<<<<<<<<<<

Original SQL:
SELECT TABLE_NAME , TABLE_TYPE FROM NAV_PROC : SP_TABLES ( 'ims' , '%' , '%' , 'TABLE,SYSTEM TABLE,VIEW,SYNONYM' , 0 )

Accessing saved query spec SP_TABLES()
from NAV_PROC DB

>>>>>>>>>>>>>>>>>>>> Execution Strategy End >>>>>>>>>>>>>>>>>>>>>>>>>>>>

o: 586 9991834 fopen >>> filename=TEST.OR5000A.DEF.NOS.IMS,mode=rb, type=
record, lrecl=2048
o: 393 0 fclose >>> stream=997C3F4
o: 424 0 fclose >>> stream=997C024
o: 586 Calling ENQ for TEST.OR5000A.DEF.NOS.SYS .
o: 586 Successful exclusive enqueue retCode=0
o: 586 9991C04 fopen >>> filename=TEST.OR5000A.DEF.NOS.SYS,mode=rb+, type
=record
o: 627 997C024 fopen >>> filename=TEST.OR5000A.DEF.NOS.SYS.I2.PATH,mode=r
b, type=record, lrecl=2048
o: 275 0 flocate >>> stream=997C024,key=9C13F50,key_len=100,options=5
o: 292 2048 fread >>> buffer=9C13748, size=1, count=2048,stream=997C024
o: 393 0 fclose >>> stream=997C024
o: 424 0 fclose >>> stream=9991C04
o: 424 Calling DEQ for TEST.OR5000A.DEF.NOS.SYS
o: 424 Successful dequeue retCode=0
o: 586 997C024 fopen >>> filename=TEST.OR5000A.DEF.NOS.IMS,mode=rb, type=
record, lrecl=2048
o: 586 Calling ENQ for TEST.OR5000A.DEF.NOS.SYS .
o: 586 Successful exclusive enqueue retCode=0
o: 586 997C3F4 fopen >>> filename=TEST.OR5000A.DEF.NOS.SYS,mode=rb+, type
=record
o: 627 997C7C4 fopen >>> filename=TEST.OR5000A.DEF.NOS.SYS.I2.PATH,mode=r
b, type=record, lrecl=2048
o: 275 0 flocate >>> stream=997C7C4,key=9C08F30,key_len=100,options=5
o: 292 2048 fread >>> buffer=9C08728, size=1, count=2048,stream=997C7C4
o: 393 0 fclose >>> stream=997C7C4
o: 424 0 fclose >>> stream=997C3F4
o: 424 Calling DEQ for TEST.OR5000A.DEF.NOS.SYS
o: 424 Successful dequeue retCode=0
o: 627 997C3F4 fopen >>> filename=TEST.OR5000A.DEF.NOS.IMS.I2.PATH,mode=r
b, type=record, lrecl=2048
o: 275 0 flocate >>> stream=997C3F4,key=9C04ED0,key_len=100,options=5
o: 292 2048 fread >>> buffer=9C046C8, size=1, count=2048,stream=997C3F4
o: 292 2048 fread >>> buffer=9C046C8, size=1, count=2048,stream=997C3F4
o: 292 2048 fread >>> buffer=9C046C8, size=1, count=2048,stream=997C3F4
o: 292 2048 fread >>> buffer=9C046C8, size=1, count=2048,stream=997C3F4
o: 292 2048 fread >>> buffer=9C046C8, size=1, count=2048,stream=997C3F4
o: 292 2048 fread >>> buffer=9C046C8, size=1, count=2048,stream=997C3F4
o: 292 2048 fread >>> buffer=9C046C8, size=1, count=2048,stream=997C3F4
o: 292 0 fread >>> buffer=9C046C8, size=1, count=2048,stream=997C3F4
o (292): ; amrc: Error = 81704
AbendSyscode = 8
AbendRc = 1704
FdbkRc = 8
Ftncd = 17
Fdbk = 4
svc99_info = 8
svc99_error = 1704
RBA = 0
last_op = 72
o (292): ; amrc: msg=NULL
DB_VSAM_IO (302): ; amrc: Error = 81704
AbendSyscode = 8
AbendRc = 1704
FdbkRc = 8
Ftncd = 17
Fdbk = 4
svc99_info = 8
svc99_error = 1704
RBA = 0
last_op = 6
DB_VSAM_IO (302): ; amrc: msg=NULL
DB_VSAM_IO (302): ;
DB_VSAM_IO(302) io_vsam_get
End of file

o: 586 997CFDC fopen >>> filename=TEST.OR5000A.DEF.NOS.IMS,mode=rb, type=
record, lrecl=2048
o: 586 Calling ENQ for TEST.OR5000A.DEF.NOS.SYS .
o: 586 Successful exclusive enqueue retCode=0
o: 586 997D3AC fopen >>> filename=TEST.OR5000A.DEF.NOS.SYS,mode=rb+, type
=record
o: 627 997DAAC fopen >>> filename=TEST.OR5000A.DEF.NOS.SYS.I2.PATH,mode=r
b, type=record, lrecl=2048
o: 275 0 flocate >>> stream=997DAAC,key=9BFEF10,key_len=100,options=5
o: 292 2048 fread >>> buffer=9BFE708, size=1, count=2048,stream=997DAAC
o: 393 0 fclose >>> stream=997DAAC
o: 424 0 fclose >>> stream=997D3AC
o: 424 Calling DEQ for TEST.OR5000A.DEF.NOS.SYS
o: 424 Successful dequeue retCode=0
o: 627 997D3AC fopen >>> filename=TEST.OR5000A.DEF.NOS.IMS.I2.PATH,mode=r
b, type=record, lrecl=2048
o: 275 -1 flocate >>> stream=997D3AC,key=9C0AF50,key_len=100,options=5
o (275): ; amrc: Error = 81704
AbendSyscode = 8
AbendRc = 1704
FdbkRc = 8
Ftncd = 17
Fdbk = 4
svc99_info = 8
svc99_error = 1704
RBA = 0
last_op = 74
o (275): ; amrc: msg=NULL
nvOUT (PROD.AC10131.NAV(QP#SQTXT) 89): select * from doctor
nvRETURN (PROD.AC10131.NAV(QPSYNON) 1140): -1
o: 275 0 flocate >>> stream=997C3F4,key=9C04ED0,key_len=100,options=5
o: 292 2048 fread >>> buffer=9C046C8, size=1, count=2048,stream=997C3F4
o: 275 0 flocate >>> stream=997C024,key=9C04ED0,key_len=4,options=5
o: 292 2048 fread >>> buffer=9C046C8, size=1, count=2048,stream=997C024
o: 586 997EADC fopen >>> filename=TEST.OR5000A.DEF.NOSBB.IMS,mode=rb, typ
e=record, lrecl=8208
o: 275 0 flocate >>> stream=997EADC,key=9C58818,key_len=4,options=3
o: 292 8208 fread >>> buffer=9C591B0, size=1, count=8208,stream=997EADC
o: 424 0 fclose >>> stream=997EADC
<<<<<<<<<<<<<<<<<<<  Execution Strategy Begin <<<<<<<<<<<<<<<<<<<<<<<<<<<<

Original SQL:
select * from doctor

Accessing file 'doctor' from 'ims' Database
Fetch strategy: scan

>>>>>>>>>>>>>>>>>>>> Execution Strategy End >>>>>>>>>>>>>>>>>>>>>>>>>>>>

<IMSDB DP> >>> OPEN_STREAM       DOCTOR
<IMSDB DP> <<< OPEN_STREAM       status=0, stream=1
<IMSDB DP> >>> SEND_RECEIVE DOCTOR   stream=1, keyLen=26, recLen=80
<IMSDB DP> >>>                 lastPCB=-1, cPCBs=1, PCBs=0
<IMSDB DP> >>>                 readahead=282, cSSAs=2
<IMSDB DP> >>>> READ HOSPITAL
<IMSDB DP> >>>>      DOCTOR
DLIPLUG Request:
09C90410 | 00000000C4D6C3E3D6D9404000010000 | ....DOCTOR  ....
09C90420 | 0000000000000000000000000000FF00 | ................
09C90430 | 0000001A000000500000000000000000 | .......&........
09C90440 | 0000000000000000000000000000011A | ................
09C90450 | 02000000000000000000000000000000 | ................
09C90460 | 000000000000001A0000000000000000 | ................
09C90470 | 00000000000000000000000000000000 | ................
09C90480 | 0000C8D6E2D7C9E3C1D3000000000000 | ..HOSPITAL......
09C90490 | 0000C4D6C3E3D6D94040000000000000 | ..DOCTOR  ......
09C904A0 | 0000                             | ..

CTDLI(2,GU  ,HOSPITAL ,DOCTOR   )

GU  , DBD(HOSPDBD ), Segment(DOCTOR  ), SSA1(HOSPITAL ), SSA2(DOCTOR   ),
Buffer(Jane Doe            Behind the fireplace          392-600359Urology
), Status(  ), RC(0), KFB(Spalding
Rehabilitat2 017 )
CTDLI(2,GN  ,HOSPITAL ,DOCTOR   )

GN  , DBD(HOSPDBD ), Segment(DOCTOR  ), SSA1(HOSPITAL ), SSA2(DOCTOR   ),
Buffer(Miki Mouse          Next to fireplace             424-337760Trauma & o
), Status(  ), RC(0), KFB(Swedish Medical
1 041 )
CTDLI(2,GN  ,HOSPITAL ,DOCTOR   )

GN  , DBD(HOSPDBD ), Segment(DOCTOR  ), SSA1(HOSPITAL ), SSA2(DOCTOR   ),
Buffer(Yetti Bigfoot       Next to fireplace             392-693961Ear, nose
), Status(  ), RC(0), KFB(Presbyterian/St.
Luke1 059 )
CTDLI(2,GN  ,HOSPITAL ,DOCTOR   )

GN  , DBD(HOSPDBD ), Segment(DOCTOR  ), SSA1(HOSPITAL ), SSA2(DOCTOR   ),
Buffer(Blonde Genius       Next to fireplace             723-135562Ophthalmol
), Status(  ), RC(0), KFB(Presbyterian/St.
Luke2 060 )
CTDLI(2,GN  ,HOSPITAL ,DOCTOR   )

GN  , DBD(HOSPDBD ), Segment(DOCTOR  ), SSA1(HOSPITAL ), SSA2(DOCTOR   ),
Buffer(Gamma Tester        Next to fireplace             974-800964Oral surge
), Status(  ), RC(0), KFB(Good Samaritan
1 061 )
CTDLI(2,GN  ,HOSPITAL ,DOCTOR   )

GN  , DBD(HOSPDBD ), Segment(DOCTOR  ), SSA1(HOSPITAL ), SSA2(DOCTOR   ),
Buffer(Dr. Verter          Next to fireplace             297-497895Restorativ
), Status(  ), RC(0), KFB(West Hills
Hospital 1 062 )
CTDLI(2,GN  ,HOSPITAL ,DOCTOR   )

GN  , DBD(HOSPDBD ), Segment(DOCTOR  ), SSA1(HOSPITAL ), SSA2(DOCTOR   ),
Buffer(Art                 Next to fireplace             594-056510Paediatric
), Status(  ), RC(0), KFB(Los Gatos
Surgical  1 064 )
CTDLI(2,GN  ,HOSPITAL ,DOCTOR   )

GN  , DBD(HOSPDBD ), Segment(DOCTOR  ), SSA1(HOSPITAL ), SSA2(DOCTOR   ),
Buffer(Joe Canabis         Next to fireplace             24-3377605Orthodonti
), Status(  ), RC(0), KFB(Los Robles
Regional 1 095 )
CTDLI(2,GN  ,HOSPITAL ,DOCTOR   )

GN  , DBD(HOSPDBD ), Segment(DOCTOR  ), SSA1(HOSPITAL ), SSA2(DOCTOR   ),
Buffer(Yoske Black         Next to fireplace             92-6939616Neurosurge
), Status(  ), RC(0), KFB(Los Robles
Regional 1 100 )
CTDLI(2,GN  ,HOSPITAL ,DOCTOR   )

GN  , DBD(HOSPDBD ), Segment(        ), SSA1(HOSPITAL ), SSA2(DOCTOR   ),
Buffer(
), Status(GB), RC(51138), KFB()
DLIPLUG Response:
09C97960 | 40400000000000000000000900000001 |   ..............
09C97970 | 00000000D181958540C4968540404040 | ....Jane Doe
09C97980 | 4040404040404040C2858889958440A3 |         Behind t
09C97990 | 88854086899985979381838540404040 | he fireplace
09C979A0 | 404040404040F3F9F260F6F0F0F3F5F9 |       392-600359
09C979B0 | E49996939687A8404040404040404040 | Urology
09C979C0 | 40404040E29781938489958740D98588 |     Spalding Reh
09C979D0 | 8182899389A381A3F240F0F1F740D489 | abilitat2 017 Mi
09C979E0 | 928940D496A4A2854040404040404040 | ki Mouse
09C979F0 | 4040D585A7A340A39640868999859793 |   Next to firepl
09C97A00 | 81838540404040404040404040404040 | ace
09C97A10 | F4F2F460F3F3F7F7F6F0E39981A49481 | 424-337760Trauma
09C97A20 | 4050409640404040404040404040E2A6 |  & o          Sw
09C97A30 | 858489A28840D4858489838193404040 | edish Medical
09C97A40 | 4040F140F0F4F140E885A3A38940C289 |   1 041 Yetti Bi
09C97A50 | 87869696A340404040404040D585A7A3 | gfoot       Next
09C97A60 | 40A39640868999859793818385404040 |  to fireplace
09C97A70 | 40404040404040404040F3F9F260F6F9 |           392-69
09C97A80 | F3F9F6F1C581996B409596A285404040 | 3961Ear, nose
09C97A90 | 4040404040404040D79985A282A8A385 |         Presbyte
09C97AA0 | 9989819561E2A34BD3A49285F140F0F5 | rian/St.Luke1 05
09C97AB0 | F940C2939695848540C7859589A4A240 | 9 Blonde Genius
09C97AC0 | 404040404040D585A7A340A396408689 |       Next to fi
09C97AD0 | 99859793818385404040404040404040 | replace
09C97AE0 | 40404040F7F2F360F1F3F5F5F6F2D697 |     723-135562Op
09C97AF0 | 88A38881939496934040404040404040 | hthalmol
09C97B00 | 4040D79985A282A8A3859989819561E2 |   Presbyterian/S
09C97B10 | A34BD3A49285F240F0F6F040C7819494 | t.Luke2 060 Gamm
09C97B20 | 8140E385A2A385994040404040404040 | a Tester
09C97B30 | D585A7A340A396408689998597938183 | Next to fireplac
09C97B40 | 8540404040404040404040404040F9F7 | e             97
09C97B50 | F460F8F0F0F9F6F4D699819340A2A499 | 4-800964Oral sur
09C97B60 | 878540404040404040404040C7969684 | ge          Good
09C97B70 | 40E28194819989A38195404040404040 |  Samaritan
09C97B80 | F140F0F6F140C4994B40E58599A38599 | 1 061 Dr. Verter
09C97B90 | 40404040404040404040D585A7A340A3 |           Next t
09C97BA0 | 96408689998597938183854040404040 | o fireplace
09C97BB0 | 4040404040404040F2F9F760F4F9F7F8 |         297-4978
09C97BC0 | F9F5D985A2A3969981A389A540404040 | 95Restorativ
09C97BD0 | 404040404040E685A2A340C8899393A2 |       West Hills
09C97BE0 | 40C896A29789A3819340F140F0F6F240 |  Hospital 1 062
09C97BF0 | C199A340404040404040404040404040 | Art
09C97C00 | 40404040D585A7A340A3964086899985 |     Next to fire
09C97C10 | 97938183854040404040404040404040 | place
09C97C20 | 4040F5F9F460F0F5F6F5F1F0D7818584 |   594-056510Paed
09C97C30 | 8981A399898340404040404040404040 | iatric
09C97C40 | D396A240C781A396A240E2A499878983 | Los Gatos Surgic
09C97C50 | 81934040F140F0F6F440D1968540C381 | al  1 064 Joe Ca
09C97C60 | 95818289A2404040404040404040D585 | nabis         Ne
09C97C70 | A7A340A3964086899985979381838540 | xt to fireplace
09C97C80 | 404040404040404040404040F2F460F3 |             24-3
09C97C90 | F3F7F7F6F0F5D699A38896849695A389 | 377605Orthodonti
09C97CA0 | 40404040404040404040D396A240D996 |           Los Ro
09C97CB0 | 829385A240D98587899695819340F140 | bles Regional 1
09C97CC0 | F0F9F540E896A2928540C29381839240 | 095 Yoske Black
09C97CD0 | 4040404040404040D585A7A340A39640 |         Next to
09C97CE0 | 86899985979381838540404040404040 | fireplace
09C97CF0 | 404040404040F9F260F6F9F3F9F6F1F6 |       92-6939616
09C97D00 | D585A49996A2A4998785404040404040 | Neurosurge
09C97D10 | 40404040D396A240D996829385A240D9 |     Los Robles R
09C97D20 | 8587899695819340F140F1F0F040     | egional 1 100

<IMSDB DP> <<< SEND_RECEIVE DOCTOR   stream=1, status='  ', readahead=9, PCB=0,
flags=1
<IMSDB DP> >>> CLOSE_STREAM    DOCTOR, stream=1
<IMSDB DP> <<< CLOSE_STREAM    0
nvRETURN (PROD.AC10131.NAV(DRVIUNWN) 804): -1210
(Last message occurred 3 times)
Disabled FilePool Cleanup(DB=___sys, FilePool Size=0)

Disabled FilePool Cleanup(DB=IMS, FilePool Size=0)

<IMSDB DP> >>> DISCONNECT
<IMSDB DP> <<< DISCONNECT
o: 393 0 fclose >>> stream=997C3F4
o: 424 0 fclose >>> stream=997C024
o: 424 0 fclose >>> stream=9991834
o: 393 0 fclose >>> stream=997D3AC
o: 424 0 fclose >>> stream=997CFDC
FilePool Shutdown(DB=___SYS, FilePool Size=0)

Closing log file at MON DEC  4 17:57:49 2006

Part IV

Installing and Configuring Oracle Database Gateway for Adabas

Before performing any of the tasks described in this part, you should read Part I, "Getting Started with Oracle Database Gateways" to get an overview of the technology, the architecture, and the process involved in installing and configuring Oracle Database Gateway for Adabas.

To be able to access Adabas data, you need to perform the tasks described in the following list, in the specified order. Each step in the list directs you to the relevant manual or chapter.

By now, you should have completed tasks 1 – 3. This part describes how to perform tasks 4 – 8.

1. Install Oracle Connect for IMS, VSAM, and Adabas Gateways
See Oracle Connect for IMS, VSAM, and Adabas Gateways Installation and Configuration Guide for IBM z/OS for information on installing Oracle Connect for IMS, VSAM, and Adabas Gateways.

2. Install Oracle Studio for IMS, VSAM, and Adabas Gateways
See Chapter 11, "Installing Oracle Studio for IMS, VSAM, and Adabas Gateways" for information on installing Oracle Studio for IMS, VSAM, and Adabas Gateways.

3. Configure Oracle Connect for IMS, VSAM, and Adabas Gateways
See Chapter 13, "Configuring Oracle Connect through Oracle Studio for IMS, VSAM, and Adabas Gateways" for information on configuring Oracle Connect for IMS, VSAM, and Adabas Gateways.

4. Set up the connection to Oracle Connect for IMS, VSAM, and Adabas Gateways
See Chapter 8, "Configuring Access to Adabas Data" for information on setting up the connection to Oracle Connect for IMS, VSAM, and Adabas Gateways.

5. Set up the Adabas data source
See Chapter 8, "Configuring Access to Adabas Data" for information on setting up the Adabas data source.

6. Set up the Adabas metadata
See Chapter 8, "Configuring Access to Adabas Data" for information on setting up the Adabas metadata.

7. Install Oracle Database Gateway for Adabas
See Chapter 9, "Installing Oracle Database Gateway for Adabas" for information on installing Oracle Database Gateway for Adabas.

8. Configure Oracle Database Gateway for Adabas
See Chapter 10, "Configuring Oracle Database Gateway for Adabas" for information on configuring Oracle Database Gateway for Adabas.

Part IV, "Installing and Configuring Oracle Database Gateway for Adabas," describes how to install and configure Oracle Database Gateway for Adabas.

It contains the following chapters:

- Chapter 8, "Configuring Access to Adabas Data"

- Chapter 9, "Installing Oracle Database Gateway for Adabas"

- Chapter 10, "Configuring Oracle Database Gateway for Adabas"

8 Configuring Access to Adabas Data

This chapter explains how to configure access to Adabas data by using Oracle Studio for IMS, VSAM, and Adabas Gateways. It contains the following sections:

- Setting Up Access to a Computer Running Oracle Connect for IMS, VSAM, and Adabas Gateways

- Setting Up an Adabas Data Source

- Setting Up Adabas Data Source Metadata

Setting Up Access to a Computer Running Oracle Connect for IMS, VSAM, and Adabas Gateways

To be able to access Adabas data, you must have a working connection to Oracle Connect for IMS, VSAM, and Adabas Gateways, which is installed on the IBM z/OS computer where your Adabas files are located. You establish this connection by using Oracle Studio for IMS, VSAM, and Adabas Gateways.

Whenever needed, you can also use Oracle Studio for IMS, VSAM, and Adabas Gateways to configure Oracle Connect for IMS, VSAM, and Adabas Gateways.

Note:

The following task assumes that you have permission to access the IBM z/OS platform and that the Oracle Connect for IMS, VSAM, and Adabas Gateways daemon is running on this computer. Check with the system administrator to ensure these requirements are fulfilled.

Perform the following steps to set up access to a computer that runs Oracle Connect for IMS, VSAM, and Adabas Gateways.

1. From the Start menu, select Programs, point to Oracle, and select Studio. Oracle Studio for IMS, VSAM, and Adabas Gateways opens.

2. In the Design perspective's Configuration view, right-click the Machines folder and select Add Machines.
The Add machine screen opens, as shown in Figure 8-1.

Figure 8-1 Add Machine Screen.

Enter the following information in each field:

- Host name/IP address: Enter the name of the computer on the network or click Browse, to browse all the systems running a daemon listener on the specified port currently accessible over the network.

- Port: Enter the port number where the daemon is running. The default port is 2551.

- Display name: Enter an alias used to identify the system when different from the host name (optional).

- User name: Enter the system administrator's user name.

Note:

You indicate the system administrator when the system is installed or by using the NAV_UTIL utility ADD_ADMIN operation. For details, see Oracle Connect for IMS, VSAM, and Adabas Gateways Installation and Configuration Guide for IBM z/OS.

- Password: Enter the system administrator's password. This is the password for the user entered in the User name field. If no password is necessary to access this system, do not enter anything.

- Connect via NAT with fixed IP address: Select this if the system uses the NAT (Network Address Translation) firewall protocol, with a fixed configuration, mapping each external IP to one internal IP, regardless of the port specified.

3. Click Finish.
The computer is displayed in the Configuration view, in the Machine folder. You can edit the system's login information, or configure bindings, daemons, and users for each system.

Setting Up an Adabas Data Source

Oracle Connect for IMS, VSAM, and Adabas Gateways supports the following types of Adabas data sources:

- Adabas (Predict): The Adabas (Predict) data source uses Predict metadata.

- ADD-Adabas: The ADD-Adabas data source uses Oracle's internal repository (ADD), which is usually imported from Natural Data Definition Module (DDM) files. Alternatively, Predict metadata can be exported and subsequently imported into the ADD-Adabas data source.

Both Adabas data sources provide very similar functions. The ADD-Adabas data source enjoys some added flexibility and functions resulting from the ability to customize the metadata in the ADD. Unless explicitly stated, all features and procedures described apply to both data sources.

This section describes how to set up an Adabas data source using Oracle Studio for IMS, VSAM, and Adabas Gateways. It includes the following tasks:

- Define the Adabas Data Source Connection

- Configure the Adabas Data Source Properties

After you defined and configured the data source, proceed to Setting Up Adabas Data Source Metadata.

Define the Adabas Data Source Connection

The Adabas data source connection is set using the Design Perspective's Configuration View in Oracle Studio for IMS, VSAM, and Adabas Gateways. Perform the following steps:

1. Expand the Machines folder.

2. Expand the Bindings folder, and then expand the binding where the data is located.

3. Right-click the Data Source folder and select New Data Source.
The New Data Source screen is displayed, as shown in Figure 8-2.

Figure 8-2 New Data Source Screen

4. In the Name field, enter a name for the new data source.

5. Select one of the following options from the Type list:

- Adabas (Predict): to define an Adabas data source that is to use Predict metadata

- Adabas (ADD): to define an Adabas data source that is to use Oracle metadata

6. Click Next.
The Data Source Connect String screen is displayed.

7. Specify the connect string according to the data source type selected:

- If you are defining an Adabas ADD data source, specify only the Database number.

- If you are defining an Adabas Predict data source, specify the following:

- Database number.

- Predict File Number: The Adabas Predict file number that describes the specified database.

- Predict database number: Specify this field only in case the Predict file does not reside in the same database as the data.

8. Click Finish.

Configure the Adabas Data Source Properties

After defining the connection, you set the data source properties.

The following properties can be configured for the Adabas data source in the Properties tab of the Configuration Properties screen:

- dbNumber: (Predict, ADD) The Adabas database number.

- predictFileNumber: (Predict only) The Predict file number.

- predictDbNumber: (Predict only) In some cases the Predict file is located in a different database than the data. If so, use this attribute to specify the database number in which the Predict file is located.

- svcNumber: (Predict, ADD; MVS only) The installation on MVS places the SVC number of Adabas in the GBLPARMS file. Alternatively, you can specify the SVC number using this attribute. This simplifies configuration in sites where several Adabas installations on different SVC numbers need to be accessed from a single installation. Each SVC will still require a different workspace, but the same GBLPARAMS and the same RACF profile can be used for the different workspaces.

- addMuInPeCounter: (Predict, ADD) Until version 4.6 Oracle Connect for IMS, VSAM, and Adabas Gateways did not support counters for MUs inside of PEs. In version 4.6 this support was added, but since it changes behavior for existing users, this attribute was added to allow existing users to turn off this new feature to preserve compatibility. Default: addMuInPeCounter='true'.

- defaultOccurences: (Predict only) If the Predict occurrences field for multiple value fields or periodic group fields is not specified, the value of this parameter is used. If a record is retrieved with more occurrences than specified, an error is returned. Default: defaultOccurances='10'.

- disableExplicitSelect: (Predict, ADD) This attribute indicates whether or not the Explicit Select option is disabled. If disabled, a select * query on an Adabas table will return all fields in the table, including ISN and subfields that are normally suppressed unless explicitly requested in the query (for example, select ISN, *…). Default: disableExplicitSelect='false'.

- disregardNonselectable: (Predict, ADD) This attribute enables you to configure the data source to ignore descriptors defined on a multiple value (MU) field, a periodic group (PE) field or phonetic/hyper descriptors. The special ACSEARCH fields that are normally created for a table are referred to as "non-selectable" because you cannot specify them in the select list of a query. Setting the disregardNonselectable attribute to 'true' will prevent these fields from being created. Default: disregardNonselectable='false'.

- fileList: (Predict, ADD) This attribute is passed as the record buffer to the OP command. Adabas allows a list of file numbers to be provided in the record buffer of the OP command, along with the operations allowed on each file. By using this attribute, a user can restrict access to the database, allowing only specific operations on specific files. For more information on the allowed syntax, visit the Software AG Documentation Web site at: http://documentation.softwareag.com/default.htm

Note:

Note that the value provided in this attribute is passed "as-is" to Adabas. No validation is performed. The default value grants unrestricted access to all files in the database: fileList='.'

- lockWait: (Predict, ADD) This attribute specifies whether the data source waits for a locked record to become unlocked or returns a message that the record is locked. In Adabas terms, if this attribute is set to true a space is passed in command option 1 of the HI/L4 commands. Otherwise an 'R' is passed in command option 1. Default: lockWait='false'.

- multiDatabasePredict: (Predict only) Turn this flag on if your Predict file includes metadata for several different databases. This has two effects on the way that the Predict information is read:

- Only tables that belong to the current database are returned in the table list.

- The file number for a table is read separate from the metadata as different databases may include the same table using a different file number.

- multifetch: (Predict, ADD) This parameter controls the number of records to be retrieved in a single read command (L2, L3, S1-L1). The value provided in this attribute controls the value passed in the ISN lower limit control block field. By default no multifetch is used. The multifetch buffer size can be controlled as follows:

- multifetch='0': Lets the driver decide the number of records to retrieve. The driver will generally retrieve rows to fill a 10k buffer. No more than 15 rows are fetch at once.

- multifetch='n': Causes n rows to be read at a time, where n is a number from 2 to 15.

- multifetch='-n': Defines a read-ahead buffer with a fixed size, where n is less than or equal to 10000 bytes.

- multifetch='1': Disables the read-ahead feature. (default)

- nullSuppressionMode: (Predict, ADD) This attribute controls the behavior of the Adabas driver with regard to null suppression handling. This attributes allows a user to change this default NULL suppression policy. Note that changing this setting improperly may result in incomplete query results. The following values can be selected:

- full: (default) NULL suppressed fields are exposed as NULLABLE and must be qualified for the Oracle optimizer to consider using a descriptor based on a NULL suppressed field.

- disabled: NULL suppressed fields are handled like any other field. Use this setting only if you completely understand the potential implications as incomplete query results may returned.

- indexesOnly: Only NULL suppressed fields that are part of a descriptor/super-descriptor are exposed as NULLABLE. Other NULL suppressed fields are handled normally. This setting is as safe as the "full" setting and does not include the risk of incomplete results as the "disabled" option does.

- scanUsingL1: (Predict, ADD) A scan strategy on a table is normally implemented by an L2 command. It is possible, however, to turn on this attribute in order to scan using the L1 command. This has the advantage of providing better data consistency at some performance penalty. Default: scanUsingL1='false'.

- supportL3Range: (Predict, ADD) Older versions of Adabas did not allow for a range specification on an L3 command (such as AA,S,AA in the search buffer). Only the lower limit could be provided. If your version of Adabas supports a range in the L3 command you can turn on this attribute to enjoy better performance in some queries. Default: supportL3Range='false'.

- traceValueBuffer: This is a debugging tool to be used in conjunction with driverTrace='true' in the environment. Turning on driverTrace will record the Adabas commands executed in the server log file. If you also want a binary dump of the value buffer and record buffer, set this attribute to true. Default: traceValueBuffer='false'.

- userInfo: (Predict, ADD) This attribute specifies the value passed as a null-terminated string to Adabas as the seventh parameter on the adabas call. The value provided is then available in Adabas user exits. This has no affect at all on Oracle Connect for IMS, VSAM, and Adabas Gateways, but some users have taken advantage of this feature to implement some specific auditing. Note that it is possible to control the value of the userInfo attribute dynamically at run time using the nav_proc:sp_setprop stored procedure. Default: userInfo=''.

- useUnderscore: (Predict, ADD) This attribute indicates whether or not to convert hyphens (-) in table and column names into underscores (_). The inclusion of hyphens in Adabas table names and field names poses an inconvenience when accessing these tables from SQL because names that include a dash need to be surrounded with double quotes. To avoid this inconvenience, the data source can translate all hyphens into underscores. Default: useUnderscore='true'.

- verifyMetadata: (Predict, ADD) This attribute indicates whether or not to cross-check the Predict or ADD metadata against the LF command. Resulting discrepancies are written to the log and removed from the metadata at run time. It is usually unnecessary to use this attribute. Default: verifyMetadata='false'.

Perform the following steps to configure the Adabas data source properties:

1. Right-click the data source and select Edit Data Source.
The Configuration Properties screen is displayed.

2. Select the Properties tab. The configuration properties are displayed.

Figure 8-3 Configuration Properties Screen

3. Configure the data source parameters as required.

4. On the Advanced tab, configure how arrays will be handled by selecting the relevant check boxes in the Virtual View Policy section. The following options are available:

- Generate sequential view: Select this option if you want to map a non-relational file to a single table.

- Generate virtual views: Select this option if you want to have an individual table created for every array in the non-relational file.

- Include row number column: Select this option if you want to include a column that specifies the row number in the virtual or sequential view.

- Inherit all parent columns: Select this option if you want the virtual views to include all the columns of the parent record.

5. Save your settings.

Setting Up Adabas Data Source Metadata

This section includes the following topics:

- Import Oracle Metadata from DDM Files

- Export Predict Metadata into Adabas ADD

Import Oracle Metadata from DDM Files

If the metadata exists in DDM files, you can use the DDM_ADL import utility to import this metadata to Oracle metadata. This utility is available on Windows and UNIX, from the platform's command line interface. This utility is not available on MVS platforms. MVS users need to perform the import on one of the supported platforms and then move the generated metadata to MVS.

The metadata is not imported using Oracle Studio for IMS, VSAM, and Adabas Gateways.

To display online help for this utility, run the following command: DDM_ADL HELP

To generate the ADD metadata, use the appropriate command according to the platform type.

The following table lists the MDD file list format according to platform type.

Table 8-1 DDM File List Format

Platform Type

Format

UNIX

This parameter is at the end of the command. Separate the files in this list with spaces.

Windows

The name of the file containing the list and the names of the files in the list must be less than or equal to eight characters (with a suffix of three characters). Separate the files in this list with commas.

Export Predict Metadata into Adabas ADD

Some users who have Predict still prefer to use ADD to store metadata. The process of moving metadata from Predict to ADD is simple, although manual. It involves exporting from Predict and importing to ADD. The process is carried out using the NAV_UTIL command line interface.

In the procedure below, for the purposes of the example, note first of all that the native qualifier is required. On the export side, the procedure generates all table definitions from a Predict data source called adapredict to an XML file. On the import side, the exported metadata is imported to a data source called adaadd.

Perform the following steps to export Predict metadata into Adabas ADD.

1. To export, execute the following NAV_UTIL command, according to your platform:

- Windows: c:\> nav_util export table -native adapredict * adapredict.xml

- UNIX: $ nav_util export table -native adapredict * adapredict.xml

- MVS (After executing the NAVCMD Rexx script in USERLIB): Local> export table -native adapredict * '<HLQ>.XML.ADAPRED'

2. To import, execute the following NAV_UTIL command, according to your platform:

- Windows: c:\> nav_util import adaadd adapredict.xml

- UNIX: $ nav_util import adaadd adapredict.xml

- MVS (After executing the NAVCMD Rexx script in USERLIB): Local> import adaadd '<HLQ>.XML.ADAPRED'

The script content on this page is for navigation purposes only and does not alter the content in any way.

9 Installing Oracle Database Gateway for Adabas

This chapter guides you through the installation procedure of Oracle Database Gateway for Adabas.

To install the gateway, follow these steps:

1. Ensure that the system meets all of the hardware and software requirements specified in "System Requirements for Oracle Database Gateway for Adabas".

2. Run the Oracle Universal Installer.
See "Running the Oracle Universal Installer" for more information about running the Oracle Universal Installer.

Oracle Universal Installer is a menu-driven utility that guides you through the installation of the gateway by prompting you with action items. The action items and the sequence in which they appear depend on your platform.

3. Configure the gateway.
Chapter 10, "Configuring Oracle Database Gateway for Adabas" provides information on how to configure the gateway.

Overview of Oracle Database Gateway for Adabas

Oracle Database Gateway for Adabas consists of the following components:

- Oracle Studio for IMS, VSAM, and Adabas Gateways, a GUI-based tool that lets you configure the Oracle Servers in your system. Oracle Studio for IMS, VSAM, and Adabas Gateways runs on Windows and Linux platforms.

- Oracle Connect for IMS, VSAM, and Adabas Gateways, which is natively located on the data server to provide standard, service-oriented integration to Adabas data. Oracle Connect for IMS, VSAM, and Adabas Gateways runs on z/OS platforms.

- Oracle Database Gateway, which provides the capabilities, SQL mappings, data type conversions, and interface to the remote non-Oracle system. The gateway interacts with Heterogeneous Services to provide the transparent connectivity between Oracle and non-Oracle systems.
The gateway must be installed on a Windows or UNIX computer. This can be the same system as the Oracle database server or a second, standalone system.

System Requirements for Oracle Database Gateway for Adabas

This section provides information about the hardware and software requirements for the gateway. It contains the following sections:

- Hardware Requirements for Oracle Database Gateway for Adabas

- Software Requirements for Oracle Database Gateway for Adabas

Hardware Requirements for Oracle Database Gateway for Adabas

Table 9-1 lists the hardware requirements for Oracle Database Gateway for Adabas on UNIX.

Table 9-1 Hardware Requirements for Oracle Database Gateway for Adabas

Requirement

IBM AIX

HP-UX 64-bit Itanium (Itanium)

Sun Solaris (SPARC) 64-bit

Linux x86

Linux x86 64-bit

Temporary disk space

700 MBFoot 1

700 MB

700 MB

700 MB

700 MB

Disk space

1.5 GB

1.5 GB

750 MB

750 MB

750 MB

Physical memory

512 MB

512 MB

512 MB

512 MB

512 MB

Swap space

1 GB

1 GB

1 GB

1 GB

1 GB

Processor

IBM RS/6000 AIX-based system processor

HP chipset sx2000 processor for HP-UX 11i v2

Sun Solaris (SPARC) processor

Processor chips that adhere to the x86 32-bit architecture

Processor chips that adhere to the x86 64-bit architecture

Footnote 1 This temporary disk space requirement assumes you download the software. The temporary disk space is less than 300 MB if you install from CD or DVD media.

Software Requirements for Oracle Database Gateway for Adabas

Oracle Database Gateway for Adabas is supported on the UNIX operating systems specified in table Table 9-2.

Table 9-2 Software Requirements for Oracle Database Gateway for Adabas

Operating System

Version

Linux x86 (32-bit)

- Red Hat Enterprise Linux AS/ES 3.0 (Update 4 or later)

- Red Hat Enterprise Linux 4.0

- Enterprise Linux 4.0

Linux x86 64-bit

- Red Hat Enterprise Linux AS/ES 3.0 (Update 4 or later)

- Red Hat Enterprise Linux AS/ES 4.0 (Update 1 or later)

- Enterprise Linux 4.0

Sun Solaris 64-bit

- Solaris 9 (Update 6 or later)

- Solaris 10

HP Itanium 64-bit

- HP-UX 11i v2

- HP-UX 11i v2

IBM AIX 5L 64-bit

Version 5.3, Maintenance Level 02 or later

Gateway Installation Configurations

You can install the gateway in either of the following configurations:

- On the same computer as an existing Oracle database but in a different ORACLE_HOME directory.

- On a system with no Oracle database.

- On the same computer as the Oracle database and in the same ORACLE_HOME directory. Note that in this case, the Oracle database and the gateway must be at the same release level.

Gateway Installation Methods

You can choose different installation methods to install the gateway, as follows:

- Interactive Installation Method

- Automated Installation Method Using Response Files

Interactive Installation Method

When you use the interactive method to install the gateway, Oracle Universal Installer displays a series of screens that enable you to specify all of the required information to install the gateway software.

Automated Installation Method Using Response Files

By creating a response file and specifying this file when you start Oracle Universal Installer, you can automate some or all of the gateway installation steps. These automated installation methods are useful if you need to perform multiple installations on similarly configured systems or if the system where you want to install the software does not have X Window system software installed.

When you use a response file, you can run Oracle Universal Installer in the following modes, depending on whether you specify all of the required information or not:

- Silent Mode: Oracle Universal Installer runs in silent mode if you use a response file that specifies all required information. None of the Oracle Universal Installer screens are displayed.

- Suppressed Mode: Oracle Universal Installer runs in suppressed mode if you do not specify all required information in the response file. Oracle Universal Installer displays only the screens that prompt for the information that you did not specify.

See Appendix A, "Using Response Files for Non-Interactive Installation" for more information about this method and about how to complete an installation using response files.

Gateway Installation Considerations

This section contains information that you should consider before installing this product. It contains the following sections:

- Release Notes

- Hardware and Software Certification

- Multiple ORACLE_HOME Directories

Release Notes

Read the release notes for the product before installing it. The release notes are available on the Oracle Database 11g Release 2 (11.2) installation media. The latest version of the release notes is also available on the Oracle Technology Network (OTN) Web site:

http://www.oracle.com/technology/documentation/index.html

Hardware and Software Certification

The platform-specific hardware and software requirements included in this installation guide were current at the time this guide was published. However, because new platforms and operating system software versions might be certified after this guide is published, review the certification matrix on the OracleMetaLink Web site for the most up-to-date list of certified hardware platforms and operating system versions. The OracleMetaLink Web site is available at the following Web site:

http://metalink.oracle.com

If you do not have a current Oracle Support Services contract, then you can access the same information at the following Web site:

http://www.oracle.com/technology/support/metalink/content.html

Multiple ORACLE_HOME Directories

This product supports multiple ORACLE_HOME directories. This means that you can install this release or previous releases of the software more than once on the same system, in different ORACLE_HOME directories.

Installing the Software on a System with an Existing Oracle Installation

You must install this product in a new ORACLE_HOME directory. You cannot install products from one release of the gateway into an ORACLE_HOME directory of a different release.

Upgrades

Upgrades are not supported for Oracle Database Gateways.

Accessing the Installation Software

You can access and install the gateway by using the following methods:

- Downloading Oracle Software from the Oracle Technology Network Web Site

- Copying the Gateway Software to a Hard Disk

Downloading Oracle Software from the Oracle Technology Network Web Site

This section describes how to download the installation files and extract them on your hard disk. It contains the following topics:

- Downloading the Installation Files

- Extracting the Installation Files

Downloading the Installation Files

To download the installation files from the Oracle Technology Network (OTN):

1. Use any browser to access the software download page on OTN:
http://www.oracle.com/technology/software

2. Navigate to the download page for the product that you want to install.

3. On the download page, identify the required disk space by adding the file sizes for each required file.
The file sizes are listed next to the file names.

4. Select a file system with enough free space to store and expand the archive files.
In most cases, the available disk space must be at least twice the size of each compressed file.

5. On the file system that you selected in step 4, create a parent directory for each product, for example, dg4adbs, to hold the installation directories.

6. Download all of the installation archive files to the directory that you created in step 5.

7. Verify that the files you downloaded are the same size as the corresponding files on OTN.

Extracting the Installation Files

To extract the installation files:

1. If necessary, change directory to the directory that contains the downloaded installation archive files.

2. To extract each file, enter the gunzip command.
For example:

$ gunzip filename.cpio.gz

This command creates files with names similar to the following:

filename.cpio

3. To extract the installation files, enter the cpio command.
For example:

$ cpio -idmv < filename.cpio

Note:

Refer to the download page for information about the correct options to use with the cpio command. Some browsers extract files while downloading them, but leave the .gz file extension. If these steps do not work, remove the .gz extension from the files and repeat step 3.

For each file, this command creates a subdirectory named Diskn, where n is either 1 or the disk number identified in the file name.

Copying the Gateway Software to a Hard Disk

Before installing the gateway, you might want to copy the software to the hard disk. This enables the installation process to run faster. Before copying the installation media content to the hard disk, you must mount the installation media.

Mounting the Installation Media

On most Sun Solaris operating systems, the disc mounts automatically when you insert it into the disc drive. If the disc does not mount automatically, perform the following steps to mount it:

1. Enter the following command to switch user to root:
$ su - root

2. If necessary, enter a command similar to one of the following to eject the currently mounted disc, then remove the disc from the drive:
On Sun Solaris (SPARC):

# eject

On IBM AIX:

# umount /cdrom

On HP-UX Itanium:

# /usr/sbin/umount /SD_CDROM

In these examples, /cdrom and /SD_CDROM are the mount point directories for the disc drive.

3. Insert the appropriate disc into the disc drive.

4. To verify that the disc mounted automatically, enter a command similar to the following, depending on your platform:
Sun Solaris (SPARC):

# ls /cdrom/cdrom0

5. If this command fails to display the contents of the disc, enter a command similar to the following to mount it, depending on your platform:
Sun Solaris (SPARC):

# /usr/sbin/mount -r -F hsfs /dev/dsk/cxtydzs2 /cdrom

In this example, /cdrom is the disc mount point directory and /dev/dsk/cxtydzs2 is the device name for the disc device, for example /dev/dsk/c0t2d0s2.

6. If Oracle Universal Installer displays the Disk Location dialog box, enter the disk mount point directory path, for example:
/mnt/cdrom

Copying the Oracle Database Gateway Software to a Hard Disk

To copy the contents of the disc to a hard disk:

1. Create a directory on the hard disk to hold the Oracle software:
$ mkdir Ora10g

2. Change directory to the directory you created in step 1:
$ cd Ora10g

3. Create subdirectories for each installation disc with names similar to the following, where n is the disc number:
$ mkdir Diskn

4. Copy the contents of the mounted disc to the corresponding new subdirectory as follows:
$ cp -R /directory_path Diskn

In this example, n is the disc number and /directory_path is the installation media mount point directory. The mount point directory is /cdrom.

5. If necessary, mount the next disc and repeat step 4.

Running the Oracle Universal Installer

Start the Installer and install the software, as follows:

1. If you are installing the software from disc, then mount the disc if it is not already mounted.
Some platforms automatically mount discs when you insert them into the drive.

2. If necessary, log in as the Oracle software owner user (oracle) and set the DISPLAY environment variable.

3. To start the Installer, enter the following commands where directory_path is the CD-ROM mount point directory or the path of the dg directory on the DVD-ROM.
directory_path/runInstaller

4. Follow the instruction displayed in the Installer window.

Caution:

The Oracle Universal Installer automatically installs the Oracle-supplied version of the Java Runtime Environment (JRE). This version is required to run Oracle Universal Installer and several Oracle assistants. Do not modify the JRE except by using a patch provided by Oracle Support Services.

Table 9-3 describes the installation procedure for Oracle Database Gateway for Adabas.

Note:

- When the Installer prompts you to run a script with root privileges, enter a command similar to the following in a terminal where you are logged in as the root user, then click Continue or OK:
# /script_path/script_name

- On Tru64 UNIX, when prompted for the JDK home directory, specify the location of JDK 1.4.2 on your system.
To determine the JDK home directory, enter the following command:

# /usr/sbin/setld -i JAVA142 | more

The default location is /usr/opt/java142.

Table 9-3 The Oracle Universal Installer: Steps for Installing the Gateway

Screen

Response

Oracle Universal Installer: Welcome

Click Next.

Oracle Universal Installer: Specify Home Details

The Path field in the Specify Home Details screen is where you specify the destination for your installation. You need not edit the path specification in the Path field. The default setting for this field points to ORACLE_HOME. After you set the fields in the Specify Home Details screen as necessary, click Next to continue. After loading the necessary information from the installation, the Oracle Universal Installer displays the Available Products screen.

Oracle Universal Installer: Available Product Components

Select Oracle Database Gateway for Adabas 11.2.0.

Click Next.

Oracle Database Gateway for Adabas

Oracle Connect for IMS, VSAM, and Adabas Gateways Host Name: Specify the host name of the system running Oracle Connect for IMS, VSAM, and Adabas Gateways on z/OS.

Oracle Connect for IMS, VSAM, and Adabas Gateways Port number: Specify the port number Oracle Connect for IMS, VSAM, and Adabas Gateways listens on.Click Next to continue.

Oracle Universal Installer: Summary

The Installation Summary screen enables you to review a tree list of options and components for this installation.

Click Install to display the Installation Status screen.

Oracle Net Configuration Assistant: Welcome

Click Cancel.

Oracle Net Configuration Assistant:

Click Yes.

Oracle Universal Installer: Configuration Tools

When Oracle Universal Installer confirms that the installation is complete, verify that the installation procedure was successful. To do this, read the contents of the installation log file, which is located in the following directory:

[designated_inventory_location]\OraInventory\logs

The default file name is InstallActionsYYYY-MM-DD_HH-mm-SS-AM/PM.log, where:

YYYY is year

MM is month

DD is day

HH is hour

mm is minute

SS is seconds

AM/PM is daytime or evening

Each of these variables in the log file name represents the date and time the product was installed.

When you finish configuring, click Exit.

Exit

Click Exit.

If you need additional information, click Help.

If you encounter errors while installing or linking the software, then see Appendix B for information about troubleshooting.

10 Configuring Oracle Database Gateway for Adabas

After installing the gateway, perform the following tasks to configure the gateway for Adabas:

- Configuring the Gateway

- Configuring Oracle Net Services Listener for the Gateway

- Configuring the Oracle Database for Gateway Access

- Creating Database Links

- Gateway Password Encryption Tool

- Configuring the Gateway for Multiple Adabas Databases

- Performing Configuration Tasks

- Testing the Adabas Data Source

Configuring the Gateway

Perform the following tasks to configure Oracle Database Gateway for Adabas:

1. Choose a System Identifier for the Gateway

2. Customize the Initialization Parameter File

Choose a System Identifier for the Gateway

Choosing a system identifier is the first task in configuring Oracle Database Gateway for Adabas. The gateway system identifier (SID) is an alphanumeric character string that identifies a gateway instance. If you want to connect simultaneously to different Adabas data sources, you need one gateway instance, and therefore one gateway SID, for each Adabas database you are accessing. The SID name is used as part of the file name for the initialization parameter file. The default SID is dg4adbs.

The HS_FDS_DATASOURCE_NAME parameter takes on the gateway SID as the default value. This means that the data source matches the gateway SID by default. However, you can specify the value of the HS_FDS_DATASOURCE_NAME parameter to match the data source that you want to access. See "HS_FDS_DATASOURCE_NAME" for more information.

If you have one Adabas data source and want to access it sometimes with one set of gateway parameter settings, and other times with different gateway parameter settings, you can do that by defining two different data sources and defining the matching SID s accordingly.

Customize the Initialization Parameter File

Customizing the initialization parameter file is the second task in configuring Oracle Database Gateway for VSAM. The initialization parameter file must be available when the gateway is started. During installation, the following default initialization parameter file is created:

$ORACLE_HOME/dg4adbs/admin/initdg4adbs.ora

Where $ORACLE_HOME is the directory under which the gateway is installed.

The name of the parameter file is init[SID].ora, where SID is the gateway SID. If you are not using dg4adbs as the gateway SID, you must rename the initialization parameter file using the SID you chose in Task 1. This default initialization parameter file is sufficient for starting the gateway, verifying a successful installation, and running the demonstration scripts.

In the initialization parameter file, specify the Adabas connection as follows:

In the initialization parameter file, specify the VSAM connection as follows:

- If you use the default workspace:

HS_FDS_CONNECT_INFO="address:port"

- If you use a workspace other than the default:

HS_FDS_CONNECT_INFO="address='host' port='port' workspace='workspace'"

Where:

- host: The name of the mainframe computer on which Oracle Connect for IMS, VSAM, and Adabas Gateways runs.

- port: The port number to listen to.

- workspace: The Adabas data source workspace name. (optional)

A number of initialization parameters can be used to modify the gateway behavior. You may want to change the initialization parameter file later to meet system requirements.

See Also:

The Oracle Database Heterogeneous Connectivity User's Guide for more information about customizing the initialization parameter file.

Configuring Oracle Net Services Listener for the Gateway

The gateway requires Oracle Net Services to provide transparent data access. After configuring the gateway, configure Oracle Net Services to work with the gateway.

1. Configure Oracle Net Services Oracle Net Listener for the Gateway

2. Stop and Start the Oracle Net Listener for the Gateway

Configure Oracle Net Services Oracle Net Listener for the Gateway

Oracle Net Services uses the Oracle Net Listener to receive incoming connections from a Oracle Net Services client. The Oracle Net Listener and the gateway must reside on the same system.

The Oracle Net Listener listens for incoming requests from the Oracle Database. For the Oracle Net Listener to listen for the gateway, information about the gateway must be added to the Oracle Net Listener configuration file, listener.ora. This file is located in the following directory:

$ORACLE_HOME/network/admin

Note:

If Oracle Net Services is reinstalled, the original listener.ora file is renamed and a new listener.ora file is put into the same directory.

The following entries must be added to the listener.ora file:

- A list of Oracle Net Services addresses on which the Oracle Net Listener listens.

- The gateway that the Oracle Net Listener starts in response to incoming connection requests.

Example of Address to Listen On in listener.ora File

The Oracle Database accesses the gateway using Oracle Net Services and the TCP/IP protocol adapter. The following is the syntax of the connect descriptor entry in the listener.ora file:

LISTENER =
(DESCRIPTION_LIST =
(DESCRIPTION =
(ADDRESS_LIST =
(ADDRESS = (PROTOCOL = IPC)(KEY = EXTPROC))
)
(ADDRESS_LIST =
(ADDRESS = (PROTOCOL = TCP)(HOST = host_name)(PORT = 1552))
)
)
)

Where:

Table 10-1 Parameters for listener.ora File

Variable

Description

host_name

is the name of the system on which the gateway is installed.

port

specifies the port number used by the Oracle Net Listener. If you have other listeners running on host_name, the value of port_number must be different from the other listeners' port numbers.

Example of Gateway to Start in listener.ora File

To direct the Oracle Net Listener to start the gateway in response to incoming connection requests, add an entry to the listener.ora file as follows.

Use the following syntax for Linux platforms:

SID_LIST_LISTENER =
(SID_LIST =
.
.
(SID_DESC=
(SID_NAME=gateway_sid)
(ORACLE_HOME=ORACLE_HOME_directory)
(PROGRAM=dg4adbs)
(ENVS=LD_LIBRARY_PATH=$ORACLE_HOME/lib)
)
)

Where:

Table 10-2 Parameters for listener.ora File

Variable

Description

sid_name

The SID of the gateway and matches the gateway SID specified in the connect descriptor entry in the tnsnames.ora file. The Oracle Net Listener uses the SID name to locate the relevant <sid_name>.ora file.

ORACLE_HOME

The Oracle home directory where the gateway is located.

The following table specifies which ENVS parameter value to use for the different platforms:

Platform

ENVS Parameter Value

Sun Solaris 64-bit

LD_LIBRARY_PATH=$ORACLE_HOME/lib

HP-UX Itanium 64-bit

SHLIB_PATH=$ORACLE_HOME/lib

IBM AIX 64-bit

LIBPATH=$ORACLE_HOME/lib

Linux 32-bit

LD_LIBRARY_PATH=$ORACLE_HOME/lib

Linux 64-bit

LD_LIBRARY_PATH=$ORACLE_HOME/lib

See Also:

Oracle Database Net Services Administrator's Guide for information about changing the listener.ora file.

Stop and Start the Oracle Net Listener for the Gateway

The Oracle Net Listener must be started to initiate the new settings, as follows:

1. Set the PATH environment variable to access the commands in the following directory:

$ORACLE_HOME/bin

If you have the Bourne or Korn Shell, enter the following:

$ PATH=$ORACLE_HOME/bin:$PATH;export PATH
$ LD_LIBRARY_PATH=$ORACLE_HOME/lib:$LD_LIBRARY_PATH; export LD_LIBRARY_PATH

If you have the C Shell, enter the following:

$ setenv PATH $ORACLE_HOME/bin:$PATH
$ setenv LD_LIBRARY_PATH $ORACLE_HOME/lib:$LD_LIBRARY_PATH

where $ORACLE_HOME is the directory where the gateway is installed.

2. If the listener is already running, use the lsnrctl command to stop the listener and then start it with the new settings, as follows:

$ lsnrctl stop
$ lsnrctl start

3. Check the status of the listener with the new settings, as follows:

$ lsnrctl status

The following is an example of output from a lsnrctl status check:

LSNRCTL for SOLARIS: Version 11.2.0 - Production on 01-JUN-2009 09:16:17

Copyright (c) 1991, 2009, Oracle. All rights reserved.

Connecting to (ADDRESS=(PROTOCOL=TCP)(HOST=204.179.99.15)(PORT=11201))
STATUS of the LISTENER
----------------------
Alias                    listener
Version                  TNSLSNR for SOLARIS: Version 11.2.0 - Production
Start Date               31-May-2009 10:16:17
Uptime                   0 days 18 hr. 5 min. 13 sec
Trace Level              off
Security                 OFF
SNMP                     OFF
Listener Parameter File  /users/oracle/gateway/network/admin/listener.ora
Listener Log File        /users/oracle/gateway/network/log/listener.log
Listening Endpoints Summary...
(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=204.179.99.15)(PORT=11201)))
Services Summary...
Service "dg4adbs" has 1 instance(s).
Instance "dg4adbs", status UNKNOWN, has 1 handler(s) for this service...
The command completed successfully

In this example, dg4adbs is the default SID value assigned during installation. You can use any valid ID for the SID, or keep the default.

Note:

You must use the same SID value in the tnsnames.ora file, and the listener.ora file.

Configuring the Oracle Database for Gateway Access

Before you can use the gateway to access Adabas data, you must configure the Oracle Database to enable communication with the gateway over Oracle Net Services.

Perform the following tasks to configure the Oracle Database accordingly:

Configuring Oracle Net Services for the Oracle Database

Configuring Oracle Net Services for the Oracle Database

To configure the server you add connect descriptors to the tnsnames.ora file. You cannot use the Oracle Net Services Assistant or the Oracle Net Services Easy Config tools to configure the tnsnames.ora file. You must edit the file manually.

See Also:

Oracle Database Net Services Administrator's Guide for information about editing the tnsnames.ora file.

For the Oracle Database to access the gateway, it needs a service name entry or a connect descriptor name entry in the tnsnames.ora file to tell the Oracle Database where to make connections.

By default, this file is in $ORACLE_HOME/network/admin, where $ORACLE_HOME is the directory in which the Oracle Database is installed. The tnsnames.ora file is required by the Oracle Database accessing the gateway, but not by the gateway.

Configuring tnsnames.ora

Edit the tnsnames.ora file to add a connect descriptor for the gateway. The following is an example of the Oracle Net Services entries using TCP/IP protocol needed for the Oracle Database to access the gateway:

connect_descriptor=
vsam =
(DESCRIPTION =
(ADDRESS_LIST =
(ADDRESS = (PROTOCOL = TCP)(HOST = host_name)(PORT = port_number))
)
(CONNECT_DATA =
(SID = gateway_sid)
)
(HS = OK)
)

Where:

Table 10-3 Parameters for tnsnames.ora File

Variable

Description

connect_descriptor

The description of the object to connect to as specified when creating the database link, such as dg4adbs.

Check the sqlnet.ora file for the following parameter setting:

names.directory_path = (TNSNAMES)

Note: The sqlnet.ora file is typically stored in $ORACLE_HOME/network/admin.

host_name

Specifies the system where the gateway is running.

port_number

Matches the port number used by the Oracle Net Services Oracle Net Listener that is listening for the gateway. The Oracle Net Listener's port number can be found in the listener.ora file used by the Oracle Net Listener. See "Example of Address to Listen On in listener.ora File".

gateway_sid

Specifies the SID of the gateway and matches the SID specified in the listener.ora file of the Oracle Net Listener that is listening for the gateway. See "Configure Oracle Net Services Oracle Net Listener for the Gateway" for more information.

For example:

connect_descriptor=
Adabas =
(DESCRIPTION =
(ADDRESS_LIST =
(ADDRESS = (PROTOCOL = TCP)(HOST = host_name)(PORT = port_number))
)
(CONNECT_DATA =
(SID = gateway_sid)
)
(HS = OK)
)

Creating Database Links

Any Oracle client connected to the Oracle Database can access Adabas data through the gateway. The Oracle client and the Oracle Database can reside on different systems. The gateway accepts connections only from the Oracle Database.

A connection to the gateway is established through a database link when it is first used in an Oracle session. In this context, a connection refers to the connection between the Oracle Database and the gateway. The connection remains established until the Oracle session ends. Another session or user can access the same database link and get a distinct connection to the gateway and Adabas database.

Database links are active for the duration of a gateway session. If you want to close a database link during a session, you can do so with the ALTER SESSION CLOSE DATABASE LINK dblink statement. The database and application administrators of a distributed database system are responsible for managing the necessary database links that define paths to the Adabas database.

See Also:

Oracle Database Net Services Administrator's Guide and Oracle Database Heterogeneous Connectivity User's Guide for more information about using database links.

Gateway Password Encryption Tool

The gateway uses userids and passwords to access the information in the remote database. Some userids and passwords must be defined in the Gateway Initialization File to handle functions such as resource recovery. In the current security conscious environment, having plain-text passwords that are accessible in the Initialization File is considered insecure. The dg4pwd encryption utility has been added as part of Heterogeneous Services' generic connectivity to help make this more secure. This utility is accessible by this gateway. The initialization parameters that contain sensitive values can be stored in an encrypted form.

See Also:

Oracle Database Heterogeneous Connectivity User's Guide for more information about using this utility.

Configuring the Gateway for Multiple Adabas Databases

The tasks for configuring the gateway to access multiple Adabas databases are similar to the tasks for configuring the gateway for a single database. The configuration example assumes the following:

- The gateway is installed and configured with the default SID of dg4adbs.

- The ORACLE_HOME environment variable is set to the directory where the gateway is installed.

- The gateway is configured for one Adabas database named dg4adbs.

- Two Adabas databases named dg4adbs2 and dg4adbs3 on a server named mvs5 with port number 2551 are added.

Configuring the gateway for additional Adabas databases is similar to configuring it for one database, and involves the following:

- Configuring the gateway.

- Configuring Oracle Net Services for the gateway and the Oracle Database.

Multiple Databases Example: Configuring the Gateway

Choose Two System IDs for Each Adabas Database

A separate instance of the gateway accesses the different Adabas databases. Each instance needs its own gateway System ID (SID). For this example, the gateway SIDs for the instances that access the Adabas databases are named as follows:

- dg4adbs2 for the gateway accessing data source dg4adbs2.

- dg4adbs3 for the gateway accessing data source dg4adbs3.

Create Two Initialization Parameter Files

Create an initialization parameter file for each instance of the gateway by copying the original initialization parameter file twice, naming one with the gateway SID for dg4adbs2 and the other with the gateway SID for dg4adbs3:

$ cd $ORACLE_HOME/dg4adbs/admin
$ cp initdg4adbs.ora initdg4adbs2.ora
$ cp initdg4adbs.ora initdg4adbs3.ora

Change the value of the HS_FDS_CONNECT_INFO parameter in the new files.

For initdg4adbs2.ora, enter the following:

HS_FDS_CONNECT_INFO="mvs5:2551"

For initdg4adbs3.ora, enter the following:

HS_FDS_CONNECT_INFO="mvs5:2551"

Note:

If you have multiple gateway SIDs for the same Adabas database because you want to use different gateway parameter settings at different times, follow the same procedure. You create several initialization parameter files, each with different SIDs and different parameter settings.

Multiple Databases Example: Configuring Oracle Net Services Listener

Add Entries to listener.ora

Add two new entries to the Oracle Net Listener configuration file, listener.ora. You must have an entry for each gateway instance, even when multiple gateway instances access the same database.

The following example shows the entry for the original installed gateway first, followed by the new entries:

SID_LIST_LISTENER=
(SID_LIST=
(SID_DESC=
(SID_NAME=dg4adbs)
(ORACLE_HOME=ORACLE_HOME_directory)
(PROGRAM=dg4adbs)
)
(SID_DESC=
(SID_NAME=dg4adbs2)
(ORACLE_HOME=ORACLE_HOME_directory)
(PROGRAM=dg4adbs)
)
(SID_DESC=
(SID_NAME=dg4adbs3)
(ORACLE_HOME=ORACLE_HOME_directory)
(PROGRAM=dg4adbs)
)
)

Multiple Databases Example: Stopping and Starting the Oracle Net Listener

If the listener is already running, use the lsnrctl command to stop the listener and then start it with the new settings, as follows:

$ lsnrctl stop
$ lsnrctl start

Multiple Databases Example: Configuring the Oracle Database for Gateway Access

This section describes the required procedures to configure the Oracle Database for the gateway access.

Configuring Oracle Net Services on the Oracle Database for Multiple Gateway Instances

Add two connect descriptor entries to the tnsnames.ora file. You must have an entry for each gateway instance, even if the gateway instances access the same database.

The following Adabas example shows the entry for the original installed gateway first, followed by the two entries for the new gateway instances:

old_db_using=(DESCRIPTION=
(ADDRESS=
(PROTOCOL=TCP)
(PORT=1541)
(HOST=gtwhost))
(CONNECT_DATA=
(SID=dg4adbs))
(HS=OK))
new_Adabas2_using=(DESCRIPTION=
(ADDRESS=
(PROTOCOL=TCP)
(PORT=1541)
(HOST=gtwhost))
(CONNECT_DATA=
(SID=dg4adbs2))
(HS=OK))
new_Adabas3_using=(DESCRIPTION=
(ADDRESS=
(PROTOCOL=TCP)
(PORT=1541)
(HOST=gtwhost))
(CONNECT_DATA=
(SID=dg4adbs3))
(HS=OK))

The value for PORT is the TCP/IP port number of the Oracle Net Listener that is listening for the gateway. The number can be found in the listener.ora file used by the Oracle Net Listener. The value for HOST is the name of the system on which the gateway is running. The name also can be found in the listener.ora file used by the Oracle Net Listener.

Multiple Databases Example: Accessing Adabas Data

Enter the following to create a database link for the dg4adbs2 gateway:

SQL> CREATE PUBLIC DATABASE LINK Adabas2 CONNECT TO
2  user2 IDENTIFIED BY password2 USING 'new_Adabas2_using';

Enter the following to create a database link for the dg4adbs3 gateway:

SQL> CREATE PUBLIC DATABASE LINK Adabas3 CONNECT TO
2  user3 IDENTIFIED BY password3 USING 'new_Adabas3_using';

Note:

To encrypt the initialization parameters that would normally be stored in the initialization file in plain text, you must use the dg4pwd utility, as described in Oracle Database Heterogeneous Connectivity User's Guide.

After the database links are established you can query the new Adabas databases, as in the following:

SQL> SELECT * FROM ALL_TABLES@Adabas2;

Or

SQL> SELECT * FROM ALL_TABLES@Adabas3;

Performing Configuration Tasks

You can perform the following configuration tasks:

- Configuring for Global Transactions

- Enabling Automatic Recovery

Configuring for Global Transactions

The gateway supports the following transaction capabilities:

- READ_ONLY

- SINGLE_SITE (default)

See the Oracle Database Heterogeneous Connectivity User's Guide for configuration information.

Enabling Automatic Recovery

For the gateway to recover distributed transactions, a recovery account and password must be set up in the Adabas data source. By default, both the user name of the account and the password are RECOVER. The name of the account can be changed with the gateway initialization parameter HS_FDS_RECOVERY_ACCOUNT. The account password can be changed with the gateway initialization parameter HS_FDS_RECOVERY_PWD.

Note:

Oracle Corporation recommends that you do not use the default value RECOVER for the user name and password. Moreover, storing plain text as user name and password in the initialization file is not a good security policy. There is now a utility called dg4pwd that should be used for encryption. Refer to Chapter 4, "Encrypting Initialization parameters" in Oracle Heterogeneous Connectivity Administration Guide for details.

1. Set up a user account in the Adabas data source. Both the user name and password must be a valid Adabas user name and password.

2. In the initialization parameter file, set the following gateway initialization parameters:

- HS_FDS_RECOVERY_ACCOUNT to the user name of the Adabas user account you set up for recovery.

- HS_FDS_RECOVERY_PWD to the password of the Adabas user account you set up for recovery.

See Also:

"Customize the Initialization Parameter File" for information about editing the initialization parameter file and Appendix B, "Initialization Parameters" for information about the HS_FDS_RECOVERY_ACCOUNT and HS_FDS_RECOVERY_PWD initialization parameters.

Testing the Adabas Data Source

Set the debug environment generalTrace parameter to true to generate entries in the standard log racing the access to Adabas data.

See Also:

Setting Up an Adabas Data Source for information on how to add a data source.

Figure 10-1 Adabas Log Entry Format

Part V

Installing and Working with Oracle Studio for IMS, VSAM, and Adabas Gateways

Before performing any of the tasks described in this part, you should read Part I, "Getting Started with Oracle Database Gateways" to get an overview of the technology, the architecture, and the process involved in installing and configuring a database gateway.

To be able to access legacy data, you need to perform the tasks described in the following list, in the specified order. Each step in the list directs you to the relevant manual or chapter.

By now, you should have completed tasks 1 and 2. This part describes how to perform task 3.

1. Install Oracle Connect for IMS, VSAM, and Adabas Gateways
See Oracle Connect for IMS, VSAM, and Adabas Gateways Installation and Configuration Guide for IBM z/OS for information on installing Oracle Connect for IMS, VSAM, and Adabas Gateways.

2. Install Oracle Studio for IMS, VSAM, and Adabas Gateways
See Chapter 11, "Installing Oracle Studio for IMS, VSAM, and Adabas Gateways" for information on installing Oracle Studio for IMS, VSAM, and Adabas Gateways.

3. Configure Oracle Connect for IMS, VSAM, and Adabas Gateways
See Chapter 13, "Configuring Oracle Connect through Oracle Studio for IMS, VSAM, and Adabas Gateways" for information on configuring Oracle Connect for IMS, VSAM, and Adabas Gateways.

4. Set up the connection to Oracle Connect for IMS, VSAM, and Adabas Gateways
See the relevant topic in any of the following chapters:

- Chapter 2, "Configuring Access to VSAM Data"

- Chapter 5, "Configuring Access to IMS Data"

- Chapter 8, "Configuring Access to Adabas Data"

5. Set up the VSAM, IMS, or Adabas data source
See the relevant topic in any of the following chapters:

- Chapter 2, "Configuring Access to VSAM Data"

- Chapter 5, "Configuring Access to IMS Data"

- Chapter 8, "Configuring Access to Adabas Data"

6. Set up the data source metadata
See the following chapters for additional information:

- Chapter 2, "Configuring Access to VSAM Data"

- Chapter 5, "Configuring Access to IMS Data"

- Chapter 8, "Configuring Access to Adabas Data"

7. Install Oracle Database Gateway for VSAM, IMS, or Adabas
See the following chapters for additional information:

- Chapter 3, "Installing Oracle Database Gateway for VSAM"

- Chapter 6, "Installing Oracle Database Gateway for IMS"

- Chapter 9, "Installing Oracle Database Gateway for Adabas"

8. Configure Oracle Database Gateway for IMS
See the following chapters for additional information:

- Chapter 4, "Configuring Oracle Database Gateway for VSAM"

- Chapter 7, "Configuring Oracle Database Gateway for IMS"

- Chapter 10, "Configuring Oracle Database Gateway for Adabas"

Part V, "Installing Oracle Studio for IMS, VSAM, and Adabas Gateways," describes how to install Oracle Studio for IMS, VSAM, and Adabas Gateways and use it to configure and manage Oracle Connect for IMS, VSAM, and Adabas Gateways.

It contains the following chapters:

- Chapter 11, "Installing Oracle Studio for IMS, VSAM, and Adabas Gateways"

- Chapter 12, "Working with the Oracle Studio for IMS, VSAM, and Adabas Gateways Workbench"

- Chapter 13, "Configuring Oracle Connect through Oracle Studio for IMS, VSAM, and Adabas Gateways"

- Chapter 14, "Managing Security for Oracle Connect for IMS, VSAM, and Adabas Gateways"

11 Installing Oracle Studio for IMS, VSAM, and Adabas Gateways

Oracle Studio for IMS, VSAM, and Adabas Gateways is a GUI tool for managing the life cycle activities of Oracle Connect for IMS, VSAM, and Adabas Gateways installations.

At design time, Oracle Studio for IMS, VSAM, and Adabas Gateways enables you to configure Oracle servers and data sources and to import and edit metadata for data sources. In addition, you can perform tests within Oracle Studio for IMS, VSAM, and Adabas Gateways to verify the configuration.

At run time, Oracle Studio for IMS, VSAM, and Adabas Gateways enables you to monitor and control the Oracle servers.

Oracle Studio for IMS, VSAM, and Adabas Gateways is available on Windows and Linux.

Note:

If you have Oracle Studio for IMS, VSAM, and Adabas Gateways already installed because you are already using a different gateway, then you do not need to reinstall it.
The following database gateways are available:

- Oracle Database Gateway for VSAM

- Oracle Database Gateway for IMS/DB

- Oracle Database Gateway for Adabas

This topic includes the following sections:

- System Requirements for Oracle Studio for IMS, VSAM, and Adabas Gateways

- Installing Oracle Studio for IMS, VSAM, and Adabas Gateways on Linux (SH Installation)

System Requirements for Oracle Studio for IMS, VSAM, and Adabas Gateways

This section provides information about the hardware and software requirements for Oracle Studio for IMS, VSAM, and Adabas Gateways. It contains the following sections:

- Hardware Requirements for Oracle Studio for IMS, VSAM, and Adabas Gateways

- Software Requirements for Oracle Studio for IMS, VSAM, and Adabas Gateways

Hardware Requirements for Oracle Studio for IMS, VSAM, and Adabas Gateways

Table 11-1 lists the system requirements for Oracle Studio for IMS, VSAM, and Adabas Gateways.

Table 11-1 System Requirements for Oracle Studio for IMS, VSAM, and Adabas Gateways

Requirement

Value

Memory

256 MB of RAM

Disk space

100 MB of free disk space

Processor

- For Microsoft Windows: Intel or 100% compatible computer (PC) based on a Pentium processor

- For Linux 32-bit: Intel Pentium-based processor

- For Linux 64-bit: Intel Itanium 2 based 64-bit system

Software Requirements for Oracle Studio for IMS, VSAM, and Adabas Gateways

Oracle Studio for IMS, VSAM, and Adabas Gateways can run on the following operating systems:

- Microsoft Windows NT Server Version 4.0 with SP5 or later

- Microsoft Windows 2000 with SP2 or later

- Microsoft Windows 2003

- Microsoft Windows XP

- Windows Vista

- Windows 2008

- Linux (all versions that support Java version 5.0)

Installing Oracle Studio for IMS, VSAM, and Adabas Gateways on Linux (SH Installation)

Carry out the following steps to install Oracle Studio for IMS, VSAM, and Adabas Gateways:

1. Access the Oracle Studio for IMS, VSAM, and Adabas Gateways for Linux software in the following Gateway installation directory:
/gateways/legacy/Studio/OracleStudio_linux.sh

2. Install into a directory where you have permission.

3. Change the mode to execute mode. Type in:

Chmod +x OracleStudio_linux.sh

4. Enter the following:

./OracleStudio_linux.sh

If you are not installing to the current directory, enter the full path.

12 Working with the Oracle Studio for IMS, VSAM, and Adabas Gateways Workbench

The workbench is a collection of screens. Each screen contains a menu bar, a toolbar, a shortcut bar, and perspectives. A perspective is a visual container for a set of views and content editors. The views are associated with a perspective and are not shared; however, editors are shared across perspectives.

A perspective is like a page within a book. It exists within a screen along with any number of other perspectives and, like a page within a book, only one perspective is visible at any time.

This section contains the following topics:

- Using Workbench Parts

- Setting Oracle Studio for IMS, VSAM, and Adabas Gateways Preferences

Using Workbench Parts

This section contains the following topics:

- Main Screen

- Main Menu Bar

- Working with Views

- Working with Perspectives

Main Screen

The Main Screen shows the main parts in Oracle Studio for IMS, VSAM, and Adabas Gateways:

Figure 12-1 Main Screen

Main Menu Bar

The Workbench main menu bar contains the File, Edit, Navigate, Search, Window, and Help top-level menus.

Figure 12-2 Main Menu Bar

Working with Views

Views support editors and provide alternative presentations as well as ways to navigate the information in the Workbench.

You can change the layout of a perspective by opening and closing views and by docking them in different positions in the Workbench screen. Views can be opened and closed according to your needs. See Customizing Views below.

The Workbench contains the following Views:

- Properties View

- Error Log View

- Metadata View

- Configuration View

Customizing Views

Views can be customized to let you set up a workbench perspective in a way that is comfortable for you. This section describes how:

- To move views into different positions

- To resize a view

- To open and close views

To move views into different positions

Click the tab at the top of a view and drag and drop it to the top, bottom, or sides of the workbench where you want to view it.

When you drag and drop a view, you see an outline for it at the position you dragged it to. The outline provides you with a guide to see where you are moving the view.

You can move to the same position as another view. If two views are in the same place, click the tab at the top of the view you want to see. For example, by default the Metadata and Configuration views are in the same place, at the left of the workspace (in the Design perspective). To change from the Metadata view to the Configuration view, click the Configuration tab.

When you move it to a new position, you can resize it.

To resize a view

1. Place your cursor on the edge of the view you want to resize. The cursor turns into a double-sided arrow.

2. Drag the view until it has the size you want.

Note:

You cannot resize a view from all sides (top, bottom, left, right) The sides that are active for resizing depend on the view's position in the workbench.

To open and close views

1. From the Window menu, click Show View and then select the view you want to open from the submenu.

2. Select the view from the list, or point to Other and select the view from the Show View window.

Properties View

The Properties view shows the properties of a selected object, with its respective attributes.

Figure 12-3 Properties View

Error Log View

The Error Log View shows errors of which you should be aware. The errors are listed by title.

Figure 12-4 Error Log View

The Error Log view lets you perform various tasks.

Configuration View

The Configuration view lets you configure all levels of access to data. Together with the Metadata View, it makes up the Design Perspective.

Figure 12-5 Configuration View

Metadata View

The Metadata View lets you define the metadata for objects. Together with the Configuration View, it makes up the Design Perspective.

Figure 12-6 Metadata View

Working with Perspectives

A perspective defines the initial set and layout of views in the Workbench screen. In the workbench, each perspective shares the same set of editors and each has its own functions. This lets you carry out a specific type of task or works with individual resources. Perspectives control what appears in certain menus and toolbars.

The following perspectives are available:

- Design Perspective

- Runtime Perspective

Design Perspective

Use the Design perspective to define your environment and create the necessary connections between the relevant data sources that contain the data you want to access.

The Design perspective is made up of the Configuration View and the Metadata View.

Runtime Perspective

The Runtime perspective lets you monitor the status of daemons and servers. You can view, print and export reports for each daemon and server, and reload and refresh daemons, servers, and configurations.

Figure 12-7 Runtime Perspective

Selecting a Perspective

You can move between the perspectives in Oracle Studio for IMS, VSAM, and Adabas Gateways using the perspective tool bar on the upper right part of the screen or from the Window menu.

To open a Perspective

Do one of the following:

- From the Window menu, click Open Perspective and select the perspective you want to open.

- Click the Perspective button on the perspective toolbar and select the perspective you want.

Setting Oracle Studio for IMS, VSAM, and Adabas Gateways Preferences

You set preferences for Oracle Studio for IMS, VSAM, and Adabas Gateways from the Window menu. When you open the Preferences screen, a list of categories appears on the left side. You can expand the entries in the tree to find additional subentries where you can set the preferences. The preferences that are important for Oracle Connect for IMS, VSAM, and Adabas Gateways are:

- Studio

- Keys

Studio

Note:

Do not edit any Solution preferences available.

The following tables describe the Studio preferences. The Studio preferences section has two tabs.

Table 12-1 Studio Security Tab

Option

Description

Use Compression

Select this option to compress data used in Oracle Studio for IMS, VSAM, and Adabas Gateways.

Use encrypted communication

Select this option to encrypt communication between Oracle Studio for IMS, VSAM, and Adabas Gateways and servers.

Remember Password

Select this option if you want Oracle Studio for IMS, VSAM, and Adabas Gateways to automatically enter the user's password each time you sign on.

Change Master Password

Click this option to open the Change Master Password screen and change or create a password for using any module in Oracle Connect for IMS, VSAM, and Adabas Gateways.

Figure 12-8 Studio Security Tab

Table 12-2 Studio Advanced Tab

Option

Description

Quick Startup (editors closed)

Select this option to start Oracle Studio for IMS, VSAM, and Adabas Gateways with all editors closed and the Design perspective Configuration views collapsed. In this case, none of the editors left open at the end of the previous session will open when you start a new session. This is the default setting. If you clear this check box, all windows open at the end of the previous session will open when you start a new session and Oracle Studio for IMS, VSAM, and Adabas Gateways will take longer to load.

Show advanced environment parameters

Select this option to display advanced binding environment properties. These properties should only be displayed in coordination with Oracle Support.

Activate JCA tracing

Select this option to implement tracing and logging on the network and communication transport layer. When you select this check box, the following fields are available:

- JCA log level: Select Error, Info, or Debug from the list.

- JCA log file: Enter the location of the JCA log file or click Browse to browse for a location.

Network XML Protocol

Select Text or Binary.

Connection timeout

Enter the amount of time (in seconds) that Oracle Studio for IMS, VSAM, and Adabas Gateways waits for a connection to another system (such as a server) before returning an error message. The default value is 60. In this case, Oracle Studio for IMS, VSAM, and Adabas Gateways waits one minute before returning an error message.

Interaction timeout

Enter the amount of time (in seconds) that Oracle Studio for IMS, VSAM, and Adabas Gateways waits for a connection to a specific interaction (such as a data source) before returning an error message. The default value is 120. In this case, Oracle Studio for IMS, VSAM, and Adabas Gateways waits two minutes before returning an error message.

Figure 12-9 Studio Advanced Tab

Configuration

The following table describes the Configuration preferences

Table 12-3 Configuration Preferences

Option

Description

Enable specifying administration authorization directly in the source XML

Select this option if you want to enter administration authorization information on the system level. It is added to the system's source XML.

Show SYS data source

Select this option to display the SYS data source, including stored procedures and views defined for it in the Design perspective Metadata tab. This option is selected by default.

Figure 12-10 Configuration Preferences

Metadata

The following table describes the Metadata preferences.

Table 12-4 Metadata Preferences

Options

Description

Enable editing source XML

Select this option to allow editing of the source tabs' XML content.

Figure 12-11 Metadata Preferences

Runtime Manager

The following table describes the Runtime Manager preferences.

Table 12-5 Runtime Manager Preferences

Option

Description

Enable periodic machine check

Select this option to set up a system check on a scheduled basis.

If you select this option, enter a time interval in the field below. The time interval is in seconds. For example, if you want a system check every minute, enter 60.

Figure 12-12 Runtime Manager Preferences

Keys

Oracle Studio for IMS, VSAM, and Adabas Gateways has many built-in keyboard shortcuts. You can also customize keyboard shortcuts in Oracle Studio for IMS, VSAM, and Adabas Gateways. The key preferences has two tabs. The View tab shows the list of default shortcuts.

Figure 12-13 Key View Tab

The Modify tab lets you make changes to the current keyboard shortcuts or add new shortcuts. If you want to return to the default settings, click Restore Defaults at the bottom of the screen.

Figure 12-14 Key Modify Tab

Default Keyboard Shortcuts

This following table shows the default shortcuts available in Oracle Studio for IMS, VSAM, and Adabas Gateways.

Table 12-6 Default Keyboard Shortcuts

Command

Key Sequence

Context in which the command is available

Content Assist

Ctrl+Space

In Dialogs and Windows

Context Information

Ctrl+Shift+Space

In Windows

Copy

Ctrl+C

In Dialogs and Windows

Copy

Ctrl+Insert

In Dialogs and Windows

Cut

Ctrl+X

In Dialogs and Windows

Cut

Shift+Delete

In Dialogs and Windows

Delete

Delete

In Windows

Find Next

Ctrl+K

Editing Text

Find Previous

Ctrl+Shift+K

Editing Text

Find and Replace

Ctrl+F

In Windows

Incremental Find

Ctrl+J

Editing Text

Incremental Find Reverse

Ctrl+Shift+J

Editing Text

Paste

Ctrl+V

In Dialogs and Windows

Paste

Shift+Insert

In Dialogs and Windows

Quick Diff Toggle

Ctrl+Shift+Q

Editing Text

Quick Fix

Ctrl+1

In Windows

Redo

Ctrl+Y

In Windows

Select All

Ctrl+A

In Dialogs and Windows

Toggle Insert Mode

Ctrl+Shift+Insert

Editing Text

Undo

Ctrl+Z

In Windows

Word Completion

Alt+/

Editing Text

Close

Ctrl+F4

In Windows

Close

Ctrl+W

In Windows

Close All

Ctrl+Shift+F4

In Windows

Close

All,Ctrl+Shift+W

In Windows

New

Ctrl+N

In Windows

New menu

Alt+Shift+N

In Windows

Print

Ctrl+P

In Windows

Properties

Alt+Enter

In Windows

Refresh

F5

In Windows

Rename

F2

In Windows

Save

Ctrl+S

In Windows

Save All

Ctrl+Shift+S

In Windows

Backward History

Alt+Left

In Windows

Forward History

Alt+Right

In Windows

Go to Line,

Ctrl+L

Editing Text

Last Edit Location

Ctrl+Q

In Windows

Next,Ctrl+.

In Windows

Open Resource

Ctrl+Shift+R

In Windows

Previous,

Ctrl+,

In Windows

Show In menu

Alt+Shift+W

In Windows

Build All

Ctrl+B

In Windows

Open Search Dialog

Ctrl+H

In Windows

Collapse

Ctrl+Numpad_Subtract

Editing Text

Copy Lines

Ctrl+Alt+Down

Editing Text

Delete Line

,Ctrl+D

Editing Text

Delete Next Word

Ctrl+Delete

Editing Text

Delete Previous Word

Ctrl+Backspace

Editing Text

Delete to End of Line

Ctrl+Shift+Delete

Editing Text

Duplicate Lines

Ctrl+Alt+Up

Editing Text

Expand

Ctrl+Numpad_Add

Editing Text

Expand

All,Ctrl+Numpad_Multiply

Editing Text

Insert Line Above Current Line

Ctrl+Shift+Enter

Editing Text

Insert Line Below Current Line

Shift+Enter

Editing Text

Move Lines Down

Alt+Down

Editing Text

Move Lines Up

Alt+Up

Editing Text

Next Word Editing Text

Ctrl+Right

Editing Text

Previous Word

Ctrl+Left

Editing Text

Scroll Line Down

Ctrl+Down

Editing Text

Scroll Line Up

Ctrl+Up

Editing Text

Select Next Word

Ctrl+Shift+Right

Editing Text

Select Previous Word

Ctrl+Shift+Left

Editing Text

To Lower Case

Ctrl+Shift+Y

Editing Text

To Upper Case Editing Text

Ctrl+Shift+X

Editing Text

Toggle Folding

Ctrl+Numpad_Divide

Editing Text

Toggle Overwrite

Insert

Editing Text

Cheat Sheets In Windows

Alt+Shift+Q, H

In Windows

Console In Windows

Alt+Shift+Q, C

In Windows

Search In Windows

Alt+Shift+Q, S

In Windows

Show View (View: Outline) In Windows

Alt+Shift+Q, O

In Windows

Show View (View:)

Alt+Shift+Q, X

In Windows

Activate Editor

F12

In Windows

Maximize Active View or Editor

Ctrl+M

In Windows

Next Editor

Ctrl+F6

In Windows

Next Perspective

Ctrl+F8

In Windows

Next View In Windows

Ctrl+F7

In Windows

Open Editor Drop Down

Ctrl+E

In Windows

Previous Editor

,Ctrl+Shift+F6

In Windows

Previous Perspective In Windows

Ctrl+Shift+F8

In Windows

Previous View In Windows

Ctrl+Shift+F7

In Windows

Show Key Assist In Dialogs and Windows

Ctrl+Shift+L

In Dialogs and Windows

Show Ruler Context Menu

Ctrl+F10

Editing Text

Show System Menu

Alt+-

In Windows

Show View Menu

Ctrl+F10

In Windows

Switch to Editor

Ctrl+Shift+E

In Windows

The script content on this page is for navigation purposes only and does not alter the content in any way.

13 Configuring Oracle Connect through Oracle Studio for IMS, VSAM, and Adabas Gateways

This section describes how to manage and configure Oracle Connect for IMS, VSAM, and Adabas Gateways by using Oracle Studio for IMS, VSAM, and Adabas Gateways. It describes the procedures necessary for smooth data integration at production time.

This section includes the following topics:

- Starting and Stopping Daemons

- Managing Daemon Configurations

- Adding and Editing Workspaces

- Managing Binding Configurations

Starting and Stopping Daemons

This section includes the following topics:

- Starting a Daemon

- Stopping a Daemon

- Checking the Daemon

Starting a Daemon

You start a daemon from a privileged account on the system where the daemon will run. A privileged account is, for example, the super user account on a UNIX platform. If not run from a privileged account, the daemon can start servers only with the same user ID as the account that started it. In this case, the daemon may also have problems validating user name/password pairs within the system.

Use Oracle Studio for IMS, VSAM, and Adabas Gateways to manage all daemon operations, except for starting the daemon. A daemon can only be started through the command line. A daemon cannot be started from within Oracle Studio for IMS, VSAM, and Adabas Gateways.

The daemon startup processes vary according to the type of platform.

Enabling Automatic Startup

The daemon is usually started automatically when the system boots up.

Manually Starting a Daemon on z/OS Platforms

The IBM /s command is used to start the daemon on z/OS platforms.

To start the daemon

1. Ensure the following:

- The NAVROOT.loadaut library is APF authorized. NAVROOT is the high-level qualifier specified during installation.

Note:

To define a DSN as APF authorized, in the SDSF screen, enter the following command, where nav002 is the volume where you installed Oracle Connect for IMS, VSAM, and Adabas Gateways:

/setprog apf,add,dsn=navroot.loadaut,volume=nav002

- NAVROOT.USERLIB(ATTSRVR) and NAVROOT.USERLIB(ATTDAEMN) have been copied to a library within the started tasks path. If they have not been copied, add the NAVROOT.USERLIB library to this path.

2. Activate NAVROOT.USERLIB(ATTDAEMN)as a started task to invoke the daemon.
For example, in the SDSF screen, enter the following:

/s ATTDAEMN

To submit the daemon as a job, uncomment the first two lines of the ATTDAEMN JCL and run the job using the sub command. The ATTDAEMN JCL is similar to the following:

//*ATTDAEMN JOB 'RR','TTT',MSGLEVEL=(1,1),CLASS=A,
//*MSGCLASS=A,NOTIFY=&SYSUID,REGION=8M
//STEP1 EXEC PGM=IRPCD,
// PARM='-B START ''NAVROOT.DEF.IRPCDINI'''
//STEPLIB DD DSN=NAVROOT.LOADAUT,DISP=SHR
//SYSPRINT DD SYSOUT=A
//GBLPARMS DD DSN=NAVROOT.DEF.GBLPARMS,DISP=SHR
// EXEC PGM=IRPCD,COND=((1,EQ,STEP1),(2,EQ,STEP1)),
// PARM='-KATTDAEMN START ''NAVROOT.DEF.IRPCDINI'''
//STEPLIB DD DSN=NAVROOT.LOADAUT,DISP=SHR
//SYSPRINT DD SYSOUT=A
//GBLPARMS DD DSN=NAVROOT.DEF.GBLPARMS,DISP=SHR
//SYSDUMP DD DUMMY

Note:

You can also run ATTDAEMN by submitting the job, without making any changes to the JCL.

Starting Multiple Daemons

You can start more than one daemon on the same system by specifying a different port number for each daemon. This option is useful, for example, when you want different users to access data on the same system using different daemon configurations.

Each daemon started must have its own configuration, which is specified when starting the daemon. In addition, the workspaces in all the configurations must be unique, so that there is no conflict between configurations and workspaces.

If you use different startup scripts in the daemon configuration settings, specify a profile of started tasks for each startup script in the security manager.

Stopping a Daemon

You can shut down the daemon on any system with Oracle Studio for IMS, VSAM, and Adabas Gateways or from the command line.

Shutting Down a Daemon Using Oracle Studio for IMS, VSAM, and Adabas Gateways

You can shut down the daemon on any system defined in Oracle Studio for IMS, VSAM, and Adabas Gateways from within the Runtime Manager perspective.

To shut down the daemon using Oracle Studio for IMS, VSAM, and Adabas Gateways

In the Runtime explorer, right-click the daemon you want to shut down and select Shutdown Daemon.

Shutting Down a Daemon Using the Command Line

You can shut down the system locally through the command line.

To shut down the daemon using the command line

On z/OS platforms, enter the appropriate command line as follows:

NAVROOT.USERLIB(IRPCDCMD)

Enter shutdown [abort[why]] at the prompt or enter a control command:

S/P ATTDAEMN or /F ATTDAEMN,STOP

Shutting down the daemon does not immediately terminate active servers. To terminate active servers, add the NVSHKILL parameter, with a value of 1, to the NAVROOT.DEF.GBLPARMS dataset (where NAVROOT is the high-level qualifier where Oracle Server is installed).

where

- abort: If non-zero, the daemon shuts down regardless of any outstanding activity or active clients.

- why: The reason for the shutdown, which is written to the log file.

Disabling a Workspace

You can disable a workspace, so that although it is defined for a daemon it is not operable. Server processes are not started through this workspace and a client requesting this workspace receives an error.

To disable a workspace using Oracle Studio for IMS, VSAM, and Adabas Gateways

In the Design perspective Configuration view, right-click the workspace to be disabled and select Disable.

Checking the Daemon

Check the daemon on any system defined in Oracle Studio for IMS, VSAM, and Adabas Gateways, from within the Runtime Manager perspective.

To check the status of a daemon using Oracle Studio for IMS, VSAM, and Adabas Gateways

In the Runtime explorer, right-click the server to be checked and select Status. The Runtime Explorer displays the daemon activity.

To check the status of a daemon using the command line

On z/OS platforms, enter the appropriate command line as follows:

NAVROOT.USERLIB(NAVCMD)

Enter CHECK IRPCD (daemon_location [, username, password]) at the prompt.

where

- daemon_location: The host name with an optional port number (specified after a colon)

- username, password: Used for logging onto the daemon.

For example, if you check a system named proc.acme.com, the following is returned if the daemon is active:

Checking IRPCD on host 'prod.acme.com'
Trying anonymous login - OK
This test took 0.500 seconds.

The following is displayed if the daemon is not active:

Checking IRPCD on host 'prod.acme.com'
Trying anonymous login - FAILED, [C043]
Failed to connect to host prod.acme.com:
PC: Connect failed - Connection refused.
This test took 1.042 seconds.

Managing Daemon Configurations

Use Oracle Studio for IMS, VSAM, and Adabas Gateways to manage daemon configurations. The daemon can be initially configured from the Design perspective Configuration view. After initial setup, it is recommended that you make changes to the daemon configuration after monitoring it in the Runtime Manager perspective.

The Runtime Manager perspective enables managing and monitoring daemon activity. Open the Runtime Manager perspective by right-clicking a system in the Design perspective Configuration view and selecting Open Runtime Perspective. Alternatively, from the Window menu, point to Open a Perspective and select Runtime Manager.

Daemon Configuration Groups

You can have a number of daemon configurations on any system.

The daemon configuration is divided into the following groups:

- Daemon Control: Specifies the server details, including daemon failure recovery, maximum request file size, default language, and time out parameters.

- Daemon Logging: Specifies the logging details, such as the log file format and location, and the parameters to log and trace (as opposed to server logging, which is performed in the Workspace section).

- Daemon Security: Specifies the administrative privileges and access for the daemon.

- Daemon Workspaces: The workspaces defined for the daemon. A daemon can include a number of workspaces. A workspace defines the server processes and environment that are used for the communication between the client and the server system for the duration of the client request. Each workspace has its own definition and includes the data sources and applications that can be accessed as well as various environment variables.
The workspace definition is divided into the following groups:

- WS Info: Specifies general information including the server type, the command procedure used to start the workspace, the binding configuration associated with this workspace (which dictates the data sources and applications that can be accessed), and the timeout parameters.

- WS Server: Specifies workspace server information including features that control the operation of the servers started up by the workspace and allocated to clients.

- WS Logging: Specifies workspace tracing options.

- WS Security: Specifies administration privileges, user access, ports available for access to the workspace and workspace account specifications.

- WS Governing: Specifies the way queries are executed. This is used particularly when running queries against large tables.

Note:

The default daemon configuration supplied with Oracle Connect for IMS, VSAM, and Adabas Gateways includes the default Navigator Workspace. This workspace is automatically used if a workspace is not specified.

Adding and Editing Daemon Configurations

The daemon is configured in the Design perspective Configuration view in Oracle Studio for IMS, VSAM, and Adabas Gateways.

A system can have a number of daemons running at the same time, each on its own port.

Configuring Logging

You can set up logging for the following:

- Daemon log files

- Workspace server process log files

Adding and Editing Workspaces

Daemons include workspaces that define the server processes and environment that are used for the communication between the client and the server system for the duration of the client request. A workspace definition is set in the Oracle Studio for IMS, VSAM, and Adabas Gateways Design perspective Configuration view, under the daemon that manages it.

Adding a Workspace

When you define a new workspace, you can copy the values of an existing workspace on the same daemon or have Oracle Connect for IMS, VSAM, and Adabas Gateways set its default values.

To add a new workspace

1. In Oracle Studio for IMS, VSAM, and Adabas Gateways Design Perspective Configuration view, expand the Machine folder and then expand the system with the daemon where you want to add the workspace.

2. Expand the daemon folder.

3. Right-click the daemon where you want to add the workspace and select New Workspace.

Figure 13-1 New Daemon Workspace

Note:

You can add a new daemon configuration in offline design mode, in a design system and later drag-and-drop the daemon configuration to this system.

4. In the New Daemon Workspace screen, enter the following:

- Name: The name used to identify the workspace. The workspace name is made up of letters, digits, underscores (_) or hyphens (-)

Note:

On HP NonStop or mainframe computers, limit the name of a workspace to five characters so that the system environment file, workspaceDEF, does not exceed eight characters. Workspace names greater than five characters are truncated to five character and the default workspace, Navigator, will look for a system environment called NavigDEF.

- Description: A short description of the workspace.

5. From the Workspace data section, select one of the following:

- Create empty workspace with default values

- Copy properties from another workspace
If you copy the properties from another workspace, the fields below the selection become active. You must indicate the workspace from where you want to copy the properties. Enter the following information:

<name of the workspace> in <name of the daemon where the workspace is located> on <name of machine where the daemon is located>.

Alternatively, you can click the browse button to select the workspace you want to use. The above information is added automatically.

6. Click Next to open the select scenario screen. In this screen you select the type of applications the daemon works with. Select from the following options:

- Application server using connection pooling.

- Stand-alone applications that connect and disconnect frequently.

- Applications that require long connections, such as reporting programs and bulk extractors.

- Custom (configure manually). If you select this option, the Workspace editor opens.

7. Click Next to open the next screen. In this screen, select one of the following. The options available depend on the scenario selected:

- The minimum number of server instances available at any time: This is the minimum number of connections that are available at any time. If the number of available connections drops below this number, the system will create new connections. (Available if you select Stand-alone applications that connect and disconnect frequently).

- The maximum number of server instances available at any time: This is the maximum number of connections that are available at any time. If the number of connections used reaches this number, no additional server connections can be made. (Available if you select Stand-alone applications that connect and disconnect frequently).

- The average number of expected concurrent connections: This lets the system know how much the average load will be and helps to distribute the resources correctly. (Available if you select Application server using connection pooling. or Stand-alone applications that connect and disconnect frequently).

- The maximum number of connections: This is the maximum number of connections that will be available. If the number of requests exceeds this number, an error message is displayed that informs the user to try again when a connection becomes available. (Available if you select Application server using connection pooling. or Stand-alone applications that connect and disconnect frequently).

- How many connections you want to run concurrently. This sets the number of connections that will run at the same time. (Available if you select Applications that require long connections, such as reporting programs and bulk extractors).

8. Click Next to open the next screen and enter the amount of wait time for the following parameters. If your system is not too overloaded, you can leave the default times.

- How long to wait for a new connection: Enter the amount of time (in seconds) to wait for a connection to be established before the system times out. For example if you want a wait time of one minute enter 60 (the default). If you enter 0, the time is unlimited.

- How long to wait for a response that is usually fast: Enter the time (in seconds) to wait for a response from the system before the system times out. For example if you want to wait for one minute, enter 60. The default is 0, which indicates unlimited wait time.

9. Click Next to open the next screen. Enter the workspace security information in this screen. You can determine which users or groups can access the workspace you are defining. See Chapter 14, "Managing Security for Oracle Connect for IMS, VSAM, and Adabas Gateways" for more information.

10. Click Next to open the summary screen. Look at the summary to be sure that all the information entered is correct. If you need to make any changes, click Back to get to the required screen.

11. Click Finish to close the wizard and add the new workspace to the Configuration view.

Editing a Workspace

After you add a workspace, you can make changes to the workspace's configuration. You can edit the information in the following workspace editor tabs:

- WS Info: Specifies general information including the server type, the command procedure used to start the workspace, the binding configuration associated with this workspace (which dictates the data sources and applications that can be accessed) and the timeout parameters.

- WS Server: Contains the workspace server information including features that control the operation of the servers started up by the workspace and allocated to clients.

- WS Logging: Contains the information about workspace tracing options.

- WS Security: Contains administration privileges, user access, ports available for access to the workspace and workspace account specifications.

- WS Governing: Contains information about how queries are executed. This is often used when running queries on large tables.

To edit a workspace

1. In the Design Perspective Configuration view, expand the Machines folder and then expand the system where you want to edit the workspace.

2. Expand the daemon folder.

3. Expand the daemon with the workspace you want to edit.

4. Right-click the workspace you want to edit and select one of the following:

- Workspace Setup Wizard: Opens the wizard that was used to add a new workspace (see Adding a Workspace). Make any required changes to the wizard settings to change the workspace definition.

- Edit Workspace: Opens the editor. The editor includes the information that was entered in the New Workspace wizard. Click the following tabs to edit the information:

- WS Info

- WS Server

- WS Logging

- WS Security

- WS Governing

Note:

The default daemon configuration supplied with Oracle Connect for IMS, VSAM, and Adabas Gateways includes the default Navigator Workspace. This workspace is automatically used if no workspace is selected.

WS Info

You enter information about the features that control the workspace operations in the WS Info tab. This information includes the server type, the command procedure used to start the workspace and the binding configuration associated with this workspace.

The following figure shows the WS Info tab:

Figure 13-2 WS Info Tab

Note:

You can also change daemon settings using the Configuration view, by selecting a computer and scrolling the list to the required daemon. Right-click the daemon and select Edit Daemon.
Changes made to the daemon configuration do not take effect immediately. They will take effect only after the configuration is reloaded using the Reload Configuration option in the Runtime Manager.

The following table shows the WS Info tab's fields:

Table 13-1 WS Info Tab

Field

Description

Workspace name

The name used to identify the workspace.

Note: The default configuration includes the default Navigator workspace. This workspace is automatically used if a workspace is not specified as part of the connection settings.

Description

A description of the workspace.

Startup script

The full path name of the script that starts the workspace server processes. The script specified here must always activate the nav_login procedure and then run the server program (svc). If you do not specify the directory, the startup procedure is taken from the directory where the daemon resides. Oracle Connect for IMS, VSAM, and Adabas Gateways includes a default startup script, which is recommended. Enter the script name only because the server is activated as a started task.

Server type

The workspace server type. For example, IMS, Java, events, or native.

Workspace binding name

The name of a specific binding configuration on the server system that you want to use with this workspace.

For z/OS, the name of the binding must be five characters or less and the name must be surrounded by single quotes.

If the high-level qualifier is not specified here, INSTROOT.DEF is assumed, where INSTROOT is the high-level qualifier specified when Oracle Connect for IMS, VSAM, and Adabas Gateways server is installed.

Workspace database name

Enter a name of a virtual database that this workspace accesses if applicable. A virtual database presents a limited view of the available data because only selected tables from either one or more data sources are available, as if from a single data source. If a value is entered in this field, only the virtual database can be accessed using this workspace.

Timeout parameters

The following two properties define the time the client waits for the workspace server to start. If the workspace server does not start within this period, then the client is notified that the server did not respond. Entering a timeout value for these properties overrides the default setting entered in the Daemon Control tab.

Client idle timeout

The maximum amount of time a workspace client can be idle before the connection with the server is closed.

Connect timeout

The time the client waits for a workspace server to start. If the workspace server does not start within this period, then the client is notified that the server did not respond.

WS Server

You enter the features that control the operation of the servers started up by the workspace and allocated to clients in the WS Server tab. For example, you can configure the workspace to use connection pooling and to start up a number of servers for future use, prior to any client request, instead of starting each server when a request is received from a client.

Figure 13-3 WS Server Tab

Notes:

- You can also change daemon settings using the Configuration view, by selecting a computer and scrolling the list to the required daemon. Right-click the daemon and select Edit Daemon.

- Changes made to the daemon configuration do not take effect immediately. They will take effect only after the configuration is reloaded using the Reload Configuration option in the Runtime Manager.

The following table shows the WS Server tab's fields:

Table 13-2 WS Server Tab

Field

Description

Workspace server mode

Specifies the type of new server processes that the daemon starts up. The daemon supports the following server modes:

- singleClient: Each client receives a dedicated server process. The account in which a server process runs is determined either by the client login information or by the specific server workspace.
This mode enables servers to run under a particular user account and isolates clients from each other, as each receives its own process. However, this server mode incurs a high overhead due to process startup times and can use a lot of server resources as it requires as many server processes as concurrent clients.

- multiClient: Clients share a server process and are processed serially. This mode has low overhead because the server processes are already initialized. However, because clients share the same process, they can impact one another, especially if they issue lengthy queries. The number of clients that share a process is determined by the Clients per server limit field.

- multiThreaded (Windows only): Clients are allocated a dedicated thread in a shared server process.
This mode has low overhead since the servers are already initialized. However, because clients share the same process, they may impact one another, especially if the underlying database is not multi-threaded.

The number of multi-threaded clients that share a process is set in the Clients per server limit field (the maximum number of concurrent clients a server process for the current workspace accepts) in the Oracle Studio for IMS, VSAM, and Adabas Gateways Design perspective configuration tab. This value is set in the daemon configuration settings maxNClientsPerServer parameter.

Notes:

Multiple multi-client and multi-threaded servers can be started at the same time for optimal performance.

- reusable: An extension of single-client mode. Once the client processing finishes, the server process does not die and can be used by another client, reducing startup times and application startup overhead.
This mode does not have the high overhead of single-client mode because the servers are already initialized. However, this server mode can use a lot of server resources as it requires as many server processes as concurrent clients.

The other modes can be set so that the server processes are reusable. The number of times a process can be reused is controlled by the Reuse limit field value in Oracle Studio for IMS, VSAM, and Adabas Gateways (the maximum number of times a server process can be reused or how many clients it can serve before it finishes). Reuse of servers enhances performance since it eliminates the need to repeat initializations. However, reuse runs a risk or using more memory over time. The default for the Reuse Limit field value is 0, which means that there is no limit.

Reuse limit

Sets the maximum number of times a particular server can be reused. A one-client server can be reused after its (single) client has disconnected. Reuse of servers enhances startup performance because it avoids the need to repeat initialization.

- Select none, if the server reuse is unlimited

- Select maximum, and then enter a maximum number of clients accepted in a server process.

This parameter is not available if the server mode value is singleClient.

Clients per server limit

Sets the maximum number of clients that a server process for the current workspace accepts. The default for this field is None, indicating that the number of clients for each server is unlimited. This field is available if the server mode value is multiClient or multiThreaded.

Server availability

Specifies the number of servers in a pool of servers, available to be assigned to a client.

The following options are available:

- Initial number of servers: The number of server processes that are prestarted for this workspace when the daemon starts up. When the number of available server processes drops lower than the value specified in the Minimum number field, the daemon again starts server processes until this number of available server processes is reached. The default for this field is 0.

- Minimum number of available servers: The minimum number of server processes in the prestarted pool before the daemon resumes creating new server processes (to the value specified in the Initial number of servers field). If this field is set to a value higher than the Initial number of servers field, the daemon uses the value specified in the Initial number of servers field. The default for this field is 0.

- Keep when daemon ends: Select this to kill all servers started by that daemon when a daemon is shutdown, even if they are active. Select this if you want the servers for the workspace to remain active, even after the daemon has been shut down. If selected, it is the responsibility of the system operator or manager to ensure that the servers are eventually killed. This must be done at the system level.

- Set maximum number of servers: The maximum number of available server processes. Once this number is reached, no new nonactive server processes are created for the particular workspace. For example, if a number of server processes are released at the same time, so that there are more available server processes than specified by this field, the additional server processes higher than this value are terminated. The default for this field is zero, meaning that there is no maximum.

Resource limitations

Lets you set the number of servers that can be in use at any one time. The more servers used, the greater the system resources that are used.

Number of sub-tasks: Set the maximum number of active server processes (either available or in use). Once reached, no new server processes will be created for the particular workspace and client connections will be rejected if there is no available server to accept them. Once the number of active servers drops below the maximum (for example, a client disconnects from a server and the server terminates), new servers can again be started. If the value of this field is set to a value other than zero, and is lower than the value for the Initial number of servers field, the daemon assumes it is set to the same value as the Initial number of servers field. The default for this field is 0, meaning that no maximum is enforced.

Limit number of active servers: Select this if you want to limit the number of active servers.

Server Priority

The priority for servers. For example, a workspace for applications with online transaction processing can be assigned a higher priority than a workspace that requires only query processing.

The following priority options are available:

- Use default priority: Sets the priority as 0. There is no specific priority for this workspace.

- Use priority specified: Enables setting the priority.

WS Logging

Use this tab to configure the Logging preferences for the workspace. The following figure shows the WS Logging tab:

Figure 13-4 The WS Logging Tab

Notes:

- You can also change daemon settings using the Configuration view, by selecting a computer and scrolling the list to the required daemon. Right-click the daemon and select Edit Daemon.

- Changes made to the daemon configuration do not take effect immediately. They will take effect only after the configuration is reloaded using the Reload Configuration option in the Runtime Manager.

- For z/OS, the default is to write the log entries to the job only

The following table describes the fields in the WS Logging tab:

Table 13-3 WS Logging Tab

Field

Description

Specific log file format

Select this to define the name and location of the server log file if you want the data written to a file instead of SYSOUT for the server process. The parameter must specify the name and the high level qualifier.

You can enter the following wildcards in this field to generate the following information:

- %A: workspace name

- %D: date (yymmdd)

- %I: instance number of the given workspace server

- %L: server account's login directory

- %P: server's process ID

- %T: time (hhmmss)

- %U: server's account name (username)

Trace options

Specifies the type of tracing. The following tracing options are available:

- No timeout: Select this to disable the standard RPC timeouts, setting them to a long duration (approximately an hour) to facilitate debugging.

- Call trace: Select this to generate a message in the server log file for each RPC function called. This is useful for troubleshooting the server.

- RPC trace: Select this to enable debugging messages on the server.

- Sockets: Select this to generate a message in the server log file for each socket operation. This is useful for troubleshooting client/server communication by providing a detailed trace of every client/server communication.

- Extended RPC trace: Select this to generate a more detailed message in the server log file for each low-level RPC function called. This is useful for troubleshooting the server.

- System trace: Select this to generate operating system-specific tracing.

- Timing: Select this to generate a timestamp for every entry to the server log file.

Event Information

This section is divided into the following categories.

Logging

Specifies the level of events that are logged for the workspace. The following event levels are available:

- none: Select this to only display the IP addresses of client that have logged in and out from the workspace.

- error: Select this to display the IP addresses for clients that have logged in and out from the workspace and any generated errors.

- debug: Select this to display the IP addresses for clients that have logged in and out from the workspace, any generated errors, and all trace results that were specified in the Daemon Logging tab.

Server

Specifies the server connection events to log. The following server events are available:

- Connect: Select this to display the server connection events.

- Disconnect: Select this to display the server disconnect events.

Client

Specifies the type of tracing performed. The following client events are available:

- Connect: Select this to display the client connection events.

- Disconnect: Select this to display the client disconnect events.

WS Security

Configure the security level for a workspace in the Workpace editor WS Logging tab. This lets you set the security options for the workspace only. See Appendix 14, "Managing Security for Oracle Connect for IMS, VSAM, and Adabas Gateways" for more information. The WS Security section is used:

- To grant administration rights for the workspace

- To determine access to the workspace by a client

The following figure shows the WS Security Tab:

Figure 13-5 WS Security Tab

The following table describes the fields in this tab:

Table 13-4 WS Security Tab

Field

Description

Workspace access:

The following fields define the users (accounts) allowed to access the workspace, firewall access ports, workspace account, and anonymous login permissions.

Workspace users

Indicate which users are allowed to use the workspace. Select one of the following

- All users: Any user who has logged on to the daemon may use the workspace

- Selected users only: Select this to allow only users (or accounts) with specific permission to use the workspace.
When this is selected, add the names of users (or accounts) and groups that can use the workspace in the field below.

To define a group of users on z/OS platforms, preface the name of the group in the configuration with '@'. The group name is validated by a security system such as RACF.

Note: If no user is specified, any user who has logged on to the daemon may use the workspace.

Enable port range

Select this to define specific firewall ports through which you access the workspace. Specifies the range of ports available for this workspace when starting server processes. Use this option when you want to control the port number, so that Oracle Connect for IMS, VSAM, and Adabas Gateways can be accessed through a firewall.

If this is selected, enter the port range in the following fields:

- To port: Enter the highest numbered port in the range

- From port: Enter the lowest numbered port in the range

Use specific workspace account

Select this if you want to define the operating system account used for the workspace.

If selected, enter the name of the workspace account in the workspace account field.

If not selected, the account name that was provided by the client is used.

Allow anonymous client login to server account

Select this if you want to allow this workspace to be invoked without authentication.

If selected, enter the name of the workspace account in the workspace account field.

If this field is not selected, then the value in the Workspace account field is used.

Administration:

The following fields define the users (accounts) allowed to perform administrative tasks (tasks that require administrative login) on this workspace.

Administrator privileges

Identifies the users (accounts) with administrator privileges. Select one of the following:

- All users: Indicates that anyone can access the workspace and change the settings.

- Selected users only: Select this to allow only users (or accounts) with specific permission to be administrators.
When this is selected, add the names of users (or accounts) and groups that can be workspace administrators.

If no user is specified, any user who has logged on to the daemon may administrator this workspace.

Allow Listing

Select this if you want this workspace to appear in the list of workspaces.

WS Governing

The WS Governing tab lets you manage the way queries are executed for the workspace.

Query governing parameters are defined at the workspace levels. All restrictions that are configured apply to all queries for all data sources that require Oracle Connect for IMS, VSAM, and Adabas Gateways metadata and which are defined in the binding associated with the workspace.

The workspace governing parameters only apply to data sources that require Oracle Connect for IMS, VSAM, and Adabas Gateways metadata.

The following figure shows the WS Governing tab:

Figure 13-6 WS Governing Tab

The following table describes the WS Governing tab's fields:

Table 13-5 WS Governing Tab

Field

Description

Max Number of Row in a Table That Can Be Read

Enter the maximum number of table rows that are read in a query. When the number of rows read from a table exceeds the number stated, the query returns an error.

Max Number of Rows Allowed in a Table Before Scan is Rejected

Enter the maximum number of table rows that can be scanned. This parameter has different behavior for query optimization and execution.

- For query optimization, the value set is compared to the table cardinality. If the cardinality is greater than the value, the scan strategy is ignored as a possible strategy (unless it is the only available strategy).

- For query execution, a scan is limited to the value set. When the number of rows scanned exceeds the number entered, the query returns an error.

Managing Binding Configurations

The information needed by Oracle for accessing applications, data sources and events is defined in a binding configuration.

A binding configuration always exists on a server system, where data sources and applications to be accessed using Oracle reside. Additionally, a binding configuration can be defined on a client system to point to data sources on a server system.

Server Binding

A binding configuration on a server includes:

- Data source definitions for data sources that can be accessed using Oracle Connect for IMS, VSAM, and Adabas Gateways, including data source specific properties.

- Data source shortcuts to data sources on other server systems and other server systems that can be accessed from the current system.

- Event queue definitions for event queues that are managed using Oracle Connect for IMS, VSAM, and Adabas Gateways, including event specific properties.

Client Binding

A binding configuration on a client includes:

- Data source shortcuts to data sources on other server systems and other server systems that can be accessed from the current system.

- You can create a new binding configuration or modify existing binding settings using the Oracle Studio for IMS, VSAM, and Adabas Gateways Design perspective Configuration view.
NAV is the default binding configuration. You can use this configuration to define all the data sources you want to access through Oracle Connect for IMS, VSAM, and Adabas Gateways.

Binding Syntax

The binding settings in XML format include the following statements:

- A <remoteMachines>statement, specifying the remote systems that can be accessed, through <remoteMachine> statements.

- <remoteMachine> statements, defining the remote systems available from the current system.

- A <datasources> statement, specifying the data sources that can be accessed, through <datasource>> statements.

- <datasource> statements, specifying the following for each data source the client can access: a name to identify the data source, the type of the data source and general information.

- <config> statements, specifying specific properties for a data source driver.

<remoteMachines> Statement

The <remoteMachines> statement lists the names of the accessible servers, through <remoteMachine> statements. These statements are only necessary when connecting to data sources through a shortcut on the client system.

<remoteMachine> Statement

The <remoteMachine> statement lists names and IP addresses of the remote systems where data sources reside and which are accessed using data source shortcuts on the current system. The names are used as aliases for the IP addresses in the <datasource> statements. This enables you to redefine the location of a group of data sources (on a given system) by changing the IP address associated with this alias. The format is:

<remoteMachine name="alias" address="address"
port="port_number"
workspace="workspace"
encryptionProtocol="RC4|DES3"
firewallProtocol="none|nat|fixednat"/>

where:

name: The name of the remote system that will be recognized by Oracle Connect for IMS, VSAM, and Adabas Gateways. The maximum length is 32 characters and must start with a character. This name cannot be the name of a data source specified in a <datasources> statement.

Note:

The name does not need to relate to the name of the system on the network.

address: The IP address type of the remote system.

port: The port on the remote system where the Oracle Connect for IMS, VSAM, and Adabas Gateways daemon is running. If you do not specify a port number, the system allocates the default Oracle-uda-server port number 2551.

workspace: The specific working configuration specified for this binding by the daemon. A workspace must be defined in the daemon configuration on the remote system.

encryptionProtocol: The protocol used to encrypt network communications. Oracle Connect for IMS, VSAM, and Adabas Gateways currently supports the RC4 and DES3 protocols.

firewallProtocol: The firewall protocol used. Valid values are none, nat or fixednat. The default is none. NAT (Network Address Translation) is a firewall protocol where internal IP addresses are hidden, enabling a network to use one set of IP addresses for internal traffic and a second set of addresses for external traffic. NAT makes all necessary IP address translations. However, using NAT requires every access by every client to go through the daemon port, even after a specific server process has been assigned to handle the client. Specifying fixednat for this parameter sets Oracle Connect for IMS, VSAM, and Adabas Gateways to access this remote system through a firewall using NAT with a fixed IP address. When the server address is returned to the client and the client sees that the IP is not the same IP of the daemon, it ignores the IP and uses the daemon's IP instead. It is recommended to use fixednat to access data through a firewall.

Example <remoteMachines> Statement

Example 13-1 <remoteMachines> Statement

<remoteMachines>
<remoteMachine name="ALPHA_ACME_COM"
address="alpha.acme.com" />
<remoteMachine name="SUN_ACME_COM"
address="sun.acme.com
port="8888" workspace="PROD" />
</remoteMachines>

<datasources> Statement

Lists the accessible data sources, through <datasource> statements.

<datasource> Statement

A <datasource> statement specifies the name and type of the data source and information required in order to connect to the data source.

The basic format is:

<datasource name="name" type="type" attribute="value">  <config .../></datasource>

where:

name: The name of the data source that will be recognized by Oracle Connect for IMS, VSAM, and Adabas Gateways. The maximum length is 32 characters. The name cannot include hyphens (“-”). It can include underscores (“_”). This name cannot be the name of a system specified in a <remoteMachines> statement.

type: The type of the data source to be accessed. This value is different for each data source driver. Refer to a specific data source driver for the value of this parameter. The value of this field when defining a data source shortcut (where the data source is located on another system) is REMOTE.

attribute: General data source attributes, such as specifying the data as read only. These attributes are set in Oracle Studio for IMS, VSAM, and Adabas Gateways in the data source advanced tab.

Table 13–6 describes additional attributes of the <datasource> statement.

When the value of an attribute can be true or false, if the value is not specified, the attribute is equivalent to a value of false. The following table describes the attribute behavior when the value is set to true.

Table 13-6 Data Source Statement Table

Data Source Advanced Tab in Oracle Studio for IMS, VSAM, and Adabas Gateways

Attribute

Description of Value

Transaction type

transactionType="trnLevelSupport|datasourceDefault"

The transaction level (0PC or 2PC) that is applied to this data source, irrelevant of what level the data source supports. The default is the data source default level, ("datasourceDefault").

Syntax name

For more details about this field, see Using the Oracle Connect for IMS, VSAM, and Adabas Gatewayst Syntax File (NAV.SYN).

syntaxName="value"

A section name in the NAV.SYN file specifying SQL syntax variations. The default syntax file contains the following predefined sections:

Oracle driver and Oracle case-sensitive data:syntaxName="ORACLE8_SYNTAX"Or, syntaxName="ORACLE_SYNTAX"

For case sensitive table and column names in Oracle, use quotes (") to delimit the names. Specify the case sensitivity precisely.

Default table owner

owner="value"

The name of the table owner that is used if an owner is not specified as part of the SQL.

Read/Write Information

readOnly="true|false"

true: Specifies read-only mode. All update and data definition language (DDL) operations are blocked.

Repository Information

Repository directory

objectStoreDir="value"

Specifies where the repository for a specific data source is located.

Repository Information

Repository name

objectStoreName="value"

Specifies the name of a repository for a specific data source. The name is defined as a data source in the binding configuration with a type of Virtual and is used to store Oracle Connect for IMS, VSAM, and Adabas Gateways views and stored procedures specific to the data source, when this is wanted in preference to the default SYS data.

Example 13-2 <datasources> Statement

<datasources name="NAV">
<datasource name="ADABAS" type="ADABAS">
<config dbNumber="3" predictFileNumber="7"/>
<datasource name="ORACLE8" type="ORACLE8">
<config oracleConnect="@ora9201_ibm4"/>
</datasource>
<datasource name="DISAM" type="ADD-DISAM">
<config newFileLocation="/users/nav/dis"/>
</datasource>
</datasources>

<config> Statement

A <config> statement specifies configuration properties of a data source. The configuration information is specific to each data source.

The basic format is:

<datasource name="name" type="type">
<config attribute="value" attribute="value"
... />
</datasource>

where:

attribute: The name of the configuration property.

value: The value of the configuration property.

Example 13-3 <config> Statement

<datasources>
<datasource name="ORACLE8" type="ORACLE8">
<config oracleConnect="@ora9201_ibm4"/>
</datasource>
</datasources>

Sample Binding

The following is an example of binding information:

<?xml version="1.0" encoding="ISO-8859-1"?>
<navobj version="...">
<bindings>
<binding name="NAV">
<remoteMachines>
<remoteMachine name="SUN_ACME_COM"
address="sun.acme.com"
workspace="PROD"/>
</remoteMachines>
<environment name="NAV">
<debug generalTrace="true"/>
<misc/>
<queryProcessor/>
<optimizer goal="none" preferredSite="server"/>
<transactions/>
<odbc/>
<oledb/>
<tuning/>
</environment>
<datasources name="NAV">
<datasource name="NAVDEMO" type="ADD-DISAM">
<config newFileLocation="$NAVDEMO"/>
</datasource>
<datasource name="ORA_EXT" type="ORACLE8"
connect="@ora8_ntdb"/>
<datasource name="ORA" type="remote"
connect="sun_acme_com"/>
</datasources>
</binding>
</bindings>
</navobj>

This binding configuration provides information for the NAVDEMO sample data source and for a local data source (an ORA_EXT Oracle database), and one remote data source.

Note:

The XML representation of the binding configuration is displayed in the Oracle Studio for IMS, VSAM, and Adabas Gateways Design perspective Configuration view, by editing the specific binding configuration and viewing the Source tab.

Environment Properties

Each binding configuration includes its own environment, specified in the environment properties.

To display environment properties for the binding configuration in Oracle Studio for IMS, VSAM, and Adabas Gateways, right-click the binding configuration and select Edit Binding.

The environment properties are listed on the Properties tab.

The following table lists the environment propertiesFoot 1  in their respective categories.

Table 13-7 Environment Properties

Category

Parameter Name

Default Value

Description

comm

comCacheBufferSize

200000 bytes

The size of a memory buffer on a client, which is used by the Oracle Connect for IMS, VSAM, and Adabas Gateways client/server to store read-ahead data.

comMaxSocketSize

-1

The maximum bytes that can be written in one chunk on a socket. The default value indicates no limitation.

conmMaxXmlInMemory

65535 bytes

The maximum size of an XML document held in memory.

conmMaxXmlSize

65535 bytes

The maximum size of an XML document passed to another system.

commXmlTransportBufferSize

-1

The maximum size of the internal communications buffer. The default value (-1) indicates there is no size limit.

sockReceiveWindowSize

This parameter affects the communication sockets created by Oracle Connect for IMS, VSAM, and Adabas Gateways. It is intended for use for fine-tuning Oracle Connect for IMS, VSAM, and Adabas Gateways network performance. For further details, see TCP/IP documentation.

sockSendWindowSize

This parameter affects the communication sockets created by Oracle Connect for IMS, VSAM, and Adabas Gateways. It is intended for use for fine-tuning Oracle Connect for IMS, VSAM, and Adabas Gateways network performance. For further details, see TCP/IP documentation.

sockTcpMaxSegmentSize

This parameter affects the communication sockets created by Oracle Connect for IMS, VSAM, and Adabas Gateways. It is intended for use for fine-tuning Oracle Connect for IMS, VSAM, and Adabas Gateways network performance. For further details, see TCP/IP documentation.

sockTypeOfService

default

This parameter affects the communication sockets created by Oracle Connect for IMS, VSAM, and Adabas Gateways. It is intended for use for fine-tuning Oracle Connect for IMS, VSAM, and Adabas Gateways network performance. For further details, see TCP/IP documentation.

Supported service types are:

- default

- lowDelay

- throughput

- reliability

- lowCost

debug

acxTrace

false

When set to true, specifies that the input XML sent to the data source and the output XML returned by the data source, are written to the log file.

adminTrace

analyzerQueryPlan

false

When set to true, specifies that the Query Optimizer plan is written to a plan file for analysis using the Oracle Connect for IMS, VSAM, and Adabas Gateways Query Analyzer.

apiTrace

binaryXmlLogLevel

none

Sets the binary XML log level. This parameter is used for troubleshooting.

The following logging levels are available:

- none

- api

- info

- debug

bindingTrace

consoleTrace

debugCriticalSections

debugLibraryLoad

driverTrace

fileTrace

gdbTrace

false

When set to true, logs the transactions of the driver created using the Oracle Connect for IMS, VSAM, and Adabas Gateways SDK.

generalTrace

false

When set to true, logs the general trace information used by Oracle Connect for IMS, VSAM, and Adabas Gateways. The default writes only error messages to the log.

Note: Changing the default setting can degrade Oracle Connect for IMS, VSAM, and Adabas Gateways performance.

ignoreEnv

invokeDebugger

keepTempFiles

logFile

The full path and filename of the log file for messages. The default log file (NAV.LOG) is located in the TMP directory under the directory where Oracle Connect for IMS, VSAM, and Adabas Gateways Server is installed.

To send log messages to the console, instead of a file, set logFile to a minus, "-", character.

The following types of message are written to the log:

- Error messages.

- Trace information about the query optimization strategy (when genralTrace is set to true).

z/OS: The default Oracle Connect for IMS, VSAM, and Adabas Gateways log file is NAVROOT.DEF.NAVLOG, where NAVROOT is the high-level qualifier specified when Oracle Connect for IMS, VSAM, and Adabas Gateways Server is installed.

memoryLogFile

memoryReport

memoryTrace

nosTrace

oledbTrace

false

When set to true, logs the trace information used when working with OLE DB providers.

The default writes only error messages to the log.

Note: Changing the default setting can degrade Oracle Connect for IMS, VSAM, and Adabas Gateways performance.

optimizerTrace

false

When set to true, trace information and information about the query optimizer strategy is written to the log file.

queryWarnings

false

When set to true, generates a log file of Query Processor warnings.

shellTrace

sortTrace

spyTrace

threadTrace

timeTrace

false

When set to true, adds a timestamp on each event row in the log.

traceDir

The directory where Oracle Connect for IMS, VSAM, and Adabas Gateways writes the log generated by the optimizer files (with a PLN extension). The optimizer files include details of the optimization strategy used by Oracle Connect for IMS, VSAM, and Adabas Gateways. By default, these files are written to the same directory as the log file (see logFile, above).

transactionTrace

false

When set to true, logs 2PC and XA transactions-related events.

triggerTrace

false

When set to true, logs trigger information. This parameter is used when working with triggers.

miscellaneous

arrayMetadataModel

virtualArray Views

Specifies the environment array metadata model. Changing this parameter has no effect.

basedDate

basedDateNullability

codepage

For use with National Language Support (NLS) to identify the charset for the workspace.

If the charset parameter is blank and a language is specified, a default charset is used, based on the language specified and the system. For details of these defaults, refer to language, below.

For information on the supported charsets, see any of the following:

- Oracle Database Gateway for Adabas User's Guide

- Oracle Database Gateway for IMS User's Guide

- Oracle Database Gateway for VSAM User's Guide

compressObjectStore

false

Enables compressing objects in the repository that take up more than 2K storage. The default value is false (compression is not performed) for all bindings.

cvtLevelSeverity

0

The data type conversion policy when a conversion error occurs. The following policies are available:

- 0: The data in the output column will be a null or empty value.

- 1: The data in the output column will be a null or empty value and the error is reported to the log.

- 2: An error is reported and processing stops.

edit

The text editor for use by the NAV_UTIL EDIT command. The default is the native text editor for the operating system.

exposeXmlField

false

When set to true, data returned for a query is displayed as XML, representing the true structure of the result. This is especially useful when querying a data source table that contains arrays or variants.

generateUniqueIndexNames

false

Enables to expose non relational index names. When set to true, all the non relational indexes names are exposed as table_name_KEYkey_number.

language

English

For use with National Language Support (NLS) to identify the application language.

For information on the supported language codes, see any of the following:

- Oracle Database Gateway for Adabas User's Guide

- Oracle Database Gateway for IMS User's Guide

- Oracle Database Gateway for VSAM User's Guide

nlsString

false

Specifies the charset used by a field whose data type is defined as "nlsString". You use this for a field whose charset is other than that of the system's charset. This parameter includes the following values:

- The name of the charset.

- Whether the character set reads from right to left (as in middle-eastern character sets).

For example, the following specifies a Japanese EUC 16-bit charset:

<misc nlsString="JA16EUC,false"/>

readV3Definition

true

This parameter is used when upgrading Oracle Connect for IMS, VSAM, and Adabas Gateways from version 3.xx

replaceInvalidXmlCharacters

false

Replaces invalid XML characters with a '?'. It is used for diagnostic and troubleshooting purposes.

tempDir

The directory where temporary files are written, including the temporary files created for use by hash joins and for sorting files. The default is the current directory.

The following is recommended for this parameter:

1. Specify a directory that contains temporary files only. You can then easily remove these files if necessary (for example, if the process stopped in the middle).

2. Specify a directory on a disk that has a significant amount of free disk space.

xmlDateFormat

ISO

Sets the XML date format used. Options include:

- ISO: The date format is: YY-MM-DDThh:mm:ss[.ss..]

- ODBC: The date format is: YYYY-MM-DD HH:MM:SS[.NNN...]

xmlFieldName

XML

The name used in a query to indicate that the data is returned as XML, instead of the keyword XML. The parameter is effective only after the exposeXmlField parameter, described above, is set.

xmlTrimCharColumns

true

Enables padded spaces to be trimmed from XML string columns when the record format of is fixed. The default attribute value for this property is true, meaning that padded spaces are trimmed for fixed size char columns.

year2000Policy

5

Determines how 2-digit years are converted into 4-digit years. Two policies are provided:

- Fixed Base Year: year2000Policy is set to a value greater than, or equal to 1900. In this case, the value of year2000Policy is the first 4-digit year after 1900 that can be represented by a 2-digit year. For example, if year2000Policy is set to 1905, the years 2000->2004 will be represented by 00->04. All other 2 digits will map to 19xx.

- Sliding Base Year: year2000Policy is set to a positive value less than 100. In this case, the value of year2000Policy represents the number of years ahead of the current year that can be represented by a 2-digit number. With each passing year the earliest year that can be represented by a 2-digit number changes to a year later.
When the parameter is not set, or when it is set to a value outside the range of values defined for the above policies, a default value of 5 and the Sliding Base Year policy is used.

generateUniqueIndexNames

Generates a unique name for every index on a table that is defined in a non-relational system. The default value for this property is false. When set to true, the names of all indexes on non-relational tables are exposed in the following format: table_name_KEYkey_number. For example, if a table is called X, the name of the first index would be X_KEY0.

reducedSequentialFlattening

false

Specifies whether the sequentially flattened table returns a row that lists only the parent record, without the values of the child array columns. When set to true, the sequentially flattened table does not return this row.

reducedVirtualViews

true

Specifies whether the virtual view returns a row that lists only the parent record, without the values of the child array columns. When set to false, the virtual view does return this row.

odbc

enableAsyncExecuting

Enables asynchronous execution.

forceQualifyTables

The catalog and table name are reported together as a single string (as DS:table_name).

maxActiveConnections

0

The maximum number of connections that an ODBC or OLE DB application can make through Oracle Connect for IMS, VSAM, and Adabas Gateways. The default indicates that the maximum is not set.

The greater the number of connections possible, the faster the application can run. However, other applications will run slower and each connection is counted as a license, restricting the total number of users who can access data through Oracle Connect for IMS, VSAM, and Adabas Gateways concurrently. This is particularly the case when using MS Access as a front-end, since MS Access allocates more than one connection whenever possible.

maxActiveStatements

0

The value returned for the InfoType of the ODBC SQLGetInfo API. The default (0) specifies that there is no limit on the number of active statements.

oledb

maxHRows

100

When using OLE DB, the maximum number of hrows (row handles) that can reside in memory at one time.

optimizer

avoidScan

false

When set to true, the optimizer does not choose the scan strategy if it can use some other strategy. If only a scan strategy is available, then it is used.

encourageLookupChache

false

goal

none

The optimization policy used. The following policies are available:

- none: All row optimization is used.

- first: First row optimization is performed based on the assumption that the results produced by the query are used as the rows are retrieved. The query optimizer uses a strategy that retrieves the first rows as fast as possible, which may result in a slower overall time to retrieve all the rows.

- all: Optimization is performed based on the assumption that the results produced by the query are used after all the rows have been retrieved. The query optimizer uses a strategy that retrieves all the rows as fast as possible, which may result in a slower time to retrieve the first few rows.

Note: Aggregate queries automatically use all row optimization, regardless of the value of this parameter.

noCacheWithoutIndex

false

noFlattner

false

noHashJoin

false

When set to true, disables hash join optimization. When hash joins are enabled, a significant amount of disk space is required (see hashMaxDiskSpace). Therefore, if the system does not have available disk space, disable hash join optimization.

noIndexCache

false

noLojDelegation

noLookupCache

false

noMultiIndex

false

noPassthru

false

noSemiJoin

false

When set to true, disables semi-join optimization.

noSubqueryCache

false

noTdpUnion

false

preferredSite

server

The system you want to process the query. Normally the query is processed as close to the data source as possible (either using the query processing of the data source, or if this is not available, the Query Processor on the same system as the data source). If a situation arises in which it is more efficient to process the query on the client system (for example, when the remote system is heavily overloaded), you can tune Oracle Connect for IMS, VSAM, and Adabas Gateways to process all or part of the query locally.

The extent that performance is improved by processing all or some of the query locally can be determined only on a trial and error basis. Consider the following points when processing the query locally:

- Increased communication costs.

- Decreased server workload.

Before adjusting this parameter, check the log to see if other tuning is more appropriate. The options are:

- server (the default): The query is processed on the server.

- nearServer: The query is processed mostly on the server with parts of the query processed on the client (determined by the specific query).

- nearClient: The query is processed mostly on the client with parts of the query processed on the server (determined by the specific query).

- client: The query is processed on the client.

semiJoinInValuesFactor

10

The number of parameters a semi-join strategy sends to an RDBMS.

traceFull

false

traceGroups

false

useRecursiveLojOptimization

true

queryProcessor

compileAfterLoad

true

When set to true, sets Query Processor to always compile an Oracle Connect for IMS, VSAM, and Adabas Gateways procedure or view after it is read.

firstTreeExtensions

150 KB

The maximum size allowed for an SQL query after compilation.

ignoreSegmentBindfailure

false

Determines how Oracle Connect for IMS, VSAM, and Adabas Gateways responds when the execution of one of the segments of a segmented data source fails:

- true: Logs a message and continues execution.

- false: Logs a message and stops execution.

maxColumnsInParsing

500

The maximum number of columns that a query references.

maxSegmentedDbThreads

3

Specifies the maximum number of open threads, when working with segmented databases.

maxSqlCache

3

The maximum number of SQL queries stored in cache memory.

minNumberOfParametersAllocated

30

Specifies the minimum number of parameters that can be used in a query.

noCommandReuse

false

When set to true, sets the query processor not to cache for reuse the executed state of a query.

noCompilationCache

false

When set to true, sets the Query Processor not to save a successfully compiled statement in the cache.

noDSPropertyCache

false

When set to true, sets the Query Processor not to cache data source properties.

noInsertParameterization

false

When set to true, sets the Query Processor not to parameterize constants in INSERT statements.

noMetadataCaching

false

When set to true, the Query Processor does not take object metadata from the cache but from the original data source.

noParallelExecution

false

When set to true, disables parallel processing within query execution. See noThreads, described below.

noQueryParametrization

false

When set to true, sets the Query Processor not to convert constants into parameters when accessing data sources.

noQueryReadAhead

false

When set to true, disables read-ahead functionality for components using Query Processor services.

noRowMarkFieldFetch

false

When set to false, OLE DB getRows errors are marked and reshown on every getRows, as long as the rowset is active.

noSQSCache

false

When set to true, compiled Oracle Connect for IMS, VSAM, and Adabas Gateways procedures and views are not saved in the cache but always read from disk.

noThreadedReadAhead

false

When set to true, disables read-ahead functionality. Also, see noThreads, below.

noThreads

false

When set to true, disables multithreading.

parserDepth

500

The maximum depth of the expression tree.

prodeduresCacheSize

3

The number of Oracle Connect for IMS, VSAM, and Adabas Gateways stored queries created with a CREATE PROCEDURE statement that can be kept in cache memory.

promptDbUserPassword

false

When set to true, sets Oracle Connect for IMS, VSAM, and Adabas Gateways to prompt the user for security information when accessing a data source.

tokenSize

350

The maximum length of a string in an SQL query. The minimum value is 64.

useAlternateQualifier

false

When set to true, the Query Processor uses the @ symbol instead of a colon (:) when connecting to multiple data sources.

Note: This value is needed when building an application using PowerBuilder from Sybase Inc. or Genio from Hummingbird Ltd.

useTableFilterExpressions

false

When set to true, enables the use of tables that have filter expressions specified in their metadata. For details of filters in ADD, refer to the filter attribute.

transactions

commitOnDestroy

false

convertAllToDistributed

false

When set to true, converts all simple Transaction Managers into distributed transactions.

convertAllToSimple

false

When set to true, converts all distributed transactions into simple transactions.

disable2PC

false

When set to true, disables global transaction capabilities, even in drivers that support 2PC.

extendedLogging

false

When set to true, the transaction manager logs extended information concerning transactions.

logFile

The full path and filename of the log file that logs activity when using transactions. This log file is used during any recovery operations. Under Windows, the default log file (TRLOG.TLF) is written to the same directory as the NAV.LOG file (which is specified by the debug logFile parameter). It is recommended to use the default log file and perform recovery from a PC.

oleThreads

Limits the number of open threads when working with OLE transactions. These threads are used for operations received from the MSDTC. The minimum value is 5. the optimum value is 15. The maximum value is 25.

recoveryDelay

The number of minutes from the start of a transaction before any recovery operation on that transaction can be attempted. The default is 15 minutes.

serverUrl

timeLimit

1

Specifies the time to wait for a transaction to complete before an error is returned.

This parameter is also used when performing a RECOVERY, and it then indicates the number of minutes to wait before a forced activity can be performed, since the last transaction activity.

useCommitConfirmTable

false

When set to true, uses the commit-confirm table for data sources that support single-phase commit.

tuning

dsmMaxBufferSize

1000000 bytes

The maximum size of a cache memory. This cache is used when memory is required on a temporary basis (as when Oracle Connect for IMS, VSAM, and Adabas Gateways sorts data for a query output, for a subquery, or for aggregate queries). This cache size is not used for hash joins and lookup joins (see the hashBufferSize parameter, below).

dsmMaxHashFilesize

200000000

bytes

dsmMaxSortBufferSize

1000000 bytes

The maximum size of the sort buffers. Use this parameter instead of dsmMaxBufferSize for sorts only.

dsmMidBufferSize

100000 bytes

The maximum size of the index cache. This cache is not used for hash joins and lookup joins.

fileCloseOnTransaction

false

When set to true, the file pool will close when a transaction is committed.

filepoolSize

10

Specifies the file pool size. The default indicates that up to 10 files can be opened in the file pool.

filepoolSizePerFile

3

Specifies the file size in the file pool.

hashBufferSize

1000000 bytes

The amount of cache memory that is available for each hash join or lookup join.

hashEnableParallelism

true

Both sides of a hash join are read concurrently.

hashEnableRO

false

hashMaxDiskSpace

-1

The maximum amount of disk space (in MBs) that a query can use for hash joins. The default is unlimited (all the free space on the allocated disk). If a query requires more space than allocated through this parameter, the query execution will stop. The minimum value for this parameter is 20 MB.

Note: Temporary files are written per query. Therefore, if several users can execute queries at the same time, adjust the amount of space available, so that the total that can be allocated at any one time does not exceed the available space.

hashMaxOpenFiles

90

The maximum number of files that a query can open at one time for use when performing hash joins. The number assigned to this parameter must not exceed the system maximum.

Note: The hash join optimization strategy results in a number of files being opened to perform the join. The larger the table size, the more files are opened. By adjusting this parameter you can disable hash joins on very large tables, while allowing hash joins for small tables. (See the description of the optimizer parameter, above, for details about disabling hash optimization for all table joins).

useGloablFilepool

false

When set to true, a global file pool is used. When the serverMode parameter is set to multiClient or reusable, this parameter also indicates whether the file pool closes upon the client disconnection.

Sample Environment Properties

The following sample shows how different environment properties are represented in XML for the NAV binding configuration:

<environment name="NAV">
<comm comCacheBufferSize="200000" />
<debug logFile="" traceDir="" />
<misc tempDir="" language="" codepage="" nlsString="" />
<odbc maxActiveConnections="0" />
<oledb maxHRows="100" />
<optimizer preferredSite="server" />
<queryProcessor proceduresCacheSize="3" firstTreeExtensions="150"
maxColumnsInParsing="500" />
<transactions/>
<tuning dsmMaxBufferSize="1000000" dsmMidBufferSize="100000"
hashBufferSize="1000000" hashMaxDiskSpace="-1"
hashMaxOpenFiles="90" />
</environment>

Note:

The XML representation of the environment properties are displayed on the Oracle Studio for IMS, VSAM, and Adabas Gateways Source tab when you edit the Binding in the Design perspective Configuration view.

Footnote Legend
Footnote 1: Other parameters that appear in Oracle Studio for IMS, VSAM, and Adabas Gateways are for reference only and should not be modified. These parameters are displayed when the Preferences window is opened and the Show advanced environment parameters field is checked, on the Advanced tab under the Studio node.

14 Managing Security for Oracle Connect for IMS, VSAM, and Adabas Gateways

Oracle Connect for IMS, VSAM, and Adabas Gateways provides the following types of security:

- Design Time: Security used to access resources during the design phase.

- Runtime: Security used to access resources from an application, including encryption over the network and impersonation.

Security for Oracle Connect for IMS, VSAM, and Adabas Gateways is managed through Oracle Studio for IMS, VSAM, and Adabas Gateways.

This section contains the following topics:

- Managing Design Time Security

- Managing Runtime Security

Managing Design Time Security

Design time security involves following tasks:

- Setting Up the Password Caching Policy in Oracle Studio for IMS, VSAM, and Adabas Gateways

- Setting Up Administration Access to a Machine

- Assigning Design Roles

- Assigning Authorization Rights to a Workspace

- Setting Up a Master Password for a User Profile

Setting Up the Password Caching Policy in Oracle Studio for IMS, VSAM, and Adabas Gateways

Oracle Studio for IMS, VSAM, and Adabas Gateways can cache passwords that are used for accessing servers and databases. The following security levels are supported:

- Oracle Studio for IMS, VSAM, and Adabas Gateways does not cache passwords. When Oracle Studio for IMS, VSAM, and Adabas Gateways needs a password to access a server or database, it prompts the user to enter the password. This is the safest level, but it is less convenient.

- Oracle Studio for IMS, VSAM, and Adabas Gateways caches passwords persistently but protects them through a master password. At this security level, Oracle Studio for IMS, VSAM, and Adabas Gateways prompts for the master password at startup.

- Oracle Studio for IMS, VSAM, and Adabas Gateways caches passwords persistently but hides them through a fixed internal master password. This security level is convenient but not safe because the cached password can be retrieved any time. This level is not recommended.

To set the password caching policy of Oracle Studio for IMS, VSAM, and Adabas Gateways

1. In Oracle Studio for IMS, VSAM, and Adabas Gateways, point to Windows, then select Preferences.

2. Select the Studio node.

3. On the Security tab, do the following:

- For the highest security level, clear the Remember passwords check box.

- For a lower security level, do the following:
Click Change master password. The Change master password dialog box opens.

Enter a master password and confirm it. Then click OK.

Select the Remember passwords check box.

Note:

If you set a master password, Oracle Studio for IMS, VSAM, and Adabas Gateways will prompt you for the password the next time you open the application. If you set the master password to an empty password, Oracle Studio for IMS, VSAM, and Adabas Gateways will use the internal default password.

4. Click OK to save your settings.

Setting Up Administration Access to a Machine

To administer an Oracle Connect for IMS, VSAM, and Adabas Gateways system, you must add it to Oracle Studio for IMS, VSAM, and Adabas Gateways. Administrative access requires that you provide Oracle Studio for IMS, VSAM, and Adabas Gateways with an Oracle Connect for IMS, VSAM, and Adabas Gateways administrator account and password.

The Oracle Connect for IMS, VSAM, and Adabas Gateways administrator account is the account that you specified during the installation of Oracle Connect for IMS, VSAM, and Adabas Gateways on this system or when running NAV_UTIL ADD_ADMIN.

You specify the administrator account and password in the Add machine screen, in the Connection area, as shown in Figure 14-1.

Figure 14-1 User Name and Password in Add Machine Screen

Assigning Design Roles

After you have defined a system in Oracle Studio for IMS, VSAM, and Adabas Gateways, you can grant viewing and editing rights to users and groups according to their roles in the design process.

The following roles are available:

- Administrator: Allowed to edit all of the definitions in Oracle Studio for IMS, VSAM, and Adabas Gateways.

- Designer: Allowed to edit binding definitions and view daemon definitions in Oracle Studio for IMS, VSAM, and Adabas Gateways.

- User: Allowed to view the definitions in Oracle Studio for IMS, VSAM, and Adabas Gateways.

Perform the following steps to assign design roles to users and groups.

1. In the Configuration view, right-click the system and select Administration Authorization.

2. In the Administration Authorization screen, click Add User or Add Group to assign authorization to specific users or a specific group of users. The name cannot contain blanks.

Note:

Administration Authorization is set from the top down. This means that if you specify users or groups at a higher level, you do not need to specify the same users or groups on a lower level.

Assigning Authorization Rights to a Workspace

After you have defined a system in Oracle Studio for IMS, VSAM, and Adabas Gateways, you can authorize the viewing and editing rights for specific workspaces.

Perform the following steps to assign authorization rights to a workspace.

1. In the Design perspective, in the Configuration view, right-click the system and select Set Authorization.

2. Specify the user name and password for the user with authorization rights for this workspace.

Setting Up a Master Password for a User Profile

The definition of a user profile stores the user names and passwords that are required to access databases and remote systems. To protect this information, you can assign a master password to a user profile. If you do not assign a password, anyone can use the information stored in the definition.

Note:

The password assigned to a user profile definition must be identical to the password of the user account of the server's operating system. Likewise, if the password of the user account of the server's operating system changes, you must also change the password of the user profile definition.

Perform the following steps to set a master password for a user profile.

1. In the Design perspective, in the Configuration view, expand the system that contains the user profile definition.

2. Expand the Users node.

3. Right-click the relevant user and select Change User Password.

4. Enter the relevant information and click OK.

Managing Runtime Security

The following security aspects are implemented at runtime:

- Daemon and Workspace Administration: Granting the authorization needed to manage a running daemon.

- Access Authorization: Granting the authorization needed to connect and use a server workspace.

- Network Communication Encryption: Encrypting the data sent over the network between the client and the server.

- Impersonation: Making the server process take on the security identity of the client so that data access permissions and restrictions apply based on the client's identity (rather than on the server's security level).

- User Profiles: Enabling a single sign-on to server systems and data sources.

The management of runtime security can involve the following tasks:

- Granting Daemon Administration Rights to Users

- Granting Workspace Administration Rights to Users

- Granting Workspace Access Rights to a User

- Accessing a Server through a Firewall

- Encrypting Network Communications

- Setting Up Impersonation

Granting Daemon Administration Rights to Users

You can grant a user run-time administration rights to the daemon. An administrator has the right to perform actions such as starting and shutting down a daemon, recycling servers of all workspaces, and updating the configuration of an active daemon.

Perform the following steps to grant daemon administration rights to a user.

1. In the Design perspective, in the Configuration view, expand the relevant system.

2. Expand the Daemons node.

3. Right-click the daemon and select Edit Daemon.

4. In the daemon editor, on the Daemon Security tab, in the Administrator privileges area, click Selected user only, as shown in Figure 14-2.

Figure 14-2 Daemon Security Tab

5. Click Add Group or Add User to grant administration rights to a group or user.

Note:

On z/OS platforms, to define a group of users, preface the name of the group in the configuration with '@'. The group name is validated by a security system such as RACF.

The Source tab shows the result in XML. For example:

- To prevent anonymous access and limit administration rights to a user called sysadmin:

<security anonymousClientAllowed="false" administrator="sysadmin" />

- To allow anonymous access to a server and to grant all users administration right:

<security anonymousClientAllowed="true" administrator="*" />

Note:

On z/OS platforms, to prevent anonymous access and limit administration rights to a user called sysadmin and to a group called sys, change the settings as follows:

<security anonymousClientAllowed="false"
administrator="sysadmin,@sys" />

Granting Workspace Administration Rights to Users

You can grant a user runtime workspace administrative rights for a specific workspace. These rights allow a user to enable, disable, and recycle workspace server.

Perform the following steps to grant administrative rights to a workspace.

1. In the Design perspective, in the Configuration view, expand the relevant system.

2. Expand the Daemons node.

3. Expand the node of the relevant daemon.

4. Right-click the workspace and select Edit Workspace.

5. In the workspace editor, on the WS Security tab, in the Administration area, click Selected user only, as shown in Figure 14-3.

Figure 14-3 Assignment of Administrator Privileges in the WS Security Tab

6. Click Add Group or Add User to grant administration rights to a group or user.

Note:

To define a group of users on z/OS platforms, preface the name of the group in the configuration with '@'. The group name is validated by a security system such as RACF.

The Source tab shows the result in XML. For example:

- Users must enter the correct user name and password to use a workspace. All authenticated users have workspace administration rights. This is defined as follows:

<workspace name="Navigator"
description="An Oracle Server"
startupScript="ATSRVR50.XY"
serverMode="reusable" reuseLimit="0"
anonymousClientAllowed="false"
administrator="*" />
</workspace>

- Users must enter the correct user name and password to use a workspace. Only the user SYSADMIN has administrator rights. This is defined as follows:

<workspace name="Navigator"
description="An Oracle Server"
startupScript="ATSRVR50.XY"
serverMode="reusable" reuseLimit="0"
anonymousClientAllowed="false"
administrator="SYSADMIN" />
</workspace>

Notes:

- The value for startupScript in these examples is system-dependent. For example, for z/OS the startup script may be: startupScript=”ATTSRVR.AB”

- On z/OS platforms, to limit administration rights to a user called SYSADMIN and a group called DEV, the following line is required: administrator="SYSADMIN,@DEV"

Granting Workspace Access Rights to a User

Clients log in to the daemon and request that a server be allocated to a particular workspace. When the client logs in, it provides its login credentials, that is the user name and password. The request for a specific workspace server is granted only if the logged-on user was granted access to the workspace.

By adding a user to the list of workspace users, you grant them access to the workspace servers only. If a database on the server requires additional authentication, you need to create a user profile definition with the name of this user.

Perform the following steps to grant workspace access to a user.

1. In the Design perspective, in the Configuration view, expand the relevant system.

2. Expand the Daemons node.

3. Right-click the daemon and select Edit Daemon.

4. In the daemon editor, on the WS Security tab, in the Workspace Access area, click Selected user only, as shown in Figure 14-4.

Figure 14-4 Assign Users in WS Security Tab

5. Click Add User to grant a user access to the workspace.

Note:

On z/OS platforms, to define a group of users instead of a single user (so that the group name is validated by a security system), preface the name of the group in the configuration with '@'.

6. Save your settings.

Accessing a Server through a Firewall

Oracle Connect for IMS, VSAM, and Adabas Gateways lets you access a server through a firewall. The following table describes the available options.

Table 14-1 Firewall Options

Firewall Traversal Technology

Description

VPN

With VPN, firewall traversal is transparent and does not require special configuration of Oracle Connect for IMS, VSAM, and Adabas Gateways.

SOCKS

Oracle Connect for IMS, VSAM, and Adabas Gateways provides no SOCKS client. You can only use SOCKS if the firewall vendor provides automatic libraries that add SOCKS support, such as WinSock2 filters on Windows, so that communication goes through SOCKS.

When Oracle Connect for IMS, VSAM, and Adabas Gateways connects through SOCKS, make sure to do the following:

- Set the Fixed NAT option at the client to Select.

- Establish a port range for the workspace server.

NAT

Oracle Connect for IMS, VSAM, and Adabas Gateways supports Network Address Translation (NAT) only when Fixed NAT, also called static NAT or one-to-one NAT, is used.

Fixed NAT uses an external IP address to connect to the daemon and starts the servers on an internal IP address.

When Oracle Connect for IMS, VSAM, and Adabas Gateways connects through Fixed NAT, the Oracle Connect for IMS, VSAM, and Adabas Gateways client ignores the server IP address that the daemon returns and uses the port number with the original external IP address instead.

When Oracle Connect for IMS, VSAM, and Adabas Gateways connects through Fixed NAT, make sure to do the following:

- Set the Fixed NAT option at the client to Select.

- Establish a port range for the workspace servers.

Specifying a Port Range for Workspace Servers

Specifying a port range for a workspace causes all servers that are started for that workspace to listen on ports within the specified range. When a new server starts, it scans the port range in random order trying to bind to a port. It then uses the first port that it manages to bind to.

Multiple workspaces can share the same port range. However, you must make sure to define a range that is large enough to allow for all servers to start. In addition, because it takes time for used ports to become available again after the server that used them has terminated, it is recommended to specify a port range that is slightly larger than the number of servers required to accommodate for transition periods.

Perform the following steps to specify a range of ports.

1. In the Design perspective, in the Configuration view, expand the relevant system.

2. Expand the Daemons node.

3. Right-click the daemon and select Edit Daemon.

4. In the daemon editor, on the WS Security tab, in the Workspace Access area, select Enable port range and enter the starting and ending port numbers in the From port and To port boxes.
For an example of the WS Security tab, see Figure 14-4.

5. Save your settings.

Accessing a Server Using Fixed NAT

When an Oracle Database Gateway needs to access the Oracle Connect for IMS, VSAM, and Adabas Gateways server through a Fixed NAT firewall, make sure to set the HS_FDS_CONNECT_INFO parameter in the init.ora file as in the following example:

HS_FDS_CONNECT_INFO="address='mvs.acme.com' port='2551'" firewallProtocol='fixednat'

This setting does not require any changes to the daemon configuration.

See Also:

For details on setting gateway parameters, see Appendix B.

Encrypting Network Communications

Because Oracle Database Gateway for IMS, VSAM, and Adabas runs on UNIX or Windows and the networking layer that connects to the data sources runs on IBM z/OS, network communications should be encrypted. The networking layer of Oracle Database Gateway for IMS, VSAM, and Adabas uses an RPC-like protocol with message primitives that are similar in concept to the Microsoft OLEDB API.

Transport Encryption

For transport encryption, Oracle Connect for IMS, VSAM, and Adabas Gateways uses shared symmetric-key encryption with a 128-bit RC4 encryption scheme, as follows:

- Upon connection, the gateway sends the name of the shared key to use to the server.

- The server computes a random 128-bit session key, encrypts it by using a named and shared symmetric key, and sends the encrypted session key back to the client.

- The Oracle Connect for IMS, VSAM, and Adabas Gateways server keeps multiple keys in a key store so that different gateway instances can use different encryption keys.

If the gateway is configured for transport encryption, further communication with the Oracle Connect for IMS, VSAM, and Adabas Gateways server occurs using the established session key. If transport encryption is not configured, the session key is used only for the process of authentication; then communication drops back to plain mode.

Setting an Encryption Protocol on the Gateway Side

To enable transport encryption, the gateway must provide both the shared key name (passed to the server) and its value (computed by the server). This is done by supplying these values in the CREATE DATABASE LINK statement and then defining the same key on the server by using Oracle Studio for IMS, VSAM, and Adabas Gateways (see Specifying the Encryption Key on the Server Machine).

To provide the name of the encryption key and the key value as part of the CREATE DATABASE LINK, append the encryption key name to the user name and the key value to the password by using the pound character (#), as follows:

CREATE DATABASE LINK [link_name]
CONNECT TO "[user_name]#[key_name]"
IDENTIFIED BY "[password]#[key_value]"

For example:

CREATE DATABASE LINK sales
CONNECT TO "sales1#saleskey"
IDENTIFIED BY "Sales1#123456"

If no shared key is defined, for example in closed, trusted networks, a fixed, built-in key is used. However, it is recommended to always encrypt network communications.

See Also:

Oracle Database Administrator's Guide and Oracle Database Heterogeneous Connectivity User's Guide for more information about using database links.

Specifying the Encryption Key on the Server Machine

Any communication from the gateway to the server system is encrypted. The server system must be configured to decipher the encrypted information using an encryption key.

To set the encryption key on the server system

1. Select the server system in the Oracle Studio for IMS, VSAM, and Adabas Gateways Design perspective Configuration view.

2. Right-click the user profile and select Edit User. The User editor is displayed.In the User editor, select the Encryption Key tab.
Figure 14-5 shows the Encryption Key tab.

Figure 14-5 Encryption Key Tab

3. Click Add. The Add Encryption Key screen is displayed, as shown in Figure 14-6.

Figure 14-6 Add Encryption Key Screen

4. Configure the encryption key parameters as follows:

- Key name: Enter the name associated with the encryption password and which the daemon on this system looks up.

- Key: Enter the encryption key.

- Confirm key: Re-enter the encryption key.

5. Click OK.

6. In the tree, expand the Daemons node.

7. Right-click the daemon managing the connection and select Edit Daemon.Select the Daemon Security tab.

8. In the Machine access area, enter RC4 in the Encryption methods field.
Figure 14-7 shows the Daemon Security tab.

Figure 14-7 Daemon Security Tab

Setting Up Impersonation

Impersonation is the ability of a server to execute in a security context that is different from the context of the process that owns the server.

The primary reason for impersonation is to cause access checks to be performed against the client's identity. Using the client's identity for access checks can cause access to be either restricted or expanded, depending on what the client has permission to do.

For example, suppose a file server has files containing confidential information and that each of these files is protected by a security system. To prevent a client from obtaining unauthorized access to information in these files, the server can impersonate the client before accessing the files.

To set up impersonation

1. On z/OS platforms, APF-authorize all the steplibs in the server script. For example:

setprog... ada622-volume adavol
CICS.CICS.SDFHEXCI - p390dx
navroot.load - 111111
navroot.loadaut - 111111

where navroot is the high-level qualifier where Oracle Connect for IMS, VSAM, and Adabas Gateways is installed.

2. On all platforms, on the WS Security tab of the daemon editor, leave the Workspace account field empty, as shown in Figure 14-8.

Figure 14-8 Workspace Account Setting on the WS Security Tab

3. On the Client platform, define a user profile for the server system with the required username and password for the remote system in the user profile.

4. Add a new user authenticator with the resource type defined as remote system, as follows:
Open Oracle Studio for IMS, VSAM, and Adabas Gateways.

In the Configuration view, right-click the user profile and select Edit User.

In the User editor, select the client system and click Add.

In the Add Authenticator screen, set the Resource type to Remote machine.

Specify the resource name and, if required, authentication information; then click OK.

Part VI

Appendixes

Part VI, "Appendixes," contains the following appendixes:

Appendix A, "Using Response Files for Non-Interactive Installation"

Appendix B, "Initialization Parameters"

Appendix C, "Oracle Database Gateway Troubleshooting"

A Using Response Files for Non-Interactive Installation

This appendix describes how to install and configure Oracle products using response files. It includes the following topics:

- Introduction

- Installation Overview

- Creating the oraInst.loc File

- Preparing a Response File

- Running Oracle Universal Installer in Silent or Suppressed Mode

Introduction

You can automate the installation and configuration of Oracle software, either fully or partially, by specifying a response file when you start Oracle Universal Installer. Oracle Universal Installer uses the values contained in the response file to provide answers to some or all of Oracle Universal Installer prompts:

- If you include responses for all of the prompts in the response file and specify the -silent option when starting Oracle Universal Installer, then Oracle Universal Installer runs in silent mode. During a silent-mode installation, Oracle Universal Installer does not display any screens. Instead, it displays progress information in the terminal that you used to start it.

- If you include responses for some or all of the prompts in the response file and omit the -silent option, then Oracle Universal Installer runs in suppressed mode. During a suppressed-mode installation, Oracle Universal Installer displays only the screens for which you did not specify all required information. You can also use variables in the response file or command-line options to suppress other installer screens, such as the Welcome screen or Summary screen, that do not prompt for information.

The following table describes several reasons why you might want to run Oracle Universal Installer in silent mode or suppressed mode:

Mode

Uses

Silent

Use silent mode if you want to:

- Complete an unattended installation, which you might schedule using operating system utilities such as at

- Complete several similar installations on multiple systems without user interaction

- Install the software on a system that does not have X Window System software installed on it

Oracle Universal Installer displays progress information in the terminal that you used to start it, but it does not display any of Oracle Universal Installer screens.

Suppressed

Use suppressed mode if you want to complete similar Oracle software installations on more than one system, providing default answers to some, but not all of Oracle Universal Installer prompts.
If you do not specify information required for a particular Installer screen in the response file, Oracle Universal Installer displays that screen. It suppresses screens for which you have provided all of the required information.

Installation Overview

To install and configure Oracle products using Oracle Universal Installer in silent or suppressed mode, follow these steps:

1. Create the oraInst.loc file.

2. Prepare a response file.

3. Run Oracle Universal Installer in silent or suppressed mode.

These steps are described in the following sections.

Creating the oraInst.loc File

If you plan to install Oracle products using Oracle Universal Installer in silent or suppressed mode, you must manually create the oraInst.loc file if it does not already exist. This file specifies the location of the Oracle Inventory directory where Oracle Universal Installer creates the inventory of Oracle products installed on the system.

Note:

If Oracle software has been installed previously on the system, the oraInst.loc file might already exist. If the file does exist, you do not need to create a file.

To create the oraInst.loc file:

1. Switch user to root:
On HP-UX Itanium and Solaris (SPARC), create the /var/opt/oracle directory if it does not exist.

2. Change directory as follows, depending on your operating system:

- On AIX type:

# cd /etc

- On HP-UX Itanium and Solaris (SPARC), type:

# cd /var/opt/oracle

3. Enter the following commands to set the appropriate owner, group, and permissions on the oraInst.loc file:

- # chown oracle:oinstall oraInst.loc

- # chmod 664 oraInst.loc

Preparing a Response File

This section describes the methods that you can use to prepare a response file for use during silent-mode or suppressed-mode installations:

- Editing a Response File Template

- Recording a Response File

Editing a Response File Template

Oracle provides response file templates for each product and installation type, and for each configuration tool. The response files for Oracle Gateways, dg.rsp and netca.rsp are located in the response directory on the media.

Note:

If you copied the software to a hard disk, the response files are located in the Disk1/response directory.

To prepare a response file:

1. Copy the response file from the response file directory to a directory on your system:

$ cp /directory_path/response/response_file.rsp local_directory

In this example, directory_path is the CD-ROM mount point directory or the directory on the DVD. If you copied the software to a hard drive, you can edit the file in the response directory.

2. Open the response file in a text editor. For example:

$ vi /local_dir/response_file.rsp

3. Edit the file, following the instructions in the file.

Note:

Oracle Universal Installer or configuration assistant fails if you do not correctly configure the response file. See"Silent Mode Response File Error Handling" for more information about troubleshooting a failed silent-mode installation.

4. Change the permissions on the file to 700. For example:

$ chmod 700 /local_dir/response_file.rsp

Recording a Response File

This method is most useful for Custom or software-only installations.

You can use Oracle Universal Installer in interactive mode to record a response file that you can edit and then use to complete silent-mode or suppressed-mode installations. When you are recording the response file, you can either complete the installation, or you can exit from Oracle Universal Installer on the Summary page, before it starts to copy the software to the system.

To record a new response file:

1. Complete the pre-installation tasks listed in respective chapters.
When you run Oracle Universal Installer to record a response file, it checks the system to verify that it meets the requirements to install the software. For this reason, Oracle recommends that you complete all of the required pre-installation tasks and record the response file while completing an installation.

2. If you have not installed Oracle software on this system previously, create the oraInst.loc file, as described in the previous section.

3. Ensure that the Oracle software owner user (typically oracle) has permissions to create or write to the Oracle home path that you will specify when you run Oracle Universal Installer.

4. To record a response file, enter a command similar to the following:

$ /directory_path/runInstaller -record -destinationFile filename

Note:

Do not specify a relative path to the response file. If you specify a relative path, Oracle Universal Installer fails.

In the previous example:

- directory_path is either the CD-ROM mount point directory, the path of the directory on the DVD, or the path of the Disk1 directory on the hard drive

- The -record parameter specifies that you want to record the responses that you enter in a response file

- filename is the full path and file name of the response file that you want to record

5. If you did not complete the installation, delete the Oracle home directory that Oracle Universal Installer created using the path you specified on the Specify File Locations screen.

6. Before using the recorded response file on another system, use a text editor to edit the file and make any required changes.
Use the comments in the file as a guide when editing it.

Running Oracle Universal Installer in Silent or Suppressed Mode

To run Oracle Universal Installer in Silent or suppressed mode, follow these steps:

1. Complete the pre-installation tasks listed in the respective chapters.

2. Log in as the Oracle software owner user (usually oracle).

3. To start Oracle Universal Installer in silent or suppressed mode, enter a command similar to the following:

/directory_path/runInstaller  -silent  -noconfig -responseFile filename

Note:

Do not specify a relative path to the response file. If you specify a relative path, Oracle Universal Installer fails.

In this example:

- directory_path is either the CD-ROM mount point directory, the path of the directory on the DVD, or the path of the Disk1 directory on the hard drive.

- -silent indicates that you want to run Oracle Universal Installer in silent mode.

- -noconfig suppresses running the configuration assistants during installation, and a software-only installation is performed instead.

- filename is the full path and file name of the installation response file that you configured.

Note:

For more information about other options for the runInstaller command, enter the following command:
$ /directory_path/runInstaller -help

B Initialization Parameters

The Oracle Database initialization parameters in the init.ora file are distinct from heterogeneous services (HS) initialization parameters. Set HS parameters in the initialization parameter file using an agent-specific mechanism, or set them in the Oracle data dictionary using the DBMS_HS package.

This appendix describes the following initialization parameters:

- Initialization Parameter File Syntax

- HS_DB_DOMAIN

- HS_DB_INTERNAL_NAME

- HS_DB_NAME

- HS_DESCRIBE_CACHE_HWM

- HS_LANGUAGE

- HS_LONG_PIECE_TRANSFER_SIZE

- HS_OPEN_CURSORS

- HS_RPC_FETCH_REBLOCKING

- HS_RPC_FETCH_SIZE

- HS_TRANSACTION_MODEL

- IFILE

- HS_FDS_CONNECT_INFO

- HS_FDS_PARSER_TOKEN_SIZE

- HS_FDS_RECOVERY_ACCOUNT

- HS_FDS_RECOVERY_PWD

- HS_FDS_TRACE_LEVEL

- HS_NLS_NCHAR

- HS_NLS_NUMERIC_CHARACTER

- HS_FDS_DATASOURCE_NAME

- HS_FDS_ACCESS_METHOD

See Also:

Oracle Database Heterogeneous Connectivity User's Guide for information on other available initialization parameters and Oracle Database Error Messages for information on handling Oracle error messages.

The initialization parameter file must be available when the gateway is started. During installation, the following default HS initialization parameter file is created:

ORACLE_HOME:[dg4<data_source>.admin]initdg4<data_source>.ora

Where ORACLE_HOME is the device under which the gateway is installed.

Initialization Parameter File Syntax

The syntax for the initialization parameter file is as follows:

- The file is a sequence of commands.

- Each command should start on a separate line.

- End of line is considered a command terminator (unless escaped with a backslash).

- Each command can have one of the following forms:

- <param> = <value>

- set <param> = <value>

- private <param> = <value>

- set private <param> = <value>

Where:

<param> is an initialization parameter name.

<value> is the initialization parameter value.

'set' and 'private' are keywords.

- The keywords 'set' and 'private' are reserved. You cannot use either as an initialization parameter name. The 'set' keyword indicates that the initialization parameter should be set as a logical in the agent. The 'private' keyword indicates that the initialization parameter should be private to the agent and should not be uploaded to the server. Most initialization parameters should not be private. If, however, you are storing something sensitive like a password in the initialization parameter file, then you may not want it uploaded to the server because the initialization parameters and values are not encrypted when uploaded. Making these initialization parameters private prevents the upload from happening.

- An initialization parameter name is a string of characters starting with a letter and consisting of letters, digits and underscores. Initialization parameter names are case-sensitive.

- An initialization parameter value is either:

- A string of characters that does not contain any backslashes, white space or double quotation marks (").

- A quoted string beginning with a double quotation mark and ending with a double quotation mark. The following can be used inside a quoted string:

- backslash (\) is the escape character

- \n inserts a newline

- \t inserts a tab

- \" inserts a double quotation mark
A backslash at the end of the line continues the string on the next line. If a backslash precedes any other character then the backslash is ignored.

If there is a syntax error in an initialization parameter file, none of the settings take effect.

HS_DB_DOMAIN

Property

Description

Default value

WORLD

Range of values

1 to 199 characters

Specifies a unique network subaddress for a non-Oracle system. The HS_DB_DOMAIN initialization parameter is similar to the DB_DOMAIN initialization parameter, described in the Oracle Database Reference. The HS_DB_DOMAIN initialization parameter is required if you use the Oracle Names server. The HS_DB_NAME and HS_DB_DOMAIN initialization parameters define the global name of the non-Oracle system.

Note:

The HS-BD_Name and HS_DB_DOMAIN initialization parameters must combine to forma unique address in a cooperative server environment.

HS_DB_INTERNAL_NAME

Property

Description

Default value

01010101

Range of values

1 to 16 hexadecimal characters

Specifies a unique hexadecimal number identifying the instance to which the Heterogeneous Services agent is connected. This parameter's value is used as part of a transaction ID when global name services are activated. Specifying a nonunique number can cause problems when two-phase commit recovery actions are necessary for a transaction.

HS_DB_NAME

Property

Description

Default value

HO

Range of values

1 to 8 characters

Specifies a unique alphanumeric name for the data store given to the non-Oracle system. This name identifies the non-Oracle system within the cooperative server environment. The HS_DB_NAME and HS_DB_DOMAIN initialization parameters define the global name of the non-Oracle system.

HS_DESCRIBE_CACHE_HWM

Property

Description

Default value

100

Description

1 to 4000

Specifies the maximum number of entries in the describe cache used by Heterogeneous Services. This limit is known as the describe cache high water mark. The cache contains descriptions of the mapped tables that Heterogeneous Services reuses so that it does not have to re-access the non-Oracle data store.

If you are accessing many mapped tables, increase the high water mark to improve performance. Increasing the high water mark improves performance at the cost of memory usage.

HS_LANGUAGE

Property

Description

Default value

System-specific

Description

Any of the character sets listed in theCodepage Values table.

Provides Heterogeneous Services with character set, language, and territory information of the non-Oracle data source. The value must use the following format:

language[_territory.character_set]

Note:

The globalization support initialization parameters affect error messages, the data for the SQL Service, and parameters in distributed external procedures.

The following table describes the supported charset values.

Table B-1 Codepage Values

Value

Description

AR8ISO8859P6

Arabic bilingual

AR8ISO8859P6

Arabic + Latin

BLT8ISO8859P13

Baltic multilingual

CL8ISO8859P5

Cyrillic multilingual

CLMSWIN1251

Cyrillic Ukraine + Euro

WE8ISO8859P15

German (Austria) + Euro

WE8ISO8859P1

German (Austria)

WE8ISO8859P15

Danish and Norwegian + Euro

NE8ISO8859P10

Danish and Norwegian

EE8ISO8859P2

Latin 2 multilingual

EL8ISO8859P7

Greek

WE8ISO8859P15

French + Euro

WE8ISO8859P1

French

WE8ISO8859P15

Italian + Euro

WE8ISO8859P1

Italian

IW8ISO8859P8

Hebrew

JA16SJIS

Japanese

KO16KSC5601

Korean

WE8ISO8859P15

Finnish and Swedish + Euro

WE8ISO8859P1

Finnish and Swedish - Sweden

TH8TISASCII

Thai IS 620-2533 EBCDIC 8-bit

WE8ISO8859P9

Turkish

WE8ISO8859P1

Latin 1

WE8ISO8859P15

English (USA, Canada) + Euro

WE8ISO8859P15

Spanish + Euro

WE8ISO8859P15

English (UK) + Euro

WE8ISO8859P15

International ECECP + Euro

WE8ISO8859P15

Western European + Euro

WE8ISO8859P1

Spanish

WE8ISO8859P1

English (UK)

WE8ISO8859P1

English (USA, Canada)

WE8ISO8859P1

French (Canada)

WE8ISO8859P1

Western Europe

NE8ISO8859P10

Icelandic

WE8ISO8859P9

Latin 9

ZHS16CGB231280

Simplified Chinese

ZHT16BIG5

Traditional Chinese

Character Sets

Ideally, the character sets of the Oracle database and the non-Oracle data source are the same. If they are not the same, Heterogeneous Services attempts to translate the character set of the non-Oracle data source to the Oracle database character set, and back again. The translation can degrade performance. In some cases, Heterogeneous Services cannot translate a character from one character set to another.

Note:

The specified character set must be a superset of the operating system character set on the platform where the agent is installed.

Language

The language component of the HS_LANGUAGE initialization parameter determines:

- Day and month names of dates

- AD, BC, PM, and AM symbols for date and time

- Default sorting mechanism

Note that Oracle does not determine the language for error messages for the generic Heterogeneous Services messages (ORA-25000 through ORA-28000). These are controlled by the session settings in the Oracle database.

Note:

Use the HS_NLS_DATE_LANGUAGE initialization parameter to set the day and month names, and the AD, BC, PM, and AM symbols for dates and time independently from the language.

Territory

The territory clause specifies the conventions for day and week numbering, default date format, decimal character and group separator, and ISO and local currency symbols. Note that the level of globalization support between the Oracle database and the non-Oracle data source depends on how the gateway is implemented.

HS_LONG_PIECE_TRANSFER_SIZE

Property

Description

Default value

64 KB

Range of values

Any value up to 2 GB

Sets the size of the piece of LONG data being transferred. A smaller piece size means less memory requirement, but more round-trips to fetch all the data. A larger piece size means fewer round-trips, but more of a memory requirement to store the intermediate pieces internally. Thus, the initialization parameter can be used to tune a system for the best performance, with the best trade-off between round-trips and memory requirements, and network latency or response time.

HS_OPEN_CURSORS

Property

Description

Default value

50

Range of values

1 to the value of OPEN_CURSORS initialization parameter of Oracle database

Defines the maximum number of cursors that can be open on one connection to a non-Oracle system instance.

The value never exceeds the number of open cursors in the Oracle database. Therefore, setting the same value as the OPEN_CURSORS initialization parameter in the Oracle database is recommended.

HS_RPC_FETCH_REBLOCKING

Property

Description

Default value

On

Range of values

Off, On

Controls whether Heterogeneous Services attempts to optimize performance of data transfer between the Oracle database and the Heterogeneous Services agent connected to the non-Oracle data store.

The following values are possible:

- OFF disables reblocking of fetched data so that data is immediately sent from agent to server.

- ON enables reblocking, which means that data fetched from the non-Oracle system is buffered in the agent and is not sent to the Oracle database until the amount of fetched data is equal or higher than the value of HS_RPC_FETCH_SIZE initialization parameter. However, any buffered data is returned immediately when a fetch indicates that no more data exists or when the non-Oracle system reports an error.

HS_RPC_FETCH_SIZE

Property

Description

Default value

50000

Range of values

1 to 100000000

Tunes internal data buffering to optimize the data transfer rate between the server and the agent process.

Increasing the value can reduce the number of network round-trips needed to transfer a given amount of data, but also tends to increase data bandwidth and to reduce latency as measured between issuing a query and completion of all fetches for the query. Nevertheless, increasing the fetch size can increase latency for the initial fetch results of a query, because the first fetch results are not transmitted until additional data is available.

HS_TRANSACTION_MODEL

Property

Description

Default value

Database Gateway for VSAM (batch) - SINGLE_SITE
Database Gateway for VSAM (cics) - 2_PHASE_COMMIT

Database Gateway for IMS (DLIBATCH) - SINGLE_SITE

Database Gateway for IMS (imsdbdc) - SINGLE_SITE

Database Gateway for IMS (dbctl) - 2_PHASE_COMMIT

Database Gateway for ADABAS - SINGLE_SITE

Range of values

COMMIT_CONFIRMREAD_ONLY
SINGLE_SITE

2_PHASE_COMMIT

Restricts the transaction mode available with the particular target to a level that can be less than that of the gateway's maximum capability. The maximum capability level is defined by the gateway. The range of values above is in order from minimum capability to maximum capability.

For example, if the maximum is SINGLE_SITE, then the HS_TRANSACTION_MODEL cannot be set to 2_PHASE_COMMIT. However, if 2_PHASE_COMMIT is the driver's maximum allowed value, then the HS_TRANSACTION_MODEL can be SINGLE_SITE.

The following values are possible:

- COMMIT_CONFIRM provides read and write access to the non-Oracle database and allows the gateway to be part of a distributed update. To use the commit-confirm model, the following items must be created in the non-Oracle database:

- Transaction log table. The default table name is HS_TRANSACTION_LOG. A different name can be set using the HS_FDS_TRANSACTION_LOG parameter. The transaction log table must be granted SELECT, DELETE, and INSERT privileges set to public.

- Recovery account. The account name is assigned with the HS_FDS_RECOVERY_ACCOUNT parameter.

- Recovery account password. The password is assigned with the HS_FDS_RECOVERY_PWD parameter.

- COMMIT_CONFIRM does not apply to Oracle Database Gateway for VSAM (batch), IMS (dlibatch) and IMS (imsdbdc), Adabas.

- READ_ONLY provides read access to the non-Oracle database.

- SINGLE_SITE provides read and write access to the non-Oracle database. However, the gateway cannot participate in distributed updates.

- 2_PHASE_COMMIT enables the non-Oracle system to participate in distributed transactions. It can participate in the server's two-phase commit protocol, as a regular two-phase commit node, but not as a commit point site. That is, it can prepare data, but it cannot remember the outcome of a particular transaction if asked to by the global coordinator.

- 2_PHASE_COMMIT does not apply to Oracle Database Gateway for VSAM (batch), IMS (dlibatch) and IMS (imsdbdc), Adabas.

IFILE

Property

Description

Default value

None

Range of values

Valid parameter file names

Use the IFILE initialization parameter to embed another initialization file within the current initialization file. The value should be an absolute path and should not contain environment variables. The three levels of nesting limit does not apply.

See Also:

Oracle Database Reference

HS_FDS_CONNECT_INFO

Property

Description

Default value

None

Range of values

Not applicable

Specifies the system and port information needed to connect to the non-Oracle system.

This is a required parameter that has two different formats, as follows:

- If you use the default workspace:

HS_FDS_CONNECT_INFO="address:port"

- If you use a workspace other than the default:

HS_FDS_CONNECT_INFO="address='host' port='port' workspace='workspace'"

Where:

- host: The name of the host computer.

- port: The port number to listen to.

- workspace: The data source workspace name (optional except for the IMS/DB DLI data source).

HS_FDS_PARSER_TOKEN_SIZE

Property

Description

Default value

1,000 Characters

Range of values

Any positive integer value

Used for setting the parser token size in case the default size is not sufficient. The default value can be changed if the following error occurs:

pclex input buffer overflowed, try to increase the variable tokenSize in your environment.

With default value of 1000, the gateway could handle SQL statements close to 2 MB. Note that the SQL statements sent to the gateway could be very different from the SQL statements issued by the users. If in doubt, turn on gateway trace. Increase this parameter to handle larger SQL statements sent to gateways

HS_FDS_RECOVERY_ACCOUNT

Property

Description

Default value

RECOVER

Range of values

Any valid user ID

Specifies the name of the recovery account used for the commit-confirm transaction model. An account with user name and password must be set up at the non-Oracle system. For more information about the commit-confirm model, see the HS_FDS_TRANSACTION_MODEL parameter.

The name of the recovery account is case-sensitive.

HS_FDS_RECOVERY_PWD

Property

Description

Default value

Recover

Range of values

Any valid password

Specifies the password of the recovery account used for the commit-confirm transaction model set up at the non-Oracle system.

The name of the password of the recovery account is case-sensitive.

HS_FDS_TRACE_LEVEL

Property

Description

Default value

OFF

Range of values

OFF, ON, DEBUG

Specifies whether error tracing is turned on or off for gateway connectivity.

The following values are valid:

- OFF disables the tracing of error messages.

- ON enables the tracing of error messages that occur when you encounter problems. The results are written to a gateway connectivity log file, in ORACLE_HOME:[dg4<data_source>.log].

- DEBUG enables the tracing of detailed error messages that can be used for debugging.

The trace goes to the following directory, where data_source is vsam, ims, or adbs, depending on your gateway: $ORACLE_HOME/dg4[data_source]/log

HS_NLS_NCHAR

Property

Description

Default value

None

Range of values

Any valid character set specification

Syntax

HS_NLS_NCHAR=character_set

HS_NLS_NCHAR specifies the character set that the gateway will use to interact with the non-Oracle system when accessing graphic data. Set this parameter to the same value as the character set component of the HS_LANGUAGE parameter. For additional details, see the Oracle Database Heterogeneous Connectivity Administrator's Guide.

HS_NLS_NUMERIC_CHARACTER

Property

Description

Default value

Value determined by the HS_LANGUAGE initialization parameter

Range of values

Any valid NLS_NUMERIC_CHARACTER value (any two valid numeric characters).

Specifies the characters to use as the group separator and the decimal character. The group separator separates integer groups (such as thousands, millions, and billions). The decimal character separates the integer portion of a number from the decimal portion.

HS_FDS_DATASOURCE_NAME

Property

Description

Default value

Gateway SID

Range of values

Any valid data source name

Specifies the name of the data source for the remote gateway. If you use this parameter, the SID name of the gateway does not need to be identical to the data source name.

HS_FDS_ACCESS_METHOD

Property

Description

Default value

VSAM-BATCH, IMS-BATCH

Range of values

VSAM-BATCH, VSAM-CICS
IMS-BATCH, IMS-DBDC, IMS-DBCTL

Specifies the gateway type that is used.

The following values are possible:

- VSAM-BATCH specifies a data source that connects directly to the VSAM data.

- VSAM-CICS specifies a data source that accesses VSAM by making EXCI calls to a CICS program.

- IMS-BATCH specifies an IMS/DB DLI data source.

- IMS-DBDC specifies an IMS/DB DBDC data source that accesses IMS/DB data under IMS/TM.

- IMS-DBCTL specifies an IMS/DB DBCTL data source that accesses IMS/DB data under CICS.

The default value is used when no init parameter is defined or when an unknown value is used.

C Oracle Database Gateway Troubleshooting

This appendix contains information about troubleshooting. It includes the following topics:

- Verify Requirements

- What to do if an Installation Error Occurs

- Reviewing the Log of an Installation Session

- Silent Mode Response File Error Handling

- Cleaning Up after a Failed Installation

Verify Requirements

Before performing any of the troubleshooting steps in this appendix, ensure that the system meets the requirements and that you have completed all of the pre-installation tasks specified in respective chapters.

Read the Release Notes

Read the release notes for the product before installing it. The release notes are available on the Oracle Database 11g installation media. The latest version of the release notes is also available on the OTN Web site:

http://www.oracle.com/technology/documentation/index.html

What to do if an Installation Error Occurs

If you encounter an error during installation:

- Do not exit Oracle Universal Installer.

- If you clicked Next after you entered incorrect information on one of the installation screens, click Back to return to the screen and correct the information.

- If you encounter an error while Oracle Universal Installer is copying or linking files, refer to the Reviewing the Log of an Installation Session section.

- If you cannot resolve the problem, remove the failed installation by following the steps listed in the Cleaning Up after a Failed Installation section.

Reviewing the Log of an Installation Session

During an installation, Oracle Universal Installer records all of the actions that it performs in a log file. If you encounter problems during the installation, review the log file for information about possible causes of the problem. The log file is in the oraInventory directory that you specified during installation.

Silent Mode Response File Error Handling

To determine whether a silent-mode installation succeeds or fails, refer to the following log file:

/oraInventory_location/logs/silentInstalldate_time.log

If necessary, refer to the previous section for information about determining the location of the oraInventory directory.

A silent installation fails if:

- You do not specify a response file

- You specify an incorrect or incomplete response file

- Oracle Universal Installer encounters an error, such as insufficient disk space

Oracle Universal Installer or configuration assistant validates the response file at run time. If the validation fails, the silent-mode installation or configuration process ends. Oracle Universal Installer treats values for parameters that are of the wrong context, format, or type as if no value was specified in the file.

Cleaning Up after a Failed Installation

If an installation fails, you must remove files that Oracle Universal Installer created during the attempted installation and remove the Oracle home directory.

The Deinstallation Tool (deinstall) is available in the installation media before installation, and is available in Oracle home directories after installation. It is located in the path $ORACLE_HOME/deinstall.

The deinstall command stops Oracle software, and removes Oracle software and configuration files on the operating system.

Perform the following steps to remove the files:

1. Log in as the installation owner.

2. Run the deinstall command, providing information about your servers as prompted.

3. Reinstall the Oracle software.

Index

A  C  D  E  F  G  H  I  L  M  N  O  P  R  S  T  V  W

A

accessing

Adabas data, 8

IMS data, 5

IMS/DB data under CICS, 5.2.1.1, 5.2.2.3

IMS/DB data under IMS/TM, 5.2.3.3

Oracle Connect for IMS, VSAM, and Adabas Gateways, 2.1, 8.1

VSAM data, 2

VSAM data under CICS, 2.2.2

accessing Oracle Connect for IMS, VSAM, and Adabas Gateways, 5.1

Adabas

configuring data access, 8

configuring data source properties, 8.2.2

data source parameters, 8.2.2

defining data source connection, 8.2.1

exporting metadata, 8.3.2

importing metadata from DDM files, 8.3.1

setting up data source, 8.2

setting up metadata, 8.3

applying metadata filters, 2.3.2, 2.4.2, 5.3.2

assigning

file names, 2.4.5, 2.4.6

C

CICS

accessing IMS/DB data, 5.2.1.1, 5.2.2.3

accessing VSAM data, 2.2.2

COBOL files

selecting, 2.3.1, 2.4.1

configuring

Adabas data source, 8.2.2

gateways, 4.1, 7.1, 10.1

global transactions, 4.7.1, 7.7.1, 10.7.1

IMS/DB DBCTL data source, 5.2.2.2

IMS/DB DLI data source, 5.2.1.3, 5.2.3.2

VSAM data source, 2.2.3

connecting to Oracle Connect, 8.1

connecting to Oracle Connect for IMS, VSAM, and Adabas Gateways, 2.1

connecting to Oracle for Connect IMS, VSAM, and Adabas Gateways, 5.1

connection to Adabas, 8.2.1

connection to IMS/DB DBCTL, 5.2.2, 5.2.2.1

connection to IMS/DB DBDC, 5.2.3, 5.2.3.1

connection to IMS/DB DLI, 5.2.1, 5.2.1.2

connection to VSAM, 2.2.1

D

daemon workspace, setting up, 5.2.1.1

data source

Adabas parameters, 8.2.2

configuring properties, 2.2.3, 5.2.1.3, 5.2.2.2, 5.2.3.2, 8.2.2

defining Adabas connection, 8.2.1

defining IMS/DB DBCTL connection, 5.2.2, 5.2.2.1

defining IMS/DB DBDC connection, 5.2.3, 5.2.3.1

defining IMS/DB DLI connection, 5.2.1, 5.2.1.2

defining VSAM connection, 2.2.1

IMS/DB DBCTL parameters, 5.2.2.2

IMS/DB DBDC parameters, 5.2.3.2

IMS/DB DLI parameters, 5.2.1.3

setting up Adabas, 8.2

setting up IMS, 5.2

setting up VSAM, 2.2

VSAM parameters, 2.2.3.1

database links, behavior, 4.4, 7.4, 10.4

defining

IMS/DB DBCTL data sources, 5.2.2

IMS/DB DBDC data sources, 5.2.3

E

error tracing, B.17

exporting Predict metadata, 8.3.2

F

file names, assigning, 2.4.5, 2.4.6

filters, applying, 2.3.2, 2.4.2, 5.3.2

G

gateways

configuring, 4.1, 7.1, 10.1

default SID, 4.1.1, 7.1.1, 10.1.1

global transactions, 4.7.1, 7.7.1

system identifier (SID), 4.1.1, 7.1.1, 10.1.1

global transactions

configuring, 4.7.1, 7.7.1

H

HS_FDS_ACCESS_METHOD initialization parameter, B.21

HS_FDS_CONNECT_INFO initialization parameter, B.13

HS_FDS_DATASOURCE_NAME initialization parameter, B.20

HS_FDS_PARSER_TOKEN_SIZE initialization parameter, B.14

HS_FDS_RECOVERY_ACCOUNT initialization parameter, B.15

HS_FDS_RECOVERY_PWD initialization parameter, B.16

HS_FDS_TRACE_LEVEL initialization parameter, B.17

HS_LANGUAGE initialization parameter, B.6

I

imported records, manipulating, 5.3.5

imported tables, manipulating, 2.3.4, 2.4.4

importing metadata, 2.3.7, 2.4.8, 5.3.7, 8.3.1

IMS

accessing data under CICS, 5.2.1.1, 5.2.2.3

accessing data under IMS/TM, 5.2.3.3

configuring data access, 5

configuring data source properties, 5.2.1.3, 5.2.2.2, 5.2.3.2

data source parameters, 5.2.1.3, 5.2.2.2, 5.2.3.2

defining data source connection, 5.2.1, 5.2.1.2, 5.2.2, 5.2.2.1, 5.2.3, 5.2.3.1

importing metadata, 5.3.7

manipulating imported records, 5.3.5

matching DBD to COBOL, 5.3.4

selecting metadata filters, 5.3.2

selecting metadata input files, 5.3.1

selecting metadata model, 5.3.6

selecting tables, 5.3.3

setting up data source, 5.2

setting up metadata, 5.3

IMS data sources, setting up metadata, 5.3

IMS/DB DBCTL data sources

defining, 5.2.2

installing, 5.2.2

IMS/DB DBDC data sources

defining, 5.2.3

installing, 5.2.3

initialization parameter file, customizing, 4.1.2, 7.1.2, 10.1.2

initialization parameters

customizing, B

HS_FDS_CONNECT_INFO, B.13

HS_FDS_DATASOURCE_NAME, B.20

HS_FDS_PARSER_TOKEN_SIZE, B.14

HS_FDS_RECOVERY_ACCOUNT, B.15

HS_FDS_RECOVERY_PWD, B.16

HS_FDS_TRACE_LEVEL, B.17

HS_LANGUAGE, B.6

initsid.ora file, 4.1.2, 7.1.2, 10.1.2, B

installing

IMS/DB DBCTL data sources, 5.2.2

IMS/DB DBDC data sources, 5.2.3

L

listener.ora file

adding entries, 4.6.2, 7.6.2, 10.6.2

example, 4.2.1.2, 7.2.1.2, 10.2.1.2

location, 4.2.1, 7.2.1, 10.2.1

M

manipulating imported records, 5.3.5

manipulating imported tables, 2.3.4, 2.4.4

matching DBD to COBOL files

matching to DBD, 5.3.4

metadata

Adabas, 8.3

applying filters, 2.3.2, 2.4.2, 5.3.2

assigning file names, 2.4.5, 2.4.6

exporting into Adabas ADD, 8.3.2

importing, 2.3.7, 2.4.8, 5.3.7

importing from DDM files, 8.3.1

IMS/DB, 5.3

manipulating imported records, 5.3.5

manipulating imported tables, 2.3.4, 2.4.4

matching DBD to COBOL, 5.3.4

selecting input files, 2.3.1, 2.4.1, 5.3.1

selecting model, 2.3.6, 2.4.7, 5.3.6

selecting tables, 2.3.3, 2.4.3, 5.3.3

VSAM, 2.3, 2.4

metadata, defining for IMS data sources, 5.3

N

names, assigning to files, 2.4.5, 2.4.6

O

Oracle Connect for IMS, VSAM, and Adabas Gateways, setting up access, 2.1, 5.1, 8.1

Oracle Net Listener

configuring, 4.2.1, 7.2.1, 10.2.1

starting, 4.2.2, 7.2.2, 10.2.2

Oracle Net Services, configuring, 4.2, 7.2, 10.2

P

Predict metadata, exporting, 8.3.2

R

recovery account, creating, 4.7.2, 7.7.2, 10.7.2, 10.7.2

S

selecting metadata input files, 2.3.1, 2.4.1, 5.3.1

selecting metadata model, 2.3.6, 2.4.7, 5.3.6

selecting tables, 2.3.3, 2.4.3, 5.3.3

servers

Reuse limit daemon parameter, 13.3.2.2

setting up

Adabas data source, 8.2

Adabas metadata, 8.3

daemon workspace, 5.2.1.1

IMS data source, 5.2

IMS/DB metadata, 5.3

VSAM data source, 2.2

VSAM metadata, 2.3, 2.4

SID, 4.1.1, 7.1.1, 10.1.1

T

tables

manipulating, 2.3.4, 2.4.4

manipulating records, 5.3.5

selecting, 2.3.3, 2.4.3, 5.3.3

two-phase commit

See global transactions

V

VSAM

accessing data under CICS, 2.2.2

assigning file names, 2.4.5, 2.4.6

configuring data access, 2

configuring data source properties, 2.2.3

data source parameters, 2.2.3.1

data source, 2.2.3.2

defining data source connection, 2.2.1

importing metadata, 2.3.7, 2.4.8

manipulating imported tables, 2.3.4, 2.4.4

selecting metadata filters, 2.3.2, 2.4.2

selecting metadata input files, 2.3.1, 2.4.1

selecting metadata model, 2.3.6, 2.4.7

selecting tables, 2.3.3, 2.4.3

setting up data source, 2.2

setting up metadata, 2.3, 2.4

W

Workspace server mode, 13.3.2.2

Copyright © 2008, 2010, Oracle and/or its affiliates. All rights reserved.