Release 9.0.1.0.1 for AIX-Based Systems (64-bit)
Part Number A90839-01
 Contents |
 Index |
| Oracle Transparent Gateway for IBM DRDA Installation and User's Guide Release 9.0.1.0.1 for AIX-Based Systems (64-bit) Part Number A90839-01 |
|
This chapter provides information about error messages and error codes. This data is specific to this release of the Oracle Transparent Gateway for IBM DRDA for AIX-Based Systems (64-bit), including the following sections:
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 upon 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 Programmer's Guide to the Oracle Precompilers for additional information about SQLGLM, and see the Programmer's Guide to the Oracle Call Interface for additional information about OERHMS. The error messages listed below apply to both TCP/IP and SNA networking communications products on the gateway.
Error conditions encountered when using the gateway can originate from many sources:
Errors detected by the integrating Oracle Server are reported back to the application or tool with the standard "ORA-" type message. Refer to Oracle9i 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 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 Oracle9i Heterogeneous Services.
Errors detected by the generic gateway are prefixed with "HGO-" and are documented in Oracle9i Heterogeneous Services.
An example error message is:
HGO-00706: HGO: Missing equal sign for parameter in initialization file.
Errors detected in the DRDA gateway, on the requestor or server side, are usually reported with error ORA-09100, followed by a gateway-specific expanded error message. There are two return codes reported in the expanded message:
drc specifies DRDA-specific errors which are documented in "Gateway Error Codes".
grc specifies generic gateway errors detected in the DRDA layer. These errors are documented in the Oracle9i Heterogeneous Services.
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 present, errmc 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-09100: Target system returned following message: TG4DRDA v9.0.1.0.1 grc=0, drc=-30061 (839C,0000), errp=GDJRFS2E errmc=XNAME
Communication errors are reported with an ORA-09101 followed by a gateway-specific expanded error message with drc=-30080 (SNA CPI-C error) or drc=-30081 (lost session). errmc indicates which CPI-C routine encounters the error, followed by the CPI-C 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-09101: Target system communication error. TG4DRDA v9.0.1.0.1 grc=0, drc=-30081 (839C,0001), errp=GDJICR errmc=Initialize_Conversation (CMINIT) 24 0
Refer to the appropriate IBM RS/6000, AIX, or SNA server documentation for more information.
Errors detected by the server database are reported with an ORA-09100 followed by a gateway-specific 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 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 initsid.ora file:
ORA-09100: Target system returned following message: TG4DRDA v9.0.1.0.1 grc=0, drc=-777 (839C,0000), errp=DSNXEPM sqlcode=-805, sqlstate=51002, errd=FFFFFF9C,0,0,FFFFFFFF,0,0 errmc=XB2V2R3..GSQL.A92617CB3FE5470DISTSERV
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 following table (3 columns, 1 header row, 9 body rows) lists the mapped sqlstate error numbers, descriptions, and their corresponding Oracle error codes:
The following is an example of a translated "object does not exist" error:
ORA-00942: table or view does not exist TG4DRDA v9.0.1.0.1 grc=0, drc=-942 (839C,0001), errp=DSNXEDST sqlcode=-204, sqlstate=52004, errd=32,0,0,FFFFFFFF,0,0 errmc=AJONES.CXDCX
Listed below are the common Oracle Transparent Gateway for IBM DRDA error codes that appear in the drc= field of the expanded error messages. If you obtain 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=YYYY-MM-DD, 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 IBM 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 allowed maximum of 32K.
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 8 characters.
Action: A user ID of length of 8 or less must be used. Refer to Chapter 11, "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 8 characters.
Action: A password of length of 8 or less must be used. Refer to Chapter 11, "Security Considerations", for a discussion of passwords.
-777 DRDA SERVER RDBMS (SQL) Error
Cause: Server database detected an application-level 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 Userid/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 11, "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 CPI-C 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 CPI-C 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.
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 appropriate trace parameters and setting up the debug Gateway.
The Oracle server has a command for capturing the SQL 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 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, 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 Oracle9i Server SQL Reference.
The production gateway does not have 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 of applications.
First, login as the Admin user ID of the gateway and setup the environment:
$ su - <Gateway-Admin-User>
Next, build the debug gateway:
$ cd $ORACLE_HOME/tg4drda/lib $ make -f tg4drda.mk ORACLE_HOME=your_oracle_home g4drsrvd
|
Note:
ORACLE_HOME is the location of your gateway installation. That is to say, |
This will create the debug gateway and store it in $ORACLE_HOME/bin/g4drsrvd. Next, change the Startup Shell Script to invoke the debug gateway. Our example assumes a SID of 'drdahoa1':
$ cd $ORACLE_HOME/bin $ vi drdahoa1.sh
Find the line which says:
exec $ORACLE_HOME/bin/g4drsrv $*
and change it to:
exec $ORACLE_HOME/bin/g4drsrvd $*
Save the Startup Shell Script and then edit the Gateway Initialization File. Add the following parameters:
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 will give full tracing of both gateway and DRDA tracing. 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, you may specify just the file name (for example, "drda.trc"), in which case the log will be written to the gateway's log directory ($ORACLE_HOME/tg4drda/log). Or you may specify a fully qualified path name. If you do not specify a LOG_DESTINATION, 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 which are passed to the DRDA server, look for the string '*** HGAPARS ***' and '*** HGAXMSQL ***'. The string after HGAPARS will be the incoming statement from the Oracle 9i 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 are done developing your application, you should revert the 'exec' line in the Startup Shell Script to it's previous form in order to use the production gateway again. You should also comment out the trace parameters in the Gateway Initialization Files.
|
 Copyright © 2001 Oracle Corporation. All Rights Reserved. |
|