5.3 Using the SAP Java Connector Test Utility

The driver uses the SAP Java Connector (JCO) and Business Application Programming Interface (BAPI) technologies to connect to and integrate data with the Identity Vault. The SAP JCO is a SAP client that creates service connections to a SAP R/3 system. After the driver is connected to the R/3 system, it calls methods on business objects within the R/3 system via BAPI.

This utility enables you to check for JCO installation and configuration issues prior to configuring the driver. Use the JCO test utility to validate installation and connectivity to the SAP JCO client, as well as testing for accessibility to the HR BAPIs used by the driver.

In order to configure the driver, you must first download the SAP JCO and install it. For installation instructions, refer to the documentation accompanying the SAP JCO.

There might be minor modifications to JCO components as the connector is updated by SAP. Always refer to the SAP installation documentation for proper configuration instructions.

5.3.1 What Does the Utility Do?

The SAP JCO Test utility completes the following checks:

  • Ensures that the sapjco.jar or sapjco3.jar file, which contains the exported JCO interface, is present.

  • Ensures that the JCO native support libraries are properly installed.

  • Ensures that connection parameters to the SAP R/3 target system are correct.

  • Ensures that the authentication parameters to the SAP R/3 target system are correct.

  • Ensures that the selected language code is valid.

  • Ensures that the BAPIs used by the driver are present as expected for the version of the SAP R/3 target system.

5.3.2 Utility Prerequisites

Before you run the JCO Test utility, you must install the SAP JCO client for the desired platform. The JCO can only be obtained from the SAP Service Marketplace Web site. The download is free to any SAP software customer or development partner, but you are required to log in.

Follow the installation instructions for your platform. Each installation requires you to set one or two environment variables, such as CLASSPATH for the sapjco.jar or the sapjco3.jar file location. For the UNIX* platforms, set either the LD_LIBRARY_PATH or LIBPATH variables for the location of native support libraries. Ensure that these variables are set in the shell environment to run this test and for the subsequent use of the Identity Manager Driver for SAP HR.

You must also make sure that you have your PATH environment variable set to include the path to your Java executable file. For Win32 platforms, the environment variables are set via the System configuration in the Control Panel. On UNIX systems, edit the appropriate .profile or .bash_profile to include and export these path variables.

5.3.3 Components

The JCO Test utility includes a JCOTest.class for SAPHR JCO2 driver and JCO3Test.class for SAPHR JCO3 driver files. You need to create a batch or script file to run the test. The format of the batch or script file varies, depending on the platform on which the JCO client has been installed.

The basic content of the file includes a path to the Java executable (or just java if your PATH is appropriately configured), and the name of the JCOTest.class and JCO3Test.class files.

A sample UNIX script file and Win32 batch file is listed below separately for the JCOTest.class and the JCO3Test.class files.

  • JCOTest.class: The sapjco.jar is in the executable directory of the JCOTest.class file and the batch file.

    Win32 jcotest.bat file
    java -classpath %CLASSPATH%;. JCOTest
    
    Unix jcotest file
    java JCOTest
    
    
  • JCO3Test.class: The sapjco3.jar is in the executable directory of the JCO3Test.class file and the batch file.

    Win32 jco3test.bat file
    java -classpath %CLASSPATH%;. JCO3Test
    
    Unix jco3test file
    java JCO3Test
    

You must use proper slash notation when specifying pathnames and use the proper classpath delimiter for the platform. You must also remember that the name of the sapjco.jar or the sapjco3.jar file is case-sensitive on UNIX platforms and that the name of the test class, JCOTest or JCO3Test must be specified with proper case for any platform.

5.3.4 Running and Evaluating the Test

Running the Test

To run the JCO Test utility on a Win32 platform:

  1. From Windows Explorer, double-click your.bat file.

    or

    From a command prompt, run your .bat script.

To run the JCO Test utility on a UNIX platform:

  1. From your preferred shell, run your jcotest script file.

When you run the test program, an error message might appear before any test output is displayed. This indicates an improper installation of the JCO client components. The error messages are documented for each platform in Understanding Test Error Messages.

Evaluating the Test

If the JCO client is installed properly, the following output is displayed:

**The SAP JCO client installation has been verified to be correct.

Version of the JCO-library: version information
Input SAP Server Connection Information
----------------------------------------

You then receive a series of prompts for connection and authentication information. All data must be provided unless a default value, identified by [] delimiters, is provided. Failure to fill in a response value to each prompt ends the test. Enter information for the following fields when prompted:

  • Application server name or IP address

  • System number[00]

  • Client number

  • User

  • User Password

  • Language code [EN]

The values you provide are the same values that could be used to authenticate via the SAPGUI client. Based on the validity of the input, the test either displays error messages with solution suggestions or runs to completion. At the end of the test, a status message displays. If the test indicates full functionality as required by the driver, the following status message appears (it describes valid values that can be used as the configuration parameters for the driver:

**All expected platform support is verified correct.
JCO Test Summary
----------------
Full JCO/BAPI Functionality has been verified.
The following parameters may be used for SAP HR Driver Configuration

Authentication ID: Username
Authentication Context: SAP Host Name/IP Address
Application Password: User password
Publisher Channel Only? 1
SAP System Number: System Number
SAP User Client Number: Client Number
SAP User Language: Language Code
Master HR IDoc: Default IDoc type for SAP R/3 version

If the test indicates that the functionality required by the driver is not available, the following status message is displayed:

**There are <number> required BAPI functions NOT supported on this platform.

JCO Test Summary
----------------
JCO/BAPI functionality issues have been detected that will prevent proper SAP HR Driver functionality.

Post-Test Procedures

After the JCO Test Utility has passed all tests successfully, the driver can be configured to run. Make sure that the sapjco.jar or the sapjco3.jar file is copied to the location where the sapshim.jar and the saphrshim.jar files have been installed.

On UNIX systems, ensure that the environment variables used for the successful completion of the JCO Test are also in the environment of the driver. If these conditions are met, there should be no driver errors that are related to the JCO.

5.3.5 Understanding Test Error Messages

Use the information in this section to analyze error messages that might display during the JCO Test. Some errors are applicable to all platforms, and other errors are platform-specific.

The test has been run on the platforms listed below. Other UNIX platforms supported by JCO are configured in a similar manner and errors generated by improper JCO installation and configuration should be similar to the errors described for IBM*-AIX* and Solaris*.

JCO2

General Errors

Error Message

Problem

Error connecting to SAP host: com.sap.mw.jco.JCO$Exception: (102)
RFC_ERROR_COMMUNICATION: Connect to SAP gateway failed

Check values of Application Server Name/IP Address and System Number

Undicates that one or both of the values entered for the Application Server Name or IP Address and System Number are incorrect.

Verify that these values are consistent with the information found in the Properties page of the SAP Logon dialog box used to connect to the SAP R/3 system.

Error authenticating to SAP host: com.sap.mw.jco.JCO$Exception: (103)

RFC_ERROR_LOGON_FAILURE: You are not authorized to logon to the target system (error code 1).

The authentication credentials are not valid. Verify that the values for Client Number, User, and User Password are correct.

Error connecting to SAP host: com.sap.mw.jco.JCO$Exception: (101) RFC_ERROR_PROGRAM: Language ’<value>’ not availableCheck value of Language Code

The language code selected is not valid or is not installed on the SAP R/3 system.

Errors on Win32 Systems

Error Message

Problem

“jcotest' is not recognized as an internal or external command, operable program, or batch file.

The jcotest.bat batch file is not present.

Exception in thread “main” java.lang.NoClassDefFoundError: com/sap/mw/jco/JCO$AbapExceptionor Exception in thread “main” java.lang.NoClassDefFoundError: com/sap/mw/jco/JCO$Exception

The sapjco.jar file is not in the location specified in the jcotest.bat file.

Exception while initializing JCO client.java.lang.UnsatisfiedLinkError: no jRFC12 in java.library.path

Verify proper installation of JCO Native support libraries packaged with JCO client.

The jRFC12.dll file that shipped with the JCO client is not installed or is installed in an incorrect location. The default location for jRFC12.dll and libRfc32.dll is /WINNT/system32.

Exception while initializing JCO client.java.lang.UnsatisfiedLinkError: C:\WINNT\system32\jrfc12.dll: Can’t find dependent libraries. 

Verify proper installation of JCO Native support libraries packaged with JCO client.

The librfc32.dll file shipped with the JCO client is not installed or is installed in an incorrect location. The default location for jRFC12.dll and libRfc32.dll is /WINNT/system32.

Errors on IBM-AIX Systems

Error Message

Problem

ksh: jcotest: not found.

The jcotest script file is not present in the directory.

Exception in thread “main” java.lang.NoClassDefFoundError: com/sap/mw/jco/JCO$AbapExceptionorException in thread “main” java.lang.NoClassDefFoundError: com/sap/mw/jco/JCO$Exception

The sapjco.jar file is not in the location specified in the jcotest script file or the case specified for sapjco.jar does not match the actual filename.

Exception while initializing JCO client.java.lang.UnsatisfiedLinkError: no jRFC12 (libjRFC12.a or .so) in java.library.path. 

Verify proper installation of JCO Native support libraries packaged with JCO client.

The libjRFC12.so file that shipped with the JCO client is not installed or is installed in an incorrect location. You must configure a LIBPATH environment variable to specify the location in which the file resides.

Exception while initializing JCO client.java.lang.UnsatisfiedLinkError: <path>/libjRFC12.so: A file or directory in the path name does not exist.

Verify proper installation of JCO Native support libraries packaged with JCO client.

The librfccm.so file shipped with the JCO client is not installed or is installed in an incorrect location. You must copy the file to the same location as libjRFC12.so or configure the LIBPATH environment variable to specify the location in which the file resides.

Errors on Solaris Systems

Error Message

Problem

ksh: jcotest: not found.orbash: jcotest: command not found

The jcotest script file is not present in the directory.

Exception in thread “main” java.lang.NoClassDefFoundError: com/sap/mw/jco/JCO$AbapExceptionorException in thread “main” java.lang.NoClassDefFoundError: com/sap/mw/jco/JCO$Exception

The sapjco.jar file is not in the location specified in the jcotest script file or the case specified for sapjco.jar does not match the actual filename.

Exception while initializing JCO client.java.lang.UnsatisfiedLinkError: no jRFC12 in java.library.path

Verify proper installation of JCO Native support libraries packaged with JCO client.

The libjRFC12.so shipped with the JCO client is not installed or is installed in an incorrect location. You must configure a LD_LIBRARY_PATH environment variable to specify the location in which the file resides.

Exception while initializing JCO client.java.lang.UnsatisfiedLinkError: <path>/libjRFC12.so: ld.so.1: <search-path>: fatal: librfccm.so: open failed: No such file or directory

Verify proper installation of JCO Native support libraries packaged with JCO client.

The librfccm.so file shipped with the JCO client is not installed or installed in an incorrect location. You must copy the file to the same location as libjRFC12.so or configure the LD_LIBRARY_PATH environment variable to specify the location in which the file resides.

Errors on Linux Systems

Error Message

Problem

ksh: jcotest: not found.orbash: jcotest: command not found

The jcotest script file is not present in the directory.

Exception in thread “main” java.lang.NoClassDefFoundError: com/sap/mw/jco/JCO$AbapExceptionorException in thread “main” java.lang.NoClassDefFoundError: com/sap/mw/jco/JCO$Exception

The sapjco.jar file is not in the location specified in the jcotest script file or the case specified for sapjco.jar does not match the actual filename.

Exception while initializing JCO client.java.lang.ExceptionInInitializerError: JCO.classInitialize(): Could not load middleware layer ’com.sap.mw.jco.rfc.MiddlewareRFCno jRFC12 in java.library.path. 

Verify proper installation of JCO Native support libraries packaged with JCO client.

The libjRFC12.so file shipped with the JCO client is not installed or is installed in an incorrect location. You must configure a LD_LIBRARY_PATH environment variable to specify the location in which the file resides

Exception while initializing JCO client.java.lang.ExceptionInInitializerError: JCO.classInitialize(): Could not load middleware layer ’com.sap.mw.jco.rfc.MiddlewareRFC<path>/libjRFC12.so: librfccm.so: cannot open shared object file: No such file or directory.

Verify proper installation of JCO Native support libraries packaged with JCO client.

The librfccm.so file shipped with the JCO client is not installed or is installed in an incorrect location. You must copy the file to the same location as libjRFC12.so or configure the LD_LIBRARY_PATH environment variable to specify the location in which the file resides.

JCO3

General Errors

Use the information in this section to analyze error messages that might display during the JCO3 Test.

Table 5-1 General Errors

Error Message

Problem

Caught Exception during connection: java.ang.Exception: SAP Connection Exception: com.sap.coon.jco.JCoException: (102) RFC_ERROR_COMMUNICATION: Connect to SAP gateway failed

Bad address or system number.

Caught Exception during connection: java.lang.Exception: SAP Connection Exception: com.sap.conn.jco.JCoException: (101) RFC_ERROR_PROGRAM: ‘client’ needs to be a three digit number string instead of ‘<input>’

Bad client number format.

Caught Exception during connection: java.lang.Exception: SAP Connection Exception: com.sap.conn.jco.JCoException: (101) RFC_ERROR_PROGRAM: ‘sysnr’ needs to be a two digit number string instead of ‘<input>’

Bad number format.

Caught Exception during connection: java.lang.Exception: SAP Connection Exception: com.sap.conn.jco.JCoException: (109) RFC_ERROR_CANCELLED: Handle closed pending

Invalid credentials (JCo 3.0.1).

Caught Exception during connection: java.lang.Exception: SAP Connection Exception: com.sap.conn.jco.JCoException: (103) RFC_ERROR_LOGON_FAILURE: Name or password is incorrect (repeat logon) on <host> sysnr <system number>

Invalid credentials (JCo 3.0.2+).

Caught Exception during connection: java.lang.Exception: SAP Connection Exception: com.sap.conn.jco.JCoException: (103) RFC_ERROR_LOGON_FAILURE: Selection one of the installed languages on <host> sysnr <system number>

Invalid Language code.

.java.lang.UnsatisfiedLinkError: no sapjco3 in java.library.path

Caught Exception during connection: java.lang.Exception: SAP Connection Exception: java.lang.NoClassDefFoundError: com.sap.conn.rfc.driver.CpicDriver

Native middleware library not installed properly 3.0.1.

java.lang.ExceptionInInitializerError: Error getting the version of the native layer: java.lang.UnsatisfiedLinkError: com.sap.conn.rfc.driverCpicDriver.nativeCpicGetVerstion([I)I Verify proper installation of JCo Native support libraries packaged with JCo client

Exception while initializing JCo client 3.0.2+.