15 Error Messages, Diagnosis, and Reporting

This chapter provides information about error messages and error codes. This chapter is specific to this release of the Oracle Transparent Gateway for DRDA, and it includes the following sections:

Interpreting Gateway Error Messages
Mapped Errors
Gateway Error Codes
SQL Tracing and the Gateway

Interpreting Gateway Error Messages

The gateway architecture involves a number of separate components. Any component might detect and report an error condition while processing SQL statements that refer to one or more DRDA database tables. This means that error situations can be complex, involving error codes and supporting data from multiple components. In all cases, however, the application ultimately receives a single Oracle error number or return code on which to act.

Because most gateway messages exceed the 70-character message area in the Oracle SQLCA, the programmatic interfaces and Oracle Call Interfaces that you use to access data through the gateway should use SQLGLM or OERHMS to view the entire text of messages. Refer to the programmer's guide to the Oracle precompilers for additional information about SQLGLM, and refer to the Oracle Call Interface Programmer's Guide for additional information about OERHMS.

Error conditions encountered when using the gateway can originate from many sources:

Errors detected by the Oracle integrating server
Errors detected by the gateway
Errors detected in the DRDA software, either on the requestor or server side
Communication errors
Errors detected by the server database

Errors Detected by the Oracle Integrating Server

Errors detected by the Oracle integrating server are reported back to the application or tool with the standard ORA- type message. Refer to the Oracle Database Error Messages for descriptions of these errors. For example, the following error message occurs when an undefined database link name is specified:

ORA-02019:  connection description for remote database not found

Errors in the ORAE9100 to ORAE9199 range are reserved for the generic gateway layer (components of the gateway that are not specific to DRDA). Messages in this range are documented in Oracle Database Error Messages.

Errors Detected by the Gateway

Errors detected by the generic gateway are prefixed with HGO- and are documented in the Oracle Database Error Messages.

An example of an error message is:

HGOE00706:  HGO:  Missing equal sign for parameter in initialization file.

Errors Detected in the DRDA Software

Errors detected in the DRDA gateway, on the requestor or server side, are usually reported with error code ORAE28500, followed by a gatewayEspecific expanded error message. There are two return codes reported in the expanded message:

drc specifies DRDAEspecific errors which are documented in "Gateway Error Codes".
grc specifies generic gateway errors detected in the DRDA layer. These errors are documented in the Oracle Database Heterogeneous Connectivity Administrator's Guide.

Note:

Error code ORAE28500 was error code ORAE09100 prior to gateway version 8. Error code ORAE28501 was error code ORAE09101 prior to gateway version 8.

The values in parentheses that follow the drc values are used for debugging by Oracle Support Services. The errp field indicates the program (requestor or server) that detected the error. If errmc is present, it lists any error tokens.

For example, the following error message is returned when the database name specified (XNAME) with the DRDA_REMOTE_NAME parameter in the initsid.ora file is not defined at the DRDA Server:

ORA-28500: connection from ORACLE to a non-Oracle system returned the message:
TG4DRDA v10.2.0.1.0 grc=0, drc=-30061 (839C,0000), errp=GDJRFS2E
errmc=XNAME

Communication Errors

Communication errors are reported with an ORAE28501 followed by a gatewayEspecific expanded error message with drc=-30080 (SNA CPIEC error) or drc=-30081 (lost session). errmc indicates which CPIEC routine encounters the error, followed by the CPIEC error code and error number.

For example, the following error message is returned when there is a failure to establish a session because DRDA_CONNECT_PARM in the initsid.ora file specifies a Side Information Profile that is not defined:

ORA-28501:  Target system communication error.
TG4DRDA v10.2.0.1.0 grc=0, drc=-30081  (839C,0001), errp=GDJICRD
errmc=Initialize_Conversation (CMINIT)  24  0

Refer to the appropriate Microsoft Windows or IBM Communication Server documentation for more information.

Errors Detected by the Server Database

Errors detected by the server database are reported with an ORAE28500 Oracle Error followed by a gatewayEspecific expanded error message with drc=-777 (sqlcode follows). This is followed by another error message line that contains the sqlcode, sqlstate, errd (error array), and errmc (error tokens) returned from the DRDA Server database. Refer to IBM documentation for the specific database being used. Also refer to "Mapped Errors" for some SQL errors that get translated.

Note:

Error code ORAE28500 was error code ORAE09100 prior to gateway version 8. Error code ORAE28501 was error code ORAE09101 prior to gateway version 8.

For example, the following error message indicates that the DRDA Server database did not recognize the collection ID or package name specified with the DRDA_PACKAGE_COLLID or DRDA_PACKAGE_NAME parameters in the initsid.ora file:

ORA-28500:  Target system returned following message:
TG4DRDA v10.2.0.1.0 grc=0, drc=-777 (839C,0000), errp=DSNXEPM
sqlcode=-805, sqlstate=51002, errd=FFFFFF9C,0,0,FFFFFFFF,0,0
errmc=XB2V2R3..GSQL.A92617CB3FE5470DISTSERV

Mapped Errors

Some SQL errors are returned from the DRDA Server database and are translated to an Oracle error code. This is needed when the Oracle instance or gateway provides special handling of an error condition. The mapped sqlstate errors are:

Table 15-1 Mapped sqlstate Errors

Description	sqlstate error	Oracle error
No rows selected	`02000`	`0`
Unique index constraint violated	`23505`	`ORA-00001`
Object does not exist	`52004` or `42704`	`ORA-00942`
Object name too long (more than 18 characters), and therefore object does not exist	`54003` or `42622`	`ORA-00942`
Insufficient privileges	`42501`	`ORA-01031`
Invalid CCSID (unimplemented character set conversion)	`22522`	`ORA-01460`
Invalid user name/password; logon denied	N/A	`ORA-01017`
Divide by zero error	`01519` or `01564`	`ORA-01476`

The following is an example of a translated "object does not exist” error:

ORA-00942: table or view does not exist
TG4DRDA v10.2.0.1.0 grc=0, drc=-942 (839C,0001), errp=DSNXEDST
sqlcode=-204, sqlstate=52004, errd=32,0,0,FFFFFFFF,0,0
errmc=AJONES.CXDCX

Gateway Error Codes

Listed below are the common Oracle Transparent Gateway for DRDA error codesthat appear in the drc= field of the expanded error messages. If you get a drc value that does not appear here, contact Oracle Support Services.

-700 Invalid ORA_MAX_DATE specified: Cause: An invalid value was specified for ORA_MAX_DATE in the initsid.ora file.; Action: Correct the value of ORA_MAX_DATE. Correct format is ORA_MAX_DATE=YYYYEMMEDD, where MM is in the range of 1 to 12, and DD is in the range of 1 to 31 (and must be valid for the month).

-701 Default CCSID value not supported: Cause: The value specified for DRDA_DEFAULT_CCSID in the initsid.ora file is not supported by the Oracle Transparent Gateway for DRDA.; Action: Refer to Appendix D, "National Language Support", for a list of supported DRDA Server character sets.

-702 Application Host (bind) variable exceeds 32K: Cause: An application program specified a host variable with length greater than the DRDA permitted maximum of 32 K.; Action: The application must be modified to take into account DRDA limits.

-703 Local Character set not supported: Cause: The character set specified for the LANGUAGE parameter in the initsid.ora file is not supported.; Action: Refer to Appendix D, "National Language Support", for a list of supported character sets.

-704 User ID length greater than maximum: Cause: The user ID being used for the allocation of an APPC conversion by the gateway is longer than eight characters.; Action: A user ID of length of 8 or less must be used. Refer to Chapter 13, "Security Considerations", for a discussion of user IDs.

-705 Password length greater than maximum: Cause: The password being used for the allocation of an APPC conversion by the gateway is longer than eight characters.; Action: A password of length of 8 or less must be used. Refer to Chapter 13, "Security Considerations", for a discussion of passwords.

-777 DRDA Server RDBMS (SQL) Error: Cause: Server database detected an applicationElevel SQL error.; Action: Refer to "Interpreting Gateway Error Messages". sqlcode and sqlstate indicate host database error. Use this information to fix your application.

-30060 Invalid User ID/Password (DRDA Server RDBMS Authorization): Cause: You have used a user ID/password that is not acceptable to the DRDA Server database.; Action: Refer to Chapter 13, "Security Considerations", for user ID/password considerations.

-30061 RDB not found: Cause: The remote database specified with the DRDA_REMOTE_DB_NAME parameter is not a valid database at the DRDA Server.; Action: Correct the value of the DRDA_REMOTE_DB_NAME parameter in the initsid.ora file.

-30080 Communication Error: Cause: The gateway encountered a CPIEC communication error.; Action: Retry processing that received error. If it persists, then refer to "Interpreting Gateway Error Messages" and report to your system administrator.

-30081 Communication Error - lost session: Cause: The current DRDA CPIEC session was disconnected.; Action: Retry processing that received error. If it persists, then refer to "Interpreting Gateway Error Messages" and report it to your system administrator.

SQL Tracing and the Gateway

When developing applications, it is often useful to be able to see the exact SQL statements that are being passed through the gateway. This section describes setting correct trace parameters and setting up the debug gateway.

SQL Tracing in the Oracle Database

The Oracle server has a command for capturing the SQL query which is actually sent to the gateway. This command is called EXPLAIN PLAN. EXPLAIN PLAN is used to determine the execution plan that Oracle follows to run a specified SQL statement. This command inserts a row (describing each step of the execution plan) into a specified table.

If you are using costEbased optimization, then this command also determines the cost of running the statement. The syntax of the command is:

EXPLAIN PLAN [ SET STATEMENT_ID = 'text' ]
    [ INTO [schema.]table [@dblink] ] FOR statement

For detailed information on this command, refer to the Oracle Database SQL Reference.

Note:

In most cases, EXPLAIN PLAN should be sufficient to extract the SQL query which is actually sent to the gateway, and thus sent to the DRDA Server. However, certain SQL statement forms have postprocessing performed on them in the gateway. The next section will describe setting up SQL tracing in the gateway.

SQL Tracing in the Gateway

To enhance speed of the gateway, tracing was not built into the production gateway.

The product ships with a debug version of the gateway for the purposes of tracing and debugging applications.

This process entails changing the listener.ora file to use the debug gateway:

Log in as the Administrator user ID of the gateway and set up the environment.
Stop the Oracle Net Listener:
```
> lsnrctl stop
```

Edit the listener.ora with any text editor:

> notepad C:\Oracle\GTWHome\network\admin\listener.ora

Find the TNS entry for the gateway and change the program this way:
```
PROGRAM=g4drsrvd
```
Save the file and exit. Next, restart the Oracle Net Listener:
```
> lsnrctl start
```
Edit the gateway's initsid.ora file with any text editor:
```
> notepad C:\Oracle\GTWHome\tg4drda\admin\initsid.ora
```
Set the following parameters:
```
TRACE_LEVEL=255
ORACLE_DRDA_TCTL=debug.tctl
```
Note:
Refer to Appendix C, "DRDAESpecific Parameters" for descriptions of those parameters.

You may, as an option, add the LOG_DESTINATION parameter, but it is not required. If you specify a LOG_DESTINATION, then you may specify just the file name (for example, drda.trc), or you may specify a fully qualified path name. If you specify a LOG_DESTINATION with just the file name, then the log will be written to the log directory (ORACLE_HOME\tg4drda\trace) of the gateway. If you do not specify a LOG_DESTINATION, then a unique log file in a default format will be generated. The log file name will be of the form:

gatewaysid_tid.trc

Where:

gateway sid is the SID of the gateway.

tid is the thread identifier (TID) of the gateway service.

An example log file name would be:

drdahoa1_3875.trc

When searching for the SQL statements which are passed to the DRDA Server, look for the strings '*** HGAPARS ***' and '*** HGAXMSQL ***'. The string after HGAPARS will be the incoming statement from the Oracle Database 10g RDBMS. The string after HGAXMSQL will be the outgoing statement after any date substitution is done. This is the actual SQL statement which will be given to the DRDA Server.

When you have finished developing your application, revert the PROGRAM= value in the listener.ora file to its previous value and reload the listener to use the production gateway again. You should also comment out the trace parameters in the gateway initialization files.