Java original equipment manufacturer (OEM) API toolkit

To set up your environment, you need the Java™ original equipment manufacturer (OEM) API toolkits for IBM® Content Manager.

In a Content Manager Enterprise Edition installation, the JAR file CMJavaOEMAPIToolkit.jar is in IBMCMROOT/lib.

To set up the environment, complete the following steps:
  1. To install the toolkit, extract the files from IBMCMROOT/lib/CMJavaOEMAPIToolkit.jar (for example, jar xvf IBMCMROOT/lib/CMJavaOEMAPIToolkit.jar) into the OEM API toolkit directory, for example, cmjavaOEMAPIInstallPath.

    Content Manager Enterprise Edition does not have to be installed for the OEM API toolkit to work.

  2. (z/OS® only.) Before the first use of the OEM toolkit, run the following commands:
    cd <cmjavaOEMAPIInstallPath>/bin
./zossetup.sh

    The zossetup.sh script converts the necessary files to EBCDIC encoding.

    Then use the Java OEM API toolkit on z/OS under UNIX System Services.

  3. Make sure that your Java environment setup is complete.
  4. Add the following directory and JAR files to your Java class path. <cmjavaOEMAPIInstallPath> is the directory where the Java OEM Toolkit is installed.
    Windows
    • <cmjavaOEMAPIInstallPath>\cmgmt
    • <cmjavaOEMAPIInstallPath>\lib\cmbicmsdk81.jar
    • <cmjavaOEMAPIInstallPath>\lib\db2jcc4.jar
    • <cmjavaOEMAPIInstallPath>\lib\db2jcc_license_cisuz.jar
    • <cmjavaOEMAPIInstallPath>\lib\log4j-api.jar
    • <cmjavaOEMAPIInstallPath>\lib\log4j-core.jar
    • <cmjavaOEMAPIInstallPath>\lib\xercesImpl.jar
    • <cmjavaOEMAPIInstallPath>\lib\xml-apis.jar
    UNIX System Services
    • <cmjavaOEMAPIInstallPath>/cmgmt
    • <cmjavaOEMAPIInstallPath>/lib/cmbicmsdk81.jar
    • <cmjavaOEMAPIInstallPath>/lib/db2jcc4.jar
    • <cmjavaOEMAPIInstallPath>/lib/db2jcc_license_cisuz.jar
    • <cmjavaOEMAPIInstallPath>/lib/log4j-api.jar
    • <cmjavaOEMAPIInstallPath>/lib/log4j-core.jar
    • <cmjavaOEMAPIInstallPath>/lib/xercesImpl.jar
    • <cmjavaOEMAPIInstallPath>/lib/xml-apis.jar

    If Oracle is used, make sure that the Oracle JAR file (for example, ojdbc8.jar) is in the class path.

    Note: In V8.7.0.1 and later, the names of the log4j .jar files do not include the version numbers. For example, the log4j-api-2.17.1.jar file in V8.7 is now called log4j-api.jar. This means that the application class path does not have to change every time that the .jar files are updated.

    The toolkit directory for Windows and UNIX System Services contains the following items:

    Windows
    • <cmjavaOEMAPIInstallPath>\CMJavaOEMAPIToolkit.readme: Java OEM toolkit readme file
    • <cmjavaOEMAPIInstallPath>\cmgmt\cmbcmenv.properties: Used by the connector to find the other .ini files and used by the logger to find cmblogconfig.properties
    • <cmjavaOEMAPIInstallPath>\cmgmt\connectors\cmblogconfig.properties: Logger properties file
    • <cmjavaOEMAPIInstallPath>\cmgmt\connectors\cmbicmenv.ini: Library server database connect ID information .ini file
    • <cmjavaOEMAPIInstallPath>\cmgmt\connectors\cmbicmsrvs.ini: Library server information .ini file
    • <cmjavaOEMAPIInstallPath>\cmgmt\connectors\cmbpool.ini: WebSphere connection pooling .ini file
    • <cmjavaOEMAPIInstallPath>\cmgmt\connectors\cmbrm.ini: Connector resource manager related options .ini file
    • <cmjavaOEMAPIInstallPath>\cmgmt\connectors\cmbicmcache.ini: Global cache .ini file
    • <cmjavaOEMAPIInstallPath>\cmgmt\connectors\ddo.dtd: DDO .dtd file
    • <cmjavaOEMAPIInstallPath>\cmgmt\connectors\log4j2.xml: log4j 2.x log settings file
    • <cmjavaOEMAPIInstallPath>\bin\cmbenvicm.bat: Windows environment setup bat file
    • <cmjavaOEMAPIInstallPath>\bin\cmbenvicm.sh: AIX environment setup sh file
    • <cmjavaOEMAPIInstallPath>\bin\cmbjavaenv.bat: Windows environment setup including Java .bat file
    • <cmjavaOEMAPIInstallPath>\bin\cmbjavaenv.sh: AIX environment setup including Java .sh file
    • <cmjavaOEMAPIInstallPath>\lib\cmbicmsdk81.jar: IBM Content Manager Connector .jar file
    • <cmjavaOEMAPIInstallPath>\lib\cmapiJavadoc.zip: IBM Content Manager Connector javadoc
    • <cmjavaOEMAPIInstallPath>\lib\db2jcc4.jar: Db2 JCC jar file
    • <cmjavaOEMAPIInstallPath>\lib\db2jcc_license_cisuz.jar: Db2 JCC license jar file
    • <cmjavaOEMAPIInstallPath>\lib\log4j-api.jar: Log4J 2.x jar file
    • <cmjavaOEMAPIInstallPath>\lib\log4j-core.jar: Log4J 2.x jar file
    • <cmjavaOEMAPIInstallPath>\lib\xercesImpl.jar: Xerces jar file
    • <cmjavaOEMAPIInstallPath>\lib\xml-apis.jar: Xerces jar file
    UNIX System Services
    • <cmjavaOEMAPIInstallPath>/CMJavaOEMAPIToolkit.readme: Java OEM toolkit readme file
    • <cmjavaOEMAPIInstallPath>/cmgmt/cmbcmenv.properties: Used by the connector to find the other .ini files and used by the logger to find cmblogconfig.properties
    • <cmjavaOEMAPIInstallPath>/cmgmt/connectors/cmblogconfig.properties: Logger properties file
    • <cmjavaOEMAPIInstallPath>/cmgmt/connectors/cmbicmenv.ini: Library server database connect id information ini file
    • <cmjavaOEMAPIInstallPath>/cmgmt/connectors/cmbicmsrvs.ini: Library server information .ini file
    • <cmjavaOEMAPIInstallPath>/cmgmt/connectors/cmbpool.ini: WebSphere connection pooling .ini file
    • <cmjavaOEMAPIInstallPath>/cmgmt/connectors/cmbrm.ini: Connector resource manager related options .ini file
    • <cmjavaOEMAPIInstallPath>/cmgmt/connectors/cmbicmcache.ini: Global cache .ini file
    • <cmjavaOEMAPIInstallPath>/cmgmt/connectors/ddo.dtd: DDO .dtd file
    • <cmjavaOEMAPIInstallPath>/cmgmt/connectors/log4j2.xml: log4j 2.x log settings file
    • <cmjavaOEMAPIInstallPath>/bin/cmbenvicm.bat: Windows environment setup .bat file
    • <cmjavaOEMAPIInstallPath>/bin/cmbenvicm.sh: AIX environment setup .sh file
    • <cmjavaOEMAPIInstallPath>/bin/cmbjavaenv.bat: Windows environment setup including Java .bat file
    • <cmjavaOEMAPIInstallPath>/bin/cmbjavaenv.sh: AIX environment setup including Java .sh file
    • <cmjavaOEMAPIInstallPath>/lib/cmbicmsdk81.jar: IBM Content Manager Connector .jar file
    • <cmjavaOEMAPIInstallPath>/lib/cmapiJavadoc.zip: IBM Content Manager Connector javadoc
    • <cmjavaOEMAPIInstallPath>/lib/db2jcc4.jar: Db2 JCC jar file
    • <cmjavaOEMAPIInstallPath>/lib/db2jcc_license_cisuz.jar: DB2 JCC license .jar file
    • <cmjavaOEMAPIInstallPath>/lib/log4j-api.jar: Log4J 2.x jar file
    • <cmjavaOEMAPIInstallPath>/lib/log4j-core.jar: Log4J 2.x jar file
    • <cmjavaOEMAPIInstallPath>/lib/xercesImpl.jar: Xerces .jar file
    • <cmjavaOEMAPIInstallPath>/lib/xml-apis.jar: Xerces .jar file
    Note: IBM Content Manager V8.7 (and later) does not include the log4j-1.2.15.jar file, because log4j 1.x is deprecated; if an application needs to use it, you must manually download the jar file.
  5. If your cmbicmenv.ini and cmbicmsrvs.ini files have not been set up for your IBM Content Manager library server, complete the following steps:

    Windows

    1. If you use Oracle, set ORACLE_HOME to your Oracle home directory.
    2. On the command line, run the following command:
      cd <cmjavaOEMAPIInstallPath>\bin
    3. Run the cmbenvicm.bat command or the cmbjavaenv.bat command (which also sets up Java and the OEM API).
      cmbenvicm <cmjavaOEMAPIInstallPath>

      or

      cmbjavaenv <cmjavaOEMAPIInstallPath> <java_home directory>
    4. Change to the connectors directory:
      cd <cmjavaOEMAPIInstallPath>\cmgmt\connectors
    5. Run the com.ibm.mm.sdk.util.cmbenvicm Java utility to add the database connect user ID and password for cmbicmenv.ini.
      java com.ibm.mm.sdk.util.cmbenvicm -a add -s <library_server_database_name> -u <database_connect_id> -p <database_connect_id_password>
      For example: 
      java com.ibm.mm.sdk.util.cmbenvicm -a add -s icmnlsdb -u icmconct -p password

      To see more options for this command, run it without any parameters, like this: 

      java com.ibm.mm.sdk.util.cmbenvicm

      For more information about this command, see V8 connector file (cmbicmenv.ini).

    6. Run the com.ibm.mm.sdk.util.cmbsrvsicm Java utility to add IBM Content Manager library server information to the cmbicmsrvs.ini file. 
      java com.ibm.mm.sdk.util.cmbsrvsicm -a add -s <library_server_database_name> -sm <database_schema> -r <database_representation_type> -rs <TRUE | FALSE> (remote server indicator (default FALSE)) -host <library_server_hostname> -port <library_server_port_number> -rdb <library_server_remote_database_name> -os <NT | MVS | AIX | SUN | Linux | OS/400> (operating system type (default no value) -jdbcDriver <JDBC_driver_main_class_name> (default ) -jdbcConnectionURL <JDBC connection URL used to get the connection from Driver Manager> -jndiref <JNDI Indirect lookup reference resource string> (default ) -dbver <database_version> (default)

      For example:

      Db2
      java com.ibm.mm.sdk.util.cmbsrvsicm -a add -s icmnlsdb -sm ICMADMIN -r DB2 -rs TRUE -host cmwin.ibm.com -port 50000 -rdb icmnlsdb -os NT
      Oracle
      java com.ibm.mm.sdk.util.cmbsrvsicm -a add -s icmnlsdb -sm ICMADMIN -r ORACLE -rs TRUE -host cmwin.ibm.com -port 1521 -rdb icmnlsdb -os NT - jdbcConnectionURL jdbc:oracle:thin:@//cmwin.ibm.com:1521/icmnlsdb

      Many of these options are optional. To see more options for this command, run it without any parameters, like this: 

      java com.ibm.mm.sdk.util.cmbsrvsicm

      For more information about this command, see V8 connector file (cmbicmenv.ini).

    UNIX System Services
    Note: Make sure that all the .ini files, properties files, and directories have a permission of 775.
    1. If you use Oracle, set ORACLE_HOME to your Oracle home directory.
    2. Change to the bin directory:
      cd <cmjavaOEMAPIInstallPath>\bin
    3. Run the cmbenvicm.sh command or the cmbjavaenv.sh command (which also sets up Java and the OEM API), after changing the file permissions to 775.
       . ./cmbenvicm.sh <cmjavaOEMAPIInstallPath>

      or

      . ./cmbjavaenv <cmjavaOEMAPIInstallPath> <java_home_directory>
    4. Change to the connectors directory:
      cd <cmjavaOEMAPIInstallPath>\cmgmt\connectors
    5. Run the com.ibm.mm.sdk.util.cmbenvicm Java utility to add the database connect user ID and password for cmbicmenv.ini.
      java com.ibm.mm.sdk.util.cmbenvicm -a add -s <library_server_database_name> -u <database_connect_id> -p <database_connect_id_password>
      For example: 
      java com.ibm.mm.sdk.util.cmbenvicm -a add -s icmnlsdb -u icmconct -p password

      To see more options for this command, run it without any parameters, like this: 

      java com.ibm.mm.sdk.util.cmbenvicm

      For more information about this command, see V8 connector file (cmbicmenv.ini).

    6. Run the com.ibm.mm.sdk.util.cmbsrvsicm Java utility to add IBM Content Manager library server information to the cmbicmsrvs.ini file. 
      java com.ibm.mm.sdk.util.cmbsrvsicm -a add -s <library_server_database_name> -sm <database_schema> -r <database_representation_type> -rs <TRUE | FALSE> (remote server indicator (default FALSE)) -host <library_server_hostname> -port <library_server_port_number> -rdb <library_server_remote_database_name> -os <NT | MVS | AIX | SUN | Linux | OS/400> (operating system type (default no value) -jdbcDriver <JDBC_driver_main_class_name> (default ) -jdbcConnectionURL <JDBC connection URL used to get the connection from Driver Manager> -jndiref <JNDI Indirect lookup reference resource string> (default ) -dbver <database_version> (default)

      For example:

      Db2
      java com.ibm.mm.sdk.util.cmbsrvsicm -a add -s icmnlsdb -sm ICMADMIN -r DB2 -rs TRUE -host cmwin.ibm.com -port 50000 -rdb icmnlsdb -os NT
      Oracle
      java com.ibm.mm.sdk.util.cmbsrvsicm -a add -s icmnlsdb -sm ICMADMIN -r ORACLE -rs TRUE -host cmwin.ibm.com -port 1521 -rdb icmnlsdb -os NT - jdbcConnectionURL jdbc:oracle:thin:@//cmwin.ibm.com:1521/icmnlsdb

      Many of these options are optional. To see more options for this command, run it without any parameters, like this: 

      java com.ibm.mm.sdk.util.cmbsrvsicm

      For more information about this command, see V8 connector file (cmbicmenv.ini).

    Note: To use Oracle, you must install it separately. Add the Oracle .jar files that are needed during runtime to the CLASSPATH.
  6. The following log directories are created if they do not exist during runtime, if the relative path Java property com.ibm.mm.sdk.logtool.cmlogrelativepath=true or the cmbcmenv.properties keyword CMLOGRELATIVEPATH=TRUE is specified.
    Windows
    <cmjavaOEMAPIInstallPath>\cmlog\connectors
    UNIX System Services
    <cmjavaOEMAPIInstallPath>/cmlog/connectors

    If the base log path (Java property com.ibm.mm.sdk.logtool.cmbaselogpath=<baselogpath> or cmbcmenv.properties keyword CMBASELOGPATH=<baselogpath>) is specified, the preceding directories are created under that path. The Java property takes precedence over the keyword.

    Windows
    <baselogpath>\cmlog\connectors
    UNIX
    <baselogpath>/cmlog/connectors

Base log path examples

Java property
com.ibm.mm.sdk.logtool.cmbaselogpath=C:\WebSphere\AppServer\profiles\AppSrv01\logs\server1\myapp
CMBASELOGPATH keyword
CMBASELOGPATH= C:\\WebSphere\\AppServer\\profiles\\AppSrv01\\logs\\server1\\myapp
These directories override the log directory that is specified in the following items:
  • the cmblogconfig.properties keywords log4j.appender.apiAppender.File for the log4j logger
  • the DKLogOutputFileName for the default logger
  • <RollingFile name="apiAppender" fileName="${sys:user.name}.dklog.log" filePattern="${sys:user.name}.dklog.log.%i"> in the log4j2.xml file.
If the log path cmlog/connectors must be created, there are two Java properties that allow you to specify the directory administration user and group directory owner. After the directory is created, the connector performs a chown for UNIX System Services to that user:group. Also, for UNIX System Services, the connector tries to change the directory permission to 775, unless the Java property com.ibm.mm.sdk.logtool.cmlogadmperm is used with a different permission.
  • com.ibm.mm.sdk.logtool.cmlogadmuser=<userid>
  • com.ibm.mm.sdk.logtool.cmlogadmgroup=<userGroup>
  • com.ibm.mm.sdk.logtool.cmlogadmperm=<directory permission>

Relative path methodology

To find the .ini file, the cmbcmenv.properties is found by the class path. After the connector finds the file, it searches for the Java property com.ibm.mm.sdk.common.cmrelativepath=true or the keyword CMRELATIVEPATH=TRUE. The relative path indicator tells the connector to find the .ini files in the cmgmt/connectors directory, which is based on the location of the cmbcmenv.properties file that is found by the class path. The Java property takes precedence over the keyword.

To find the cmblogconfig.properties file, which contains logging information, the cmbcmenv.properties is found by the class path. After the connector finds the file, it searches for the Java property com.ibm.mm.sdk.logtool.cmlogrelativepath=true or the keyword CMLOGRELATIVEPATH=TRUE. The relative path indicator tells the connector to find the cmblogconfig.properties file in the cmgmt/connectors directory, which is based on the location of the cmbcmenv.properties file that is found by the class path. The Java property takes precedence over the keyword.

Enabling traces

To enable full traces for the IBM Content Manager API, you must set the DKAPIJavaLogLevel property in the log4j2.xml file. For more information, see Changing the logging configuration files for the IBM Content Manager connectors.

In IBM Content Manager V8.7 (and later), the API uses log4j 2.x by default. All applications must use log4j 2.x, because support for log4j 1.x is deprecated. For more information, see Moving from log4j 1.x to log4j 2.x.

Testing the configuration

Testing the connection to the library server

To test the connection to the library server that has been set up in the .ini files (see step 5), run the following command: 

java com.ibm.mm.sdk.server.TTestConnectUtilityICM -server <library_server_database_name> -userid <userid> -password <password> -connectString <connect_string (optional)> -configString <configuration_string (optional)>

For example:

java com.ibm.mm.sdk.server.TTestConnectUtilityICM -server icmnlsdb -userid icmadmin -password password

Testing the list data sources

To test the list data sources that are in the cmbicmsrvs.ini file (see step 5), run the following command:

java com.ibm.mm.sdk.server.TTestListDataSourcesUtilityICM

For example:

java com.ibm.mm.sdk.server.TTestListDataSourcesUtilityICM

Testing the listing catalog

To test the listing catalog (that is, item types and item type views) from a library server, run the following command:

java com.ibm.mm.sdk.server.TTestListCatalogUtilityICM -server <library_server_database_name> -userid <userid> -password <password> -connectString <connect_string (optional)> -configString <configuration_string (optional)>

For example:

java com.ibm.mm.sdk.server.TTestListCatalogUtilityICM -server icmnlsdb -userid icmadmin -password password

Testing the connection to the resource manager

(This feature is available in IBM Content Manager V8.7 fix pack 3 and later.)

To test the connection to the resource manager, run the following command:

java com.ibm.mm.sdk.server.TTestConnectRMUtilityICM -server <library_server_database_name> -userid <userid> -password <password> -connectString <connect_string (optional)> -configString <configuration_string (optional)> -rmName <resource_manager_name>

For example:

java com.ibm.mm.sdk.server.TTestConnectRMUtilityICM -server icmnlsdb -userid icmadmin -password password -rmName rmdb