Installing SAP JCo

on-site-related topic

This section tells you how to install the SAP JCo library on Windows and UNIX. Redwood Platform installs the JCo automatically for you when you place the unzipped file (tgz for UNIX, ZIP for Windows) into the <install_dir>/j2ee/cluster/global/tomcat directory. Note that you have to restart Redwood Platform for it to detect the changes.

Note: SAP Service marketplace zips the actual JCo archive; this means that for Linux on x86_64, for example, you have to unzip the file to get the tgz file. For Microsoft Windows, it is the same, except that the ZIP file you downloaded contains another ZIP file; this is the file you need to copy to the directory specified above. Windows users can use Windows Explorer to make sure they have the correct ZIP file which contains sapjco3.dll at the root of the ZIP file.

SAP JCo Installation Files

  • sapjco3.jar
  • sapjco3.dll - Windows
  • libsapjco3.so - AIX, HP-UX on IA64 (Itanium), Linux

Prerequisites

  • All Platforms
    • SAP JCo 3.1 or higher
    • You need the SAP JCo of the same platform as your JVM; a 32-bit JCo requires a 32-bit JVM, even on 64-bit platforms. Note that the use of 32-bit JVM's is not recommended on 64-bit platforms.
    • JCo requires the Java Cryptographic Extension (JCE) Unlimited Strength Jurisdiction Policy Files; available for Oracle JVM's on Java SE Downloads. Note that SAP JVM's already have these installed.
    • On Microsoft Windows platforms, JCo 3.1 requires the Microsoft Visual C++ 2013 redistributable libraries.
    • javac (available in the Java JDK)
    • SAP Note 1456826 - The jco.use_repository_roundtrip_optimization property defaults to 1 with JCo 3.1, its default is 0 with JCo 3.0, hence if you are upgrading, RFC_METADATA_GET authorizations are now mandatory.

Checking your JVM for Java Cryptographic Extension (JCE)

These instructions are provided for your convenience; the provided Java code is very trivial, for example, it has no error handling and is provided solely for checking for the JCE unlimited strength jurisdiction policy files.

Note: This program is not covered by your support contract, it is provided to help you ensure you have installed the necessary policy files correctly and that your JVM has picked them up properly; if this program fails in some manner, you should contact your JVM vendor.

Skipping the JCo Installation

If the JCO Libraries installation was skipped at some point, edit the registry entry /configuration/jco/skip and set the value to false before restarting the central server.

Prerequisites

  • javac (available in the Java JDK)

Create the Program

You create a tiny trivial Java program to check for the JCE:

  1. Create a file named testJCE.java (It must have that name unless you want to change the code below).
  2. Copy the below code into the testJCE.java file.
  3. Compile the Java program: javac testJCE.java.
  4. Execute the compiled program: java -cp . testJCE.
Copy 
public class testJCE
{
  public static void main (String[] args)
   throws java.security.NoSuchAlgorithmException
   {
    int maxKeyLen = javax.crypto.Cipher.getMaxAllowedKeyLength("AES");
    //without JCE, maxKeyLen is 128, with JCE, it is Integer.MAX_VALUE
    if (maxKeyLen < 129)
    {
      System.out.println("No, you do not have the policy files installed!\n Maximum key length is set to: " + maxKeyLen);
    }
    else
    {
      System.out.println("Yes, you have the policy files installed!\n Maximum key length is set to: " + maxKeyLen);
    }
  }
}

The program should print the following when the policy files have been picked up by your JVM:

Copy 
Yes, you have the policy files installed!
 Maximum key length is set to: [...]

Procedure

Install SAP JCo

This procedure uses the capabilities of Redwood Platform to install SAP JCo.

  1. Go to service.sap.com/connectorsMore about SAP Java Connector and download the appropriate 3.1.x JCo file for your platform and unzip the file.
  2. On Windows, copy the file to ${install_dir}/j2ee/cluster/global/tomcat, the file will be automatically extracted on startup.
  3. On unix, extract the sapjco3.jar, as well as the library libsapjco3, from the archive downloaded from SAP. The jar file must be copied into your CLASSPATH, for example the ${install_dir}/j2ee/cluster/global/tomcat/lib directory of your application server. The library needs to be copied into your library path, for example ${JAVA_HOME}/bin.

Note: Ensure that the library has met all its dependencies, use ldd on most Unices. See SAP Note 2786882 for more information.

SAP JCo on Windows

  1. Go to Microsoft Download Center, download the file, and install it onto the server.
  2. Go to SAP ConnectorsMore about SAP Java Connector and download the appropriate 3.1.x JCo file for Windows on your platform and unzip the file.
    1. If the file you just unzipped is yet another ZIP file, unzip it once more.
  3. Copy sapjco3.dll to <install_dir>/j2ee/cluster/global/tomcat/lib/<platform> and the sapjco3.jar to <install_dir>/j2ee/cluster/global/tomcat/lib/.

SAP JCo on AIX

  1. Go to service.sap.com/connectorsMore about SAP Java Connector > Tools and download the appropriate 3.1.x JCo file for AIX and unzip the file.
  2. Gunzip, and untar the downloaded file into a temporary directory.
  3. Place the libsapjco3.so into a directory referenced by the LIBPATH environment variable; you set the LIBPATH in the <install_dir>/j2ee/cluster/server1/bin/setvars.sh.
  4. Place the sapjco3.jar into the classpath of the application server, such as <install_dir>/j2ee/cluster/global/tomcat/lib.
  5. (Optional) You issue ldd /path/to/libsapjco3.so to check all dependencies are met.

Note: AIX 5.3 and later support both LIBPATH and LD_LBRARY_PATH.

SAP JCo on Other UNIX

These instructions cover HP-UX on IA64 (Itanium), Linux, and Solaris, the latter two on all platforms.

  1. Go to service.sap.com/connectorsMore about SAP Java Connector and download the appropriate 3.1.x JCo file for your platform and unzip the file.
  2. Gunzip, and untar the downloaded file into a temporary directory.
  3. Place the libsapjco3.so into a directory referenced by the LD_LIBRARY_PATH environment variable; you set the LD_LIBRARY_PATH in the <install_dir>/j2ee/cluster/server1/bin/setvars.sh.
  4. Place the sapjco3.jar into the classpath of the application server, such as <install_dir>/j2ee/cluster/global/tomcat/lib.
  5. (Optional) You issue ldd /path/to/libsapjco3.so to check all dependencies are met.

Troubleshooting

The following code will traverse all paths specified in java.library.path and print all JCo libraries found. You can issue this in the web-based shell. Note that you might have to temporarily skip JCo initialization prior to executing the following code in the web-based shell ( "Scripting > Shell" ).

Copy 
import java.io.File;
{
  File[] fList;
  File directory;
  String[] dlist = System.getProperty("java.library.path").split(System.getProperty("path.separator"));

  for (String dirName : dlist)
  {
    directory = new File(dirName);
    fList = directory.listFiles();
    if (fList != null)
    {
      for (File file : fList)
      {
        if (file != null && file.isFile() && file.getName().indexOf("jco") > -1)
        {
            jcsOut.println(file.getAbsolutePath());
        }
      }
    }
  }
}

See Also

Download and Extract redwood-platform.zip