Contents

Title and Copyright Information

Preface

Audience

Documentation Accessibility

Related Documents

Conventions

1 Getting Started with Oracle Database Gateway

Overview

Oracle Heterogeneous Services

Oracle Database Gateways

Gateway Architecture

Gateway Process Flow

Setup Flow

2 Installing Oracle Connect for IMS, VSAM, and Adabas Gateways

Overview of Oracle Database Gateway for IMS, VSAM, and Adabas

System Requirements for Oracle Connect for IMS, VSAM, and Adabas Gateways

Hardware Requirements for Oracle Connect for IMS, VSAM, and Adabas Gateways

Software Requirements for Oracle Connect for IMS, VSAM, and Adabas Gateways

Accessing the Installation Software

Downloading Oracle Software from the Oracle Technology Network Web Site

Downloading the Installation Archive File

Extracting the Installation Files

Copying the Oracle Software to a Hard Disk

Mounting Discs

Installing Oracle Connect for IMS, VSAM, and Adabas Gateways

Installation Worksheet

Preinstallation Instructions

Kit Installation Instructions

Transferring the Kit to the Dataset

Installation Instructions

Data Source Configuration Instructions

Postinstallation Instructions

Postinstallation Tasks

Starting the Daemon

Setting Up Oracle Connect for IMS, VSAM, and Adabas Gateways for Reentrancy

Configuring Additional Settings for Working with CICS

Configuring OTMA for Working with IMS/TM

Setting Up Oracle Connect for IMS, VSAM, and Adabas Gateways to Update VSAM, IMS, or Adabas Data

3 Troubleshooting Oracle Connect for IMS, VSAM, and Adabas Gateways

Troubleshooting Overview

Troubleshooting Methods

Using the NAV_UTIL CHECK SERVER Utility

Using the NAV_UTIL CHECK DATASOURCE Utility

Using Trace Log Files

Log Traces

Common Errors and Solutions

A Using NAV_UTIL Utility

Running NAV_UTIL

Activating NAV_UTIL

Basic NAV_UTIL Syntax

ADD_ADMIN

CHECK

check irpcd

check network [port]

check irpcdstat

check tcpip

check server

check license

check datasource

DELETE

Deleting Data Source Objects

EDIT

EXECUTE

EXECUTE Overview

Running SQL Statements

On-the-fly

From a File

From within a Transaction

EXECUTE Commands

EXPORT

GEN_ARRAY_TABLES

IMPORT

IMS_MERGE

IRPCDCMD

LOCAL_COPY

PASSWORD

SVC

TEST

UPDATE

Removing Metadata Statistics

UPD_DS

UPD_SEC

VERSION

VERSION_HISTORY

VIEW

XML

XML Samples

Index

Oracle® Connect for IMS, VSAM, and Adabas Gateways

Installation and Configuration Guide

11g Release 2 (11.2) for IBM z/OS

E12075-01

July 2009

Oracle Connect for IMS, VSAM, and Adabas Gateways Installation and Configuration Guide, 11g Release 2 (11.2) for IBM z/OS

E12075-01

Copyright © 2008, 2009, 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 Connect for IMS, VSAM, and Adabas Gateways, a prebuilt driver to mainframe data. Oracle Connect for IMS, VSAM, and Adabas Gateways is located natively on the data server to provide standard, service-oriented integration to data sources on z/OS platforms. With robust support for metadata, bi-directional read/write access, and transaction management, Oracle Connect for IMS, VSAM, and Adabas Gateways simplifies and reduces the cost of legacy integration.

Audience

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

Installing Oracle Connect for IMS, VSAM, and Adabas Gateways

Configuring and managing Oracle Connect for IMS, VSAM, and Adabas Gateways

Troubleshooting Oracle Connect for IMS, VSAM, and Adabas Gateways

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.

Deaf/Hard of Hearing Access to Oracle Support Services

To reach Oracle Support Services, use a telecommunications relay service (TRS) to call Oracle Support at 1.800.223.1711. An Oracle Support Services engineer will handle technical issues and provide customer support according to the Oracle service request process. Information about TRS is available at http://www.fcc.gov/cgb/consumerfacts/trs.html, and a list of phone numbers is available at http://www.fcc.gov/cgb/dro/trsphonebk.html.

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.

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 extend 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 VSAM, IMS, and Adabas allow Oracle client applications to access VSAM, IMS, 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 VSAM, IMS, 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 VSAM, IMS, or Adabas 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 machine as the gateway or on another machine.

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 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

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

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

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

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.

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

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

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

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.

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

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.

Install Oracle Connect for IMS, VSAM, and Adabas Gateways

See:

Chapter 2, "Installing Oracle Connect for IMS, VSAM, and Adabas Gateways" for information on installing Oracle Connect for IMS, VSAM, and Adabas Gateways

Install Oracle Studio for IMS, VSAM, and Adabas Gateways

See:

Oracle Database Gateway for IMS, VSAM, and Adabas Installation and Configuration Guide for Microsoft Windows or Oracle Database Gateway for IMS, VSAM, and Adabas Installation and Configuration Guide for AIX 5L Based Systems (64-Bit), HP-UX Itanium, Solaris Operating System (SPARC 64-Bit), Linux x86, and Linux x86-64

Configure Oracle Connect for IMS, VSAM, and Adabas Gateways

See:

Oracle Database Gateway for IMS, VSAM, and Adabas Installation and Configuration Guide for Microsoft Windows or Oracle Database Gateway for IMS, VSAM, and Adabas Installation and Configuration Guide for AIX 5L Based Systems (64-Bit), HP-UX Itanium, Solaris Operating System (SPARC 64-Bit), Linux x86, and Linux x86-64

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

See:

Oracle Database Gateway for IMS, VSAM, and Adabas Installation and Configuration Guide for Microsoft Windows or Oracle Database Gateway for IMS, VSAM, and Adabas Installation and Configuration Guide for AIX 5L Based Systems (64-Bit), HP-UX Itanium, Solaris Operating System (SPARC 64-Bit), Linux x86, and Linux x86-64

Set up the VSAM, IMS, or Adabas data source

See:

Oracle Database Gateway for IMS, VSAM, and Adabas Installation and Configuration Guide for Microsoft Windows or Oracle Database Gateway for IMS, VSAM, and Adabas Installation and Configuration Guide for AIX 5L Based Systems (64-Bit), HP-UX Itanium, Solaris Operating System (SPARC 64-Bit), Linux x86, and Linux x86-64

Set up the data source metadata

See:

Oracle Database Gateway for IMS, VSAM, and Adabas Installation and Configuration Guide for Microsoft Windows or Oracle Database Gateway for IMS, VSAM, and Adabas Installation and Configuration Guide for AIX 5L Based Systems (64-Bit), HP-UX Itanium, Solaris Operating System (SPARC 64-Bit), Linux x86, and Linux x86-64

Install Oracle Database Gateway for VSAM, IMS, or Adabas

See:

Oracle Database Gateway for IMS, VSAM, and Adabas Installation and Configuration Guide for Microsoft Windows or Oracle Database Gateway for IMS, VSAM, and Adabas Installation and Configuration Guide for AIX 5L Based Systems (64-Bit), HP-UX Itanium, Solaris Operating System (SPARC 64-Bit), Linux x86, and Linux x86-64

Configure Oracle Database Gateway for VSAM, IMS, or Adabas

See:

Oracle Database Gateway for IMS, VSAM, and Adabas Installation and Configuration Guide for Microsoft Windows or Oracle Database Gateway for IMS, VSAM, and Adabas Installation and Configuration Guide for AIX 5L Based Systems (64-Bit), HP-UX Itanium, Solaris Operating System (SPARC 64-Bit), Linux x86, and Linux x86-64

2 Installing Oracle Connect for IMS, VSAM, and Adabas Gateways

This chapter guides you through the installation procedure of Oracle Connect for IMS, VSAM, and Adabas Gateways.

To install Oracle Connect for IMS, VSAM, and Adabas Gateways, follow these steps:

Ensure that the system meets all of the hardware and software requirements specified in "System Requirements for Oracle Connect for IMS, VSAM, and Adabas Gateways".

Install Oracle Connect for IMS, VSAM, and Adabas Gateways. See "Installing Oracle Connect for IMS, VSAM, and Adabas Gateways" for instructions.

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

You configure Oracle Connect for IMS, VSAM, and Adabas Gateways through Oracle Studio for IMS, VSAM, and Adabas Gateways. See Oracle Database Gateway for IMS, VSAM, and Adabas Installation and Configuration Guide for Microsoft Windows or Oracle Database Gateway for IMS, VSAM, and Adabas Installation and Configuration Guide for AIX 5L Based Systems (64-Bit), HP-UX Itanium, Solaris Operating System (SPARC 64-Bit), Linux x86, and Linux x86-64 for details.

Overview of Oracle Database Gateway for IMS, VSAM, and Adabas

Oracle Database Gateway for IMS, VSAM, and 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 IMS, VSAM, and Adabas. 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 machine as the Oracle database server or a second, standalone machine.

System Requirements for Oracle Connect for IMS, VSAM, and Adabas Gateways

This section provides information about the hardware and software requirements for Oracle Connect for IMS, VSAM, and Adabas Gateways. It contains the following sections:

"Hardware Requirements for Oracle Connect for IMS, VSAM, and Adabas Gateways"

"Software Requirements for Oracle Connect for IMS, VSAM, and Adabas Gateways"

Hardware Requirements for Oracle Connect for IMS, VSAM, and Adabas Gateways

Table 2-1 lists the hardware requirements for Oracle Connect for IMS, VSAM, and Adabas Gateways.

Table 2-1 System Requirements for Oracle Connect for IMS, VSAM, and Adabas Gateways

Requirement | Value
Processor | An IBM mainframe computer
Memory | The minimum requirement is 4 MB for each connection. A connection is defined as a connection to a server process or daemon. The actual memory requirement depends on such things as the size of the database and the number of databases accessed.
Disk Space (3380 and 3390 disks) | 150 cylinders.

Software Requirements for Oracle Connect for IMS, VSAM, and Adabas Gateways

Table 2-2 lists the software requirements for Oracle Connect for IMS, VSAM, and Adabas Gateways.

Table 2-2 System Requirements for Oracle Connect for IMS, VSAM, and Adabas Gateways

Requirement | Value
Operating System | IBM z/OS Series Version 1.8 or higher
IMS/DB | Versions 8.1 or later OTMA and OTMA C/I Note: OTMA C/I requires OTMAINIT to be executed.

IMS/DBCTL Access

CICS version 4.1 or later

CICS Transaction Server version 1.3 or later

OTMA and OTMA C/I

Note: OTMA C/I requires OTMAINIT to be executed.

IMS/TM | OTMA and OTMA C/I Note: OTMA C/I requires OTMAINIT to be executed.
AdabasFoot 1  | Adabas MVS versions 6.2 or later

CICS TP Monitor (when accessing VSAM or IMS/DB data under CICS)

V4R1 or higher (recommended to use CICS V6R1 or later).

CICS EXCI support must be installed and IRCSTRT=YES must be specified in the CICS initialization parameters, so that the IRC (Inter Region Communication) starts.

You can also set the IRC to open by issuing the following command: CEMT SET IRC OPEN. Also the IBM group DFH$EXCI (or an equivalent user-defined group) must be installed in the CICS region - using the CEDA RDO facility.

Oracle Database Gateway | Oracle Database Gateway 11g Release 2 (11.2.0).

Footnote 1 Oracle certifies its connectivity with the versions listed explicitly. Backward compatibility of higher versions relies on SoftwareAG's backward compatibility policies.

Accessing the Installation Software

You can access Oracle Connect for IMS, VSAM, and Adabas Gateways by using one of the following methods:

Download the software from OTN. Refer to Downloading Oracle Software from the Oracle Technology Network Web Site for details.Copy the software to a hard disk. Refer to Copying the Oracle Software to a Hard Disk for details.

Downloading Oracle Software from the Oracle Technology Network Web Site

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

Downloading the Installation Archive File

Extracting the Installation Files

Downloading the Installation Archive File

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

Use any browser to access the software download page on OTN:

http://www.oracle.com/technology/software

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

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.

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 all of the archive files.

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.

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

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

Extracting the Installation Files

To extract the installation archive files:

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

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

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 Oracle Software to a Hard Disk

Before installing Oracle Connect for IMS, VSAM, and Adabas Gateways, you might want to copy the software to the hard disk. This enables the installation process to run a bit faster. Before copying the installation media content to the hard disk, you must mount the installation media. The following section describes how to mount discs and copy their content to the hard disk.

Mounting Discs

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:

Enter the following command to switch user to root:

$ su - root

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.

Insert the appropriate disc into the disc drive.

To verify that the disc mounted automatically, enter a command similar to the following, depending on your platform:

Sun Solaris (SPARC):

# ls /cdrom/cdrom0

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.

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 as the following file:

/gateways/legacy/Connect/Connect.zip

You can unzip this file on any machine. It includes the following files:

transmit.kit

transmit.load

brand.bin

Installing Oracle Connect for IMS, VSAM, and Adabas Gateways

This section explains how to install Oracle Connect for IMS, VSAM, and Adabas Gateways from the CD-ROM. This section includes the following topics:

Installation Worksheet

Preinstallation Instructions

Kit Installation Instructions

Installation Instructions

Data Source Configuration Instructions

Postinstallation Instructions

Note:

The back-end database gateways that run on an IBM z/OS platform are:

Oracle Database Gateway for VSAM

Oracle Database Gateway for IMS/DB

Oracle Database Gateway for Adabas

Installation Worksheet

Verify that you have all the information detailed in Table 2-3 so you can refer to it during the configuration process.

Table 2-3 Preinstallation Information

Topic | Required Information | Default | Comment
General | Operating system | - | IBM z/OS Version 1.8 or higher
- | Disk space | - | 150 cylinders
- | Memory | - | The minimum requirement is 4 MB for each connection. A connection is defined as a connection to a server process or daemon. The actual memory requirement depends on such things as the size of the database and the number of databases accessed.
- | Installation high-level qualifier | AC10131 | -
- | Volume | - | -
- | Unit | 3390 | SMS only: unit where SMS is located.
- | Output class | A | -
- | JCL job card | - | An optional card (up to 6 lines) to replace the prefix job (entered as it will appear in the job)
- | ISPF load library name | ISP.SISPLOAD | -
CICS | CICS EXCI load library name | CICS.CICS.SDFHEXCI | To access VSAM or IMS/DB data under CICS

Preinstallation Instructions

Before starting the installation, make sure that you have the following information available:

The output class for the installation output if you do not want to use the default value A.

If you use SMS to manage all datasets, then you cannot provide unit and volume information, which is the unit where SMS is located.

Before starting the installation, make sure that you have the following permissions:

Permission to define an APF-authorized library.

Permission to write to an active proclib, such as user.proclib.

Permission to read the CICS EXCI library when accessing data under CICS.

Permission to update the security manager, such as RACF.

Optionally, permission to specify an output class for Oracle Connect for IMS, VSAM, and Adabas Gateways output. Assigning a device that is set on HOLD prevents the loss of log information when the started tasks of Oracle Connect for IMS, VSAM, and Adabas Gateways finish.

Oracle Connect for IMS, VSAM, and Adabas Gateways for the IBM z/OS platform is included in the following datasets:

[INSTROOT].TRANSMIT.KIT

[INSTROOT].TRANSMIT.LOAD

where INSTROOT is the high-level qualifier of the installation, such as AC10131.

Kit Installation Instructions

Perform the following on the mainframe:

Run the following command:

tso profile noprefix

The user name will not be used as part of the dataset name. On some systems this is the default.

Allocate datasets with the following space for each of these files:

[INSTROOT].TRANSMIT.KIT = 130 tracks (3380 and 3390 disks)

[INSTROOT].TRANSMIT.LOAD = 500 tracks (3380 and 3390 disks)

For each dataset: RECFM=FB and LRECL=80. The block size is 3120.

Transferring the Kit to the Dataset

You need to move the contents of the kit to the mainframe computer in the dataset that you allocated. When you copy the contents of the kit, you will see that the contents are now utilized.

Perform the following steps to copy the Oracle Connect for IMS, VSAM, and Adabas Gateways installation kit contents to the mainframe:

Extract the compressed file to a folder on a computer running Microsoft Windows.

Open the Command console on the Windows computer.

Type FTP and the name of the mainframe computer where you want to connect. This creates an FTP connection to the mainframe machine. You may have to enter a user name and password to use the machine.

Type bin to transfer binary data.

Enter the following command to transfer the data from the .KIT file to the mainframe computer:

put transmit.kit '[INSTROOT].transmit.kit' (replace

where:

transmit.kit is the name of your installation file.

(replace ensures that any data on the volume where the kit is installed is overwritten.

Enter the following command to transfer the data from the .LOAD file to the mainframe computer:

put transmit.load '[INSTROOT].transmit.load' (replace

Close the FTP connection.

Installation Instructions

Perform the following steps to install Oracle Connect for IMS, VSAM, and Adabas Gateways:

From within TSO, run the following command at the TSO prompt:

RECEIVE INDSNAME('INSTROOT.TRANSMIT.KIT')

where INSTROOT represents the high-level qualifier you want to assign to the Oracle Connect for IMS, VSAM, and Adabas Gateways installation. The default value is AC10131.

Note:

You can use more than one high-level qualifier (such as ACME.DEV.AC10131) with the following conditions:

The total length must be less than twenty characters.

The words transmit and buildkit cannot be used as high-level qualifiers.

Enter the following command when prompted for the restore parameters:

da('INSTROOT.TRANSMIT.LIB') [UNIT (unit), VOLUME (volume)]

This extracts the INSTROOT.TRANSMIT.LIB library from the INSTROOT.TRANSMIT.KIT kit to the specified unit and volume. If a unit and volume are not specified, the library is extracted to the current unit and volume.

Run the PREPARE member of the [INSTROOT].TRANSMIT.LIB library:

ex PREPARE

Follow the instructions in the Response column in Table 2-4 for each entry in the Screen column.

Table 2-4 Installation Prepare Job Prompts and Responses

Screen | Response
DO YOU WANT TO USE SMS MANAGED STORAGE FOR THIS INSTALLATION Y/N [N]: | If you want to manage the storage using SMS, answer Y, otherwise answer N.
ENTER THE STORCLASS FOR INSTALLATION TEMP DATASETS [ ]: | This prompt is displayed only if SMS is used to manage the installation (you answered Y to the first prompt). Enter the storage class
ENTER THE UNIT NAME FOR INSTALLATION TEMP DATASETS [3390]: | If a storage class is not specified, then enter the unit name for temporary datasets used during the installation procedure
ENTER THE VOLUME NAME FOR INSTALLATION TEMP DATASETS: | This prompt is displayed only if SMS is not used to manage the installation (you answered N to the first prompt). The volume name for temporary datasets used during the installation procedure
ENTER THE OUTPUT CLASS FOR INSTALLATION OUTPUT [A]: | Enter the output class only if you do not want the default class used (the default is A)
DO YOU WANT TO USE THE DEFAULT JOB CARD Y/N [Y]: | A job card is displayed. If you want to use a replacement card, then it must be entered as it will appear in the job. You can enter up to six lines. Enter a blank card to end input. If you do not enter a card, then the Oracle Connect for IMS, VSAM, and Adabas Gateways default card is used.
DO YOU WANT TO PERFORM A MANUAL (M) OR AUTOMATIC (A) INSTALLATION [A]: | If you want to review the JCL used to install Oracle Connect for IMS, VSAM, and Adabas Gateways before it is submitted, then respond M for a manual installation.
PLEASE REVIEW AND SUBMIT FOR EXECUTION THE HLQ.TRANSMIT.LIB(INSTJO) | This prompt is displayed only if a manual installation is requested (you answered M to the previous prompt).

The following libraries are generated:

INSTROOT.BUILDKIT.LOAD
INSTROOT.BUILDKIT.SRC
INSTROOT.BUILDKIT.GENDEMO

Where INSTROOT is the high-level qualifier you assigned in step 0.

In the INSTROOT.BUILDKIT.SRC library, run the NAVINST member:

ex NAVINST

Follow the instructions in the Response column in Table 2-5 for each entry in the Screen column.

Table 2-5 Installation Prompts and Responses

Screen | Response
DO YOU WANT TO USE SMS MANAGED STORAGE FOR THIS INSTALLATION Y/N [N]: | If you want to manage the storage using SMS, then answer Y, otherwise answer N.

THE SOFTWARE WILL BE INSTALLED UNDER THE HIGH LEVEL QUALIFIER THAT YOU WILL CHOOSE.

ENTER THE HIGH LEVEL QUALIFIER ["QUALIFIER"]:

This prompt is displayed only if SMS is used to manage the installation (you answered Y to the first prompt).

The high-level qualifier for the installation (referred to as INSTROOT throughout this guide).

You can use more than one high-level qualifier (such as ACME.DEV.VA10). The total length must be less than or equal to twenty characters. The qualifiers can be the same as the ones used for the installation (step 0).

The words "transmit" and "buildkit" cannot be used as high-level qualifiers.

ENTER THE STORCLASS FOR TEMP DATASETS ['STORCLASS']: | This prompt is displayed only if SMS is used to manage the installation (you answered Y to the first prompt). Enter the storage class.
ENTER THE UNIT NAME FOR INSTALLATION TEMP DATASETS [3390]: | The unit name for temporary datasets used during the installation procedure.
ENTER THE VOLUME NAME FOR INSTALLATION TEMP DATASETS: | This prompt is displayed only if SMS is not used to manage the installation (you answered N to the first prompt). The volume name for temporary datasets used during the installation procedure.
PLEASE CONFIRM (YES/NO/QUIT) [YES]: | Confirm the entered details.
ENTER THE OUTPUT CLASS FOR INSTALLATION OUTPUT [A]: | Enter the output class for Oracle Connect for IMS, VSAM, and Adabas Gateways output. Assigning a device that is set on HOLD prevents the loss of log information when the Oracle Connect for IMS, VSAM, and Adabas Gateways started tasks finish (the default is A).

ADDING AND UPDATING ORACLE CONNECT CONFIGURATION ON THIS MACHINE, FROM A REMOTE ORACLE ADMINISTRATION CONSOLE, CAN ONLY BE DONE BY SOMEONE DEFINED AS AN ADMINISTRATOR FOR ORACLE CONNECT ON THIS MACHINE.

ENTER A VALID USER NAME FOR AN ORACLE CONNECT ADMINISTRATOR [ALL]:

To manage Oracle Connect for IMS, VSAM, and Adabas Gateways on this computer from Oracle Studio for IMS, VSAM, and Adabas Gateways, you need to enter a user account of a user who will have administrative authorization, or press Enter to enable any user to administer Oracle Connect for IMS, VSAM, and Adabas Gateways on this computer. The administrative rights can be changed from within Oracle Studio for IMS, VSAM, and Adabas Gateways after the installation.

DO YOU WANT TO USE THE DEFAULT JOB CARD Y/N [Y] | A job card is displayed. If you want to use a replacement card, then it must be entered as it will appear in the job. You can enter up to six lines. Enter a blank card to end input. If you do not enter a card, then the Oracle Connect for IMS, VSAM, and Adabas Gateways default card is used.
DO YOU WANT TO PERFORM A MANUAL (M) OR AUTOMATIC (A) INSTALLATION [A]: | If you want to review the JCL used to install Oracle Connect for IMS, VSAM, and Adabas Gateways, before it is submitted, then respond M for a manual installation.
PLEASE REVIEW AND SUBMIT FOR EXECUTION THE DSN1 (INSTJBOR) | This prompt is displayed only if a manual installation is requested (you answered M to the previous prompt). DSN1 is the dataset name where INSTJBOR is located.

Data Source Configuration Instructions

Perform the following steps to configure the different data sources:

In the INSTROOT.BUILDKIT.SRC library, run the following command:

ex CUSTOCL

Follow the instructions on the screen.

See Table 2-6 for installation prompts and responses when configuring the VSAM data source.

See Table 2-7 for installation prompts and responses when configuring the IMS/DB data source.

See Table 2-8 for installation prompts and responses when configuring the Adabas data source.

Table 2-6 VSAM Gateway-Specific Installation Prompts and Responses

Screen | Response
ORACLE CONNECT ADAPTERS CUSTOMIZATION HLQ IS [TEST.OR5021]: | Specify the high-level qualifier of the installation.
DO YOU WANT ORACLE CONNECT TO WORK WITH ADABAS (YES/NO) [YES]: | Answer NO to this prompt.
DO YOU WANT ORACLE CONNECT TO WORK WITH IMS/DB (YES/NO) [NO]: | Answer NO to this prompt.
DO YOU WANT ORACLE CONNECT TO WORK WITH CICS APP ADAPTER (YES/NO) [YES]: | Answer NO to this prompt.
THE VSAM DRIVER IS INSTALLED AUTOMATICALLY. DO YOU ALSO WANT ORACLE CONNECT TO WORK WITH VSAM UNDER CICS (YES/NO) [NO]: | If you want to access VSAM data under CICS, answer YES to this prompt.
ENTER THE CICS EXCI LOAD LIBRARY NAME [CICSTS13.CICS.SDFHEXCI]: | This prompt is displayed only if you answered YES to the previous prompt. Enter the EXCI LOAD library name only if you do not want to use the default.
PLEASE CONFIRM (YES/NO/QUIT) [YES]: | Confirm the entered details.
ENTER THE ISPF LOAD LIBRARY NAME [ISP.SISPLOAD]: | Enter the ISPF load library name only if you do not want to use the default.
PLEASE CONFIRM (YES/NO/QUIT) [YES]: | Confirm the entered details.
ENTER THE OUTPUT CLASS FOR INSTALLATION OUTPUT [A]: | Enter the output class character for the job automatically generated for the installation process.
DO YOU WANT TO USE THE DEFAULT JOB CARD (Y/N) [Y]: | A job card is displayed. If you want to use a replacement card, then it must be entered as it will appear in the job. You can enter up to six lines. Enter a blank card to end input. If you do not enter a card, then the Oracle Connect for IMS, VSAM, and Adabas Gateways default card is used.

Table 2-7 IMS/DB Gateway-Specific Installation Prompts and Responses

Screen | Response
ORACLE CONNECT ADAPTERS CUSTOMIZATION HLQ IS: | Specify the high-level qualifier of the installation.
DO YOU WANT ORACLE CONNECT TO WORK WITH ADABAS (YES/NO) [YES]: | Answer NO to this prompt.
DO YOU WANT ORACLE CONNECT TO WORK WITH IMS/DB (YES/NO) [NO] | Answer YES to this prompt.
ENTER DBD LIBRARY NAME [IMS.DBDLIB]: | Enter the IMS DBD library name for IMS on your system only if you do not want to use the default.
ENTER PSB LIBRARY NAME [IMS.PSBLIB]: | Enter the IMS PSB library name for IMS on your system only if you do not want to use the default.
ENTER RES LIBRARY NAME [IMS.SDFRESL]: | Enter the IMS RES library name for IMS on your system only if you do not want to use the default.
ENTER PROC LIBRARY NAME [IMS.PROCLIB]: | Enter the IMS PROC library name for IMS on your system only if you do not want to use the default.
ENTER PGM LIBRARY NAME [IMS.PGMLIB] | Enter the IMS PGM library name for IMS on your system only if you do not want to use the default.
ENTER YOUR PSB NAME [HOSPPSB]: | Enter the PSB name only if you do not want to use the default.
PLEASE CONFIRM (YES/NO/QUIT) [YES]: | Confirm the entered details.
DO YOU WANT ORACLE CONNECT TO WORK WITH CICS TO ACCESS IMS/DB OR VSAM (YES/NO) [NO]: | If you want to access IMS/DB data under CICS, answer YES to this prompt.
ENTER THE CICS EXCI LOAD LIBRARY NAME [CICSTS13.CICS.SDFHEXCI]: | This prompt is displayed only if you answered YES to the previous prompt. Enter the EXCI LOAD library name only if you do not want to use the default.
PLEASE CONFIRM (YES/NO/QUIT) [YES]: | Confirm the entered details.
DO YOU WANT ORACLE CONNECT SERVER TO WORK WITH CICS APP ADAPTER (YES/NO) [YES]: | Answer NO to this prompt.
ENTER THE ISPF LOAD LIBRARY NAME [ISP.SISPLOAD]: | Enter the ISPF load library name only if you do not want to use the default.
PLEASE CONFIRM (YES/NO/QUIT) [YES]: | Confirm the entered details.
ENTER THE OUTPUT CLASS FOR INSTALLATION OUTPUT [A]: | Enter the output class character for the job automatically generated for the installation process.
DO YOU WANT TO USE THE DEFAULT JOB CARD (Y/N) [Y]: | A job card is displayed. If you want to use a replacement card, then it must be entered as it will appear in the job. You can enter up to six lines. Enter a blank card to end input. If you do not enter a card, then the Oracle Connect for IMS, VSAM, and Adabas Gateways default card is used.

Table 2-8 Adabas Gateway-Specific Installation Prompts and Responses

Screen | Response
ADAPTERS CUSTOMIZATION HLQ IS: | Specify the high-level qualifier of the installation.
DO YOU WANT ORACLE CONNECT TO WORK WITH ADABAS (YES/NO) [NO]: | Answer YES to this prompt.
ENTER THE ADABAS SVC NUMBER [249]: | Enter the SVC number only if you do not want to use the default number.
ENTER THE ADABAS DATABASE NUMBER: | Enter the number of the Adabas database.
ENTER THE ADABAS LOAD LIBRARY NAME [ADA622.LOAD]: | Enter the Adabas load library name only if you do not want to use the default library.
ENTER THE UNIT FOR ADABAS LOAD LIBRARY [3390]: | Enter the unit only if you do not want to use the default library. The unit to use is the number that you prepared during the preinstallation.
PLEASE CONFIRM (YES/NO/QUIT) [YES]: | Confirm the entered details.
DO YOU WANT ORACLE CONNECT TO WORK WITH IMS/DB (YES/NO) [YES]: | Answer NO to this prompt.
DO YOU WANT ORACLE CONNECT TO WORK WITH CICS APP ADAPTER (YES/NO) [YES]: | Answer NO to this prompt.
THE VSAM DRIVER IS INSTALLED AUTOMATICALLY. DO YOU ALSO WANT ORACLE CONNECT TO WORK WITH VSAM UNDER CICS (YES/NO) [NO]: | Answer NO to this prompt.
ENTER THE ISPF LOAD LIBRARY NAME [ISP.SISPLOAD]: | Enter the ISPF load library name only if you do not want to use the default.
PLEASE CONFIRM (YES/NO/QUIT) [YES]: | Confirm the entered details.
ENTER THE OUTPUT CLASS FOR INSTALLATION OUTPUT [A]: | Enter the output class character for the job automatically generated for the installation process.
DO YOU WANT TO USE THE DEFAULT JOB CARD (Y/N) [Y]: | A job card is displayed. If you want to use a replacement card, then it must be entered as it will appear in the job. You can enter up to six lines. Enter a blank card to end input. If you do not enter a card, then the Oracle Connect for IMS, VSAM, and Adabas Gateways default card is used.

The installation is completed. All JCL jobs and REXX procedures are included in the INSTROOT.USERLIB library. INSTROOT is the high-level qualifier for the installation.

Postinstallation Instructions

The following postinstallation tasks must be done to work with Oracle Connect for IMS, VSAM, and Adabas Gateways:

Postinstallation Tasks

Starting the Daemon

Setting Up Oracle Connect for IMS, VSAM, and Adabas Gateways for Reentrancy

Configuring Additional Settings for Working with CICS

Configuring OTMA for Working with IMS/TM

Setting Up Oracle Connect for IMS, VSAM, and Adabas Gateways to Update VSAM, IMS, or Adabas Data

Postinstallation Tasks

Perform the following tasks after completing the installation to configure Oracle Connect for IMS, VSAM, and Adabas Gateways:

Allocate a dataset for INSTROOT.DEF.BRANDBIN, using 1 track and with RECFM=VB and LRECL=256. The block size is 6233.

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

Using FTP, copy the brand.bin file to INSTROOT.DEF.BRANDBIN on the mainframe in binary.

Change the following line in the ATTDAEMN script to include the IP address and port of the IBM z/OS platform.

For example, before:

// PARM='-B START IRPCDINI'

After:

// PARM='-B -L ip_address:2551 START IRPCDINI'

Where ip_address is the IP address of the computer, 2551 is the default port for starting the daemon and IRPCDINI is the default daemon configuration.

Move the INSTROOT.USERLIB(ATTDAEMN) and INSTROOT.USERLIB(ATTSRVR) members to any active proclib (such as user.proclib). ATTDAEMN and ATTSRVR are run as started tasks.

If you decide to change the name of the ATTSRVR member when you move it to a general high-level qualifier, then change the name specified in the StartupScript parameter in the daemon configuration to the new name:

Run INSTROOT.USERLIB(NAVCMD) and enter EDIT DAEMON IRPCDINI at the prompt.

Change the startupScript parameter from ATTSRVR to the new name for the server as follows, where [NEW_NAME] is the new name that you chose for the server:

<Workspace name="Navigator"
           startupScript="[NEW_NAME]"
           serverMode="reusable"
           ... />

Exit and save the change.

Note:

If you change the name of the ATTSRVR member, make sure to use this new name in all related tasks.

Define the LOADAUT library as an APF-authorized library.

To use the global transactions capability, define every steplib library in the ATTSRVR JCL as an APF-authorized library. Make sure that the libraries are APF-authorized after each IPL.

If you want to use transactions, make sure that RRS is installed.

Note:

To define a data set as APF-authorized, in the SDSF screen, enter the following command, where volume_name is the volume where the data set is allocated:

"/setprog apf,add,dsn=[data_set_name],volume=[volume_name]"

If the site uses SMS, enter the following command when defining APF-authorization in the SDSF screen:

"/setprog apf,add,dsn=[data_set_name],SMS"

The ATTDAEMN, ATTSRVR, and NVIMSSRV started tasks need permission to use an OMVS TCP/IP stack. The owner must be a user with OMVS segment defined and OMVS UID= 0000000000.

In the security manager, such as RACF, create the STARTED class general resource profiles ATTDAEMN, ATTSRVR, and NVIMSSRV. These profiles need to have the following permissions:

Permission to issue master console commands.

START authority for both profiles.

Access to an OMVS segment (that defines access to TCP/IP OMVS sockets).

ALTER authority on datasets under INSTROOT.hlq (to access to read, write, allocate and delete datasets under INSTROOT.hlq).

The installation includes the data set INSTROOT.DEF.GBLPARMS, which contains global environment information. This data set is read at startup and the correct software version is used, based on the details provided in the startup task.

If you change the location of this data set, then you must also change the relevant DD card in the used started tasks and scripts.

The input during the installation procedure is written to INSTROOT.BUILDKIT.SRC(PARS2). You can use this file to provide the same inputs if you rerun the installation, where INSTROOT is the high-level qualifier you assign for the installation.

Consult TCP/IP documentation for information about specifying Oracle Connect for IMS, VSAM, and Adabas Gateways as the service using port 2551 in the TCP/IP network services file.

Starting the Daemon

Activate INSTROOT.USERLIB(ATTDAEMN) as a started task to invoke the daemon. For example, in the SDSF screen, enter the following:

'/s ATTDAEMN'

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

To submit the daemon as a job, uncomment the first two lines of the ATTDAEMN JCL, change the PARM line as described earlier, and run the job using the subcommand. 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 IRPCDINI'
//* PARM='-B -L :8883 START'
//STEPLIB DD DSN=INSTROOT.LOADAUT,DISP=SHR
//SYSPRINT DD SYSOUT=A
//GBLPARMS DD DSN=INSTROOT.DEF.GBLPARMS,DISP=SHR
// EXEC PGM=IRPCD,COND=((1,EQ,STEP1),(2,EQ,STEP1)),
// PARM='-KATTDAEMN START ''INSTROOT.DEF.IRPCDINI'''
//STEPLIB DD DSN=INSTROOT.LOADAUT,DISP=SHR
//SYSPRINT DD SYSOUT=A
//GBLPARMS DD DSN=INSTROOT.DEF.GBLPARMS,DISP=SHR
//SYSDUMP DD DUMMY

Setting Up Oracle Connect for IMS, VSAM, and Adabas Gateways for Reentrancy

All Oracle Connect for IMS, VSAM, and Adabas Gateways load modules are reentrant to enable subtasking. Therefore, move INSTROOT.LOAD to the Link Pack Area (LPA), where INSTROOT is the high-level qualifier where Oracle Connect for IMS, VSAM, and Adabas Gateways is installed.

Using the LPA reduces real storage usage (because everyone shares the LPA copy) and fetch time.

Note:

If you intend to use impersonation—the ability of a server to execute in a security context that is different from the context of the process that owns the server—, do the following:

Place the INSTROOT.LOAD(ATYSVCW) member in an APF-authorized library outside the LPA.

Change the ATTSRVR member (located in the active proclib), by adding the following to the STEPLIB list:

// DD DSN=apf_library,DISP=SHR

Where apf_library is the APF-authorized library outside the LPA where the ATYSCVW member was moved.

Configuring Additional Settings for Working with CICS

If you did not set up CICS during the installation, do the following to work with CICS:

Add the DD card that defines the CICS EXCI load library to the steplib of the ATTSRVR started task.

ATTSRVR is located in both INSTROOT.USERLIB and an active proclib (such as USER.PROCLIB).

Add the CICS EXCI load library to the TASKLIB list of the REXX procedures NAVCMD and NAVSQL of the INSTROOT.USERLIB, as follows:

ALLOCATE DDNAME(TASKLIB) DA(...[CICS_EXCI_load_library]...) SHR

For the IRC (Inter Region Communication) to start, IRCSTRT=YES must be defined in the CICS initialization parameters, as specified in Software Requirements for Oracle Connect for IMS, VSAM, and Adabas Gateways.

By default, Oracle Studio for IMS, VSAM, and Adabas Gateways sets the VTAM netname for CICS data sources to ATYCLIEN.

You can set up ATYCLIEN by doing one of the following:

Use the JCL in the INSTROOT.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).

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

If you work intend to work with the IMS-DBCTL data source, initialize the EXCI by using the CDBC transaction.

Configuring OTMA for Working with IMS/TM

If you want to use the IMS/DBDC data source, you need to check your OTMA configuration. If the OTMA is not configured, perform the following procedure:

If OTMA is not installed, install it using the IMS INSTALL/IVP Dialog.

Set the startup parameter in the IMS startup procedure to OTMA=Yes.

In addition, set OTMA-related parameters such as GRNAME= for the XCF group name and OTMANM= for the IMS member name in that XCF group, as in the following example:

EDIT IMS.PROCLIB(DFSPBIV1) - 01.03command ===>000082 AOIS =,000083 GRNAME=IMSATT01,000084 OTMA=YES,000085 MAXPST=000086 OTMANM=

Add an entry in the program properties table (PPT) for the OTMA C/I initialization program by editing the SCHEDxx member of the SYS1.PARMLIB dataset and adding the following entry:

PPT PGMNAME(DFSYSVI0)     /*PROGRAM NAME =DFSYSVI0 */CANCEL    /*PROGRAM CAN BE CANCELED */KEY(7)    /*PROTECT KEY ASSIGNED IS 7 */SWAP      /*PROGRAM IS SWAPPABLE */NOPRIV    /*PROGRAM IS NOT PRIVILEGED */DSI       /*REQUIRES DATA SET INTEGRITY */PASS      /*CANNOT BYPASS PASSWORD PROTECTION */SYST      /*PROGRAM IS A SYSTEM TASK */AFF(NONE) /*NO CPU AFFINITY */NOPREF    /*NO PREFERRED STORAGE FRAMES */

Do one of the following for the SCHEDxx changes to take effect:

Execute IPL.

Issue the SET SCH= command.

Edit and submit the following JCL procedure to run DFSYSVI0 after the IPL to initialize OTMA C/I:

//OTMAINIT PROC RGN=3000K,SOUT=A,/PARM1=//*//IEFPROC EXEC PGM=DFSYSVI0,//REGION=&RGN//*//STEPLIB DD DISP=SHR,UNIT=SYSDA,//DSN=IMSVS.RESLIB//*//SYSPRINT DD SYSOUT=&SOUT//SYSUDUMP DD SYSOUT=&SOUT//*

It is recommended to add the step for running this program to the IMS/TM started task.

Setting Up Oracle Connect for IMS, VSAM, and Adabas Gateways to Update VSAM, IMS, or Adabas Data

You can set up Oracle Connect for IMS, VSAM, and Adabas Gateways to directly update VSAM, IMS/DB, or Adabas data. The setup procedure depends on whether your data source runs under CICS or not. Perform the relevant task.

To set up Oracle Connect for IMS, VSAM, and Adabas Gateways so that you can update VSAM data from a CICS transaction

Copy the UPDTRNS load module from INSTROOT.LOAD to a CICS user load library and then define the UPDTRNS program under CICS using any available group:

CEDA DEF PROG(UPDTRNS) G(group_name) LANG(C) DA(ANY) DE(ORACLE data source UPDATE PROG)

Where INSTROOT is the high-level qualifier where Oracle Connect for IMS, VSAM, and Adabas Gateways is installed and data source is VSAM.

After defining the UPDTRNS program to a group, install it as follows:

CEDA IN G(group_name)

To set up Oracle Connect for IMS, VSAM, and Adabas Gateways so that you can update IMS/DB data from a CICS transaction

Copy the ATYDBCTL load module from INSTROOT.LOAD to a CICS user load library and then define the ATYDBCTL program under CICS using any available group:

CEDA DEF PROG(ATYDBCTL) G(group_name) LANG(C) DA(ANY) DE(ORACLE data source UPDATE PROG)

Where INSTROOT is the high-level qualifier where Oracle Connect for IMS, VSAM, and Adabas Gateways is installed and data source is IMS.

After defining the ATYDBCTL program to a group, install it as follows:

CEDA IN G(group_name)

3 Troubleshooting Oracle Connect for IMS, VSAM, and Adabas Gateways

This section contains the following topics:

Troubleshooting Overview

Troubleshooting Methods

Common Errors and Solutions

Troubleshooting Overview

Oracle Connect for IMS, VSAM, and Adabas Gateways may require troubleshooting issues that involve multiple technologies, platforms, data sources, applications and networks. This section presents an orderly approach for troubleshooting Oracle Connect for IMS, VSAM, and Adabas Gateways issues. Troubleshooting functions are available in Oracle Studio for IMS, VSAM, and Adabas Gateways, command line utilities, and product logs. In some case you must use command line utilities to troubleshoot a feature because it may not be possible to use Oracle Studio for IMS, VSAM, and Adabas Gateways (especially if there is a problem with communications or installation).

Troubleshooting Methods

This section describes procedures and utilities that are used to check specific problems. This section includes:

Using the NAV_UTIL CHECK SERVER Utility

Using the NAV_UTIL CHECK DATASOURCE Utility

Using Trace Log Files

Using the NAV_UTIL CHECK SERVER Utility

The NAV_UTIL CHECK SERVER utility performs basic network checks to check access to Oracle Connect for IMS, VSAM, and Adabas Gateways servers.

When you run this utility, it performs the following steps:

Connecting to the Oracle Connect for IMS, VSAM, and Adabas Gateways daemon on the specified machine.

Requesting a server instance of the specified workspace. This returns the server location.

Disconnecting from the daemon.

Connecting to the server instance at the determined location.

Disconnecting from the server instance.

By running this utility, you can detect networking and configuration problems and get a better idea of the point where the error occurs.

The complete syntax for this utility is as follows:

$ nav_util check server(<daemon-location>,<workspace-name>[,<username>,<password>])

Where:

daemon-location: The IP address (or hostname) and port where the daemon listens. For example, corpsrv.acme.com or corpsrv.acme.com:2800

workspace-name: The name of a workspace to check (the server checked will be a server of this workspace). If omitted, the default NAVIGATOR workspace will be used.

username and password: The credentials to be used if access to the server requires authentication.

Using the NAV_UTIL CHECK DATASOURCE Utility

The NAV_UTIL CHECK DATASOURCE utility performs basic Oracle Connect for IMS, VSAM, and Adabas Gateways data source access checks.

When you run this utility, it performs the following steps:

Connecting to the specified binding

Loading the definition of the specified data source

Loading the driver of the specified data source

Connecting to the specified data source

Disconnecting from the data source

By running this utility, you can detect data source configuration problems and get a better idea of the point where the error occurs.

The complete syntax for this utility is as follows:

$ nav_util check [-b <binding-name>] datasource(<datasource-name>])

Where:

binding-name: An optional binding name to use. If omitted, the default binding 'NAV' is used.

datasource-name: The name of the data source to check

Using Trace Log Files

You can use logs that are created by Oracle Connect for IMS, VSAM, and Adabas Gateways to find possible problems and troubleshoot them. Oracle Connect for IMS, VSAM, and Adabas Gateways creates various trace logs that trace specific types of information. The trace logs usually are saved in a temporary folder or directory (called temp) in the Oracle root folder. To create the log files, you must activate the log trace. Follow the steps below for activating a log trace.

See also: Log Traces.

In the Oracle Studio for IMS, VSAM, and Adabas Gateways Design perspective Configuration view, expand a machine with the binding you are working with.

Right click the binding and select Edit Binding. The Binding editor opens in the editor section.

At the bottom of the editor, click the Properties tab. The editor displays a list of property categories.

Expand the Debug category. The editor displays a list of trace options.

Set the value to true for one or more of the trace options.

Note:

For the binaryXmlLogLevel log, you set its level. For more information on setting the level for this log, see binaryXmlLogLevel.

Log Traces

The following table describes some of the log traces available and the type of information available in each.

Table 3-1 Available Log Traces

Log Trace | Description
analyzerQueryPlan | Activates a plan file for the query analyzer. This lets you see the Oracle Connect for IMS, VSAM, and Adabas Gateways Query Analyzer's analysis of the SQL sent.

binaryXmlLogLevel

This sets a log level for the binary XML log. This log provides specific debugging information and information about the API. The levels are:

none

api

info

debug

gdbTrace | This trace logs the driver transactions created with the Oracle Connect for IMS, VSAM, and Adabas Gateways SDK.
generalTrace | This trace logs the general error messages that are generated.
optimizerTrace | This trace logs information about the Query Optimizer strategy.
queryWarnings | This trace logs the Query Processor warnings.
timeTrace | This trace adds a time stamp to each event in a log. This lets you see the time frame for the various events in the log.
transactionTrace | This trace logs two- phase commit transactions in the 2PC and XA protocols and events related to those transactions.
triggerTrace | This trace logs information on triggers that are implemented. Whenever the database fires the trigger the information is logged.

Common Errors and Solutions

The following table explains some common communications errors and possible solutions for them.

Table 3-2 Client/Server Communication Error Messages

Code | Message and Explanation | Possible Action
C000 | Cannot shutdown a non-local IRPCD with a signal. Explanation: The oper parameter in the "irpcd shutdown" command is available only with a local daemon. | Check that a remote machine was not specified in the -l [host[:port]] parameter of the irpcd shutdown command. Check that the port number specified in the irpcd shutdown command is correct.

C001

Failed to open the IRPCD PID file.

Explanation: The daemon could not open the irpcd[_port].pid file to find the process ID of the daemon to shut down.

The irpcd[_port].pid file is located in the BIN directory, which is located in the directory where Oracle Connect for IMS, VSAM, and Adabas Gateways is installed.

Check that the daemon has permission to access the irpcd[_port].pid file.

C002

Cannot shutdown IRPCD, PID cannot be found.

Explanation: The shutdown operation failed because the irpcd[_port].pid file was not found in the BIN directory, which is located in the directory where Oracle Connect for IMS, VSAM, and Adabas Gateways is installed.

Check whether the irpcd[_port].pid file exists.

Check that the daemon is running (another user may have shut down the daemon). Run the following command from a computer that is connected to the network:

nav_util check irpcd(hostname[:port])

C003 | Invalid PID in the IRPCD PID file (%s). Explanation: The shutdown failed because the irpcd[_port].pid file in the BIN directory, which is located in the directory where Oracle Connect for IMS, VSAM, and Adabas Gateways is installed. | Terminate the daemon with a system command.

C004

Failed to create a PID file (%s).

Explanation: The daemon was not able to create the irpcd[_port].pid file in the BIN directory, which is located in the directory where Oracle Connect for IMS, VSAM, and Adabas Gateways is installed. Oracle Connect for IMS, VSAM, and Adabas Gateways still runs, however when you shut down the daemon, the irpcd shutdown oper will not work.

Check that the account where the daemon runs has permission to access the irpcd[_port].pid file.

C005

Could not open the IRPCD log file for write.

Explanation: The daemon was not able to create or write to its log file.

Check that the account where the daemon runs has permission to generate/write to the log file.

Check the path specified for the log file in the daemon configuration.

Check that there is no existing log file owned by another user at the specified location.

Ensure that the disk device is not full.

C007

Server initialization failed.

Explanation: The daemon failed to start its network service.

Check the processes that are run on the system to see whether another daemon or program is using the port specified in the -l [host[:port]] parameter of the irpcd start command. The netstat program on most platforms shows this information.

Check the TCP/IP subsystem on the current machine by trying to ping it or run FTP or telnet to or from it.

Check whether the daemon has privileges to use the TCP/IP services on the current machine with the designated port number.

C008 | Setting server event handler failed. Explanation: Internal error. | Contact Oracle Support Services. Contact local support at https://metalink.oracle.com/
C009 | IRPCD process has been terminated by user request. Explanation: This message is informational only. The daemon successfully shut down. | No action is required.

C00A

Application %s not found.

Explanation: The requested workspace does not exist.

Check that the workspace defined in the client binding is also defined in the daemon configuration on the target server.Use the following command from a PC to check the workspace:

nav_util check server(hostname, workspace)

where:

hostname: The host name with an optional port number (the port number is specified after a colon).

workspace: The name of the workspace as defined in the client binding.

C00B | Invalid IRPCD client context. Explanation: A non-Oracle Connect for IMS, VSAM, and Adabas Gateways program is trying to connect to the daemon. | Check the processes and Terminate the relevant process with a system command.
C00C | Daemon request requires a server login. Explanation: A non-Oracle Connect for IMS, VSAM, and Adabas Gateways server or program was trying to use a daemon service that is reserved for Oracle Connect for IMS, VSAM, and Adabas Gateways servers. | Check the processes and terminate the relevant process with a system command.
C00D | Daemon request requires a client login. Explanation: The requested daemon requires a valid client login, which was not supplied. | Reissue the command and specify a username and password. Edit the User Profile in Oracle Studio for IMS, VSAM, and Adabas Gateways to specify a valid username and password for the remote machine.
C00E | Daemon request requires an administrator login. Explanation: The requested daemon service requires an administrative login. | Reissue the irpcd command using the -u parameter and a valid administrator username and password. Edit the User Profile in Oracle Studio for IMS, VSAM, and Adabas Gateways to specify a valid administrator username and password for the remote machine.

C00F

Anonymous client logins are not allowed.

Explanation: The daemon is configured to require a valid username and password, which were not supplied.

Reissue the irpcd command using the -u parameter and a username and password.

Enable anonymous client access by setting the AnonymousClientAllowed parameter to true in the Security section of the daemon configuration.

Edit the User Profile in Oracle Studio for IMS, VSAM, and Adabas Gateways to specify a valid username and password for the remote machine.

C010 | Anonymous server logins are not allowed. Explanation: Internal error. | Contact Oracle Support Services. Contact local support at https://metalink.oracle.com/
C011 | Client has already timed out. Explanation: A server process was started on behalf of a client and the client has timed out before the server completed its startup. | Increase the ConnectTimeout value for the server workspace in the Workspace section of the daemon configuration.

C012

Invalid username/password.

Explanation: Invalid username/password supplied when logging on to the daemon.

On Windows platforms, the daemon is not registered correctly.

Reissue the irpcd command using the -u parameter and a username and password.

See the daemon log file for the reason that the username/password were not accepted.

Edit the User Profile in Oracle Studio for IMS, VSAM, and Adabas Gateways to specify a valid username and password for the remote machine.

Make sure the daemon is started from an account that is allowed to check for system usernames and passwords. On some platforms, only a privileged account can check for authentication.

C014

Client connection limit reached. Try later.

Explanation: The maximum number of server processes for the workspace has been reached, and none of the active servers could accept the client connection.

On z/OS platforms, increase the number of subtasks per address space in the NsubTasks parameter in the Workspace section of the daemon configuration.

On UNIX, increase the value of the MaxNActiveServers and/or MaxNClientsPerServer parameters in the Workspace section of the daemon configuration.

Try running the command later.

C015

Failed to start server process.

Explanation: The Oracle Connect for IMS, VSAM, and Adabas Gateways daemon failed to start a server process or the started server failed upon starting up.

See the daemon and server log files for the reason the server did not start. For example, if you receive a message similar to the following:

[C015] Failed to start NAVIGATOR server process: No server account name defined for anonymous client; code: -1601: SQL code: 0

If you use impersonation, check the user profile on the client. Also see C069, below.

C016 | Unexpected server state. Explanation: Internal error. | Contact Oracle Support Services. Contact local support at https://metalink.oracle.com/
C017 | Active daemon clients exist. Shutdown canceled. Explanation: One or more clients are still connected to the daemon. | Wait until all the clients log off the daemon and then retry the shutdown operation. Force a shutdown by using the irpcd shutdown abort command.
C019 | Request is not granted because someone else is locking it. Explanation: A request to lock a resource managed by the daemon was denied because another user has locked the resource. | Wait for the other user to release the resource.
C01A | Lock %s not found. Explanation: A request to free a resource was denied because the caller did not lock that resource. For example, another user shut down the daemon that you are working with. | Contact Oracle Support Services. Contact local support at https://metalink.oracle.com/
C01B | Unexpected error in %s. Explanation: Internal error. | Contact Oracle Support Services. Contact local support at https://metalink.oracle.com/
C01C | Cannot update configuration without _APPLICATIONS lock. | Contact Oracle Support Services. Contact local support at https://metalink.oracle.com/
C01D | Need to lock the application first. Explanation: Internal error. | Contact Oracle Support Services. Contact local support at https://metalink.oracle.com/
C01F | Cannot set configuration of a deleted application. Explanation: Internal error. | Contact Oracle Support Services. Contact local support at https://metalink.oracle.com/
C020 | Failed in looking up host name (gethostname()) Explanation: Cannot connect to the remote machine. | Check that the machine name in the binding is correct. Check that a domain name server (DNS) is available to look up the host name. Check the TCP/IP subsystem on the machine by trying to ping it or run FTP or telnet to or from it.
C021 | Required variable %s not found Explanation: An environment variable required by the Oracle Connect for IMS, VSAM, and Adabas Gateways server was not defined when the server started up. | Check whether the startup script makes any changes to the environment variables used by Oracle Connect for IMS, VSAM, and Adabas Gateways. Check whether the system-defined environment size is sufficiently large for Oracle Connect for IMS, VSAM, and Adabas Gateways.

C022

Server failed to connect and register with the daemon.

Explanation: An Oracle Connect for IMS, VSAM, and Adabas Gateways server started by the daemon was not able to connect or register back with the daemon.

Try to connect again.

Increase the client's ConnectTimeout value for the target server workspace (in the Workspace section of the daemon configuration).

Check that the startup script for the workspace launches the correct version of Oracle Connect for IMS, VSAM, and Adabas Gatewayst.

On z/OS platforms, increase the number of subtasks per address space in the NsubTasks parameter in the Workspace section of the daemon configuration.

On UNIX, increase the value of the MaxNActiveServers and/or MaxNClientsPerServer parameters in the Workspace section of the daemon configuration.

C023 | Call made to unregistered module %d. Explanation: Internal error. | Contact Oracle Support Services. Contact local support at https://metalink.oracle.com/
C024 | Failed to create a socket. Explanation: An error occurred within the TCP/IP subsystem. | Check whether you have sufficient system privileges. Check the TCP/IP subsystem on the machine by trying to ping it or run FTP or telnet to or from it.
C025 | Failed to set socket option %s Explanation: An error occurred within the TCP/IP subsystem. | Check whether you have sufficient system privileges. Check the TCP/IP subsystem on the machine by trying to ping it or run FTP or telnet to or from it.
C026 | Failed to bind server to port %s Explanation: An Oracle Connect for IMS, VSAM, and Adabas Gateways server or daemon was not able to bind to the specified port. | Check whether another program is holding the port that was specified. Check whether you have sufficient system privileges.
C027 | Cannot create TCP service for %s Explanation: An error occurred within the TCP/IP subsystem | Check the TCP/IP subsystem on the machine by trying to ping it or run FTP or telnet to or from it.
C028 | Unable to register (%s, %d, tcp) Explanation: This error may happen when a portmapper is used (host:a) but the portmapper is not available. | Enable the portmapper. Avoid using the portmapper by not using “:a” when starting the daemon.
C02A | Server thread failed to start Explanation: Internal error. | Contact Oracle Support Services. Contact local support at https://metalink.oracle.com/

C02B

Stopping the %s server - no client

Explanation: A server that was started by the Oracle Connect for IMS, VSAM, and Adabas Gateways daemon to service a client did not get a client connection request within one minute. The server terminates.

In most cases, the client was terminated by a user request, so no specific action is required.

If no client can connect to the server, it may be that the server has multiple network cards and the Oracle Connect for IMS, VSAM, and Adabas Gateways daemon is not aware of this. In this case, start the daemon with an IP address.

C02C | Unexpected event - a termination signal intercepted Explanation: Internal error. | Contact Oracle Support Services. Contact local support at https://metalink.oracle.com/
C02D | Modified transport, context unknown/lost Explanation – Internal error. | Contact Oracle Support Services. Contact local support at https://metalink.oracle.com/
C02E | Call made to non-existing procedure %d Explanation: This error typically is caused by a client of a newer version that is calling an old server. | Verify that the client and server are using the same version of Oracle Connect for IMS, VSAM, and Adabas Gateways.
C02F | Corrupted arguments passed to procedure Explanation: Internal error. | Contact Oracle Support Services. Contact local support at https://metalink.oracle.com/
C030 | Unable to free arguments for %s() of %s Explanation: Internal error. | Contact Oracle Support Services. Contact local support at https://metalink.oracle.com/
C031 | Cannot register a non-module RPC %s Explanation: Internal error. | Contact Oracle Support Services. Contact local support at https://metalink.oracle.com/
C032 | An IRPCD program is required Explanation: Internal error. | Contact Oracle Support Services. Contact local support at https://metalink.oracle.com/
C033 | An IRPCD super-server is required for module events Explanation: Internal error. | Contact Oracle Support Services. Contact local support at https://metalink.oracle.com/
C034 | An invalid super-server module ID was specified, %d Explanation: Internal error. | Contact Oracle Support Services. Contact local support at https://metalink.oracle.com/
C035 | out of memory Explanation: Not enough memory to service a client request. | Increase the process memory quota and/or add memory to the system.
C036 | Failed to register RPC procedure module %s Explanation: Internal error. | Contact Oracle Support Services. Contact local support at https://metalink.oracle.com/
C037 | Failed to register an invalid RPC procedure number %x Explanation: Internal error. | Contact Oracle Support Services. Contact local support at https://metalink.oracle.com/
C038 | Cannot re-register RPC procedure number %x Explanation: Internal error. | Contact Oracle Support Services. Contact local support at https://metalink.oracle.com/
C042 | Remote call to %s failed; %s Explanation: Remote call to API failed. | Check the daemon log file. If necessary, change the level of detail that is written to the log file to help resolve the problem. Change the level of detail in the daemon configuration and run the irpcd reloadini command.
C043 | Failed to connect to host %s;%s Explanation: The remote host is not correctly defined to Oracle Connect for IMS, VSAM, and Adabas Gateways or is not working. | Check that the remote machine definition in the binding configuration. Check the daemon is up on the remote machine (NAV_UTIL CHECK). Check the network connection by trying to ping the host machine or run FTP or telnet to or from it.
C045 | Failed to create a service thread Explanation: The server failed to create a thread to service a client request. | A system or process quota limit has been exceeded. Either increase the quota or lower the NClientsPerServer setting for the server in the Workspace section of the daemon configuration.

C047

%s out of memory

Explanation: Not enough memory was available to Oracle Connect for IMS, VSAM, and Adabas Gateways to complete a requested operation.

Terminate unnecessary processes running on the server.

Add more memory to the system.

Allow the process to use more memory.

Limit the number of processes that the daemon can start. If the demand for servers exceeds the number of available servers, clients get a message telling them that the maximum number of servers were reached and asking them to try again later.

C066 | Communication error with the server%s Explanation: Connection to the Oracle Connect for IMS, VSAM, and Adabas Gateways daemon or server failed, or an established session with a server has failed. | Check that the remote machine definition in the binding configuration. Check the daemon is up on the remote machine (NAV_UTIL CHECK). In case of a network problem, check the network connection by trying to ping the host machine or run FTP or telnet to or from it.

C067

unexpected error occurred in server function %s

Explanation: One of the server functions has exited with an exception, such as an Access Violation (a GPE) or an Invalid Instruction).

If the server contains user code, such as an Oracle Connect for IMS, VSAM, and Adabas Gateways procedure, a user-defined data type, or a user-written provider, verify that this code is not causing the exception.

Otherwise, contact Oracle Support Services. Contact local support at https://metalink.oracle.com/

C068 | fail to login daemon Explanation: The daemon is not running on the server machine. | Use the following command from a PC to check whether a daemon is running on the server: irpcd -l hostname[:port] test Have the system administrator re-install Oracle Connect for IMS, VSAM, and Adabas Gateways on the server.

C069

Fail to get server

Explanation: The Oracle Connect for IMS, VSAM, and Adabas Gateways daemon (IRPCD) on the server machine could not start a server process to serve the client. A separate message provides more detail on why the server process could not start.

There are many possible causes of this error. If the cause is not clear from the related message, see the Oracle Connect for IMS, VSAM, and Adabas Gateways daemon log file on the server

The resolution to this error is highly dependent on the particular cause. The following are some typical causes and resolutions:

The process creation quota was exceeded. Either try again later or increase the quota or the other relevant system resources.

The server startup script failed. This could be caused by some instructions in the process logon script, such as LOGIN.COM on OpenVMS, .cshrc on UNIX.

The username given is not allowed to use the requested server. Use an authorized username.

A limit on concurrent clients for a server has been reached. Try again later.

If you use impersonation, check the user profile on the client. Also see C015.

C06A | Failed to connect to server Explanation: The server assigned to the client did not accept the client connection. A separate message provides more detail about why the server process did not accept the connection. | See the daemon and server log files for the reason that the server was not available to accept its assigned client. If a multi-threaded server is used and many clients are trying to connect to it at the same time, some may get a Connection Refused error if the TCP/IP request queue fills up.
C06B | Disconnecting from server Explanation: A network failure, a server machine failure, or a server program failure caused the connection to abort. The currently active transaction is aborted as well. | Oracle Connect for IMS, VSAM, and Adabas Gateways will automatically try to re-establish a connection with a server when it receives the next SQL command for the server. Once the network or machine failure is corrected, the connection to the daemon is re-established automatically.
C06C | No conversion between server codepage %s and client codepage %s Explanation: Client and server machines use different codepages. | Using the codepage environment variable in the Oracle Connect for IMS, VSAM, and Adabas Gateways environment settings, synchronize the codepages used on the server and client.
C06D | Too many codepages in use, cannot load any additional codepages Explanation: Multiple codepages are specified for the server. | Delete one or more of the codepages specified in the codepage environment variable of the server environment settings.
C06E | Versions of Oracle Connect for IMS, VSAM, and Adabas Gateways client (%d) and server (%d) do not match Explanation: A new version of Oracle Connect for IMS, VSAM, and Adabas Gateways was installed on either the client or server without using the upgrade installation procedure. | Reinstall the new version of Oracle Connect for IMS, VSAM, and Adabas Gateways.
C06F | There is no codepage defined for the server Explanation: The codepage environment variable is not specified in the environment settings. | Specify the codepage environment variable in the Oracle Connect for IMS, VSAM, and Adabas Gateways environment settings.
C070 | Server failed to send reply to the client Explanation: Server terminated unexpectedly. | Unless the client was intentionally stopped, for example, using Control-C, contact Oracle Support Services. Contact local support at https://metalink.oracle.com/

C071

Connection to server %s was disconnected. Cursors state was lost.

Explanation: Either a network failure, a server machine failure or a server program failure caused the connection to abort. The currently active transaction is aborted as well.

Normally, Oracle Connect for IMS, VSAM, and Adabas Gateways automatically tries to create a new session with the server upon the next attempt to access the server. If the network and server are accessible, the next operation should succeed, otherwise, the network and/or server machine should be fixed before the connection is resumed.

In case of a server crash that is not related to a callable user code, contact Oracle Support Services. Contact local support at https://metalink.oracle.com/

C072 | Reconnect to server %s Explanation: This is an informational message only. The client has reestablished its connection with the server. | No action required.
C073 | The parameters passed to the admin server are invalid: %s Explanation: Internal error. | Contact Oracle Support Services. Contact local support at https://metalink.oracle.com/
C074 | No authorization to perform the requested operation (%s) Explanation: The user or account has insufficient privileges. | Grant administrative privileges to the user or account with the Administrator parameter of the Security or Workspace sections in the daemon configuration.
C075 | Failed to register daemon in the TCP/IP service table Explanation: The registration of irpcd daemon in the TCP/IP services file has failed. | Check that the account running the daemon has the permissions to update the TCP/IP services file.
E000 | Licensed number of concurrent users has been exceeded, try again later Explanation: The number of active Oracle Connect for IMS, VSAM, and Adabas Gateways sessions that access local data sources exceeds the number licensed. | Purchase additional concurrent user licenses.
E001 | Failed in lock/release operation Explanation: A lock or release operation of a global resource has failed. A separate message provides more details. | The separate message indicates the cause of this error. There are various causes for this error, including lack of sufficient privileges or a system resource shortage.

A Using NAV_UTIL Utility

Oracle Connect for IMS, VSAM, and Adabas Gateways includes the NAV_UTIL utility. It is a command-line console that enables executing a collection of commands including troubleshooting and metadata utilities.

This section explains how to run the NAV_UTIL utility and describes the available commands. It contains the following topics:

Running NAV_UTIL

ADD_ADMIN

CHECK

DELETE

EDIT

EXECUTE

EXPORT

GEN_ARRAY_TABLES

IMPORT

IMS_MERGE

LOCAL_COPY

PASSWORD

SVC

TEST

UPDATE

UPD_DS

UPD_SEC

VERSION

VERSION_HISTORY

VIEW

XML

Running NAV_UTIL

This section contains information on the following topics:

Activating NAV_UTIL

Basic NAV_UTIL Syntax

Activating NAV_UTIL

Perform the following procedure to activate NAV_UTIL on z/OS platforms.

Run the following command: NAVROOT.USERLIB(navcmD)

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

At the prompt, enter:

[<options>] <command_name> [<command_params>]

Where:

<options>: One of the values listed in Table A-1.

Table A-1 NAV_UTIL Options

Option | Description
-p<password> | The master password specified for the user profile with the name specified in the -u parameter (or the default NAV user profile if the -u option is not specified). If a master password has been set, use of NAV_UTIL requires this password.
-u<name> | The name of a user profile to be used other than the default (NAV).
-b<binding_name> | A binding setting other than the default (NAV) binding configuration.
-command | Runs the utility from a shell environment.
-db | Runs the utility on an Oracle Connect for IMS, VSAM, and Adabas Gateways virtual database.

<command_name>: The name of the command you want to execute.

<command_params>: Command-specific parameters. If you do not supply the command parameters, you are prompted for them.

Basic NAV_UTIL Syntax

The syntax used herein reflects the way in which the command line utility is also written. To this end, bear in mind the meaning of the following symbols:

Plain text: an absence of symbols signifies a keyword, which must be entered as it appears.

<>: parameters inside angular brackets need to be entered in context. For example <data_source> must be replaced with the appropriate data source on which you wish to conduct the transaction at hand.

[]: parameters inside square brackets are optional. Note that you can have a combination of angular and square brackets, signifying an optional parameter that, if entered, must be in context, such as [<data_source>].

|: signifies 'or'. For example <bindings | datasource | remote_machine> signifies any one of the parameters inside the angular brackets.

ADD_ADMIN

The ADD_ADMIN command enables you to specify which users can manage the machine where this command is run, from within Oracle Connect for IMS, VSAM, and Adabas Gateways.

Perform the following procedure to run the ADD_ADMIN command on z/OS platforms.

At the prompt, enter:

add_admin <admin_username> | *

Where:

admin_username: The name of a valid user who can administer the current machine from within Oracle Studio for IMS, VSAM, and Adabas Gateways.

*: All users can administer the current machine from within Oracle Studio for IMS, VSAM, and Adabas Gateways.

Note:

The user specified can be changed from within Oracle Studio for IMS, VSAM, and Adabas Gateways.

CHECK

The CHECK command checks various facets of the client/server system. The following parameters can be checked:

check irpcd

check network [port]

check irpcdstat

check tcpip

check server

check license

check datasource

check irpcd

This checks whether an Oracle Connect for IMS, VSAM, and Adabas Gateways daemon is running. Perform the following procedure to run the CHECK IRPCD command on z/OS platforms.

At the prompt, enter:

CHECK IRPCD (daemon_location [, username, password])

check network [port]

This lists the machines that have an active daemon. You can list all machines or specific machines, based on a specified port number. Perform the following procedure to run the CHECK NETWORK command on z/OS platforms.

At the prompt, enter:

CHECK NETWORK (<port>)

check irpcdstat

This checks the status of a daemon for all workspaces, including active server processes (both those connected to a client and those that are available), the name and location of the log file, and the IRPCD configurations. Use this option to identify server processes that need terminating. You can also check the status of a specific daemon workspace.

Perform the following procedure to run the CHECK IRPCDSTAT command on z/OS platforms.

At the prompt, enter:

CHECK IRPCDSTAT(<daemon_location>, <workspace> [,<username>, <password>])

check tcpip

This checks the basic TCP/IP configuration on the machine (as far as Oracle Connect for IMS, VSAM, and Adabas Gateways can check it).

check server

This checks whether a client can access a specific workspace and checks the details of the workspace configuration. Perform the following procedure to run the CHECK SERVER command on z/OS platforms.

At the prompt, enter:

CHECK SERVER(<daemon_location>, <workspace> [,<username>, <password>])

check license

This checks the license details. You can also check the license details for a specific remote machine.

check datasource

This tests the connection to a specific data source, defined in the default local binding configuration. Perform the following procedure to run the CHECK DATASOURCE command on z/OS platforms.

At the prompt, enter:

CHECK DATASOURCE(<ds_name>[,<connect_info>])

DELETE

DELETE is used to remove the following objects from the repository:

Binding

User Profile

Daemon

There is a separate syntax for Deleting Data Source Objects. Perform the following procedure to run the DELETE command on z/OS platforms.

At the prompt, enter:

[<options>] delete <obj_type> <obj_name>

Where:

options: See Table A-1, "NAV_UTIL Options" for details.

obj_type: The type of object to be deleted. You can specify any of the following:

binding: A particular set of binding information.

daemon: Daemon general configuration settings.

datasources: The data sources specified in a binding.

env[ironment]: Environment properties for a particular binding.

remote_machines: Remote machines defined in the binding.

user: A user profile definition.

obj_name: The name of the specific object (of the type specified in the obj_type parameter) to be deleted. Use the following table to determine the obj_name to supply, dependent on the value of obj_type:

binding, datasources, remote_machines, and environment: The name of the binding in which these objects are defined.

daemon: The daemon name.

user: The user name that identifies the user profile.

Deleting Data Source Objects

You can delete from the repository the information about the following for a given data source:

Tables that rely on ADD metadata

ADD metadata for a table generated by the LOCAL_COPY command

Stored procedures that rely on ADD metadata

ADD metadata for a stored procedure generated by the LOCAL_COPY command

Views

Synonyms

Perform the following procedure to delete data source objects on z/OS platforms.

At the prompt, enter:

[<options>] delete <obj_type> <ds_name> <obj_name>

Where:

options: See Table A-1, "NAV_UTIL Options" for details.

obj_type: The type of object to be deleted. You can specify any of the following:

table: Deletes the information for the specified table.

local_table: Deletes a local copy of a table.

procedure: Deletes an Oracle Connect for IMS, VSAM, and Adabas Gateways procedure.

local_procedure: Deletes a local copy of a stored procedure.

view: Deletes an Oracle Connect for IMS, VSAM, and Adabas Gateways view.

synonym: Deletes an Oracle Connect for IMS, VSAM, and Adabas Gateways synonym.

ds_name: The name of the data source, as specified in the binding configuration, for the data source object that is deleted.

obj_name: The name of the specific object (of the type specified in the obj_type parameter) to be deleted. Use the following table to determine the obj_name to supply, dependent on the value of obj_type:

table: The name of the table to be deleted or * to delete all the tables for the specified ds_name.

local_table: The name of a local copy of a table to be deleted or * to delete all the local copy tables for the specified ds_name.

procedure: The name of an Oracle Connect for IMS, VSAM, and Adabas Gateways procedure for the specified ds_name.

local_procedure: The name of a local copy of a procedure to be deleted or * to delete all the local copy procedures for the specified ds_name.

view: The name of the view to be deleted or * to delete all the views for the specified ds_name.

synonym: The name of the synonym to be deleted or * to delete all the synonyms for the specified ds_name.

EDIT

The EDIT command enables you to modify the contents of a repository. You can directly edit the following types of repository objects:

All configuration information for a particular machine, including all the other elements listed ahead.

User profile definitions

The list of available bindings

Information for a particular binding, which can include information about the following:

Data sources

Remote machines

Environment settings

Information about the available daemons

Information about the following for a particular data source:

Tables that rely on ADD metadata

ADD metadata for a table generated by the LOCAL_COPY command

Stored procedures that rely on ADD metadata

ADD metadata for a stored procedure generated by the LOCAL_COPY command

Views

Synonyms

The object is exported to an XML file that is automatically displayed in a text editor. When the text editor is closed, the XML file is saved back to the repository. However, you cannot delete a repository entry by deleting it from the text editor through this command. To delete a repository entry, use the DELETE command.

The text editor used is the native text editor for the operating system. You can change the editor in the miscellaneous environment settings, either using Oracle Studio for IMS, VSAM, and Adabas Gateways or running a command.

Perform the following procedure to run the EDIT command on z/OS platforms.

At the prompt, enter:

navedit obj_type [<ds_name> [-native]] <obj_name>

Where:

options: See Table A-1, "NAV_UTIL Options" for details.

obj_type: The type of object to be edited. You can specify the following types of objects:

bindings: All available bindings and their environments.

binding: A particular set of binding information.

daemon: Daemon general configuration settings.

daemons: Daemon general configuration settings of all daemons.

datasources: The data sources specified in a binding.

remote_machines: Remote machines defined in the binding.

env[ironment]: Environment properties for a particular binding.

table: Table definitions that rely on ADD metadata per data source.

local_procedure: ADD metadata for a stored procedure generated by the LOCAL_COPY command.

local_table: ADD metadata for a table generated by the LOCAL_COPY command.

machine: All configuration information for a particular machine.

procedure: Stored procedure definitions that rely on ADD metadata.

synonym: Synonyms definitions per data source.

user: A user profile definition.

users: All user profile definitions.

ds_name: The name of data source for the object to be edited, as specified in the binding configuration, when the obj_type is any of: table, local_table, view, procedure, local_procedure, and synonym.

-native: Extracts metadata from the native data source. This option is relevant only for viewing the definition of a local table or procedure (when the obj_type value is local_table or local_procedure).

obj_name: The name of the specific object (of the type specified in the obj_type parameter) that is edited. Use the following table to ascertain the obj_name to supply, according on the value of obj_type, or use * for all of the objects of the specified type:

binding: The name of the binding. If not provided, the default binding (NAV) is used.

bindings: No value necessary.

datasources: The name of the binding configuration.

daemon: The daemon name.

daemons: No value necessary.

env[ironment]: The name of the binding configuration for this working environment.

local_procedure: The name of a local copy of a procedure to be edited or * to edit all the local copy procedures for the specified ds_name.

local_table: The name of a local copy of a table to be edited or * to edit all the local copy tables for the specified ds_name.

machine: No value necessary.

procedure: The name of the procedure to be edited or * to edit all the procedures for the specified ds_name.

remote_machines: The name of the binding configuration.

synonym: The name of the synonym to be edited or *to edit all the synonyms for the specified ds_name.

table: The name of the table to be edited or * to edit all the tables for the specified ds_name.

user: The user name that identifies the user profile.

view: The name of the view to be edited or * to edit all the views for the specified ds_name.

Supplying a value for obj_name that does not exist in the repository, will also create a template, based on the default object (such as NAV for binding or IRPCD for daemon).

EXECUTE

This section contains information on the following topics:

EXECUTE Overview

Running SQL Statements

EXECUTE Commands

EXECUTE Overview

Use the EXECUTE command to test data connections and SQL statements in the interactive NavSQL environment. Running the EXECUTE command gives you the NavSQL prompt.

An example of when to use the EXECUTE command is to check the available data types supported by the data source. For example, if a table in the data source requires a float, the SQL must specify a float rather than a string.

Perform the following procedure to run the EXECUTE command on z/OS platforms.

At the prompt, enter:

execute [-P<password>] [-W<workspace>] <ds_name> [<filename>]

Where:

password: The master password that was specified for the user profile. If the password is not supplied, you are prompted for it.

workspace: The name of the binding that is used as the basis for information. If the binding is not supplied, the default Oracle Connect for IMS, VSAM, and Adabas Gateways binding is used.

ds_name: The name of the data source, as specified in the binding configuration. If you don't supply this parameter, you are prompted for it.

filename: The name of a file, which contains SQL statements. The SQL statements in the file are run immediately. The file is a text file (with any extension). Multiple SQL statements in the file must be separated by semi-colons (;).

The EXECUTE command lets you perform the following tasks:

Run SQL statements.

Request Help and information about a data source.

Change the name of the default data source.

Enter the command tdp with the new name that you want as the default data source. This name must have been defined in the binding configuration.

Exit the NavSQL environment.

Enter quit or exit.

Each entered command can span a number of lines. End the command with a semi-colon (;).

Running SQL Statements

You can write and run SQL statements as follows:

On-the-fly

From a File

From within a Transaction

On-the-fly

Compose an SQL statement and end it with a semi-colon. Press <Enter> to execute the statement.

If the SQL contains data from more than one data source, use a colon (:) to identify the data source (that is, datasource_name:Table_name).

From a File

Enter the full name of a dataset that contains SQL, surrounded by single quotes and prefixed by @. Press <Enter> to execute the SQL contained in the dataset. For example:

@'NAVROOT.TMP.SQL1'

will execute the SQL contained in the SQL1 dataset.

Perform the following procedure to run a dataset immediately.

At the prompt, enter:

execute <data_source> <file>

Where:

data_source is the name of the data source as defined in the binding and file is the name of the SQL file.

Perform the following procedure to run all the queries in the dataset without the overhead of displaying query information on the screen for each query.

At the prompt, enter:

execute <data_source> -quiet <file>

In this case, only queries that fail cause information to be displayed to the screen during the run. A message is displayed after all the queries have been run, stating the number of queries that succeeded and the number that failed.

From within a Transaction

Enter the command begin-transaction (optionally with either read-only or write permission) to start a transaction where you can commit a number of SQL statements together. Use commit to update the data sources with any changes or rollback if you decide that you do not want to accept the changes.

EXECUTE Commands

Use the HELP command to list all the available EXECUTE commands, as shown in Figure A-1.

Figure A-1 Available EXECUTE commands

NavSQL Environment
Description of "Figure A-1 Available EXECUTE commands"

The following transaction-based commands are available for use with the EXECUTE command:

Begin-transaction

Commit

Rollback

The following command can be used to change the default data source:

tdp <ds_name> or tdp-default <ds_name>

The following commands can be used to extract information related to the data source:

describe [<ds-name>:]<table-name> [full] [index]: Provides table information. If full is specified, additional column information is provided. If index is specified, where available a visual representation of the record structure is displayed (this structure can be made available by running the NAV_UTIL EXPORT command).

desc is a short form of the describe command.

describe @<proc_name>: To provide a description of a stored procedure and/or procedures that are included in an Oracle Connect for IMS, VSAM, and Adabas Gateways procedure (the type is Application Connection (Procedure) or Natural/CICS in the binding configuration).

desc is a short form of the describe command.

list catalogs [<mask>]: Lists details about all the catalogs, or a subset of the catalogs when a mask is supplied.

list cata or list catas are short forms of the list catalogs command.

list columns [<table-mask>] [<column-mask>]: Lists details about the columns of the data source. You can list details about specific columns of the data source and about columns in specific tables belonging to the data source. You must also specify if the data source management system is case sensitive.

list procedures [<mask>]: Lists details of all the Oracle Connect for IMS, VSAM, and Adabas Gateways procedures, or a subset of the procedures when a mask is supplied.

list procedure_col [<proc-mask>] [<column-mask>]: Lists details about the columns referenced by the Oracle Connect for IMS, VSAM, and Adabas Gateways procedures. You can list details about specific columns and about columns in specific procedures. You must also specify if the data source management system is case sensitive.

list special-col [<mask>]: Lists details about all the columns with special characteristics (for example key fields), for the data source or a specific table belonging to the data source when a mask is supplied.

list statistics [<mask>]: Lists statistics about all the tables, or a subset of the tables when a mask is supplied.

list synonyms: Lists details about all the synonyms.

list tables [<mask>]: Lists details about all the tables, identified by the type of table: views, synonyms and system tables. A subset of the tables is displayed when a mask is supplied.

list tab or list tabs are short forms of the list tables command.

list tables @*: Provides a listing of all procedures included in an Oracle Connect for IMS, VSAM, and Adabas Gateways procedure (type is Application Connection (Procedure) in the binding configuration).

list tab or list tabs are short forms of the list tables command.

show datatype [<dt-id>]: Lists details about all the data types available, or a specific data type when a number (the dt-id parameter) is supplied.

list views: Lists details about all the views.

native_describe [<ds-name>:]<table-name> [full] [index]: Runs the describe command of the data source. If full is specified, additional column information is provided.

query[_describe] <query>: Provides query information, including the number of fields in the query with the field descriptions and the number of parameters expected by the query.

EXPORT

The EXPORT command enables you to export the contents of a repository to an XML document. You can export the following types of objects from the repository to an XML file:

All configuration information for a particular machine

User profile definitions

The list of available bindings

Information for a particular binding, which can include information about the following:

Data sources

Remote Machine

Environment settings

Information about the available daemons

Information about the following for a particular data source:

Tables that rely on ADD metadata

ADD metadata for a table generated by the LOCAL_COPY command

Stored procedures that rely on ADD metadata

ADD metadata for a stored procedure generated by the LOCAL_COPY command

Views

Synonyms

In addition, you can use the EXPORT utility to export metadata from a data source where the metadata is readable by Oracle Connect for IMS, VSAM, and Adabas Gateways (such as Oracle metadata). The metadata is converted to XML, which is editable. When running EXPORT, use the -native option, as described below. After editing, import the metadata to a local repository for the data source.

Example A-1 EXPORT Syntax

Local> [<options>] export <obj_type>
[ds_name [-native]] <obj_name> <xml_file>

Where:

options: See Table A-1, "NAV_UTIL Options" for details

obj_type: The type of object to be exported. You can specify the following types of objects:

all: All configuration information for a data source.

bindings: All available bindings and their environments.

binding: A particular set of binding information.

daemon: Daemon general configuration settings.

daemons: Daemon general configuration settings of all daemons.

datasources: The data sources specified in a binding.

remote_machines: Remote machines defined in the binding.

env[ironment]: Environment properties for a particular binding.

table: Table definitions per data source.

local_procedure: ADD metadata for a data source stored procedure generated by the LOCAL_COPY command.

local_table: ADD metadata for a table generated by the LOCAL_COPY command.

machine: All configuration information for a particular machine.

procedure: Stored procedure definitions that rely on ADD metadata.

synonym: Synonyms definitions per data source.

user: A user profile definition.

users: All user profile definitions.

view: Oracle Connect for IMS, VSAM, and Adabas Gateways view on a data source.

ds_name: The name of data source for the object to be exported, as specified in the binding configuration, when the obj_type is any of: table, local_table, view, procedure, local_procedure, and synonym.

-native: Extracts metadata from the native data source where the metadata is readable by Oracle Connect for IMS, VSAM, and Adabas Gateways (such as Oracle metadata). The metadata is converted to XML which is editable. Use the -native option to view the native metadata. This option is relevant only for exporting a table or stored procedure (when the obj_type parameter is table or procedure).

If the data source is an ADD data source, the metadata is extracted from the repository and from information specific to the driver for that data source, which is usually retrieved from the data source at runtime. For example, the ISN value in Adabas or RFA column in RMS.

obj_name: The name of the specific object (of the type specified in the obj_type parameter) that is exported. Use the following table to ascertain the obj_name to supply, dependent on the value of obj_type, or use * for all of the objects of the specified type

all: All configuration information for a data source.

bindings: All available bindings and their environments.

binding: A particular set of binding information.

daemon: Daemon general configuration settings.

daemons: Daemon general configuration settings of all daemons.

datasources: The data sources specified in a binding.

remote_machines: Remote machines defined in the binding.

env[ironment]: Environment properties for a particular binding.

table: Table definitions per data source.

local_procedure: ADD metadata for a data source stored procedure generated by the LOCAL_COPY command.

local_table: ADD metadata for a table generated by the LOCAL_COPYcommand.

machine: All configuration information for a particular machine.

procedure: Stored procedure definitions that rely on ADD metadata.

synonym: Synonyms definitions per data source.

user: A user profile definition.

users: All user profile definitions.

view: An Oracle Connect for IMS, VSAM, and Adabas Gateways view on a data source.

xml_file: The XML file to which the specified object is exported (output). If a file name is not specified, the output is displayed on the terminal.

Perform the following procedure to back up Oracle server definitions on z/OS.

At the prompt, enter: export all <ds_name> * <xml_file1>

where ds_name is the name of a data source in the binding with Oracle Connect for IMS, VSAM, and Adabas Gateways metadata defined for it.

Repeat the previous step for every data source with Oracle Connect for IMS, VSAM, and Adabas Gateways metadata defined for it, changing the name of the output file for each data source.

The collection of output files together constitute a complete backup of all the Oracle Connect for IMS, VSAM, and Adabas Gateways definitions on the machine.

GEN_ARRAY_TABLES

The GEN_ARRAY_TABLES command creates virtual tables for Adabas, CISAM, DBMS, DISAM, Enscribe, RMS, and VSAM arrays from existing metadata. The Adabas database can be accessed using ADD or Predict.

Virtual tables are created automatically by Oracle Connect for IMS, VSAM, and Adabas Gateways when the metadata is created for the data source.

Perform the following procedure to run the GEN_ARRAY_TABLES command on z/OS platforms.

At the prompt, enter:

gen_array_tables <ds_name> <table>

Where:

ds_name: The data source name, as specified in the binding configuration.

table: The name of the table in the repository that is defined with an array. Use wildcards if you want to generate virtual tables for more than one table.

IMPORT

The IMPORT command enables you to import the contents of a valid XML document (formatted correctly for Oracle Connect for IMS, VSAM, and Adabas Gateways) to the repository. You can import the following types of objects to the repository from an XML file:

User profile definitions

Binding information

Environment settings (per workspace)

Daemon configuration information

Table definitions that rely on ADD metadata (per data source)

View definitions (per data source)

Stored procedures that rely on ADD metadata

Synonym definitions (per data source)

Metadata generated by the LOCAL_COPY command

Perform the following procedure to run the IMPORT command on z/OS platforms.

At the prompt, enter:

[<options>] import <name> <xml_file>

Where:

options: See Table A-1, "NAV_UTIL Options" for details.

name: The name of the data source for the object to be imported, as specified in the binding configuration, when the object is any of: table, local_table, view, procedure, local_procedure, and synonym.

The value of ds_name is used and not the value of the data source attribute in the XML file. The data source value is generated when using NAV_UTIL EXPORT. Thus, for example, if you export a table definition and then want to import the definition to another data source, you do not need to change the data source attribute value in the XML file before imported the file.

xml_file: The XML file to which the specified object is exported (output). If a file name is not specified, the output is displayed on the terminal.

When importing the following types of objects, you must specify SYS as the ds_name entry:

Binding information

Daemon configuration information

User profiles

Working environment configuration

IMS_MERGE

The IMS_MERGE command creates IMS ADDL and command files from COBOL ADDL files and IMS metadata. Perform the following procedure to run the IMS_MERGE command on z/OS platforms.

At the prompt, enter:

ims_merge <COBOL_ADDL> <DBD_file> <PSB_file> <ouput_ADDL> <output_allocation_template> [cobol_segment_translation_file]

IRPCDCMD

The IRPCDCMD is a utility for the z/OS platform that is used to perform management tasks on the daemon. This utility can be used from the IRPCDCMD REXX.

To use this utility, execute the IRPCDCMD script, located in navroot.userlib.

When you get the prompt, you can invoke the required command.

For example:

> -l 183.22.12.10 status

Usage Format

irpcd [-l daemon_location] [-u username] [-p password] command [arguments]

The following commands are available:

APPLIST [app-name or app-mask]

RELOADINI

RESETLOG

SHUTDOWN [<ABORT|OPERATOR> ["why..."]]

STATUS [workspace-name]

REFRESH [workspace-name]

KILL [workspace-name]

TEST

ENABLE [workspace-name]

DISABLE [workspace-name]

LOCAL_COPY

The LOCAL_COPY command extracts the data definition of a table or stored procedure from the data source catalogs and saves it to the repository. This utility enables you to improve query performance by creating a copy (“snapshot”) of the data source metadata, which is used instead of the data source metadata. The copy must be on the same machine as the data.

Perform the following procedure to run the LOCAL_COPY command on z/OS platforms.

At the prompt, enter:

local_copy <ds_name> <src_table>

Where:

ds_name: The data source name, as specified in the binding configuration.

src_table: The source table name (wildcards are allowed).

PASSWORD

The PASSWORD command allows you to define a master password.

Perform the following procedure to run the PASSWORD command on z/OS platforms.

At the prompt, enter:

password [-u<username>] <new_password>

If you have an existing password, you are prompted to specify it before defining the new master password.

SVC

The SVC command starts a server on the port specified.

Perform the following procedure to run the SVC command on z/OS platforms.

At the prompt, enter:

svc :<port-number>

TEST

The TEST command is for use only when instructed by Oracle Support.

UPDATE

The UPDATE command collects information about tables, indexes, and optionally column cardinalities, for use by the Oracle Connect for IMS, VSAM, and Adabas Gateways Query Optimizer. Each time the utility is run, the resulting statistics overwrite previous statistics.

The UPDATE command collects information about tables, indexes, and optionally column cardinalities, for use by the Oracle Connect for IMS, VSAM, and Adabas Gateways Query Optimizer. Each time the utility is run, the resulting statistics overwrite previous statistics.

This command can be used for all data sources (both those that require ADD metadata and relational data sources). For relational data sources, an entry is created in the Oracle Connect for IMS, VSAM, and Adabas Gateways repository for the data source. An example of when statistics would be used for a relational driver is with SQL/MP, to generate index statistics in addition to the column statistics generated by SQL/MP.

Caution:

Executing the UPDATE command with the reset option deletes all statistics on the specified table.

Perform the following procedure to run the UPDATE command on z/OS platforms.

At the prompt, enter:

update[_statistics] <ds_name> <table_name> [EXACT | rows <row_num>] [+All | [column-options] [index-options]]

Removing Metadata Statistics

On z/OS platforms, remove metadata statistics as follows:

Run the following command: NAVROOT.USERLIB(navcmD)

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

At the prompt, enter:

update[_statistics] <ds_name> <table_name> reset

Where:

ds_name: The name of the data source, as specified in the binding configuration.

Note:

The data source must be local. For a remote data source, run the utility on the remote machine.

table_name: The name of the table. You can specify the wildcards * and % as part of the table name.

Note:

If you use a wildcard as part of the table name, only the default -All parameter is available (the column-options and index-options parameters are invalid).

EXACT: The exact statistical information is returned. Note that this option does not work with large tables.

rows row_num: The number of rows in the table. This value is used to shorten the time to produce the statistics, assuming that the value specified here is the correct value, or close to the correct value. It is recommended to specify a value for rows. The number of unique values per index is also returned.

When the number of rows in the table is not provided, the number of rows used is determined as the maximum value between the value specified in the tuningdsmMaxBufferSize parameter of the environment settings and the value set in the nRows attribute (specified as part of the metadata for the data source).

+All: Information about the table, indexes, partial indexes and columns is included in the output. The default is that only information about the table and indexes is included in the output and not information for partial indexes and columns.

column-options: The following column options can be specified:

+fcol_name1 +fcol_name2…: Returns information only about the specified table columns.

+f*: Returns information about all the table columns.

index-options: The following index options can be specified:

+i1 +i2 …: Returns information only about the specified indexes and partial indexes.

+i*: Returns information about all the table indexes.

If you want information about all the indexes and only some of the partial indexes, you can run the utility twice: once with the -All option and once with the +i1, +i2,... option for the required partial indexes.

Example A-2 Eliminating Statistics Samples

Local> update disam nation

Estimates the number of rows in the NATION table of the data source. The result is based on the number of nRows specified as part of the metadata for the data source and the amount of available memory as specified by the dsmMaxBufferSize parameter of the environment settings.

Local> update disam nation rows 100

Estimates the number of rows in the NATION table of the data source. The result is based on the number of rows specified (100). If the value specified here is the correct value, or close to the correct value, the time to calculate the statistics is shortened.

Local> update disam nation EXACT

Exact statistics for the NATION table of the data source are returned.

UPD_DS

To update the default binding configuration, use the UPD_DS command. This enables you to update the binding only with changes that involve specifying the connection information.

Perform the following procedure to run the UPD_DS command on z/OS platforms.

At the prompt, enter:

[<options>] upd_ds <ds_name> <ds_type> <connect_string>

Where:

options: See Table A-1, "NAV_UTIL Options" for details.

ds_name: The name of the data source to be added to the binding configuration.

ds_type: The name of the driver that is used when accessing the data source.

connect_string: The connect string to be used to access the data source.

UPD_SEC

To update the default user profile, use the UPD_SEC command. This enables you to update the user name and password for both a specific data source or machine in a user profile. Perform the following procedure to run the UPD_SEC command on z/OS platforms.

At the prompt, enter:

[<options>] upd_sec <ds_name> | -machine <machine>[:<port>] [-u<username>] [-p<password>]

Where:

options: See Table A-1, "NAV_UTIL Options" for details.

ds_name: The name of the data source, as specified in the binding configuration, to which the user profile is related.

machine[:port]: The name and, optionally, the port of the data source to which the user profile is related.

username: The user name to access the data source or machine.

password: The password to access the data source or machine.

VERSION

The VERSION command enables you to check which version of Oracle Connect for IMS, VSAM, and Adabas Gateways is running on the machine.To display the version of the Oracle Connect for IMS, VSAM, and Adabas Gateways installation, use the following command line:

At the prompt, enter:

version [-history]

VERSION_HISTORY

The VERSION_HISTORY command returns a report of installations, upgrades and patches installed on the machine. Perform the following procedure to run the VERSION_HISTORY command on z/OS platforms.

At the prompt, enter:

version_history

VIEW

The VIEW command enables you to view the contents of a repository. With this command you can see the definitions of the following types of repository objects:

All configuration information for a particular machine, including all the elements listed below.

User profile definitions

The list of available bindings

Information for a particular binding, which can include information about the following:

Data sources

Remote machines

Environment settings

Information about the available daemons

Information about the following for a particular data source:

Tables that rely on ADD metadata

ADD metadata for a table generated by the LOCAL_COPY command

Stored procedures that rely on ADD metadata

ADD metadata for a data source stored procedure generated by the LOCAL_COPY command.

Views

Synonyms

Perform the following procedure to run the VIEW command on z/OS platforms.

At the prompt, enter:

[<options>] view <obj_type> [<ds_name> [-native]] <obj_name>

Where:

options: See Table A-1, "NAV_UTIL Options" for details.

obj_type: The type of object whose definition is displayed. You can specify the following types of objects:

binding: A particular set of binding information.

bindings: All available bindings and their environments.

datasources: The data sources specified in a binding.

datasources: The data sources specified in a binding.

daemon: Daemon general configuration settings.

daemons: Daemon general configuration settings of all daemons.

env[ironment]: Environment properties for a particular binding.

local_procedure: ADD metadata for a stored procedure generated by the LOCAL_COPY command.

local_table: ADD metadata for a table generated by the LOCAL_COPY command.

machine: All configuration information for a particular machine.

procedure: Stored procedure definitions that rely on ADD metadata.

remote_machines: Remote machines defined in the binding.

synonym: Synonyms definitions per data source.

table: Table definitions per data source.

user: A user profile definition.

view: An Oracle Connect for IMS, VSAM, and Adabas Gateways view on a data source.

ds_name: The name of data source, as specified in the binding configuration, for the object whose definition is displayed, when the obj_type is any of: table, local_table, view, procedure, local_procedure, and synonym.

-native: Extracts metadata from the native data source. This option is relevant only for viewing the definition of a table or stored procedure (when the obj_type value is table or procedure). You usually define this feature in Oracle Studio for IMS, VSAM, and Adabas Gateways.

obj_name: The name of the specific object (of the type specified in the obj_type parameter) that is displayed. Use the following table to ascertain the obj_name to supply, dependent on the value of obj_type, or * for all of the objects of the specified type:

binding: The name of the binding. If not provided, the default binding (NAV) is used.

bindings: No value necessary.

datasources: The name of the binding configuration.

daemon: The daemon name.

daemons: No value necessary.

env[ironment]: The name of the binding configuration for this working environment.

local_procedure: The name of a local copy of a procedure to be viewed or * to view all the local copy procedures for the specified ds_name.

local_table: The name of a local copy of a table to be viewed or * to view all the local copy tables for the specified ds_name.

machine: No value necessary.

procedure: The name of the procedure to be viewed or * to view all the procedures for the specified ds_name.

remote_machines: The name of the binding configuration.

synonym: The name of the synonym to be viewed or * to view all the synonyms for the specified ds_name.

table: The name of the table to be viewed or * to view all the tables for the specified ds_name.

user: The user name that identifies the user profile.

view: The name of the view to be viewed or * to view all the views for the specified ds_name.

XML

The XML command sends an XML request directly to Oracle Connect for IMS, VSAM, and Adabas Gateways for processing, much like execute sends an SQL query directly to Oracle Connect for IMS, VSAM, and Adabas Gateways. XML is particularly suited to troubleshooting, by enabling system administrators and DBAs to check the Oracle Connect for IMS, VSAM, and Adabas Gateways XML dispatcher's handling of queries specified in XML documents.

Perform the following procedure to run the XML command on z/OS platforms.

At the prompt, enter:

xml <fin>.xml <fout>.xml

Where:

fin.xml: The file name with the input XML.

fout.xml: The file name of the output XML. If a file name is not specified, the output is displayed on the terminal.

XML Samples

Oracle Connect for IMS, VSAM, and Adabas Gateways processes XML requests (including queries) specified only in documents formatted in the syntax specific to Oracle Connect for IMS, VSAM, and Adabas Gateways. The general structure of this syntax is as follows:

Example A-3 XML Sample

header>
  <request-step1>…</request-step1>
  ...
  <request-stepn>…</request-stepn>
</header>

The following input file is formatted according to the requirements of the Oracle Connect for IMS, VSAM, and Adabas Gateways XML implementation and specifies the SQL query select * from navdemo:nation:

Example A-4 XML Input FIle Sample

<?xml version="1.0"?>
<acx>
  <connect adapter="query" />
  <execute>
    <query id="1">
            select * from navdemo:nation
    </query>
  </execute>
  <disconnect/>
</acx>

Running the XML command with the above file as input generates the following output file:

Example A-5 XML Output File Sample

<?xml version='1.0' encoding='ISO-8859-1'?>
<acx type='response'>
  <connectResponse idleTimeout='0'></connectResponse>
  <executeResponse>
    <recordset id='1'>
      <record N_NATIONKEY='0' N_NAME='ALGERIA' N_REGIONKEY='0'
              N_COMMENT='New Distributor                            '/>
      <record N_NATIONKEY='1' N_NAME='ARGENTINA' N_REGIONKEY='1'
              N_COMMENT='Far Away                                   '/>
      <record N_NATIONKEY='2' N_NAME='BRAZIL' N_REGIONKEY='1'
              N_COMMENT='Nearby                                     '/>
       ...
    </recordset>
  </executeResponse>
</acx>

Index

D  H  I  K  M  N  P  R  S  U 

D

daemon, starting, 2.4.6.2

data, updating, 2.4.6.6

disk space requirements, 2.2.1

H

hardware requirements, 2.2.1, 2.2.1, 2.2.1, 2.2.1

I

importing installation kit, 2.4.3

installation

from CD-ROM, 2.4

importing kit, 2.4.3

instructions, 2.4.4

kit, 2.4.3

prepare job prompts, 2.4.4

preparing, 2.4.1

prompts, 2.4.5

with VSAM, 2.4.4

IRPCDCMD, REXX script, A.11

K

kit installation, 2.4.3

M

master password, A.13

memory requirements, 2.2.1

N

NAV_UTIL utility, A

P

postinstallation, 2.4.6

preinstallation, 2.4.2

instructions, 2.4.2

preparing, 2.4.1

prepare job prompts, 2.4.4

preparing installation, 2.4.1

processor requirements, 2.2.1

R

reentrancy, setting up, 2.4.6.3

requirements

hardware, 2.2.1

software, 2.2.2

S

setting up

CICS, 2.4.6.4

IMS/TM, 2.4.6.5

reentrancy, 2.4.6.3

SMS

See system managed storage

software requirements, 2.2.2

starting daemon, 2.4.6.2

system managed storage, 2.4.2

system requirements, 2.2

U

updating

data, 2.4.6.6

This figure shows the available EXECUTE commands

Oracle Legal Notices

Copyright Notice

Copyright © 1994-2012, Oracle and/or its affiliates. All rights reserved.

Trademark Notice

Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.

Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced Micro Devices. UNIX is a registered trademark of The Open Group.

License Restrictions Warranty/Consequential Damages Disclaimer

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.

Warranty Disclaimer

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.

Restricted Rights Notice

If this is software or related documentation that 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 America, Inc., 500 Oracle Parkway, Redwood City, CA 94065.

Hazardous Applications Notice

This software or hardware 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 that may create a risk of personal injury. If you use this software or hardware in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software or hardware in dangerous applications.

Third-Party Content, Products, and Services Disclaimer

This software or hardware 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.

Alpha and Beta Draft Documentation Notice

If this document is in prerelease status:

This documentation is in prerelease status and is intended for demonstration and preliminary use only. It may not be specific to the hardware on which you are using the software. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to this documentation and will not be responsible for any loss, costs, or damages incurred due to the use of this documentation.