Troubleshooting common problems with WebSphere Adapter for SAP Software


IBM® WebSphere® Adapter for SAP Software (hereafter called the Adapter) is a J2EE Connector Architecture (JCA) compliant resource adapter that provides bidirectional connectivity between enterprise applications and SAP systems. The Adapter uses SAP JCo 3.x (hereafter called JCo) to connect to SAP.

In this article, outbound communication refers to the Adapter being used by an enterprise application to perform work on SAP, while inbound communication refers to the Adapter receiving events from SAP and delivering them to the enterprise application. The information exchanged with SAP can be in the form of Remote Function Calls (RFCs) or Intermediate Documents (IDocs). The article describes the various logs generated by the Adapter, where to find them, and how to analyze the information provided in them. It then covers problem scenarios that you might encounter and shows you how to solve them. The article assumes that you are familiar with the Adapter and its interfaces and features.

Logs and traces

To troubleshoot problems with the Adapter, you need to know how to enable various logs generated by the Adapter and the underlying JCo components, and then analyze them to understand the problem and determine a solution.

Enabling Adapter traces

All the information traced by the Adapter is found in the logs generated by the runtime on which the Adapter is deployed and run. To enable traces, log in to the server Admin Console and select Troubleshooting => Logs and Trace. Select the server and click on Change Log Detail Levels. Select the Runtime tab and check Save runtime changes to configuration as well. Add the statement*=all to enable Adapter traces, as shown below, then apply and save to the master configuration. You can set the tracing level as required -- Fine, Finer, Finest, Config, All, Severe, and so on.

Logging and Tracing
Logging and Tracing
Logging and Tracing

To specify the trace path, select the server and click Diagnostic trace service. Select the Configuration tab and check Save runtime changes to configuration as well. Specify the name and location of the trace file in File Name, and then apply and save to the master configuration. By default, the trace will be generated in the specified file profile installation directory\logs\serverName\trace.log.

To enable tracing in WebSphere Message Broker (hereafter called Message Broker), you first need to start the trace, execute the flow, and then disable the trace. For more information, see the topic Using trace in the Message Broker V8 information center.

When two or more applications are using the Adapter, the traces from those applications can be individually determined by using the Adapter ID property, which you can configure via the Resource Adapter properties on the Advanced tab:

Configuring Adapter ID
Configuring Adapter ID
Configuring Adapter ID

You can also enable tracing during the discovery of any business object. In the Specify Discovery Properties wizard during discovery, check Change the logging properties for the wizard. Then select the trace path, file name, and tracing level, as shown in Figure 2 above. By default, the trace is generated in the file:

<workspace directory>/.metadata/SAPMetadataDiscovery.log
Configure logging during discovery
Configure logging during discovery
Configure logging during discovery

Enabling JCo component traces

JCo uses the Remote Function Call (RFC) and Common Programming Interface – Communication (CPIC) libraries. Traces generated by these components include JCo API calls, RFC traces, and CPIC traces. You can trace JCo API calls by enabling the JCo traces and setting the appropriate trace level in the Adapter configuration.

The trace level property specifies the level of detail in the traces produced by JCo. The amount of trace data increases with trace level, and each level contains all of the trace data from the lower levels. If you choose one of the higher trace levels, you need to ensure that you have enough free disk space available. Here are the trace levels and level of detail for each one:

  • 0 -- Nothing
  • 1 -- Errors
  • 2 -- Errors and warnings
  • 3 -- Info messages, errors and warnings
  • 4 -- Execution path, info messages, errors and warnings
  • 5 -- Verbose execution path, info messages, errors and warnings
  • 6 -- Verbose execution path, limited data dumps, info messages, errors and warnings
  • 7 -- Full execution path, data dumps with metadata, verbose info messages, errors and warnings
  • 8 -- Full execution path, full data dumps with metadata, verbose info messages, errors and warnings

In the trace path property, you can specify a valid directory to which the JCo and RFC traces are generated. Here is the naming convention for the JCo trace file: JCO(date)_(timestamp).trc. Here is the naming convention for the RFC trace file: rfc(ProcessID)_(ThreadID).trc.

The other permissible values here are null, stdout, and stderr. When you specify null or stdout, traces are written to the standard output stream. When you specify stderr, traces are written to the standard error stream. dev_jrfc.trc is always created when an RFC error occurs, even if traces are turned off

CPIC traces are written into the current user directory, which is the directory specified by the Java® system property user.dir of the underlying runtime. CPIC traces are written to a file with a name of the form CPIC(ProcessID).

JCo traces can also be written into the Adapter traces by checking Write JCo traces to adapter traces. JCo trace level and path are JVM settings, so if a new module is deployed with new values for these settings, the previous settings will be overlayed. You can also activate JCo traces for all applications by specifying these properties via the Java system properties of the underlying runtime. The properties are: jco.trace_path and jco.trace_level. To stop the JCo trace, set JCo trace level property to 0.

To activate the RFC trace, set the property jrfc.trace – to 1 and to disable it, set the property to 2. To activate the CPIC trace, set the property cpic.trace to 0 (trace off), 1, 2, or 3 (most verbose trace).

Activating any of these traces significantly slows down performance, so they are recommended only for a support request or during development

Analyzing JCo traces

Look for input content in the JCO*.trc file to see the inputs sent to SAP. For example, in the lines below:

Analyzing JCo input
Analyzing JCo input
Analyzing JCo input

BAPI_CUSTOMER_GETDETAIL is the input, and it produces the output below:

Analyze JCo output
Analyze JCo output
Analyze JCo output

PARAMS shows seven rows returned by SAP.

You can analyze JCo traces in the above format to learn about the input to and output from SAP by converting the hex string into String by writing some Java code:

//inputting the first row of input
String input = "0042004100500049005F 0043005500530054004F 004D00450052..";
input = input.replaceAll("\\s", "");

//printing the output after converting to string
System.out.println(new String(new BigInteger(input, 16).toByteArray()));

//alternate code to print the output after converting
StringBuilder output = new StringBuilder();
for (int i = 0; i < input.length(); i+=2) {
   String str = input.substring(i, i+2);
   output.append((char)Integer.parseInt(str, 16));

Common errors and their solutions

1. Problem: Request processing fails with java.lang.UnsatisfiedLinkError

Here is a typical error message:

java.lang.UnsatisfiedLinkError: sapjco (.\sapjco3.dll is not a valid Win32 application.)
java.lang.ExceptionInInitializerError: Native library sapjco3 is too old. Found library …
\sapjco3.dll has version “720.63”, but required is at least version “720.94”


To correct this error, verify the following points:

  1. JCo is compatible with the underlying JVM. The 64-bit JCo is required on a JVM that runs in 64-bit mode, and the 32-bit JCo on a JVM running in 32-bit mode.
  2. On Microsoft® Windows®, JCo requires the Microsoft Visual Studio 2005 C/C++ runtime libraries.
  3. The sapjco.jar, and sapjco3.dll or files must be from the same JCo package.

You can verify JCo installation by running the Java class

2. Problem: Adapter starts but fails to send and receive events

The application deploys but doesn't send or receive events sent to or from the SAP System. The traces produced by the Adapter contain this message:

ERROR service ‘sapgwXX’ unknown…
Return code: RFC_FAILURE(1)
Error group: 102


The error indicates that the gateway service (sapgwXX) configured in the Adapter component is not reachable. The gateway service is resolved to a port by the network layer of the operating system. Therefore, an entry that maps the gateway service to the corresponding port has to be made in the services file of the operating system:

sapgwXX 33XX/tcp  (For example, sapgw00 3300/tcp)

If the SAP Gateway is SNC secured, the services file entry should look like this:

sapgwXXs 48XX/tcp  (For example, sapgw00s  4800/tcp)

where XX is the SAP Instance number whose value can be 00 through 99.

On Windows, the services file is located at <WINDOWS>\System32\drivers\etc\services. On Unix, the services file is located at /etc/services.

End the last entry in the services file with a carriage return, because some operating systems do not recognize the last entry.

Alternatively, you can set the gateway service configured in the Adapter component to the port number (33XX), which avoids the port resolution and the above entry in the services file:

Gateway service
Gateway service
Gateway service

On Windows, you can use telnet to verify the gateway host or gateway service connection:

telnet <SAP Gateway HOST> <PORT NUMBER (or) PORT NAME>
For example, telnet 3300 (or) telnet sapgw00

If the connection succeeds, you will see a blank screen. A connection error indicates a problem in the gateway service lookup that will need to be fixed.

On Windows, you can also run into this error if the registry key:


is not set to the location of the services file:


3. Problem: RFC server configured incorrectly


Incorrect settings for RFC destination may result in an exception or an event not getting delivered to the endpoint. The Gateway Host and Gateway Service in the RFC Destination (shown below) must be correct. Otherwise the Adapter will be started but the events will not reach the Adapter and the event will not reach the endpoint:

SAPGUI gateway service and host
SAPGUI gateway service and host
SAPGUI gateway service and host

Also, the Unicode or non-Unicode setting must be correct:

SAPGUI Unicode setting
SAPGUI Unicode setting
SAPGUI Unicode setting

If they are incorrect, you will see this exception in the error trace:

CallbackEventSender sendRecord Unable to deliver event:
Caused by: commonj.connector.runtime.Selec
torException: Business object definition for 'SapAU16640u19456u17664?u17664?AlesapsdlSd1c
l' in namespace '
u17664?alesapsdlsd1cl' not found.. The adapter has not been configured for the IDoc Type
??????????????????????????Oa  ALESAPSDL SD1CL ???: caused by: commonj.connector.runtime.
SelectorException: Business object definition for'SapAU16640u19456u17664?u17664?Alesapsdl
Sd1cl' in namespace '
664?u17664?alesapsdlsd1cl' not found.. The adapter has not been configured for the IDoc 
Type ??????????????????????????Oa  ALESAPSDL SD1CL          ??? at

4. Problem: Maximum conversations exceeded

Outbound requests fail with an error like this:

LOCATION    CPIC (TCP/IP) on local host with Unicode
ERROR       max no of 202 conversations exceeded
TIME        Mon Jul 30 23:00:05 2012
RELEASE     720
COMPONENT   CPIC (TCP/IP) with Unicode


Reduce the timeout value in the endpoint configuration so that unused connections are terminated automatically:

  • Configure the Websphere runtime and SAP gateway to support more RFC connections.
  • On Windows, create and set the environment variable CPIC_MAX_CONV to a value of 100 or higher.
  • Increase the profile values gw/max_conn and gw/max_sys on the SAP gateway to support more parallel connections.
  • If you run into memory bottlenecks, increase gw/max_overflow_size and gw/max_shm_req.
  • Set the maximum connections value in SAP Endpoint to a realistic value, depending on load and parallel requests.
  • Set the server instance value in SAP Endpoint to around 10.

Example Values

  • SAP Gateway: gw/max_conn=2000, gw/max_sys=1200
  • Adjust memory allocation: gw/max_overflow_size =40000000, gw/max_shm_req = 200
  • CPIC_MAX_CONV=5000

5. Problem: Object_unknown or Segment_unknown error


This error occurs when an IDoc whose segments are from a later version is discovered using an earlier version. You can see the error during discovery as well as runtime. To avoid this error, use the correct IDoc release.

6. Problem: Not_authorized error


When you are not authorized to access a particular object, use the SAP GUI to gain access to the object.

7. Problem: Posting multiple IDocs bundled in a flat file


During discovery, a delimiter is selected to delimit every IDoc when posting multiple iDocs, and the streamed data must use this delimiter:


The same delimiter must be present in the stream data when posting the iDocs to SAP.

8. Problem: Performance issues during runtime for BAPI and ALE


If you see performance issues during runtime, remove the optional parameters in BAPI if they are not required while generating the artifacts. Similarly, you can remove the optional segments in an IDoc. When creating artifacts, select the required parameters or segments as shown below:


Frequently asked questions

1. Why doesn't the Adapter receive RFCs or IDocs sent asynchronously (tRFC or qRFC) from a SAP system, even though the SAP System reports that the RFCs or IDocs were sent without errors?

Answer: You need to verify the tRFC events using the t code sm58 in the SAP GUI, and determine whether the event was sent successfully or encountered an error. If the event was sent successfully and you did not receive it, undeploy the existing module and check whether the RFC Program Id is already in use. Go to the TCP/IP connection, select the RFC Destination using the t code sm 59 and click Connection Test. If the RFC Program Id is already in use you will see the screen below:

SAPGUI connection test
SAPGUI connection test

The problem might be that your RFC Program ID is already configured for that particular event and is deployed on a server.

2. Does the SAP Adapter support global transactions?

Answer: No.


This article provided tips and techniques for diagnosing and correcting many of the most common problems when using WebSphere Adapter for SAP Software.


The authors would like to thank Ramkumar Ramalingam from the IBM Emerging Technologies x2020 Analytics team for reviewing this article.

Downloadable resources

Related topics


Sign in or register to add and subscribe to comments.

ArticleTitle=Troubleshooting common problems with WebSphere Adapter for SAP Software