JCo
Exceptions
Problem Description
A J2EE application which uses either Java Remote Function Call (JRFC) or Java Resource Adapter (JRA) to connect to an SAP system has caught JCo exception com.sap.mw.jco.JCO$Exception. The exception text was written to a log file or displayed on the GUI (Web Browser, Swing GUI, etc.).
Scenario Type: |
Error analysis |
NetWeaver Component: |
SAP JCo 6.40 (JRFC) and SAP Java Resource Adapter (JRA) |
Validity: |
JRFC and JRA since WebAS 6.40 SP4 |
Decision Roadmap
Main Tools
● Config Tool
● Visual Administrator
Analysis
In order to analyze JCo exceptions in the J2EE application server context, it is helpful to know how SAP JCo, JRFC and SAP JRA relate to one another. SAP JCo Standalone is the component that you can always use to connect to an SAP system from a Java application. JRFC was developed for J2EE applications in the WebAS JRFC; it differs from SAP JCo in the implementation of the lower layers, but has the same API. Finally, if you want to integrate SAP systems compliant to the Java Connector Architecture (JCA), you have to use JRA. JRA again uses internally JRFC for communicating with an SAP system.
If you see a JCo$Exception, you should first check whether the exception text tells you the reason for the failure. If this does not help, activate traces to get more information. The final step is to open an OSS message and attach the traces. As this is how you would typically analyze JCo exceptions, the text below is structured accordingly: first there are some comments about exception groups, a system for classifying JCo exceptions, then there is a subsection about traces and how to get information from trace files, and finally the correct OSS component for JCo problems.
Exception Groups
If an error occurs during the call to the SAP system, JCo throws exception com.sap.mw.jco.JCo$Exception. JRFC throws this exception unchanged and JRA wraps it in a javax.resource.ResourceException. Each of these exceptions is assigned to a group and each group is characterized by a keyword. This keyword can be seen in the exception text and starts either with JCO_ERROR or RFC_ERROR. The groups that are currently available are listed and described below.
The corresponding keywords look like the group names, except that for exceptions that were thrown from a lower communication layer, the prefix JCO is replaced by RFC. So, for example, the keyword for the group name JCO_ERROR_LOGON_FAILURE is RFC_ERROR_LOGON_FAILURE, because the communication layer RFC reported the logon failure.
The latest set of group names can always be retrieved from the documentation of the latest SAP JCo Standalone version, which can be downloaded from SAP Service Marketplace under the alias Connectors. You have to change to SAP Java Connector (JCo) -> Tools and Services and get one of the JCo releases. If you unpack the JCo archive, open <jcoinstall>/docs/jco/index.html in a browser and select the method getGroup() for the class JCO.Exception, you will see the description of the exception groups.
Currently available groups
|
Group |
Description |
Possible Actions |
|
JCO_ERROR_ABAP_EXCEPTION |
An exception has been thrown by a function module in the remote system |
Get more information about the function module exception from the JCo exception text and the SAP system data from the calling application or the JCo traces; if the exception was thrown on the ABAP side, check the function module or BAPI in transaction SE37 or SE80 |
|
JCO_ERROR_APPLICATION_EXCEPTION |
An application exception has occurred in the remote SAP system |
Get more information about the function module exception from the JCo exception text and the SAP system data from the calling application or the JCo traces; if the exception was thrown on the ABAP side, check the function module or BAPI in transaction SE37 or SE80 |
|
JCO_ERROR_CANCELLED |
A registered JCo server has been cancelled |
Find out from the JAVA application or the JCo traces which JCo Server was cancelled and restart the server; in the J2EE Application Server context, JCo Servers are often started via the Service JCo RFC Provider |
|
JCO_ERROR_COMMUNICATION |
Exception caused by network problems, connection breakdowns, gateway problems, unavailability of the remote SAP system, etc. |
Get the host of the SAP System from dev_jrfc.trc or the JRFC trace; ping the SAP system from command line; check routers, gateways, SAP systems
|
|
JCO_ERROR_CONVERSION |
A conversion between two representations of either a parameter, structure, or table field has failed |
Get the respective parameters from the exception text and check the JAVA application |
|
JCO_ERROR_FIELD_NOT_FOUND |
A referenced field in either a JCO.ParameterList, JCO.Structure, or JCO.Table does not exist |
Get the relevant field from the exception text and check the JAVA application |
|
JCO_ERROR_FUNCTION_NOT_FOUND |
A function interface or one of the data structures could not completely be retrieved from the repository |
Get the function module name from the exception text; if the meta data repository was implemented in the JAVA application (there is no call to the SAP system to get the meta data), check the JAVA application, otherwise check and try to execute the function module in the SAP system. |
|
JCO_ERROR_ILLEGAL_TID |
An invalid transaction ID has been encountered. The TID was either longer than 24 characters or contained illegal characters |
Check the JAVA application |
|
JCO_ERROR_INITIALIZATION |
An initialization process failed |
Get the jlaunch and JRFC version from the header of the JCo trace file and check consistency |
|
JCO_ERROR_INTERNAL |
An exception inside of JCo |
Read the exception text and check JCo and JRFC traces |
|
JCO_ERROR_LOGON_FAILURE |
Authorization failures during the logon phase usually caused by unknown username, wrong password, invalid certificates, etc. |
Get the logon data from the JAVA application or JCo trace |
|
JCO_ERROR_NOT_SUPPORTED |
A feature is not being supported by the current version of JCo |
Check the JAVA application |
|
JCO_ERROR_NULL_HANDLE |
An internally used connection handle is invalid |
Read the exception text and check JRFC and JCo traces |
|
JCO_ERROR_PROGRAM |
A general program exception has occurred |
Read the exception text and check JRFC and JCo traces |
|
JCO_ERROR_PROTOCOL |
An internal communication protocol error has been detected |
Get JRFC and JCo traces, open an OSS message for component BC-MID-CON-JCO and attach the traces |
|
JCO_ERROR_RESOURCE |
Indicates that JCO has run out of resources such as connections in a connection pool |
Read the exception text and check the JAVA application |
|
JCO_ERROR_SERVER_STARTUP |
Something went wrong during the startup phase of a JCo server, usually caused by passing a wrong gateway host or gateway service |
Find out from the JAVA application or the JCo traces which server could not be started and check the properties of the JCo server used in your JAVA application |
|
JCO_ERROR_STATE_BUSY |
The remote SAP system is busy. Try again later |
Get SAP system data from the application or the JCo traces and check the SAP system, such as transaction SM50, dpmon |
|
JCO_ERROR_SYSTEM_FAILURE |
A system failure in the remote SAP system has occurred |
Get SAP system data from the application or the JCo traces and check the SAP system, such as transaction ST22 |
|
JCO_ERROR_UNSUPPORTED_CODEPAGE |
Either the remote SAP system or the local systems runs under a codepage which is not supported by JCo |
Get the unsupported codepage from the exception text or the JCo traces |
|
JCO_ERROR_XML_PARSER |
A parse error due to an invalid XML document has occurred |
Get the XML part that caused the error from the JCo trace and check the XML document used in the application |
|
JCO_ERROR_ILLEGAL_ARGUMENT |
An illegal method argument has been detected |
Get the method argument from the exception text and check the JAVA application |
|
JCO_ERROR_CONCURRENT_CALL |
A concurrent method call has been detected |
A JCo client is used in more than one thread, check the JAVA application |
When a JCO$Exception has occurred, first of all you can categorize and so localize the cause of the error by the group the exception belongs to. For example, if you see an RFC_ERROR_LOGON_FAILURE error, you know that incorrect logon parameters were used. Whereas if you see an RFC_ERROR_SYSTEM_FAILURE error, you conclude something is wrong with the SAP system you want to connect to, so you have a look at the SAP system. Besides keywords, JCo exceptions return text that is often very helpful for determining the cause of the error.
The above list of exception groups also comprises a column of “possible actions” that help to analyze the failure. If an error has occurred on a lower communication layer, for example an RFC_ERROR_COMMUNICATION or RFC_ERROR_SYSTEM_FAILURE exception, have a look at the dev_jrfc.trc files. These files are written by JRFC and can be found in the directories j2ee/cluster/server* of the J2EE Application Server Installation.
Traces
If the JCo exception group and the dev_jrfc.trc file do not return enough information to localize the error, switch on tracing, which returns detailed information about calls to and from SAP systems. As the Java Connectivity is build up in three layers, the JRA at the top, then the JCo API in the middle and the JRFC at the bottom, there are three trace files: the JRA, JCo and JRFC trace file. For the JCO and JRA file you can increase the amount of information that is provided by increasing the trace level. The JRFC trace can only be switched on and off. The information below describes the name and the location of the trace files and how tracing can be switched on and off.
JRFC trace
name |
jrfc*.trc |
location |
directory j2ee/cluster/server* or defined path |
how to switch on and off |
set JVM options for the server via the Config Tool and restart server: -Djrfc.trace=0/1, -Djco.trace_path=[defined_path] |
JCO trace
name |
JCO*.trc |
location |
directory j2ee/cluster/server* or defined path |
how to switch on and off |
set JVM options for the server via the Config Tool and restart server: -Djco.trace_level=[0-10],-Djco.trace_path=[defined_path] |
JRA trace
name |
JRA*.trc |
location |
directory j2ee/cluster/server* or defined path |
how to switch on and off |
set JVM options for the server via the Config Tool and restart server: -Djra.trace_level=[0-10], -Djra.trace_path=[defined_path] or from version 630.2.4 switch on via Visual Administrator -> Services -> Connector Container -> <deployed sapjra> -> Managed Connection Factory -> Properties: TraceJRA=[0/10] |
If you are not familiar with the JCo, JRFC or JRA internals, it is sometimes very difficult to read and interpret the traces of these components. Because tracing is often switched on to find out in which SAP system the error occurred, the following information describes how you retrieve this information: first you have to switch on JCo tracing with trace level 5, reproduce the error and search for the name of the exception group in the JCO trace file or, in the case of an JCO_ERROR_ABAP_EXCEPTION, search the string JCO$AbapException.
Now you have to figure out the SAP system parameters of the failed connection. These parameters are written to the JCo trace file when the connection is opened. So in case of a so-called client connection, where you call from Java to ABAP, these parameters can be seen at the file entry “before RfcOpenEx”. For JCo Servers, which handle requests from the ABAP side, the equivalent entry is “Listen before RfcAccept”. If only one client connection was opened or one server thread was started, this is simple.
In real scenarios, however, you have several connections, all writing to the same JCo trace file. In this case you have to look for two characteristics of a connection: the thread in which the connection was opened and the handle for this connection, an integer number. Both do not change from the moment the connection is opened to the moment it is closed. The thread number can be found very easily because the first entry of each line in the JCo trace file is the thread number. The handle of the client connection is returned by the call RfcOpenEx. Search for the entry “after RfcOpenEx(..)=<handle_number>”.
In the case of the server, the handle is returned at “Listen after RfcAccept(…)=<handle_number>”. For all actions related to a connection, this handle number is mentioned in the trace file and often written in brackets []. So in order to find the SAP system of the failed connection, search for the thread number and handle for which the error occurred, then look for the line where this connection was open. This is where you will find the connection parameters. Sometimes a connection cannot be opened, then you see “before RfcOpenEx”, but no “after RfcOpenEx” or “after RfcOpenEx” returns 0 as handle. The same can be observed for “Listen before(after) RfcAccept”. In this case, you should see error messages after the “RfcOpenEx” and “RfcAccept” lines.
Because the upper paragraph is easier to understand, if you have a trace file on hand, below are four examples of a JCo trace: a client connecting to an SAP system, a client call and a server startup which fail, and a server where an error occurs during the request handling.
JCo trace of a client connecting to an SAP system:
SAPEngine_Application_Thread[impl:3]_1 [16:28:56:237]: Connect before RfcOpen(TYPE=A USER="wolf" PASSWD=********** CLIENT=000 LANG=E ASHOST=b20main SYSNR=21 PCS=1) SAPEngine_Application_Thread[impl:3]_1 [16:28:56:357]: RfcException: message: Name or password is incorrect. Please re-enter Return code: RFC_SYS_EXCEPTION(3) error group: 103 key: RFC_ERROR_LOGON_FAILURE
|
JCo trace of a client call where an ABAP exception is thrown:
main [11:01:12:182]: Connect before RfcOpen(TYPE=A USER="wolf" PASSWD=********** CLIENT=000 LANG=D ASHOST=ld0020 SYSNR=21 TRACE=1 PCS=1) main [11:01:12:222]: Connect after RfcOpen(TYPE=A USER="wolf" PASSWD=********** CLIENT=000 LANG=D ASHOST=ld0020 SYSNR=21 TRACE=1 PCS=1)=1 main [11:01:12:222]: [JAV-LAYER] JCO.Client.execute (SBC_TEST_RAISE_EXC) on handle [1] main [11:01:12:222]: [JAV-LAYER] JCO.Client.execute (SBC_TEST_RAISE_EXC) on handle [1] Input: null Input tables: null
main [11:01:12:222]: Executing SBC_TEST_RAISE_EXC for handle 1 main [11:01:12:222]: getCodepage trying codepage 1100 main [11:01:12:222]: getCodepage returns partner codepage 1100 main [11:01:12:222]: Execute before RfcCall(1, SBC_TEST_RAISE_EXC, null, null, null) main [11:01:12:232]: Execute after RfcCall(1, SBC_TEST_RAISE_EXC, null, null, null) main [11:01:12:232]: Execute before RfcReceive(1, SBC_TEST_RAISE_EXC, null, null, null) main [11:01:12:242]: [JAV-LAYER] JCO.Client.execute (SBC_TEST_RAISE_EXC) threw an ABAP exception: com.sap.mw.jco.JCO$AbapException: (126) NO_INPUT_GIVEN: NO_INPUT_GIVEN main [11:01:12:242]: [JAV-LAYER] JCO.Client.execute (SBC_TEST_RAISE_EXC) on handle [1] returns Output: null Output tables: null
main [11:01:12:242]: Disconnect before RfcClose(1) main [11:01:12:252]: Disconnect after RfcClose(1)
|
JCo trace of a server where the startup fails:
main [16:16:13:158]: [JAV-LAYER] JCO.Server.start() on [0] [enter] main [16:16:13:158]: [JAV-LAYER] JCO.Server.start() on [0] [leave] JCO.ServerThread-1 [16:16:13:158]: Listen before RfcAccept( -g"B20MAIN" -x"sapgw22" -a"JRASERVER") JCO.ServerThread-1 [16:16:14:329]: Listen in RfcAccept throws RfcException: message: Connect to SAP gateway failed Connect_PM TPNAME=JRASERVER, GWHOST=B20MAIN, GWSERV=sapgw22
LOCATION CPIC (TCP/IP) on local host ERROR partner not reached (host 10.21.82.172, service sapgw22)
TIME Mon Sep 13 16:16:14 2004 RELEASE 640 COMPONENT NI (network interface) VERSION 37 RC -10 MODULE nixxi.cpp LINE 8588 DETAIL NiPConnect2 SYSTEM CALL SiPeekPendConn ERRNO 10061 ERRNO TEXT WSAECONNREFUSED: Connection refused COUNTER 1
Return code: RFC_FAILURE(1) error group: 102 key: RFC_ERROR_COMMUNICATION
JCO.ServerThread-1 [16:16:14:339]: [JAV-LAYER] JCO.Server.disconnect() on [0]
|
JCo trace of a server where an ABAP exception occurs during request handling:
main [16:16:59:956]: [JAV-LAYER] JCO.Server.start() on [0] [enter] main [16:16:59:956]: [JAV-LAYER] JCO.Server.start() on [0] [leave] JCO.ServerThread-1 [16:16:59:966]: Listen before RfcAccept( -g"B20MAIN" -x"sapgw21" -a"XTSAPBC") JCO.ServerThread-1 [16:17:00:086]: Listen after RfcAccept( -g"B20MAIN" -x"sapgw21" -a"XTSAPBC")=1
….
JCO.ServerThread-1 [16:18:07:604]: [JAV-LAYER] dispatchRequest( SBC_DEMO_COPY) enter JCO.ServerThread-1 [16:18:07:604]: [JAV-LAYER] dispatchRequest() before handleRequest(SBC_DEMO_COPY) on handle [1] Input: ….
JCO.ServerThread-1 [16:18:07:604]: [JAV-LAYER] dispatchRequest() after handleRequest(SBC_DEMO_COPY) on handle [1] Output: ….
JCO.ServerThread-1 [16:18:07:604]: [JAV-LAYER] Exception in dispatchRequest( SBC_DEMO_COPY):com.sap.mw.jco.JCO$AbapException: (126) NO_INPUT_GIVEN: NO_INPUT_GIVEN at com.sap.mw.jco.test.SAPServer.executeSbcDemoCopy(SAPServer.java:304) at com.sap.mw.jco.test.SAPServer.handleRequest(SAPServer.java:242) at com.sap.mw.jco.JCO$Server.dispatchRequest(JCO.java:7234) at com.sap.mw.jco.MiddlewareJRfc$Server.dispatchRequest(MiddlewareJRfc.java:2078) at com.sap.mw.jco.MiddlewareJRfc$Server.listen(MiddlewareJRfc.java:1507) at com.sap.mw.jco.JCO$Server.listen(JCO.java:6820) at com.sap.mw.jco.JCO$Server.run(JCO.java:6749) at java.lang.Thread.run(Thread.java:479)
JCO.ServerThread-1 [16:18:07:604]: [JAV-LAYER] dispatchRequest( SBC_DEMO_COPY) leave JCO.ServerThread-1 [16:18:07:604]: dispatchRequest caught an application exception: NO_INPUT_GIVEN JCO.ServerThread-1 [16:18:07:624]: Listen after dispatchRequest(1, SBC_DEMO_COPY)
|
OSS message
You can often find the cause of the JCO$Exception if you look at the error group, error message or trace files. However, if this was of no help, open an OSS message. If it is a failure of the application that uses JCo, open the message under the component which is responsible for the application, and if it was caused by JCo, use the component BC-MID-CON-JCO. Application failures are likely for error groups where you are recommended to check the Java application or function module as an action.