Skip Headers
Oracle® Connect for IMS, VSAM, and Adabas Gateways Installation and Configuration Guide
11g Release 1 (11.1) for IBM z/OS

B32527-01
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

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

This section contains the following topics:

3.1 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).

3.2 Troubleshooting Methods

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

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

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

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

  3. Disconnecting from the daemon.

  4. Connecting to the server instance at the determined location.

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

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

  1. Connecting to the specified binding

  2. Loading the definition of the specified data source

  3. Loading the driver of the specified data source

  4. Connecting to the specified data source

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

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

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

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

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

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

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

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


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