Release 9.2.0.4 for IBM z/OS (OS/390)
Part Number B10580-01
 Contents |
 Index |
| Oracle Transparent Gateway for iWay Installation and User's Guide Release 9.2.0.4 for IBM z/OS (OS/390) Part Number B10580-01 |
|
This chapter discusses error messages generated by Oracle Transparent Gateway for iWay, the diagnosis of suspected Oracle errors, and the requirements for documenting these errors to Oracle Support Services. Specific topics in this chapter include: documentation requirements, categorization of errors, system dump requirements, and methods of reporting to Oracle Support Services.
The following topics are included:
For information on Oracle for OS/390 error messages, refer to the Oracle9i Enterprise Edition Messages Guide.
The gateway architecture includes a number of separate components. Any of these components can detect and report an error condition while processing a SQL statement referring to one or more iWay Server database tables. An error condition can be complex, involving error codes and supporting data from multiple components. In all cases, the application ultimately receives a single Oracle error code upon which to act.
Error conditions are represented in one of two ways:
When possible, an error code from the iWay Server database is converted to the Oracle error code associated with the same logical condition.
For example, when the gateway is used to access the iWay Server and a reference is made to a nonexistent table, the iWay Server SQL code is mapped to Oracle error number ORA-942: TABLE OR VIEW DOES NOT EXIST.
Error code mapping is provided to support application designs that test for and act upon specific error conditions. The set of mapped errors is limited to those associated with conditions common to most relational databases.
Most gateway error conditions are reported to the application using one of the gateway error codes in the range of ORA-9100 through ORA-9199. These messages are less closely linked to specific iWay Server database conditions. The message format is explained under "Interpreting Message Formats".
The ORA-9100 error code is returned for all errors for which a more specific error code does not exist. When an ORA-9100 error code is returned, the error might have been caused in the gateway by an iWay Server support component on the target database system.
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:
where:
nnnn is an Oracle error number.
If nnnn is between 9100 and 9199, then the message is from the gateway. If it not in this range, then it is a mapped error message.
Error Message Text is the text of the message that is associated with the error.
Gateway message line(s) are additional messages that are generated by the gateway.
The gateway message lines are described in "Diagnosing Errors Detected by the Oracle Server".
n is the total number of gateway message lines.
dblink is the name of the database link that is used to access the gateway.
The following messages are generated by Oracle Transparent Gateway for iWay.
ORA-09100 TARGET SYSTEM RETURNED FOLLOWING MESSAGE
Cause: 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
Cause: 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.
ORA-09100 TARGET SYSTEM RETURNED FOLLOWING MESSAGE
EDA-EDAnnnnn ERROR: UNACCEPTABLE SQL STATEMENT
ORA-02063 Preceding 1 lines from GTWLINK
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.
Oracle Support Services serves as the interface to the Oracle user community. Refer to the applicable Oracle Support Services publications for a discussion of policies and procedures for using their services.
During the error resolution cycle, Oracle Support Services might request that you provide them with computer readable data. Send computer readable data, not formatted or printed data. Magnetic tape is the most convenient form for sending large amounts of data.
If you are requested to send data to Oracle Support Services, then follow the documentation requirements provided in "General Documentation Requirements". Failure to follow these requirements might result in the inability to process your tape. This can delay the resolution of any errors you are reporting.
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:
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.
When you report a suspected error, you might be asked to describe the Oracle subsystem and OS/390 operating system environments in detail. Provide the full version number of each component that has an error. The full version number includes important PUT levels for your OS/390 system.
Before you contact Oracle Support Services, ensure the following information is available:
In addition to describing the Oracle operational environment, detailed documentation specific to the error might be required. This might include:
Remember that more than one error is often associated with a single failure. Describe all errors for the failure being reported. If your application uses Pro*C, Pro*COBOL, or another Oracle precompiler, then ensure your application displays or prints out all errors it encounters. Without this information, diagnosing the problem is much more difficult.
When investigating a potential Oracle gateway error, start by determining which component is failing, where it is failing, and the error category.
When reporting a problem to Oracle Support Services, identify the component suspected of failure, along with its full version and correct release level.
Use the following error categories to describe the error:
When reporting documentation errors, you are asked to provide the following information:
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:
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:
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.
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:
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 the system dump includes all of the private area of the gateway address space.
Further diagnosis might be required using OS/390 SLIP commands. Oracle Support Services furnishes specific instructions on the use of SLIP, depending upon circumstances.
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:
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.
When providing documentation on suspected Oracle failures, it might be necessary for you to provide a system dump of the Oracle gateway or utility address spaces. Dumps are initiated through the OS/390 operator interface using the DUMP and SLIP commands, or automatically by the Oracle gateway if it detects a problem.
Dumps sent to Oracle Support Services as documentation for suspected errors must not be formatted. Formatted dumps cannot be used. Formatting a system dump results in a significant delay in processing reported errors, and you might have to send a new, unformatted dump.
When specifying dump parameters in response to an OS/390 DUMP COMM=('') command, you must include the following specification:
PSA,TRT,RGN
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.
Operator initiated dumps are accomplished with the OS/390 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.
|
 Copyright © 1995, 2003 Oracle Corporation. All Rights Reserved. |
|
