SAP Java Connector 3.0

 
 
Configuration and Requirements
 
Components of the SAP Java Connector
The SAP Java Connector 3.0 runtime environment consists of 2 parts:
  • sapjco3.jar - The archive containing JCo's Java runtime classes
  • {library prefix}sapjco3{shared library extension} - The JNI library containing JCo's native code
JCo's JNI library contains the native code for the network communication. There is only a loose coupling between the JCo archive and the JNI library, however JCo needs a specific minimum version of the JNI library which is usually the one being shipped together with the JCo archive in the distribution package.

Note: If you are using a 32-bit JVM you will also need the 32-bit JCo JNI library, regardless if you are running on a 32-bit or 64-bit operating system.
 
Runtime initialization
When an application references a JCo class for the first time it will be loaded by the associated class loader. During this process JCo's static initializer will be executed. This routine will search and load the JCo JNI library by using the following algorithm:
  1. Try to load the sapjco3 JNI library from the same directory where the sapjco3.jar file resides.
  2. Try to load the sapjco3 JNI library from a platform dependent subdirectory where the sapjco3.jar file resides. The appropriate JNI library loading path is determined by considering the currently used operating system and JVM runtime environment and refers to one of the following subdirectories: ntamd64, ntintel, ntia64, linuxx86_64, linuxintel, linuxppc64, linuxia64, linuxs390x, darwinintel64, darwinintel, rs6000_64, hpia64, hp_64, sunx86_64, sun_64, os390_64, as400_pase_64
  3. Search the sapjco3 JNI library along the directory path defined in the java.library.path system property from left to right, and if found load it from there.
    Note: If this property is not set manually, the JVM will usually set the OS specific library path environment variable as the default java.library.path system property at startup.
  4. Let the JVM handle the loading of the sapjco3 JNI library by delegating this task to its System.loadLibrary(String libname) method.
If the sapjco3 JNI library cannot be found or loaded, you will get an UnsatisfiedLinkError with details provided from the operating system.
This error message may be caused for one of the following reasons:
  • The sapjco3 JNI library cannot be found by using the above described algorithm, because you unintentionally installed it to the wrong directory or forgot to specify its directory in the OS specific library path environment variable or alternatively in the java.library.path system property.
  • The version of the found sapjco3 JNI library is too old.
  • The found sapjco3 JNI library lacks the execute permission flag.
  • The found sapjco3 JNI library does not have the same bit width as the JVM (32-bit vs. 64-bit).
  • The found sapjco3 JNI library is from a different JCo distribution and is not for use with your operating system and/or your hardware processor.
  • The found sapjco3 JNI library requires a higher operating system version.
Please note that JCo sometimes investigates the call stack and hence needs stack traces for working properly.
Hence, the JVM special option -XX:-StackTraceInThrowable cannot be used.
 
Version dialog / Smoke installation test
You can check if JCo is installed correctly by starting its About dialog. This can conveniently be done by using the command

   java -jar {sapjco-install-path}/sapjco3.jar
or
   java -classpath {sapjco-install-path}/sapjco3.jar com.sap.conn.jco.rt.About

The command will pop up a dialog containing all relevant JCo version information. On non-windowing systems you can get the same information printed to the console by typing

   java -jar {sapjco-install-path}/sapjco3.jar -stdout
or
   java -classpath {sapjco-install-path}/sapjco3.jar com.sap.conn.jco.rt.About
   -stdout

There should be no exception or error thrown and all versions should be listed with their correct version numbers and date. Otherwise please see the above chapter "Runtime initialization" for possible installation or configuration errors.
 
Network configuration
JCo uses the CPI-C protocol based on TCP/IP for its low level network communication. Usually the TCP/IP protocol is a communication service provided by the operating system. So, as a prerequisite for JCo to work, the TCP/IP service must be configured.
If you have a working SAPGUI installed on your machine all necessary TCP/IP configuration steps should have been already made during its installation process. But if you install JCo from scratch on a new system, you have to take care of the following:

  • Make sure that the SAP application, message and gateway servers or alternatively the SAP router can be reached physically by using their IP addresses (ping <nnn.nnn.nnn.nnn>). If this won't work please ask your network administrator for help.
  • If desired, make sure that the SAP application, message and gateway servers or alternatively the SAP router can also be reached by using their logical host names (ping <hostname>). If they cannot be reached this way please check your DNS (Domain Name Service) entries or maintain the respective host name in your local hosts file (for Windows systems: <WinDir>\system32\drivers\etc\hosts).
  • If you would like to use the load balanced log on, check if the SAP message server service and its TCP port is defined in the services file. There must be an entry of format "sapms<SID> <portnumber>/tcp" in the services file where <SID> = 3-letter SAP System ID. (In Windows systems the services file is usually stored at <WinDir>\system32\drivers\etc\services)
For more information on the SAP technical infrastructure, network communication and configuration please have a look at SAP Note 21151.
 
Application configuration for Unicode SAP Systems
If you would like to do RFC outbound calls from a Unicode SAP System to a JCoServer instance, you have to set the  Unicode  option for your RFC destination in transaction SM59. This option can be found on the Tab "Special Options", section "Character Width in Target System".
For RFC outbound calls from a Non-Unicode SAP System to a JCoServer instance or for any inbound RFC calls to non-Unicode or Unicode SAP Systems you don't have to do any special configuration tasks.
 
Tracing mechanisms
JCo's tracing mechanism can be turned on by setting the following java environment properties at startup:

   -Djco.trace_level=N (where 0 ≤ N ≤ 10 with 10 = most detailed trace)

and optionally

   -Djco.trace_path=<PATH>

If a trace path is set the JCo traces will be written to one or multiple files named JCO<date>_<time>.<n>.trc in the specified PATH directory. Otherwise the JCo traces will be written to the standard output stream (default is an output to the console).
The same tracing behavior can be achieved by modifying the program code calling the JCo API JCo.setTrace(int level, String path).

The tracing mechanism on the RFC layer can be turned on by setting the java environment property at startup:

   -Djco.jrfc=1. Please note that in this case all connections will be traced, hence this should be only the last resort.

The RFC layer trace files are named jco_rfc<processID>_<threadID>.<n>.trc and will be written to the current working directory, or to the path which jco.trace_path is pointing to. The RFC error log file dev_jco_rfc.trc that can be found in the same directory, is created independently from any trace setting. RFC errors will always be logged in this file. If you would like to trace a special connection only, you can turn on the RFC layer tracing specifically by setting trace=1 in the appropriate JCoDestination or JCoServer configuration properties.


Copyright © 2008-2014 SAP AG. All Rights Reserved.