10 Error Messages, Diagnosis, and Reporting

10.1.1 Interpreting Message Formats

Error messages are generally accompanied by additional message text, beyond the text associated with the Oracle message number. The additional text includes details about the error.

Most gateway messages exceed the 70 character message area in the Oracle SQLCA. Use SQLGLM or OERHMS in the programmatic interfaces and the Oracle Call Interface you use with the gateway to view the entire message. Refer to the Programmer’s Guide to the Oracle Precompilers for information about SQLGLM and the Oracle Call Interface Programmer’s Guide for information about OERHMS.

Gateway messages use the following format:

ORA-nnnn Error Message Text

Gateway message line(s).

10.1.2 Messages Generated by Oracle Transparent Gateway for iWay

The following messages are generated by Oracle Transparent Gateway for iWay.

ORA-09100 TARGET SYSTEM RETURNED FOLLOWING MESSAGE

This message indicates an error from the iWay Server. It is followed by messages from the iWay Server. Message ORA-02063 provides more information.

ORA-02063 PReceding n lines from dblink

This message indicates an error from Oracle Transparent Gateway for iWay. The n variable indicates the total number of gateway message lines referenced in message ORA-09100. The dblink variable indicates the name of the database link that was used to access the gateway.

10.1.3 Diagnosing Errors Detected by the Oracle Server

If an error is detected by the Oracle server, then the gateway message lines do not occur. For example, if the gateway cannot be accessed because of an Oracle Net or gateway installation problem, then the gateway message line is not present in the error message.

Another example of error messages without gateway message lines occurs when an INSERT statement attempts to insert data into a table, but does not include values for all of the columns in the table. The following SQL statement causes an error message:

SQL> insert into EMP@EDA values(9999);
ERROR at line 1:
ORA-00947: not enough values

Message ORA-00947 is not accompanied by gateway message lines because the error is detected by the Oracle server. The Oracle server obtains a description of the iWay Server table before sending the INSERT statement to the gateway for processing. This allows the Oracle server to detect when the INSERT statement is invalid.

10.3.1 Tape Format

Data must be sent on tape cartridges for the IBM 3480 or 3490 tape subsystem. Multiple files can be sent on a single volume. Each tape can be in standard label or no label format. In either case, include the following written documentation with each tape:

• Volume serial, if it is a standard label tape

• Data set name and label number for each file on each tape

• DCB characteristics of each data set

10.3.2 Tape Return

Oracle Support Services does not return tapes unless specifically requested to do so. You must provide a return address on the tape and request that the tape be returned.

10.5.1 Components

When reporting a problem to Oracle Support Services, identify the component suspected of failure, along with its full version and correct release level.

10.6.1 Documentation Errors

When reporting documentation errors, you are asked to provide the following information:

• Document name

• Document part number

• Date of publication

• Page number

Describe the error in detail. Documentation errors can include erroneous documentation and omission of required information.

Documentation errors can also be reported directly to the IBM Products Division documentation group. You can do this in one of two ways:

• Using the RCF at the back of this document

• Using the e-mail address: infoibm_us@oracle.com

10.6.2 Incorrect Output

In general, an incorrect output error exists whenever an Oracle utility produces a result that differs from written Oracle documentation. When describing errors of incorrect output, you must describe, in detail, the operation of the function in error. Be prepared to describe your understanding of the proper function, the specific Oracle documentation that describes the proper operation of the function, and a detailed description of the incorrect operation.

If you think you have found a software bug, then be prepared to answer the following questions:

• Does the problem occur in more than one Oracle tool? (Examples of Oracle tools are SQL*Plus and Oracle Developer forms.)

• What are the exact SQL statements used to reproduce the problem?

• What are the full version numbers of the Oracle database, Oracle gateway, and related Oracle software?

• What is the problem and how is it reproduced?

10.6.3 Oracle External Error

Oracle error messages are produced whenever an Oracle gateway, server, tool, or iWay Server system detects an error condition. Depending on the circumstances, error messages might be successful or unsuccessful to the utility or server.

Be prepared to identify the exact error message, message number received, and the complete circumstances surrounding the error.

10.6.4 ABEND

Any program check in an Oracle utility or the Oracle gateway address is considered an error. A full system dump is required as documentation if there is a program check.

Ensure the system dump contains all of the private area of the Oracle gateway address space; without it, diagnosis is sometimes impossible.

System abends might or might not indicate a failure of the Oracle subsystem depending upon circumstances. The following abends are not considered Oracle failures:

• 013 - open failure

• 122 - canceled by operator

• 222 - canceled by operator

• 322 - CPU time exceeded

• 722 - SYSOUT lines exceeded

10.6.5 Program Loop

A program loop is evident when the Oracle gateway task consumes CPU time rapidly, but no actual work is performed.

Any program loop occurring within an Oracle gateway address space is considered an Oracle gateway failure. Loop conditions are rarely experienced and are considered serious errors. The initial diagnostic approach with a loop consists of a system dump. If a task is in a program loop, then ensure that the system dump includes all of the private area of the gateway address space.

Further diagnosis might be required using z/OS SLIP commands. Oracle Support Services furnishes specific instructions on the use of SLIP, depending upon circumstances.

10.6.6 Performance

Oracle system performance is determined by many factors, most of which are not within the control of Oracle Corporation. Considerations such as system load, I/O topology, network topology utilization, and iWay Server resource availability and utilization, make the documentation of performance errors difficult.

Provide detailed information about the state of your environment when reporting a performance error. Specific documentation might include:

• CPU type and memory configuration

• Database topology

• I/O topology

• Network topology

• System workload by type

• Oracle workload characterization

• Query execution plans

• iWay Server threads and resource information

10.6.7 Missing Functionality

Enhancement requests can be opened with Oracle Support Services to request the inclusion of functions and features Oracle products do not currently have. When opening an enhancement request, describe the specific feature or function to be added to the product and provide a business case to justify the enhancement.

10.7.1 System Dump Data Sets

After a SYS1.DUMPxx data set is created, the system operator is notified whenever a dump to that data set occurs. Because all Oracle abends are dumped to SYS1.DUMP data sets and are not dynamically allocated by MPM, you must ensure a SYS1.DUMP data set is always available. If a SYS1.DUMP data set is not available, then a dump might be lost.

You must also ensure the SYS1.DUMP data set is large enough to accommodate the gateway address space.

10.7.2 Operator Initiated Dumps

Operator initiated dumps are accomplished with the z/OS DUMP command:

DUMP COMM=(text) 

where text is the title you want the dump to have.

After the DUMP command is entered, you must respond to the system WTOR with:

R xx,[JOBNAME=(ssn)|ASID=(nnn),]SDATA=PSA,TRT,RGN)

where:

xx is the reply identification number.

ssn is the name of the Oracle subsystem.

nnn is the hexadecimal address space identifier of the address space that you want to dump.