Oracle Audio Technologies B31003-01 User Manual

Oracle® Application Server

Adapter for IMS/TM User’s Guide

10g Release 3 (10.1.3.1.0)

B31003-01

January 2007

Oracle Application Server Adapter for IMS/TM User’s Guide, 10g Release 3 (10.1.3.1.0)

B31003-01

Primary Author: Jeanne Wiegelmann

Contributing Authors: Yishai Hadas, Dror Harari, Adeeb Massad, Meera Srinivasan, Bo Stern, Shashi Suravarapu, Costi Zaboura, Sheela Vasudevan, Marian Jones

The Programs (which include both the software and documentation) contain proprietary information; they are provided under a license agreement containing restrictions on use and disclosure and are also protected by copyright, patent, and other intellectual and industrial property laws. Reverse engineering, disassembly, or decompilation of the Programs, except to the extent required to obtain interoperability with other independently created software or as specified by law, is prohibited.

The information contained in this document is subject to change without notice. If you find any problems in the documentation, please report them to us in writing. This document is not warranted to be error-free. Except as may be expressly permitted in your license agreement for these Programs, no part of these Programs may be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose.

If the Programs are delivered to the United States Government or anyone licensing or using the Programs on behalf of the United States 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, use, duplication, disclosure, modification, and adaptation of the Programs, including documentation and technical data, shall be subject to the licensing restrictions set forth in the applicable Oracle license agreement, and, to the extent applicable, the additional rights set forth in FAR 52.227-19, Commercial Computer Software--Restricted Rights (June 1987). Oracle USA, Inc., 500 Oracle Parkway, Redwood City, CA

94065.

The Programs are not intended for use in any nuclear, aviation, mass transit, medical, or other inherently dangerous applications. It shall be the licensee's responsibility to take all appropriate fail-safe, backup, redundancy and other measures to ensure the safe use of such applications if the Programs are used for such purposes, and we disclaim liability for any damages caused by such use of the Programs.

Oracle, JD Edwards, PeopleSoft, and Siebel are registered trademarks of Oracle Corporation and/or its affiliates. Other names may be trademarks of their respective owners.

The Programs may provide links to Web sites and access to content, products, and services from third parties. Oracle is not responsible for the availability of, or any content provided on, third-party Web sites. You bear all risks associated with the use of such content. If you choose to purchase any products or services from a third party, the relationship is directly between you and the third party. Oracle is not responsible for: (a) the quality of third-party products or services; or (b) fulfilling any of the terms of the agreement with the third party, including delivery of products or services and warranty obligations related to purchased products or services. Oracle is not responsible for any loss or damage of any sort that you may incur from dealing with any third party.

Preface ................................................................................................................................................................ vii

Audience...................................................................................................................................................... vii

Documentation Accessibility.................................................................................................................... vii

Related Documents ................................................................................................................................... viii

Conventions ............................................................................................................................................... viii

1 Introduction

OracleAS Adapter for IMS/TM Overview .......................................................................................... 1-1

OracleAS Adapter for IMS/TM Architecture...................................................................................... 1-2

Integration Flow from Oracle Application Server to a Legacy Application ............................. 1-2

2 Integrating OracleAS Adapter for IMS/TM with OC4J

Integrating OracleAS Adapter for IMS/TM with OC4J.................................................................... 2-1

Configuring the J2CA 1.5 IMS/TM Adapter....................................................................................... 2-2

Using the CCI API to Develop Applications ...................................................................................... 2-3

Configuring Multiple Adapters ............................................................................................................ 2-4

Updating Configuration Information .................................................................................................. 2-4

3 Troubleshooting OracleAS Adapter for IMS/TM

Troubleshooting the Daemon ................................................................................................................ 3-1

Starting the Daemon .......................................................................................................................... 3-1

Task: Starting the Daemon ........................................................................................................ 3-2

Shutting Down the Daemon............................................................................................................. 3-2

Monitoring the Daemon During Run Time.................................................................................... 3-2

Daemon (Computer) Options ................................................................................................... 3-2

Workspace Options .................................................................................................................... 3-3

Server Options............................................................................................................................. 3-4

Daemon Logs ...................................................................................................................................... 3-4

The Daemon Log Monitor ......................................................................................................... 3-5

The Workspace Log Monitor..................................................................................................... 3-5

The Server Log Monitor............................................................................................................. 3-5

Resolving Communication Errors......................................................................................................... 3-5

Resolving Specific Errors........................................................................................................................ 3-6

iii

4 Integrating OracleAS Adapters for IMS/TM with Oracle BPEL Process Manager

Overview of Integrating OracleAS Adapters for IMS/TM with Oracle BPEL Process Manager.....

4-1

Configuring Oracle BPEL Process Manager to interact with the OracleAS Adapter for IMS/TM ..

4-2

Setting up the Connection to the Oracle Connect Server ............................................................. 4-2

Checking Metadata Availability Using Oracle JDeveloper ......................................................... 4-2

Configuring the WSDL for Outbound Applications .................................................................... 4-2

5 Advanced Features of OracleAS Adapter for IMS/TM

Configuring the Daemon for High Availability ................................................................................ 5-1

Adding a New Daemon Workspace Configuration...................................................................... 5-1

Editing the Workspace ...................................................................................................................... 5-2

Configuring the Server Mode........................................................................................................... 5-3

Configuring a Binding Environment ................................................................................................... 5-5

comm Category .................................................................................................................................. 5-6

debug Category .................................................................................................................................. 5-6

miscellaneous Category .................................................................................................................... 5-7

odbc Category..................................................................................................................................... 5-8

oledb Category ................................................................................................................................... 5-8

optimizer Category ............................................................................................................................ 5-8

queryProcessor Category.................................................................................................................. 5-8

transactions Category ........................................................................................................................ 5-8

tuning Category.................................................................................................................................. 5-9

Migration Considerations....................................................................................................................... 5-9

Security Considerations ....................................................................................................................... 5-10

Setting Design Time Security ........................................................................................................ 5-10

Setting Run-time Security .............................................................................................................. 5-10

Transaction Support.............................................................................................................................. 5-11

6 Installing and Configuring OracleAS Adapter for IMS/TM

Preinstallation Tasks................................................................................................................................ 6-1

IBM OS/390 or z/OS Hardware and Software Requirements.................................................... 6-1

Hardware Requirements ........................................................................................................... 6-1

Software Requirements ............................................................................................................. 6-2

Windows Hardware and Software Requirements ........................................................................ 6-2

Hardware Requirements............................................................................................................ 6-2

Software Requirements .............................................................................................................. 6-2

Installing Oracle Connect on an IBM OS/390 or z/OS Series Platform......................................... 6-3

Installation Worksheet....................................................................................................................... 6-3

Preinstallation Instructions............................................................................................................... 6-4

Installing the Kit ................................................................................................................................. 6-5

Installation Instructions..................................................................................................................... 6-5

Postinstallation Instructions ............................................................................................................. 6-8

Postinstallation Procedures ....................................................................................................... 6-8

Starting the Daemon................................................................................................................ 6-10

Setting Up Oracle Connect to Work Under IMS/TM......................................................... 6-10

Setting Up Oracle Connect for Reentrancy .......................................................................... 6-11

Updating an Existing Oracle Connect Installation with IMS/TM............................................... 6-12

Installing Oracle Studio....................................................................................................................... 6-13

Installing Oracle Studio from the CD-ROM................................................................................ 6-14

Configuring Oracle Connect ............................................................................................................... 6-14

Setting Up the IBM OS/390 or z/OS Platform in Oracle Studio ............................................. 6-14

Securing Access to Oracle Connect .............................................................................................. 6-15

Setting Password Access to Oracle Studio ........................................................................... 6-15

Specifying Users with Administrative Rights ..................................................................... 6-17

Setting Up Run-time User Access to the IBM OS/390 or z/OS Platform ....................... 6-18

Modeling Interactions for OracleAS Adapter for IMS/TM...................................................... 6-19

Setting Up an Oracle Connect Adapter ................................................................................ 6-19

Generating Outbound Interactions ....................................................................................... 6-21

Viewing the XML Schema.............................................................................................................. 6-26

Creating XML Schemas .................................................................................................................. 6-27

A Advanced Tuning of the Metadata

Metadata for the Back-end Adapter..................................................................................................... A-1

General Tab ........................................................................................................................................ A-1

Interaction Tab................................................................................................................................... A-2

Schema General Tab ......................................................................................................................... A-3

Schema Record Tab........................................................................................................................... A-5

Source Tab .......................................................................................................................................... A-7

B Back-end Adapter Data Type Support

Data Type Mapping ................................................................................................................................ B-1

C Advanced Tuning of the Daemon

Daemon Control ...................................................................................................................................... C-1

Daemon Logging ..................................................................................................................................... C-3

Daemon Security ..................................................................................................................................... C-5

Workspaces ............................................................................................................................................... C-7

WS Info. .............................................................................................................................................. C-7

WS Server ........................................................................................................................................... C-9

WS Logging...................................................................................................................................... C-13

WS Security ..................................................................................................................................... C-16

D Globalization Settings

Defining the Language and Codepage................................................................................................ D-1

Index

Audience

Preface

This guide is the primary source of user and reference information on OracleAS Adapters for IMS/TM, which enables client applications to access transactions running under IMS/TM through the Sun J2EE Connector Architecture (J2CA) API.

This document describes the features of OracleAS Adapters for IMS/TM that apply to the UNIX, Windows 2000, Windows XP, and Windows Server 2003 operating systems.

This preface covers the following topics:

■ Audience

■ Documentation Accessibility

■ Related Documents

■ Conventions

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

■ Installing and configuring OracleAS Adapters for IMS/TM

■ Diagnosing errors

■ Using OracleAS to access IMS/TM transactions

Note: You should understand the fundamentals of OracleAS,

OC4J, the UNIX and Microsoft Windows operating system before using this guide to install or administer OracleAS Adapters for IMS/TM.

Documentation Accessibility

Our goal is to make Oracle products, services, and supporting documentation accessible, with good usability, to the disabled community. 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

vii

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.

TTY Access to Oracle Support Services

Oracle provides dedicated Text Telephone (TTY) access to Oracle Support Services within the United States of America 24 hours a day, seven days a week. For TTY support, call 800.446.2398.

Conventions

■ Oracle Application Server Adapter Concepts Guide

■ Oracle Application Server Adapter Installation Guide

■ Oracle Application Server Adapter Concepts Guide

■ Oracle Application Server Containers for J2EE User’s Guide

■ Oracle Application Server Containers for J2EE Services Guide

■ Oracle Application Server Containers for J2EE Security Guide

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.

viii

Oracle Application Server Adapter for IMS/TM (OracleAS Adapter for IMS/TM) enables you to connect Oracle Application Server to an Information Management System-Transaction Management (IMS/TM) system. This section provides an overview of the features and architecture of OracleAS Adapter for IMS/TM.

This section contains the following topics:

■ OracleAS Adapter for IMS/TM Overview

■ OracleAS Adapter for IMS/TM Architecture

OracleAS Adapter for IMS/TM Overview

IMS/TM is a high-performance transaction management system that is part of the IBM IMS product family.

The application components in IMS/TM are executable programs called transactions. These programs are typically written in COBOL but may possibly be written in other languages, such as PL/I, C and even Java. There are several types of IMS/TM programs including MPPs (Message Processing Programs) and BMP (Batch Message Processing Programs).

Introduction

IMS/TM transaction are invoked using an API called OTMA (Open Transaction Manager Access) as well as through 3270 terminals. IMS/TM transactions are built around an input message-output message concept with a special layer (MFS) translating the message to the screen and back, for a user interface.

In addition to OTMA, there is also an IMS/TM transaction gateway that enables TCP/IP access to IMS/TM transactions.

OracleAS Adapter for IMS/TM includes the following features:

■ Captures and maintains a metadata schema for IMS/TM by importing COBOL

copybooks and transforming them into mapping definitions for Oracle Connect on the OS/390 or z/OS Series platform and by associating the data structures with specific physical files.

■ Utilizes an enterprise application integration (EAI) model. Users of a requesting

application can model the interactions that they want implemented, specifying what each interaction does, when it occurs, and the inputs and outputs expected for each interaction.

■ Provides access to MPP based IMS/TM transactions. Each OracleAS Adapter for

IMS/TM outbound interaction is mapped to a specific IMS/TM transaction.

■ Maps data structures for facilitating access to IMS/TM transactions from within

OracleAS.

Introduction 1-1

OracleAS Adapter for IMS/TM Architecture

OracleAS adapter includes the following components:

■ J2CA 1.5 IMS/TM adapter: The J2CA IMS/TM adapter is a standard resource

adapter that is compliant with J2EE Connector Architecture, providing J2EE components connectivity.

■ Oracle Connect: Oracale Connect runs on the legacy system and handles requests

from the J2CA 1.5 IMS/TM adapter, that runs within Oracle Application Server Containers for J2EE (OC4J).

■ Oracle Studio: Oracle Studio is the configuration tool for Oracle Connect.

Configuration tasks using Oracle Studio are performed on a Windows platform. Oracle Studio uses perspectives that enables you to generate specific information necessary to model OracleAS Adapter for IMS/TM.

The following figure illustrates the components of OracleAS Adapter for IMS/TM:

Figure 1–1 Adapter Architecture

Note: For a comprehensive description of the integration adapter

architecture, see the following Oracle documentation:

Oracle Application Server Adapter Concepts Guide

Integration Flow from Oracle Application Server to a Legacy Application

The J2CA 1.5 IMS/TM adapter converts the J2CA interaction invocation received from an application client to the XML format and passes the XML format to Oracle Connect on the legacy server. The daemon listens for the request coming from the J2CA 1.5 IMS/TM adapter client and assigns a server process to handle the request. The properties of the server process, such as connection pooling requirements, are defined by a workspace definition within the daemon. The server process includes an instance of the application engine, which converts the XML format into native structures understandable by IMS/TM and passes the converted XML to the back-end adapter. The back-end adapter builds an interaction based on the metadata for the back-end adapter stored in the repository and the incoming converted XML, and passes it to the legacy application to be executed. The results of the execution are passed back to the application engine, using the back-end adapter, where these results are converted to XML and passed back to the client.

1-2 Oracle Application Server Adapter for IMS/TM User’s Guide

Integrating OracleAS Adapter for IMS/TM

To deploy and integrate OracleAS Adapter for IMS/TM with Oracle Application Server Containers for J2EE (OC4J), you need to configure the J2CA 1.5 IMS/TM adapter.

This section includes the following topics:

■ Integrating OracleAS Adapter for IMS/TM with OC4J

■ Configuring the J2CA 1.5 IMS/TM Adapter

■ Using the CCI API to Develop Applications

■ Configuring Multiple Adapters

■ Updating Configuration Information

Integrating OracleAS Adapter for IMS/TM with OC4J

Oracle Application Server provides a complete Java 2 Enterprise Edition (J2EE) environment that executes on the Java Virtual Machine (JVM) of the standard Java Development Kit (JDK). OC4J is J2EE certified and provides all the J2EE specific containers, APIs, and services. OC4J supports the J2CA 1.5 standard.

with OC4J

J2CA defines standard Java interfaces for simplifying the integration of applications with the EIS. OracleAS adapters are deployed as a Resource Adapter (RA) within the OC4J container.

The contract between the OC4J client application and the resource adapter is defined by the common client interface (CCI). The contract between the OC4J container and the resource adapter is defined by the service provider interface (SPI). The SPI API addresses the connection management, transaction management and the security management.

Connection management enables application components to connect to an EIS and leverage any connection pooling provided by the application server.

Transaction management enables an application server to use a transaction manager to manage transactions across multiple resource managers. Security management provides authentication, authorization, and secure communication between the J2EE server and the EIS.

Lifecycle management contracts enable an application server to initialize a resource adapter instance during the deployment of the adapter or application server startup. In addition, it enables the application server to notify the resource adapter instance during server shutdown or undeployment of the adapter.

Integrating OracleAS Adapter for IMS/TM with OC4J 2-1

Configuring the J2CA 1.5 IMS/TM Adapter

The lifecycle contract provides the mechanism for the application server to manage the lifecycle of the resource adapter instance.

Work management contracts enable the resource adapter to carry out its logic by using threads dispatched by an application server, rather than creating threads on its own.

The handshake is done through a Work instance submission. This makes the

application server threads management more efficient, providing better control over their execution contexts (like security and transaction).

See Also: Oracle Application Server Adapter Concepts Guide, Oracle

Application Server Containers for J2EE User’s Guide, Oracle Application Server Containers for J2EE Services Guide, and Oracle Application Server Containers for J2EE Security Guide.

Configuring the J2CA 1.5 IMS/TM Adapter

To connect to the J2CA 1.5 IMS/TM adapter under Oracle Application Server, perform the following steps:

1. Edit the oc4j-ra.xml file, which is located at the following path:

root\j2ee\home\application-deployment\default\oracle\oc4j-ra.xml

Where root is the Oracle Application Server root directory.

2. Set the following settings for each connection:

<oc4j-connector-factories> <connector-factory location=" " connector-name="Oracle Legacy Adapter"> <config-property name="userName" value=" "/> <config-property name="password" value=" "/> <config-property name="eisName" value=" "/> <config-property name="serverName" value=" "/> <config-property name="workspace" value=" "/> <config-property name="portNumber" value=" "/> <config-property name="persistentConnection" value=" "/> <config-property name="keepAlive" value=" "/> <config-property name="firewallProtocol" value=""/> <config-property name="connectTimeout" value=""/> <config-property name="encryptionProtocol" value=""/> <config-property name="encryptionKeyName" value=""/> <config-property name="encryptionKeyValue" value=""/> </connector-factory> </oc4j-connector-factories>

The following table lists the properties that must be specified, and optional properties:

Table 2–1 OC4J Connection Properties

Property Description

location Specifies the JNDI location where Oracle Application Server

eisName Sets the name of the adapter to use. The adapter is defined in the

2-2 Oracle Application Server Adapter for IMS/TM User’s Guide

should bind the connection factory instance for application components.

Oracle Connect server using Oracle Studio, as described in

"Setting Up an Oracle Connect Adapter" on page 6-19.

Using the CCI API to Develop Applications

Table 2–1 (Cont.) OC4J Connection Properties

Property Description

serverName Sets the TCP/IP address or host name where the Oracle Connect

daemon is running. The daemon runs on the computer specified at the beginning of

in Oracle Studio" on page 6-14.

See Also: Appendix C, "Advanced Tuning of the Daemon" for details about the daemon.

"Setting Up the IBM OS/390 or z/OS Platform

workspace Specifies the name of an Oracle Connect server workspace to use.

portNumber Specifies the TCP/IP port where the Oracle Connect daemon is userName

(optional)

password

(optional)

persistentConnecti on

(optional)

keepAlive

(optional)

firewallProtocol

(optional)

connectTimeout

(optional)

The default workspace is Navigator.

See Also: "Workspaces" on page C-7 for details about workspaces.

running on the server. The default port is 2552.

Specifies a user who can access the Oracle Connect server. The user is defined in the Oracle Connect daemon configuration.

See Also: "Daemon Security" on page C-5 and "WS Security" on page C-16 for details about users allowed to access an Oracle Connect server.

Specifies a valid password for the user..

Set to true or false. When set to true, connections can persist

across multiple requests or connection context changes. It is recommended to set this property to true.

Set to true or false. When set to true, the socket used for the

connection is always kept open. It is recommended to set this property to true.

Specifies the firewall protocol used: either none or fixedNat (the Nat protocol using a fixed address for the daemon). The default

value is none.

Specifies the connection timeout in seconds. The default is 0, meaning that there is no connection timeout.

encryptionProtocol

(optional)

encryptionKeyName

(optional)

encryptionKeyValue

(optional)

fakeXa Set to true of false. When set to true, the XA APIs are

Specifies the name of encryption protocol to use. The default is null. The RC4 protocol is supported.

Specifies the name of the symmetric encryption key to use.

Specifies the value of the symmetric encryption key to use.

internally converted to local transaction APIs.

Using the CCI API to Develop Applications

You can develop applications to run adapter interactions using the Common Client Interface (CCI) API.

Perform the following steps to use the CCI API with the J2CA 1.5 IMS/TM adapter:

1. Select a ConnectionFactory for the J2CA 1.5 IMS/TM adapter.

Integrating OracleAS Adapter for IMS/TM with OC4J 2-3

Configuring Multiple Adapters

2. Create a Connection object using the selected ConnectionFactory. A

Connection is a handle to the underlying network connection to the EIS, which is identified in the oc4j-ra.xml file by the serverName property.

3. Create a Connection object using the selected ConnectionFactory. Specify

the interaction properties using an AttuInteractionSpec object. The AttuInteractionSpec object has the following format:

AttuInteractionSpec(java.lang.String name, int verb, int timeOut)

The following table describes the properties that can be specified:

Table 2–2 Interaction Spec Properties

Property Description

name Specifies the interaction name to be executed. verb Specifies the mode for the interaction: SYNC_SEND, SYNC_

timeOut Specifies the time (in milliseconds) to wait for an EIS to

SEND_RECEIVE, or SYNC_RECEIVE.

run the specified interaction.

The following is an InteractionSpec sample:

AttuInteractionSpec iSpeq = new AttuInteractionSpec("query", javax.resource.cci.InteractionSpec.SYNC_RECEIVE, 60 javax.resource.cci.RecordFactory rf = new AttuRecordFactory(con, mcf.getLogger()); javax.resource.cci.MappedRecord queryRecord = rf.createMappedRecord("query"), queryRecord.put("##text", "select * from disam:nation"); javax.resource.cci.Record oRec = interaction.execute(iSpec, queryRecord);

4. Invoke the execute method on the interaction to initiate a call to the EIS. Pass

any data for the interaction as input and output records.

5. Once the interactions have been processed, close the Interaction and

Connection objects.

Configuring Multiple Adapters

Each J2CA 1.5 IMS/TM adapter requires an entry in the oc4j-ra.xml file as

described in

on page 2-2.

);

See Also: Oracle Application Server Adapter Concepts Guide

Updating Configuration Information

You can change the configuration settings for a resource adapter by editing the

relevant connector-factory entry in the oc4j-ra.xml file. For these changes to

take effect, you need to stop and restart Oracle Application Server.

2-4 Oracle Application Server Adapter for IMS/TM User’s Guide

Troubleshooting OracleAS Adapter for

Troubleshooting Oracle AS Adapter for IMS/TM involves checking various definitions and properties in Oracle Connect, including daemon status, workspace options, server parameters, and various system logs.

This section contains the following topics:

■ Troubleshooting the Daemon

■ Resolving Communication Errors

■ Resolving Specific Errors

Troubleshooting the Daemon

Troubleshooting the daemon and the communication between Oracle Application Server and OracleAS Adapter for IMS/TM is performed using Oracle Studio. It is used to monitor the daemon and server activity and control what happens to the daemon and server processes.

IMS/TM

This section contains the following topics:

■ Starting the Daemon

■ Shutting Down the Daemon

■ Monitoring the Daemon During Run Time

■ Daemon Logs

Starting the Daemon

The daemon is started when OracleAS Adapter for IMS/TM is installed. In case you have shut down the daemon, as described in page 3-2, you can restart the daemon as described in the following task.

See Also: Appendix C, "Advanced Tuning of the Daemon" for

details about the configuration settings.

"Shutting Down the Daemon" on

Note: The daemon is started on the IBM OS/390 or z/OS

platform. It cannot be started remotely using Oracle Studio.

Troubleshooting OracleAS Adapter for IMS/TM 3-1

Troubleshooting the Daemon

Task: 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'

WhereINSTROOT is the high-level qualifier where Oracle Connect is installed.

See Also: "Starting the Daemon" on page 6-10 for details about

the ATTDAEMN JCL.

Shutting Down the Daemon

To shut down the daemon, use Oracle Studio, as follows:

1. From the Start menu, select Programs, Oracle, and then select Studio.

2. Select the required computer in the Configuration Explorer.

3. Right-click the computer and select Open Runtime Perspective.

4. In the Runtime Explorer, right-click the computer, and select Shutdown Daemon.

Monitoring the Daemon During Run Time

Use the Runtime Manager perspective of Oracle Studio to monitor the daemon during run time.

1. From the Start menu, select Programs, Oracle, and then select Studio.

2. Right-click the required computer in the Configuration Explorer and select Open

Runtime Perspective.

You can manage the daemon by expanding the relevant node, daemon, workspace or server process, and choosing the relevant option, as described in the following sections.

Daemon (Computer) Options

Right-click the daemon to display the options available for it, including the ability to display the daemon log.

The following table lists the avaiable options:

Table 3–1 Daemon Options

Option Description

Edit Daemon Configuration

Status Checks the status of the daemon. The information about

Opens the daemon editor, enabling you to reconfigure the daemon.

See Also: Appendix C, "Advanced Tuning of the Daemon" for details about the configuration settings.

the daemon includes the daemon name, configuration used, the active client sessions, and logging information.

Reload Configuration Reloads the configuration after any changes. Any servers

3-2 Oracle Application Server Adapter for IMS/TM User’s Guide

currently started are not affected by the changed configuration.

See Also: Appendix C, "Advanced Tuning of the Daemon" for details about the configuration settings.

Troubleshooting the Daemon

Table 3–1 (Cont.) Daemon Options

Option Description

View Log Displays the daemon log. For details see "Daemon Logs"

on page 3-4.

View Events Displays the daemon events log.

Daemon Properties

Shutdown Daemon

Recycle servers Closes all unused servers and prepares all active servers to

Kill servers Immediately closes all active and unused servers.

Rename

Remove

Refresh

Displays information about the computer where the daemon is running, such as the physical address and any username and password needed to access the computer.

Shuts down the daemon on the computer.

close when the client disconnects. New connection requests are allocated with new servers.

Note: It is recommended to use this option with caution, as it may lead to data loss.

Enables to change the name of the daemon displayed in the Runtime Explorer.

Removes the daemon from the Runtime Explorer.

Refreshes the display.

Workspace Options

Right-click a workspace to display the options available for the workspace, including the ability to display the workspace log.

The following table lists the available options:

Table 3–2 Workspace Options

Option Description

Edit Workspace Configuration

Status Checks the status of the workspace, whether it is available

View Log Displays the log for all servers for the workspace. For

View Events Displays the workspace events log.

Recycle Servers Closes all unused servers and prepares all active servers to

Kill Servers Immediately closes all active and unused servers.

Remove Removes the selected workspace from the Runtime

Disable Disables the selected workspace.

Refresh Refreshes the display.

Opens the daemon editor to enable you to reconfigure the workspace.

See Also: Appendix C, "Advanced Tuning of the Daemon" for details about the configuration settings.

or not.

details see

close when the client disconnects. New connection requests are allocated with new servers.

Note: It is recommended to use this option with caution, as it may lead to data loss.

Explorer.

"Daemon Logs" on page 3-4.

Troubleshooting OracleAS Adapter for IMS/TM 3-3

Troubleshooting the Daemon

Server Options

Right-click a server to display the options available for the server, including the ability to display the server log.

The following table lists the available options:

Table 3–3 Server Options

Option Description

Status

Checks the status of the server. The information about the server includes the server mode and the number of active client sessions for the server.

Daemon Logs

View Log

View Events Displays the the server events log.

Kill server Ends the server process, regardless of its activity status.

Refresh

Displays the server log. For details see "Daemon Logs" on page 3-4.

Note: It is recommended to use this option with caution, as it may lead to data loss.

Refreshes the display.

Oracle Connect produces a number of logs that you can use to troubleshoot problems. The daemon manages the following logs:

■ The daemon log

■ The workspace log

■ The server process log

The Runtime Manager perspective of Oracle Studio provides a monitor for these logs, as shown in the following figure:

Display the required log by right-clicking the level you want (daemon, workspace or server) and selecting View Log. Each log is displayed in a different tab. You can flick between logs by clicking the required tab.

3-4 Oracle Application Server Adapter for IMS/TM User’s Guide

Resolving Communication Errors

The Daemon Log Monitor

The daemon log displays activity between clients and the daemon, including clients logging in and logging out from the daemon. You can change the level of logging by clicking Properties. The following levels of logging are available:

■ none: The log displays who has logged in and out from the daemon.

■ error: The log displays who has logged in and out from the daemon and any

errors that have been generated.

■ debug: The log displays who has logged in and out from the daemon, any errors

that have been generated, and any tracing that has been specified in the daemon configuration.

The Workspace Log Monitor

The workspace log displays information about the workspace being used by the client. You can change the level of logging by clicking Properties. The following levels of logging are available:

■ none: The log displays who has connected and disconnected from the server

process.

■ error: The log displays who has connected and disconnected from the server

process and any errors that have been generated.

■ debug: The log displays who has connected and disconnected from the server

process, any errors that have been generated, and any tracing that has been specified in the daemon configuration.

The Server Log Monitor

The server log displays activity between clients and the server process used by that client to handle the client request. You can change the level of logging by clicking Properties. The following levels of logging are available:

■ none: The log displays who has connected and disconnected from the server

process.

■ error: The log displays who has connected and disconnected from the server

process and any errors that have been generated.

■ debug: The log displays who has connected and disconnected from the server

process, any errors that have been generated, and any tracing that has been specified in the daemon configuration.

Resolving Specific Errors

Table 3–4 Scenarios When a Client Is Disconnected

Scenario

Explicit Disconnect

(client explicitly closes connection or client program terminates)

Abrupt Disconnect

(client closed without proper shutdown or client system hanged and communication disconnected)

Idle (Not Processing a Client Request)

The server is immediately notified of the disconnect and either becomes available for use by another client or terminates (if it is not reusable).

The server does not know that the client has disconnected and remains in the idle state.

After timing out based on whichever comes first of the value for the client idle timeout daemon workspace parameter or the TCP/IP KEEPALIVE parameter, the server is notified of the disconnect and either becomes available for use by another client or terminates (if it is not reusable).

Processing a Client Request

The server does not know that the client has disconnected and continues processing. When processing completes, the server tries to reply to the client and immediately gets an error that the connection was lost. The server either becomes available for use by another client or terminates (if it is not reusable).

The server does not know that the client has disconnected and continues processing. When processing completes, the server tries to reply to the client. After an interval (typically several minutes, depending on the TCP/IP configuration), during which the TCP/IP subsystem retries sending the message to the client, the server assumes that the client has terminated and notifies the server that the connection has been closed. The server either becomes available for use by another client or terminates (if it is not reusable).

To troubleshoot client/server communication problems, you need to be familiar with the following:

■ Daemon configuration settings.

■ Oracle Connect security.

■ TCP/IP subsystem. OracleAS Adapter for IMS/TM uses TPC/IP for internal

intermachine communications.

■ System details, such as the account name and password of the administrator

account, the IP address of the computers involved and whether a portmapper is being used.

Resolving Specific Errors

The following error messages relate to errors received from Oracle Connect.

C007: Server initialization failed.

Cause: The daemon failed to start its network service.

Action: Check the processes being run on the system to see whether another

daemon or program is using the port specified in the oc4j-ra.xml file for the

adapter.

Action: Check the TCP/IP subsystem on the current computer by trying to ping it or run FTP or Telnet to or from it.

Action: Check whether the daemon has privileges to use the TCP/IP services on

the current computer with the port specified in the oc4j-ra.xml file for the

adapter.

C008: Setting server event handler failed.

Cause: Internal error.

Action: Contact Oracle Support Services.

3-6 Oracle Application Server Adapter for IMS/TM User’s Guide

Resolving Specific Errors

C009: IRPCD process has been terminated by user request.

Cause: This message is informational only. The daemon successfully shut down.

Action: No action required.

C00A: Application %s not found.

Cause: The requested workspace does not exist.

Action: Check that the workspace defined in the oc4j-ra.xml file is also

defined in the daemon configuration on the IBM OS/390 or z/OS platform. Use the Status option in the Runtime Manager perspective.

C00B: Invalid IRPCD client context.

Cause: A non-Oracle Connect program is trying to connect to the daemon.

Action: Check the processes and kill the relevant process with a system

command.

C00C: Daemon request requires a server login.

Cause: A non-Oracle Connect server or program was trying to use a daemon

service reserved for Oracle Connect servers.

Action: Check the processes and kill the relevant process with a system command.

C00D: Daemon request requires a client login.

Cause: The requested daemon requires a valid client login, which was not

supplied.

Action: Reissue the command and specify a username and password.

Action: Edit the user profile in Oracle Studio to specify a valid username and

password for the IBM OS/390 or z/OS platform.

See Also: "Setting Up Run-time User Access to the IBM OS/390

or z/OS Platform" on page 6-18.

C00E: Daemon request requires an administrator login.

Cause: The requested daemon service requires an administrative login.

Action: Edit the daemon security in Oracle Studio to specify a valid administrator

username and password.

See Also: "Daemon Security" on page C-5.

C00F: Anonymous client logins are not allowed.

Cause: The daemon is configured to require a valid username and password,

which were not supplied.

Action: Enable anonymous client access in daemon security in Oracle Studio.

See Also: "Daemon Security" on page C-5.

Action: Edit the user profile in Oracle Studio to specify a valid username and password for the IBM OS/390 or z/OS platform.

See Also: "Setting Up Run-time User Access to the IBM OS/390

or z/OS Platform" on page 6-18.

Troubleshooting OracleAS Adapter for IMS/TM 3-7

Resolving Specific Errors

C010: Anonymous server logins are not allowed.

C011: Client has already timed out.

C012: Invalid username/password.

Cause: Internal error.

Action: Contact Oracle Support Services.

Cause: A server process was started on behalf of a client and the client has timed

out before the server completed its startup.

Action: Increase the Connect timeout value for the server workspace in the WS Info. section of the daemon configuration.

Oracle Audio Technologies B31003-01 User Manual

Specifications and Main Features

Frequently Asked Questions

User Manual

Contents

Audience

Preface

Documentation Accessibility

Related Documents

Conventions

OracleAS Adapter for IMS/TM Overview

Introduction

OracleAS Adapter for IMS/TM Architecture

Integration Flow from Oracle Application Server to a Legacy Application

Integrating OracleAS Adapter for IMS/TM with OC4J

Integrating OracleAS Adapter for IMS/TM with OC4J 2-1

Configuring the J2CA 1.5 IMS/TM Adapter

Using the CCI API to Develop Applications

Configuring Multiple Adapters

Updating Configuration Information

Troubleshooting the Daemon

Starting the Daemon

Troubleshooting OracleAS Adapter for IMS/TM 3-1

Task: Starting the Daemon

Shutting Down the Daemon

Monitoring the Daemon During Run Time

Daemon (Computer) Options

Workspace Options

Server Options

Daemon Logs

Resolving Communication Errors

The Daemon Log Monitor

The Workspace Log Monitor

The Server Log Monitor

Resolving Specific Errors