Setting up the IIOP sample environment

To configure CICS® as an IIOP server or client, you need to set up the following host software environment:

Then follow these steps to set up the IIOP environment:

  1. Define the following JCL parameter in the start-up jobstream for a CICS region that supports IIOP:
    REGION
    1000M minimum is recommended
  2. Define the following system initialization parameters in the start-up jobstream for a CICS region that supports IIOP:
    EDSALIM
    500M minimum is recommended
    MAXJVMTCBS
    Specify the number of JVMs that your CICS region can support. The CICS Performance Guide tells you how to work out an appropriate setting for the MAXJVMTCBS system initialization parameter.
    TCPIP
    YES
  3. Add the following DD statements to the start-up jobstream for a CICS region that supports IIOP, and create these files:
    DFHEJDIR
    A recoverable shared file containing the request streams directory. This can be a VSAM file or a coupling facility data table. CICS supplies sample JCL to help you create this file, in the DFHDEFDS member of the SDFHINST library.
    DFHEJOS
    A non-recoverable shared file used by CICS when CORBASERVERS are installed and to store stateful session beans that have been passivated. This can be a VSAM file or a coupling facility data table. CICS supplies sample JCL to help you create this file, in the DFHDEFDS member of the SDFHINST library.

    Sample local VSAM data set definitions for these files are provided in the CICS-supplied RDO group DFHEJVS. These data sets must be authorized with RACF® for UPDATE access. See the CICS RACF Security Guide.

  4. Create a shelf directory on HFS and give the CICS region userid full access to it. See Giving CICS regions access to z/OS UNIX System Services and HFS directories and files for guidance.
  5. Choose a suitable JVM profile and JVM properties file and ensure that CICS is able to locate them, as described in Setting up JVM profiles and JVM properties files.
  6. Ensure that the following environment variables are correctly defined in the JVM profile for the server side application:
    CICS_HOME
    The installation directory prefix of CICS TS:
     /usr/lpp/cicsts/cicsts31/
    where cicsts31 is your chosen value for the USSDIR installation parameter that you defined when you installed CICS TS.
    JAVA_HOME
    The installation directory prefix of the SDK. This is:
     /usr/lpp/java142/J1.4/
    where java142/J1.4 is defined when you install the IBM Software Developer Kit for z/OS, Java 2 Technology Edition, Version 1.4.2.
  7. Ensure that the following files are added to a suitable class path in the JVM profile or JVM properties file:
    • The sample Java source and makefiles that are stored in the z/OS UNIX System Services HFS during CICS installation, in the following directories:
      • $CICS_HOME/samples/dfjcorb/HelloWorld
      • $CICS_HOME/samples/dfjcorb/BankAccount
    • The location where you have compiled the classes for the server side applications.

    Adding application classes to the class paths for a JVM tells you how to do this.

  8. Ensure that the CICS-supplied resource definition groups DFHIIOP and DFH$IIOP are installed. Do this by including the groups in DFHLIST before starting CICS or by using the CEDA option INSTALL to install the resources in CICS whilst it is running. See the CICS Supplied Transactions for information about using CEDA to install resource definitions.
    The supplied group DFH$IIOP contains:
    • Resource definitions required for the TCP/IP listener region (which may also be the same region that runs the sample programs):
      • SSL TCPIPSERVICE definition
      • NOSSL TCPIPSERVICE definition
    • Resource definitions required for the HelloWorld sample:
      • IIHE TRANSACTION definition
      • DFJIIRH REQUESTMODEL definition
      • IIOP CORBASERVER definition
    • Resource definitions required for the BankAccount sample:
      • DFH$IIBI PROGRAM definition
      • DFH$IIBQ PROGRAM definition
      • DFH$IICC PROGRAM definition
      • BANKINQ MAPSET definition
      • BNKI TRANSACTION definition
      • BNKQ TRANSACTION definition
      • BNKS TRANSACTION definition
      • BANKACCT FILE definition
      • DFJIIRB REQUESTMODEL definition
      • IIOP CORBASERVER definition

    The TCPIPSERVICE and IIOP CORBASERVER definitions refer to the default port numbers, 683 and 684. You may need to change these to port numbers that are available to you. Also, the IIOP definition refers to CICSHOST as the host of the corbaserver. You will need to change this to your own host name. See the CICS Resource Definition Guide for information about TCIPSERVICE and CORBASERVER resource definitions..

  9. Translate and compile the following CICS C language programs and mapset and include them in a library in the CICS DFHRPL concatenation. They are stored in SDFHSAMP during CICS installation. The order of compilation is important. Both DFH$IIBI and DFH$IICC can be compiled independently, but the BMS mapset DFH$IIMA must be compiled before compiling DFH$IIBQ. See the CICS Application Programming Guide for guidance on translating, compiling and linking CICS application programs.

    The file DFH$IIMA contains one mapset BANKINQ with two maps. Compile and link the mapset BANKINQ.

    See the CICS Application Programming Guide for guidance on compiling and linking BMS maps.

    DFH$IIBI
    C program that initializes the BANKACCT file. Run by the BNKI transaction.
    DFH$IIBQ
    C program that queries the accounts held in BANKACCT.
    DFH$IICC
    C program that performs a credit check. This is called by DFH$IIBQ.
    DFH$IIMA
    BMS mapset BANKINQ.
    Note: In the names of sample programs and files described in this book, the dollar symbol ($) is used as a national currency symbol and is assumed to be assigned the EBCDIC code point X'5B'. In some countries a different currency symbol, for example the pound symbol (£), or the yen symbol (¥), is assigned the same EBCDIC code point. In these countries, the appropriate currency symbol should be used instead of the dollar symbol.
  10. To compile the IIOP HelloWorld client you require the CosLifeCycle and CosNaming runtime classes. If your client ORB environment does not provide these services ready-built you can use the omgcos.jar file shipped in the $CICS_HOME/lib directory. Alternatively, you may choose to build these classes from the original OMG supplied IDL. In this case a copy of the relevant IDL files is available in $CICS_HOME/samples/dfjcorb. The process of turning pure IDL into executable code is ORB dependent, but if you are using an ORB supplied with a JVM then it is likely that the following commands will work:
     idlj -pkgprefix CosNaming org.omg -pkgprefix CosLifeCycle org.omg -fall CosLifeCycle.idl 
     idlj -pkgprefix CosNaming org.omg -pkgprefix CosLifeCycle org.omg -fall CosNaming.idl
     javac org\omg\CosLifeCycle\*.java org\omg\CosNaming\NamingContextPackage\*.java
           org\omg\CosNaming\*.java  
    You must ensure that these classes are available on your classpath environment variable when you attempt to build any CICS stateless CORBA client application.
  11. Obtain a genfac.ior file containing an object reference to your server's generic factory, and place it in the current directory. The genfac.ior file is created when you issue a PERFORM CORBASERVER PUBLISH command for the installed sample IIOP CORBASERVER resource definition. It is written to the CORBASERVER's shelf directory:
    /var/cicsts/applid/IIOP
    where applid is the APPLID identifier associated with the CICS region.

    You can use the CICS CEMT master terminal command ( see the CICS Supplied Transactions) to issue the PERFORM command, or you can issue the EXEC CICS PERFORM command ( see the CICS System Programming Reference) from a CICS application.

    You can download the IOR to your client workstation (in ascii mode) from the shelf using ftp.