IBM Support

How to set up the IBM Content Manager for z/OS Toolkit sample programs to run in CICS

Question & Answer


Question

What are steps required to run a sample Java program that uses Content Manager Java API in a CICS environment?

Cause

Each component used by CICS must be enabled for running the sample programs in a CICS environment.

Answer

There are several components that need to be enabled and customized in order to run Java programs that use Content Manager Java application programming interfaces (API) in a CICS environment. The Content Manager Java API is a component of IBM Content Manager for z/OS Toolkit (hereon referred simply as toolkit).

Toolkit provides sample Java and COBOL application to test the CICS environment to access Content Manager. This document provides necessary steps to customize the toolkit and CICS configuration in order to run the sample application. If you decide to follow these steps, the sample customization statements must be modified based on your environment. This document can be used as a supplement to the section Configuring the Content Manager for z/OS Toolkit for the CICS environment, in the Content Manager IBM Knowledge Center.

There are three sample programs included in the toolkit for running under CICS. One is a standalone Java program called SCICSTransactionICM.java. The other two is a COBOL calling Java application (ICMCOBOL and SCICSCMAPI.java). This tech note describes the set up required for running the COBOL to java application, and will equally applies to the standalone Java sample as well by omitting the COBOL related steps.


1. Configure the Content Manager for z/OS Toolkit
  • After the toolkit is successfully installed using SMP/E, you must then run the ICMCONFG job in order to complete the configuration of the toolkit. To run it, you have to customize the input file SICMSAMP(ICMCNFPA) and the job SICMSAMP(ICMCONFG).
      Note: the variable ?prefix? in the ICMCONFG job has the same value as the variable -PathPrefix- specified in the ICMJSMKD job.
  • The next step is to run the ICMVERFY job in order to verify that the toolkit was configured successfully. To run it, you have to customize the input file SICMSAMP(ICMVFYPA) and the job SICMSAMP(ICMVERFY).

2. Update the cmbicmsrvs.ini file
This file can be found under the /prefix/usr/lpp/icm/V8R5M0/cmgmt/connectors directory. Change the values of ICMSSO, ICMDBAUTH, and ICMREMOTE as shown here.
    ICMSERVER=DB1F
    ICMSCHEMA=JT15850L
    ICMSERVERREPTYPE=DB2
    ICMSSO=TRUE
    ICMDBAUTH=CLIENT
    ICMREMOTE=FALSE
    ICMHOSTNAME=
    ICMPORT=

3. Update your TSO user ID .profile
  • Add the statement for the toolkit

    • . /prefix/usr/lpp/icm/V8R5M0/bin/cmbenv81.sh xmlsdk
  • Modify the sample statements for the DB2 JDBC

    • export JCCROOT=/db1f/usr/lpp/db2a10/jdbc
    export STEPLIB=SYS1.DB1F.SDSNEXIT:SYS1.DB1F.SDSNLOAD:SYS1.DB1F.SDSNLOD2
    export PATH=$PATH:$JCCROOT/bin
    export PATH=$PATH:$JCCROOT/lib
    export LIBPATH=.:$JCCROOT/lib
    export CLASSPATH=$CLASSPATH:$JCCROOT/classes/db2jcc.jar
    export CLASSPATH=$CLASSPATH:$JCCROOT/classes/db2jcc_javax.jar
    export CLASSPATH=$CLASSPATH:$JCCROOT/classes/sqlj.zip
    export CLASSPATH=$CLASSPATH:$JCCROOT/classes/db2jcc_license_cisuz.jar
    export CLASSPATH=$CLASSPATH:$JCCROOT/classes
  • Modify the sample statement for CICS TS V4.2

    • export CLASSPATH=$CLASSPATH:/CICS420/lib/com.ibm.cics.server.jar
  • Modify the sample statements for the IBM 64-bit SDK for z/OS, Java Technology Edition V6.0.1 which is required by the CICS TS 4.2

    • export PATH=/jdk6_64bit/J6.0.1_64/bin:$PATH

4. Compile sample programs
The toolkit has a sample COBOL application that calls a Java program which uses the IBM Content Manager Java API to store and retrieve a text file. This step describes how to compile the sample programs.
  • Compile the sample Java program, SCICSCMAPI.java
    • Log on to USS either under TSO OMVS or Telnet by using the user ID that has the .profile modified earlier
    • Issue the following commands

      • cd /prefix/usr/lpp/icm/V8R5M0/samples/java/icm
      javac SCICSCMAPI.java
  • Modify, compile, and link the sample COBOL program, ICMSAMP(ICMCBLCO)
    • Modify the member according to the prolog section. As an example, change ?JAVANAME? to SVT$JAVA
    • Change the cm-commarea

      • 01 cm-commarea.
      05 cm-cmd picture X(12).
      05 dbname picture X(8) value 'DB1F'.
      05 userid picture X(10) value 'icmadm'.
      05 passwd picture X(10) value 'password'.
      05 itemtp picture X(8) value 'NOINDEX'.
      05 attrn1 picture X(8) value 'SOURCE'.
      05 attrv1 picture X(8) value 'cics'.
      05 attrn2 picture X(8) value 'USER_ID'.
      05 attrv2 picture X(8) value 'svt'.
      05 parttp picture X(8) value 'ICMBASE'.
      05 partsrc picture X(60) value '/ICMV850/JT15/usr/lpp/icm/V8R
      - '5M0/samples/java/icm/svt.txt'.
      05 partrtr picture X(60) value '/ICMV850/JT15/usr/lpp/icm/V8R
      - '5M0/samples/java/icm/svt.rtr'.
      05 rc pic s9(9) comp-5 value zero.
    • Submit the job ICMCBLCO to compile and link the COBOL program. A load module, SVT$CBJV will be stored in a loadlib which is in the CICS DFHRPL concatenation
5. Define the sample programs to your CICS region
Add the DFHCSDUP to define program names of sample programs and a CICS transaction.
    DEFINE PROGRAM(SVT$JAVA) GROUP(SVT$SMP)
    DESCRIPTION(SCICSCMAPI.java called by pgm SVT$CBJV)
    LANGUAGE(LE370)
    JVM(YES)
    JVMCLASS(SCICSCMAPI)
    JVMPROFILE(FVTCICSC)

    DEFINE PROGRAM(SVT$CBJV) GROUP(SVT$SMP)
    DESCRIPTION(COBOL CALLING JAVA pgm SVT$JAVA)
    LANGUAGE(COBOL) RELOAD(NO) RESIDENT(NO)
    TRANSID(TDCB) EXECUTIONSET(FULLAPI)
    JVM(NO)

    DEFINE TRANSACTION(TDCB) GROUP(SVT$SMP)
    DESCRIPTION(Transation to call COBOL pgm SVT$CBJV)
    PROGRAM(SVT$CBJV)

6. Create a JVM profile, FVTCICSC
A JVM profile, FVTCICSC, is needed for the JVM to use.
  • Copy the default JVM profile, DFHJVMPR, to the directory specified by the SIT parameter JVMPROFILEDIR as FVTCICSC.

      • As an example in the CICS SYSIN, has the following specified
        JVMPROFILEDIR=/ICMV850/JT15/usr/lpp/icm/V8R5M0/samples/java/icm
      And the JVM profile, FVTCICSC, is in this directory
        EUID=0 /ICMV850/JT15/usr/lpp/icm/V8R5M0/samples/java/icm/
        Type Filename Row 1 of 157
        _ Dir .
        _ Dir ..
        _ File CMFirstSteps.log
        _ File ddo.dtd
        _ File dfhjvmerr.CICSCI4C.data
        _ File dfhjvmin.CICSCI4C.data
        _ File dfhjvmout.CICSCI4C.data
        _ File FVTCICSC
  • Specify REUSE=YES and update the CLASSPATH with all the class paths that are specified in the prefix/usr/icm/V8R5M0/bin/cmbenv81.sh file
7. Create a DB2 plan, DSNJCC
If you do not have a DB2 plan DSNJCC defined in your DB2 subsystem, in the dklog.log, you will see this error message, execConnect:1399: DB2 engine SQL error, SQLCODE = -923, SQLSTATE = 57015, error tokens = ACCESS;00E30301;00000800;DSNJCC.

For details about the DSNJCC, see http://www.ibm.com/support/knowledgecenter/SSGMCP_4.2.0/com.ibm.cics.ts.doc/dfhtk/topics/dfhtk64.html?lang=en

See the sample statements for bind DB2 package DSNJCC and plan DSNJCC.
  • Bind DB2 package DSNJCC using the DB2Binder.
      • java com.ibm.db2.jcc.DB2Binder \
      -url jdbc:db2://stlab49.svl.ibm.com:8010/DB1F \
      -user icmadm \
      -password password \
      -collection DSNJCC
  • Bind DB2 plane DSNJCC
      • //SYSTSIN DD *
      DSN SYSTEM(DB1F)
      BIND PLAN(DSNJCC) KEEPDYNAMIC(YES) ACTION(REPLACE) -
      PKLIST(DB1F.DSNJCC.*)
      RUN PROGRAM(DSNTIAD) PLAN(DSNTIA10) -
      LIB('DSN.DB1F.RUNLIB.LOAD')
      END
      //SYSIN DD *
      GRANT BIND, EXECUTE ON PLAN DSNJCC TO PUBLIC;

8. Test the sample programs
When your CICS TS V4.2 region is activated, ensure the following messages are found in the CICS address space.
    +DFHSJ0101I CICSCI4C 715
    The JVM (SJ) domain for Java has started initializing. Java is a trademark of Oracle and/or its affiliates
    +DFHAP1211I CICSCI4C Language Environment initialization completed.
    +DFHDB2023I 11/25/2015 09:51:34 CICSCI4C The CICS-DB2 attachment has connected connected to DB2 subsystem DB1F
    +DFHSI1517 CICSCI4C Control is being given to CICS
    DFHAM4893 I 11/25/2015 09:51:34 CICSCI4C Install for group SVT$SMP has completed successfully.

The next step is to issue the TDCB transaction to execute the sample programs and by using Client for Windows to display the stored document.
  • Log on to the CICS region using a valid CM user ID
  • Issue transaction TDCB to invoke the sample COBOL program. The CICS session will have the following messages displayed.
      • First Java program call:
        User command is create
        Connect to CM server
        connected
        Creating a document
        created
        Get/Set attriutes name/value
        Attributes setup
        Creating parts
        Part setup
        Storing document to CM
        Document stored successfully
        Disconnect CM server
        Exiting Java sample
      Second Java program call:
        User command is retrieve
        Connect to CM server:
        connected
        Retrieving document from CM server
        Retrieving a document
        query string: /NOINDEX
        Evaluating Query:/NOINDEX
        Number of results:1
        Item Id: A1001001A15K20B54840B00002 (ICMBASE)
        Retrieve document successfully
        Exiting Java sample
  • Log on to the Content Manager Library Server using Client for Windows to display the stored document in the item type NOINDEX


Trouble shooting:
For this implementation:
  • The same set of data sets, SDSNEXIT, SDSNLOAD, SDSNLOD2, and SDSNAHFS is needed
  • The same IBM 64-bit SDK for z/OS, Java Technology Edition V6.0.1 should be used by java, javac, toolkit, and CICS

When testing the sample programs, in addition to the messages displayed on your CICS session, you can check the following area for additional messages:
  • CICS region CEEMSG for the messages printed by sample programs
  • dklog.log in the directory /prefix/usr/lpp/icm/V8R5M0/log/connectors

    • The level of logging can be set by the cmblogconfig.properties file in the directory /prefix/usr/lpp/icm/V8R5M0/cmgmt/connectors
  • dfhjvmerr, dfhjvmin, and dfhjvmout in the directory specified by the WORK_DIR statement in the JVMPROFILE. See sample in the step 6.

[{"Product":{"code":"SSLQWS","label":"Content Manager for z\/OS"},"Business Unit":{"code":"BU053","label":"Cloud & Data Platform"},"Component":"CICS","Platform":[{"code":"PF035","label":"z\/OS"}],"Version":"8.5.0.4;8.5.0.3;8.5.0.2;8.5.0.1;8.5","Edition":"","Line of Business":{"code":"LOB45","label":"Automation"}}]

Document Information

Modified date:
17 June 2018

UID

swg21972287

Page Feedback