5 Error Messages, Diagnosis, and Reporting

5.1.1 Errors Detected by the Oracle Database

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

ORA-02019:  connection description for remote database not found 

Errors in the ORA-9100 to ORA-9199 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.

5.1.2 Errors Detected by the Gateway

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

A sample error message is:

HGO-00706:  HGO:  Missing equal sign for parameter in initialization file.

5.1.3 Errors Detected in the DRDA Software

Errors detected in the DRDA gateway, on the client or server side, are usually reported with error ORA-28500, followed by a gateway-specific expanded error message. There are two return codes reported in the expanded message:

• drc specifies DRDA-specific errors that are documented in "Gateway Error Codes".

• grc specifies generic gateway errors detected in the DRDA layer. These errors are documented in the Oracle Database Error Messages.

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

For example, the following error message is returned when the database name specified 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:
DG4DRDA v11.1.0.5.0 grc=0, drc=-30061 (839C,0000), errp=GDJRFS2E
errmc=XNAME

5.1.4 Communication Errors

Communication errors are reported with an ORA-28501 followed by a gateway specific error message with drc=-30080 or drc=30081 indicating either a network error or lost session condition. errmc indicates which network function encountered the error, followed by a network interface specific 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: communication error on heterogeneous database link
DG4DRDA v11.1.0.5.0 grc=0, drc=-30081  (839C,0001), errp= file or directory(2)
errmc=Initialize_Conversation (CMINIT) CM_PROGRAM_PARAMETER_CHECK(24) No such > file or directory(2)

Refer to the appropriate host operating system documentation for more information.

5.1.5 Errors Detected by the Server Database

Errors detected by the server database are reported with an ORA-28500 followed by a gateway-specific expanded error message with drc=-777 sqlcode follows.) This is followed by another 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 in this chapter for some SQL errors that get translated.

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 sid{{Emphasis Role='CodeInline'}}.ora{{/Emphasis}}"?>initsid.ora file:

ORA-28500: connection from ORACLE to a non-Oracle system returned the message:
DG4DRDA v11.1.0.5.0 grc=0, drc=-30020 (839C,0000), errp=GDJMRCM
sqlcode=-805, sqlstate=51002, errd=FFFFFF9C,0,0,FFFFFFFF,0,0
errmc=124c

5.4.1 SQL Tracing in the Oracle Database

Oracle database has a command for capturing the SQL statement which is actually sent to the gateway. This command is called EXPLAIN PLAN. EXPLAIN PLAN is used to determine the execution plan that Oracle database follows to execute a specified SQL statement. This command inserts a row (describing each step of the execution plan) into a specified table. If you are using cost-based optimization, then this command also determines the cost of executing 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 Language Reference.

5.4.2 SQL Tracing in the Gateway

For Unix Based Systems:

The production gateway does not have built-in tracing built into it for the purpose of enhancing its speed. The product ships with a debug library that can be used to build a debug gateway for the purposes of tracing and debugging applications.

First, login using the Admin user ID of the gateway and setup the environment:

$ su - <gateway-Admin-User>
 

Next, build the debug gateway:

$ cd $ORACLE_HOME/dg4drda/lib 
$ make -f dg4drda.mk ORACLE_HOME=your_oracle_home g4drsrvd 

This will create the debug gateway and store it in $ORACLE_HOME/bin/g4drsrvd. Next, change the listener.ora to invoke the debug gateway. Change the PROGRAM parameter to specify the debug program name:

(SID_DESC=
        (SID_NAME=drdahoa1)
        (ORACLE_HOME=/oracle/dg4drda/11.1.0)
        (PROGRAM=g4drsrvd))

The listener will need to be reloaded for this change to take effect. Next, edit the Gateway Initialization File and add the following parameters:

TRACE_LEVEL and

ORACLE_DRDA_TCTL

You may optionally add the LOG_DESTINATION parameter, but it is not required.

The following is a fragment of a Gateway Initialization File with the parameters set:

#
TRACE_LEVEL=255
ORACLE_DRDA_TCTL=debug.tctl
#

The above example provides full tracing of both gateway and DRDA. In many cases, only the gateway tracing is desirable. To obtain only gateway tracing, remove (or comment out) the "ORACLE_DRDA_TCTL" parameter.

If you specify a LOG_DESTINATION, then you may specify only the file name (for example, drda.trc), in which case the log will be written to the log directory of the gateway ($ORACLE_HOME/dg4drda/log). Or you may specify a fully qualified path name. If you do not specify a LOG_DESTINATION, then a unique log file in a default format will be generated.

The logfile name will be of the form:

gatewaysid_pid.trc 

where:

gatewaysid is the SID of the gateway. The value of this is determined by the setting of the FDS_INSTANCE parameter, and pid is the process identifier (PID) of the gateway process.

An example log file name would be:

drdahoa1_3875.trc 

When searching for the SQL statements that 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 11g Relational database Management System (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 developed your application, revert the PROGRAM= value in the listener.ora 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.

For Microsoft Windows:

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:

1. Log in as the Administrator user ID of the gateway and set up the environment.

2. Stop the Oracle Net Listener:

   > lsnrctl stop
   

3. Edit the listener.ora with any text editor:

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

4. Find the TNS entry for the gateway and change the program this way:

   PROGRAM=g4drsrvd
   

5. Save the file and exit. Next, restart the Oracle Net Listener:

   > lsnrctl start
   

6. Edit the gateway's initsid.ora file with any text editor:

   > notepad C:\Oracle\GTWHome\dg4drda\admin\initsid.ora
   

7. Set the following parameters:

   TRACE_LEVEL=255
   ORACLE_DRDA_TCTL=debug.tctl
   

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\dg4drda\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 11g 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.