Using the IMS Samples

The IMS samples demonstrate how BEA WebLogic Java Adapter for Mainframe (WebLogic JAM) integrates WebLogic applications with IMS applications on a mainframe. This section provides the following information:

• About the IMS Samples

• Roadmap for the Samples

• Using the Samples

 

---

About the IMS Samples

The following section provides a brief overview of each of the IMS samples described in this guide. A detailed description of how each sample works and instructions for running each sample are provided in the Using the Samples section.

IMS Application to WebLogic Server JMS Topic

This sample demonstrates an asynchronous call through WebLogic JAM from IMS to a Java application running under WebLogic Server. In this sample, the supplied IMS client uses implicit APPC to make a request of a service advertised by the WebLogic JAM Gateway. This service takes all request data and places it on a JMS topic. The Gateway uses a DataView to convert the request data to XML before it is placed on the JMS topic. A topic receiver class is shipped with this sample so you can view the messages as they are placed on the JMS topic.

This sample highlights WebLogic JAM support of JMS that allows mainframe client programs to insert messages onto JMS queues or topics. In this sample, a COBOL copybook is created to use with the eGen Application Code Generator by examining the record layout for the IMS client application.

The WebLogic JAM Gateway uses DataView classes to translate the data received from the mainframe into XML. To accomplish this translation, the Gateway must be able to load the necessary DataView class; the necessary DataView class must be in the CLASSPATH set in the WebLogic Server startup script.

Java Client to IMS Sample Application

This sample demonstrates a Java client calling remote services located in an IMS application. The Java client receives a command and a record name from you. You enter one of the following commands: add, display, update, or delete. You may enter a host address and port if the gateway is running on a different machine. Depending on the command, the client may prompt you for additional information. The client then makes a service call to the installation verification transaction, IVTNO, that is shipped with IMS. The result displays.

IVTNO was chosen for a back-end application to this sample because IMS users will already have it installed or can easily do so. If you want to run this sample and IVTNO is not installed in your IMS region, coordinate the installation with your IMS system programmer. The use of IVTNO as a back-end application also illustrates how WebLogic JAM facilitates the integration of Java application with legacy applications without change to the legacy application. In this sample, COBOL copybooks are created to use with the eGen Application Code Generator by examining the record layout for the IMS application instead of using pre-existing copybooks. The record definitions are in the IMS sample program, DFSIVA1.

Transactional Sample from WebLogic Server to IMS

This sample demonstrates how a Java client makes calls to remote services located in an IMS application. The service calls that alter the data on the mainframe occur within the boundaries of two-phase commit transactions. The sample contains a transaction that is distributed over resources managed by WebLogic Server and resources located on the mainframe. This transaction uses a service call to add a record to the IVTNO database. The key to the record is inserted on a JMS queue within the boundaries of the same transaction as the service call to create the record. The queuing of the record key and the creation of the record in IMS will either be committed or rolled back together depending on the command line option you set.

The installation verification transaction, IVTNO, (shipped with IMS) was chosen for a back-end application to this sample because IMS users will already have it installed or can easily do so. If you want to run this sample and IVTNO is not installed in your IMS region, coordinate the installation with your IMS system programmer. The use of IVTNO also illustrates how WebLogic JAM facilitates the integration of Java applications with legacy applications with no change to the legacy application. In this sample, COBOL copybooks are created to use with the eGen utility by examining the record layout for the IMS application instead of using pre-existing copybooks. The record definitions are in the IMS sample program DFSIVA1.

 

---

Roadmap for the Samples

To run the IMS samples, follow the roadmap listed below. General tasks for all of the IMS samples include:

1. Verify prerequisite tasks.

   For a listing of prerequisite tasks, see the Before You Run the Samples section.

2. Prepare to use the IMS sample.

   1. Start the CRM.

   2. Update the WebLogic JAM configuration file.

   3. Start the examples domain.

   4. Configure the WebLogic JAM Gateway.

Specific tasks for each sample include:

1. Set up the sample.

   1. Enable services.

   2. Set the environment.

   3. Generate and build source (optional).

   4. Complete mainframe tasks.

2. Run the sample.

 

---

Using the Samples

After you have completed the tasks described in the Before You Run the Samples section, you are ready to use the sample. Information about how to use the IMS samples is presented in the following sections:

• Preparing to Use the IMS Samples

• Using the IMS Application to WebLogic Server JMS Topic

  • Understanding How the Sample Works

  • Setting up the Sample

  • Running the Sample

• Using the Java Client to IMS Sample Application

  • Understanding How the Sample Works

  • Setting up the Sample

  • Running the Sample

• Using the Transactional Sample from WebLogic Server to IMS

  • Understanding How the Sample Works

  • Setting up the Sample

  • Running the Sample

Preparing to Use the IMS Samples

The following steps are common to all the IMS samples. These steps only need to be performed once for all IMS samples.

Step 1: Start the CRM

Before starting the WebLogic JAM Gateway, start the CRM. The CRM must be configured with certain parameter values at startup. These parameter values include:

• The address of the machine on which the CRM is running

• The port on which the CRM listens

• The name the Gateway will use to refer to the CRM

For running the samples, you must set the machine address and port. The values that you set for the machine address and port when the CRM is started, must agree with the values that you set for the CRM in the WebLogic Administration Console for the samples CRM. The name of the CRM that is preconfigured for running all of the samples is CRM1. Use this name when the CRM is started to run any of the samples.

The way you start the CRM depends on whether the CRM will be started under a Unix or MVS system. On Unix, start the CRM using a shell script. On MVS, start the CRM using JCL.

Starting the CRM on z/OS or OS/390 Unix

On z/OS or OS/390 Unix, you may use a script to start the CRM. Scripts are installed with the Gateway in the <BEA_HOME>/<JAM_INSTALL_DIR>/samples/crm/unix directory. The script, crm.env, appends the necessary values to your environment variables. The script, startcrm.sh, starts the CRM. To use these scripts, complete the following steps:

1. FTP the following two scripts to the directory from which the CRM will run:

   • crm.env

   • startcrm.sh

2. Edit crm.env. Supply the correct values for the APPDIR and CRMDIR variables. APPDIR is the directory from which the CRM will run. CRMDIR is the CRM installation directory.

3. Edit startcrm.sh. To use a different port than the default port, 7101, change the port number. However, if you change the port number, make sure to change it in the corresponding field in the WebLogic Administration Console CRM1 pane. You do not need to change the address because the script will run on the machine where the CRM is installed.

   Note: BEA recommends that you do not change the CRM name from CRM1. This name for the CRM is preconfigured for all of the samples.

4. Execute the startcrm.sh script:

   . ./startcrm.sh 

Compare Figure 2-1 with the script in Listing 2-1. Notice how the parameters in the script correspond to the fields in the WebLogic Administration Console. The script illustrates the values for startcrm.sh script parameters for running the samples.

Note: The port number is 7101. You can change the port number; however, if the port number is changed make sure to change it in the corresponding field in the Gateway configuration CRM1 pane of the WebLogic Administration Console.

 

Figure 2-1 Fields for the CRM

 

Listing 2-1 Command to Run the CRM

$CRMDIR/bin/CRM //127.0.0.1:7101 CRM1 < /dev/null > std.out 2>std.err & 

Starting the CRM on z/OS or OS/390 MVS

On z/OS or OS/390 MVS, start the CRM by submitting the CRMSTART JCL that is installed with the CRM. The CRMSTART JCL must be modified for your environment. For information about modifying the CRMSTART JCL, see the BEA WebLogic Java Adapter for Mainframe Configuration and Administration Guide.

As you modify the CRMSTART JCL, make sure that you note the following parameters in the value of the STARTCMD parameter in the JCL. These parameters correspond to fields in the WebLogic Administration Console. These values must be the same in the JCL and in the WebLogic Administration Console.

• The machine address where the CRM will run

• The port number on which the CRM will listen

• The name by which the Gateway will refer to the CRM

Compare Figure 2-1 with the JCL in Listing 2-2. Notice how the parameters in the JCL correspond to the fields in the WebLogic Administration Console. The JCL illustrates the values for STARTCMD parameters for running the samples.

• The machine where the CRM will run is myhost in this sample. You must replace myhost with the hostname or IP address of your mainframe to allow IP-based communication from the Windows or Unix machine where WebLogic Server is running. You may verify this parameter with the ping command on Windows or Unix.

• The port number is 7101. You can change the port number; however, if you change the port number, make sure to change it in the corresponding field in the Gateway configuration CRM1 pane of the WebLogic Administration Console.

Note: BEA recommends that you do not change the CRM name from CRM1, because this name for the CRM is preconfigured for all of the samples.

Listing 2-2 The STARTCMD parameter in the CRMSTART JCL

// SET STARTCMD='"//myhost:7101" CRM1'

Step 2: Update the WebLogic JAM Configuration File

On the machine where the Gateway is installed, update the WebLogic JAM configuration file from the command prompt by completing the following steps:

1. Locate the jamconfig_IMS.xml file under the following directory:

   <BEA_HOME>/<JAM_INSTALL_DIR>/config/examples

2. Copy jamconfig_IMS.xml to jamconfig.xml.

Step 3: Start the examples Domain

From the command prompt, execute the following command from the examples directory to start the examples domain:

• For Microsoft Windows:

  startExamplesServer.cmd 

• For Unix:

  . ./startExamplesServer.sh 

Step 4: Configure the WebLogic JAM Gateway

Most configuration tasks are preconfigured or completed during the installation process by the installer program. For additional information about configuring WebLogic JAM, see the BEA WebLogic Java Adapter for Mainframe Configuration and Administration Guide. However, you must make the following configuration changes for the IMS samples to run on your system. These changes can be made in the WebLogic Administration Console in the following way.

1. From your browser, open the WebLogic Administration Console using the following address:

   http://hostname:7001/console

   In this address, the following definitions apply:

   hostname is the address of the machine where WebLogic Server is running.

   7001 is the port for WebLogic Server that has been configured for the examples domain.

2. When prompted, supply the following user and password information:

   • user: system

     This user name cannot be changed.

   • password: security

     To change the password, see the BEA WebLogic Server documentation.

   The WebLogic Administration Console displays.

   
    

3. To configure the CRM to the WebLogic JAM Gateway, complete the following steps:

   1. In the left pane, click on Java Adapter for Mainframe —> JAM Components —> CRMs. In the right pane, click CRM1. On the General tab, set the following fields to correspond with your system. Click Apply. When the CRM is active, Status turns from red to green.

      
       

      
       

Field	Field Description
Listen Address	The address of the machine where the CRM is installed and running. This address must match the address set in the CRM startup JCL or script.
Listen Port	The port for the CRM. This entry must match the port set in the CRM startup JCL or script.
Logical Unit	The name of the Logical Unit defined for the CRM.
Stack Type	The stack type.

.

1. To configure the IMS region, click Java Adapter for Mainframe —> Regions —> IMS Regions in the left pane. In the right pane, click VS10IMS. Enter the Logical Unit name that supplies your IMS control region with APPC communication. You will find this name with the DISPLAY APPC operator command in IMS. Do not enter the Logical Unit name for APPLID of the IMS control region. This APPLID does not support APPC communication. If your IMS control region does not currently support APPC communication, you will need to set up this communication in APPC/MVS. Then activate the communication within IMS using the START APPC Operator command. Click Apply to set the Logical Unit.

Note: This Logical Unit is not the same as the Logical Unit for the CRM in (3a).


 

1. Click IMS Regions at the top of the right pane. In the new window, click CRM1toIMS. On the Links tab, check Deployed and click Apply.

   
    

2. In the left pane, click Gateways. Click JAM5.1 in the right pane. On the General tab, check Deployed and click Apply.

   
    

4. To start the Gateway, select the Administration tab —>Start/Stop tab. Click Start to start the Gateway.

   
    

   If the Gateway is running, Status changes to green in the WebLogic Administration Console and the following message appears in the WebLogic Server log:

   "JAM Gateway ready for use. Current link status: up(1)."

You have completed the general steps required to prepare your system to run the IMS samples. Select the IMS sample you want to run and follow the steps in that section to set up and run that sample.

Using the IMS Application to WebLogic Server JMS Topic

After completing the steps in the Preparing to Use the IMS Samples section, you are ready to set up and run the IMS Sample Application to WebLogic Server JMS topic.

How the Sample Works

This sample illustrates making an asynchronous call through WebLogic JAM from an IMS client to a Java application running under WebLogic Server. In this sample, the supplied IMS client uses implicit APPC to make a request of a service advertised by the WebLogic JAM Gateway. This service takes all request data and places it on a JMS topic. The Gateway uses a DataView to convert the request data to XML before it is placed on the JMS topic.

Understanding the Sample Configuration

The client IMS program, IMSTOJMS, is defined to the IMS region in the same way any program is defined to an IMS region. No special considerations are required for use as a client making requests through WebLogic JAM.

The message inserted by IMSTOJMS on the IMS message queue is sent to WebLogic JAM. To accomplish this task, an IMS LU 6.2 descriptor must be created that maps the LTERM name that is passed to the program IMSTOJMS to the Logical Unit defined for the CRM and a transaction name. In this sample, the LTERM name is JAMIMS01. This is mapped in the sample IMS LU 6.2 descriptor DFS62DTI to the Logical Unit CRMLU. The transaction name is ITOJMSSV.

The CRMLU must be changed to the Logical Unit that was defined for the CRM. ITOJMSSV is the name of a JMSEvent in the WebLogic JAM configuration. The attributes of the ITOJMSSV JMSEvent in the WebLogic JAM configuration describe the JMS topic where the message will be queued and give the name of the DataView used to translate the message to XML. In this sample, the DataView is named Chardata.

Because the WebLogic JAM Gateway uses the Chardata DataView to translate the mainframe data to XML before placing it on the JMS topic, the Chardata.class file must be in the WebLogic Server CLASSPATH. A directory named dataviews is located under the <BEA_HOME>/<JAM_INSTALL_DIR>/config/examples/clientclasses directory and the Chardata.class is compiled into the <BEA_HOME>/<JAM_INSTALL_DIR>/config/examples/clientclasses/
dataviews/examples/IMS/inbound/gateway directory. The dataview directory is in the CLASSPATH set in the WebLogic Server startup script for the examples domain. The SUPPORTS XML directive is also included in the definition of the chardata.java in the eGen script chardata.egen.

Understanding the Sample Programming

The programming for this sample is described in the following sections.

WebLogic Application

Two classes compose the WebLogic side of this sample application:

• Chardata

• TopicReceive

Chardata is a DataView class that is generated by the eGen Application Code Generator. The data member in the Chardata.class corresponds to the data field in the CHARDATA copybook. The Chardata.class is responsible for all data translation between the mainframe format of the data and the Java format of the data. The WebLogic JAM Gateway uses this class to translate the mainframe data to XML.

The TopicReceive class allows you to view the messages as they are placed on the JMS topic. TopicReceive should be started before running the IMS client. TopicReceive establishes a connection to the JMS topic, receives messages placed on the topic by WebLogic JAM that have been sent by the IMS client, and then reports the messages to you. TopicReceive shuts down when a "quit" message is sent.

IMS Program

IMSTOJMS is a simple COBOL IMS client program that makes an asynchronous, no-response request by placing the request on the IMS message queue. IMSTOJMS receives an LTERM name and a string input from you. It issues a change call to change its output destination to the specified LTERM. Then it inserts the input string to this destination. Because the IMS LU 6.2 descriptor has been created and associated with the LTERM name, the message is sent to the CRM and then on to the WebLogic JAM Gateway. No special considerations are required in this program as a result of being used as a client making requests of a Java server through WebLogic JAM.

Sample Files

The files for the WebLogic side of the sample are installed in the following directory:

<BEA_HOME>/<JAM_INSTALL_DIR>/samples/examples/IMS/inbound/gateway

The following table lists the sample files and their purpose:

Table 2-1 Files for the WebLogic Application

File Name	File Purpose
chardata.cpy	COBOL copybook that defines the structure of the string mainframe data.
chardata.egen	eGen script that generates the Chardata.java DataView class.
Chardata.java	DataView class that corresponds to the chardata.cpy COBOL copybook.
TopicReceive.java	Class that implements MessageListener interface used to monitor the JMS topic for incoming messages.
build.cmd	Script that builds the Chardata and TopicReceive classes. The built class files are under the <BEA_HOME>\<JAM_INSTALL_DIR>\config\examples\ clientclasses\examples\IMS\inbound\gateway directory.
build.sh	Unix script that builds the Chardata and TopicReceive classes. The built class files are under the <BEA_HOME>/<JAM_INSTALL_DIR>/config/examples/ clientclasses/examples/IMS/inbound/gateway directory.

The files for the IMS side of the sample are installed in the following directory:

<BEA_HOME>/<JAM_INSTALL_DIR>/samples/examples/IMS/inbound/
mainframe/source

The following table lists the sample files and their purpose:

Table 2-2 Files for the IMS Application

File Name	File Purpose
COMPIMSC	JCL that compiles and links the IMSTOJMS program.
IMSINDEF	Contains sample IMS stage 1 input and PSBGEN for the IMS configuration of the IMSTOJMS program.
DFS62DTI	IMS LU 6.2 descriptor that maps LTERM name to Logical Unit and remote transaction name.
IMSTOJMS	IMS client program that receives LTERM name and string from the user and queues request data on IMS message queue.

Setting Up the Sample

To set up the IMS application to WebLogic Server JMS topic, complete the following steps.

Step 1: Enable the Service

To enable the JMS Event, click Java Adapter for Mainframe —> Exports—>JMS Events in the left pane. Click ITOJMSSV. Check Local Service Enabled—>and click Apply to enable the Local Service.

 

 

Step 2: Set the Environment

Set the environment by executing the setExamplesEnv command. From a command prompt, change to the <BEA_HOME>/<JAM_INSTALL_DIR>/config/examples directory and execute the command that corresponds to your system:

For Microsoft Windows:

setExamplesEnv.cmd 

For Unix:

. ./setExamplesEnv.sh

The following message will display:

"Your environment has been set."

Step 3: Generate and Build Source (Optional)

The WebLogic JAM samples provide generated source. The samples also provide classes to run the samples. If you want to see how the source is generated and the classes are built, change to the <BEA_HOME>/<JAM_INSTALL_DIR>/samples/examples/IMS/inbound/gateway directory and complete the following steps.

Warning: Using the following options will overwrite files that are installed with the WebLogic JAM samples.

• Run the build.cmd (.sh) script to build the TopicReceive.class and the Chardata.class. The TopicReceive.class is put in the <BEA_HOME>/<JAM_INSTALL_DIR>/config/clientclasses/examples/IMS/inbound/gateway directory. The Chardata.class file is put in the <BEA_HOME>/<JAM_INSTALL_DIR>/config/clientclasses/dataview/examples/IMS/inbound/gateway directory.

• Run egencobol to use the eGen Application Code Generator on chardata.egen to generate Chardata.java.

  This option will generate the source. To compile the source, use the previous option to run the build.cmd (sh) script.

  For information about running the eGen Application Code Generator, see the BEA WebLogic Java Adapter for Mainframe Programming Guide.

Step 4: Run the TopicReceive Program

On the machine where the Gateway is installed, run the TopicReceiver program that listens on the JMS topic for incoming messages from IMS. At the command prompt, type:

java examples.IMS.inbound.gateway.TopicReceive "t3://hostname:port"

In this statement, the following definitions apply:

hostname is the address of the machine where WebLogic Server is running.

port is the port for WebLogic Server.

For example, if TopicReceive is run on the same machine as WebLogic Server examples domain, the statement is:

java  examples.IMS.inbound.gateway.TopicReceive"t3://localhost:7001"

Step 5: Complete Mainframe Tasks

On the machine with the IMS region:

1. Create a Partitioned Data Set (PDS) to store the source and JCL for this sample.

2. From the machine where the Gateway was installed, FTP the following files from the <BEA_HOME>/<JAM_INSTALL_DIR>/samples/examples/IMS/inbound/
   mainframe/source directory to the PDS that you created:

   • IMSTOJMS

   • IMSINDEF

   • DFS62DTI

   • COMPIMSC

3. In the COMPIMSC JCL, make the following changes:

   • Change the JOB statement.

   • Change YOURHLQ.SOURCE to the PDS you created.

   • Change YOUR.PGMLIB to a PGMLIB for your IMS region.

   • Change YOUR.PROCLIB to the location of CBLTDLI (usually IMS.PROCLIB).

   • Change YOUR.RESLIB to the proper value.

   • Change RESLIB to SDFSRESL if you are using a newer IMS version. Refer to CBLTDLI in your PGMLIB to determine which library name your version uses. Make sure that if your IMS version requires this change, that you make the change to both the DD name and the library name.

4. Submit the COMPIMSC JCL. Make sure that all condition codes are 0.

5. Define the program IMSTOJMS to the IMS region. IMSINDEF contains sample IMS stage 1 and PSBGEN input. See your IMS systems programmer for assistance.

6. Define the LTERM. DFS62DTI contains sample definition for an APPC LTERM. See your IMS systems programmer for assistance.

   • Change the Logical Unit name to match the Logical Unit configured for the CRM in Step 4 of the Preparing to Use the IMS Samples section.

   • If you change the LTERM name, make sure to change it at the command prompt when you run the sample. See the Running the Sample section.

   • Do not change the TPNAME. It is configured to match the name of the JMSEVENT in the WebLogic JAM configuration.

Running the Sample

To run the sample, complete the following steps:

1. Log in to the IMS region.

2. Type the following command in the IMS terminal:

   IMSTOJMS JAMIMS01 hello (or any other string)

   The string will be displayed in the XML that is printed in the shell where the TopicReceive is running.

   Note: JAMIMS01 is the LTERM name in the LU6.2 descriptor DFS62DTI. If you changed the LTERM name in the Step 5: Complete Mainframe Tasks section, you must enter that LTERM name at the command prompt instead of JAMIMS01.

To shut down the TopicReceive, type the following command in the IMS terminal:

IMSTOJMS JAMIMS01 quit

Using the Java Client to IMS Sample Application

After completing the steps in the Preparing to Use the IMS Samples section, you are ready to set up and run the Java client to IMS sample application.

Understanding How the Sample Works

This sample demonstrates requests from a Java client through WebLogic JAM to a remote service provided by an IMS application. The back-end application for this sample is the installation verification transaction, IVTNO, that is shipped with IMS. IVTNO is a non-conversational installation verification transaction that uses an OSAM database. This sample illustrates how Java applications may integrate with legacy IMS applications without modification to the IMS programs or configuration.

Understanding the Sample Configuration

No special configuration is required for this simple sample. The Java client calls the service, doIVTNO. The doIVTNO is an APPC service that is mapped to the IMS transaction, IVTNO. IVTNO is defined to IMS in the usual way. No special considerations are required for use with a Java client making requests through WebLogic JAM.

Understanding the Sample Programming

The programming for this sample is described in the following sections.

WebLogic Application

Four classes compose the WebLogic side of this sample application:

• IvtnoInRecord

• IvtnoOutRecord

• BaseClient

• Client

IvtnoInRecord and IvtnoOutRecord are DataView classes that are generated by the eGen Application Code Generator. The data members in these classes correspond to the data fields in the ivtno-in.cpy and ivtno-out.cpy copybooks. These copybooks match the input and output record layouts for the IVTNO transaction. These layouts are found in the IMS program DFSIVA1. IvtnoInRecord and IvtnoOutRecord are responsible for all data translation between the mainframe format of the data and the Java format of the data.

The BaseClient class that is generated by the eGen Application Code Generator is an extension of the EgenClient class. The callIVTNO method of BaseClient is a wrapper for calls to the callService method of the EgenClient class with doIVTNO as the service parameter in the call.

The Client class is the actual user interface. The Client class has a BaseClient member. The Client class receives a command and employee last name as command line parameters. The command must be one of the following: add, display, update, or delete. You may also enter an address and a port number if the WebLogic JAM Gateway is running on a different machine or the corresponding instance of WebLogic Server is listening on a different port than 7001. The URL is set in the BaseClient member. In the Client class, an IvtnoInRecord DataView is initialized with the input data. Depending on the command that you input, either the doDisplayOrDelete, doAdd, or doUpdate method is called. These methods, defined in the Client class, are wrappers for the callIVTNO method of BaseClient. The difference in the methods occur in the value set for the command as well as other fields of the input IvtnoInRecord. The returned IvtnoOutRecord DataView displays.

IMS Program

No IMS programs or configuration files are shipped with this sample because the sample uses the installation verification transaction, IVTNO, that is shipped with IMS.

Sample Files

The files for the WebLogic side of the sample are installed in the following directory:

<BEA_HOME>/<JAM_INSTALL_DIR>/samples/examples/IMS/outbound/
gateway

The following table lists the sample files in this directory and their purpose:

Table 2-3 Files for the WebLogic Application

File Name	File Purpose
ivtno-in.cpy	COBOL copybook that defines the structure of the input data for the IVTNO transaction.
ivtno-out.cpy	COBOL copybook that defines the structure of the output data from the IVTNO transaction.
ivtno.egen	eGen script that generates the IvtnoInRecord.java and IvtnoOutRecord.java DataView classes.
IvtnoInRecord.java	DataView class that corresponds to the ivtno-in.cpy COBOL copybook.
IvtnoOutRecord.java	DataView class that corresponds to the ivtno-out.cpy COBOL copybook.
baseClient.egen	eGen script that generates the IvtnoInRecord.java and IvtnoOutRecord.java DataView classes and the BaseClient.java EgenClient class.
BaseClient.java	Java class that extends EgenClient class that calls the IVTNO service.
Client.java	The user interface client class that receives a command and record name from the user, prompts the user for additional information, if necessary, and displays the result of the IVTNO service to the user. It invokes the IVTNO service by calling the callService method of its BaseClient member.
build.cmd	Script that builds the IvtnoInRecord, IvtnoOutRecord, BaseClient and Client classes. The built class files are under the <BEA_HOME>\<JAM_INSTALL_DIR>\config\examples\ clientclasses\examples\IMS\outbound\gateway directory.
build.sh	Unix script that builds the IvtnoInRecord, IvtnoOutRecord, BaseClient and Client classes. The built class files are under the <BEA_HOME>/<JAM_INSTALL_DIR>/config/examples/ clientclasses/examples/IMS/outbound/gateway directory.

Setting Up the Sample

To set up the Java client to IMS sample application, complete the following steps.

Note: This sample requires that IVTNO is installed and working in the IMS region before this sample is run. IVTNO should have been installed with the IBM IMS distribution. For information about IVTNO, see your IMS documentation.

Step 1: Enable the Service

To enable the APPC service, click Java Adapter for Mainframe —>Services—>APPC Services in the left pane. In the right pane, click doIVTNO under Service Name. Check Enabled and click Apply.

 

 

Step 2: Set the Environment

On the machine from which the sample client is run, set the environment by performing the following step.

Note: This machine does not have to be the machine on which the Gateway is running, but WebLogic JAM must be installed.

• From a command prompt, change to the <BEA_HOME>/<JAM_INSTALL_DIR>/config/examples and execute the following command to set the environment:

  For Microsoft Windows:

  setExamplesEnv.cmd 

  For Unix:

  . ./setExamplesEnv.sh

  The following message will display:

  "Your environment has been set."

Step 3: Generate and Build Source (Optional)

The WebLogic JAM samples provide generated source. The samples also provide classes to run the samples. If you want to see how the source is generated and the classes are built, change to the <BEA_HOME>/<JAM_INSTALL_DIR>/samples/examples/IMS/outbound/
gateway directory and complete the following steps.

Warning: Using the following options will overwrite files that are installed with the WebLogic JAM samples.

• Run the build.cmd (.sh) script to build the client classes and put them in the <BEA_HOME>/<JAM_INSTALL_DIR>/config/examples/clientclasses/
  examples/IMS/outbound/gateway directory.

• Run egencobol to use the eGen Application Code Generator on:

  • ivtno.egen to generate IvtnoInRecord.java and IvtnoOutRecord.java.

  • baseClient.egen to generate BaseClient.java, IvtnoInRecord.java, and IvtnoOutRecord.java.

  This option will generate the source. To compile the source, use the previous option to run the build.cmd (sh) script.

  For information about running the eGen Application Code Generator, see the BEA WebLogic Java Adapter for Mainframe Programming Guide.

Running the Sample

To run the sample, type the following command at the command prompt:

java examples.IMS.outbound.gateway.Client [-m hostname] [-p port] -c command -n name

In this command, the following definitions apply:

• The first pair of command line switches are optional, and represent the hostname and port for a remote machine on which the WebLogic JAM Gateway is running in WebLogic Server. If you are running the client on the same machine as the Gateway and the WebLogic Server port is 7001, then these options are not required.

• The second pair of command line switches are mandatory. The command must be one of the following:

  • display

  • add

  • delete

  • update

• name is the last name of the person that is the key to the record.

The following command is an example of a command that you might enter:

java examples.IMS.outbound.gateway.Client -c display -n LAST1

Using the Transactional Sample from WebLogic Server to IMS

After completing the steps in the Preparing to Use the IMS Samples section, you are ready to set up and run the transactional sample from WebLogic Server to IMS.

Understanding How the Sample Works

This sample demonstrates transactional requests made to an IMS application from a Java client through WebLogic JAM. This sample highlights client-initiated transactions that are distributed between an IMS-managed resource and a WebLogic Server-managed resource, a JMS queue. The back-end application for this sample is the IMS transaction, IVTNO. IVTNO is an IMS non-conversational installation verification transaction that uses an OSAM database. This sample illustrates how Java applications may be integrated with legacy IMS applications without modification to the IMS programs or configuration.

Understanding the Sample Configuration

No special configuration is required for this simple sample. The Java client calls the service doIVTNO. doIVTNO is an APPC service that is mapped to the IMS transaction, IVTNO. IVTNO is defined to IMS in the usual way and requires no special considerations to be used with a Java client making requests through WebLogic JAM.

Understanding the Sample Programming

The programming for this sample is described in the following sections.

WebLogic Application

Four classes compose the WebLogic side of this sample application:

• IvtnoInRecord

• IvtnoOutRecord

• BaseClient

• Client

IvtnoInRecord and IvtnoOutRecord are DataView classes that are generated by the eGen Application Code Generator. The data members in these classes correspond to the data fields in the ivtno-in.cpy and ivtno-out.cpy copybooks. These copybooks match the input and output record layouts for the IVTNO transaction. These layouts are in the IMS program, DFSIVA1. IvtnoInRecord and IvtnoOutRecord are responsible for all data translation between the mainframe format of the data and the Java format of the data.

The BaseClient class that is generated by the eGen Application Code Generator is an extension of the EgenClient class. The callIVTNO method of BaseClient is a wrapper for calls to the callService method of the EgenClient class with doIVTNO as the service parameter in the call.

The Client class is the actual user interface. The Client class has a BaseClient member. It has three optional command line parameters. You may enter an address and a port number if the WebLogic JAM Gateway is running on a different machine or the corresponding instance of WebLogic Server is listening on a different port than 7001. The URL is set in the BaseClient member. You may also enter a command line option that indicates that the distributed transaction in this sample should roll back. If this command line option is not used, the distributed transaction is committed.

doDisplayOrDelete, doAdd, and doUpdate methods are defined in the Client class. These methods are wrappers for the callIVTNO method of BaseClient. The difference in the methods occurs in the value set for the command as well as other fields of the input IvtnoInRecord.

The Client class first performs a check to make sure that the sample starts in a consistent state. The record that will be added to the OSAM database later is deleted by making a call to the doDisplayOrDelete method. The Client clears the JMS queue and then initiates the distributed transaction. The Client adds the record to the OSAM database using IVTNO by calling the doAdd method. The Client queues the record key on the JMS queue. Depending on your input, the Client then commits or rolls back the transaction. The Client class verifies the result by attempting to display the record from the OSAM database and the key from the JMS queue. Calling the doDisplayOrDelete method does the reading of the record from the OSAM record through IVTNO.

IMS Program

No IMS programs or configuration files are shipped with this sample because the sample uses the installation verification transaction, IVTNO, that is shipped with IMS.

Sample Files

The files for the WebLogic side of the sample are installed in the following directory:

<BEA_HOME>/<JAM_INSTALL_DIR>/samples/examples/transactional/IMS/
outbound/gateway

The following table lists the sample files in this directory and their purpose:

Table 2-4 Files for the WebLogic Application

File Name	File Purpose
ivtno-in.cpy	COBOL copybook that defines the structure of the input data for the IVTNO transaction.
ivtno-out.cpy	COBOL copybook that defines the structure of the output data from the IVTNO transaction.
ivtno.egen	eGen script that generates the IvtnoInRecord.java and IvtnoOutRecord.java DataView classes.
IvtnoInRecord.java	DataView class that corresponds to the ivtno-in.cpy COBOL copybook.
IvtnoOutRecord.java	DataView class that corresponds to the ivtno-out.cpy COBOL copybook.
baseClient.egen	eGen script that generates the IvtnoInRecord.java and IvtnoOutRecord.java DataView classes and the BaseClient.java EgenClient class.
BaseClient.java	Java class that extends EgenClient class that calls the IVTNO service.
Client.java	The user interface client class that receives a command line option to roll back or commit from the user. All invocations of the IVTNO transaction that it makes are made by calling the callService method of its BaseClient member. First, it deletes a record and clears the JMS queue. Then, it initiates a transaction. Within the boundaries of that transaction, it adds the record and queues the key to the record on the JMS queue. It then commits or rolls back the previous operations based on the command line option. It then verifies the operation by attempting to read the record and check the contents of the JMS queue.
build.cmd	Script that builds the IvtnoInRecord, IvtnoOutRecord, BaseClient and Client classes. The built class files are under the <BEA_HOME>\<JAM_INSTALL_DIR>\config\examples\ clientclasses\examples\transactional\IMS\outbound\gateway directory.
build.sh	Unix script that builds the IvtnoInRecord, IvtnoOutRecord, BaseClient and Client classes. The built class files are under the <BEA_HOME>/<JAM_INSTALL_DIR>/config/examples/ clientclasses/examples/transactional/IMS/outbound/gateway directory.

Setting Up Sample

To set up the transactional sample from WebLogic Server to IMS, complete the following steps.

Note: The IMS installation verification sample (shipped with IMS), IVTNO, must be installed and working in the IMS region before running the sample.

Step 1: Enable the Service

To enable the APPC service, click Java Adapter for Mainframe —> Services—>APPC Services in the left pane. In the right pane, click doIVTNO. Check Enabled—>and click Apply.

 

Step 2: Set the Environment

On the machine from which the sample client is to be run, set the environment by performing the following step.

Note: This machine does not have to be the machine on which the Gateway is running, but WebLogic JAM must be installed.

• From a command prompt, change to the <BEA_HOME>/<JAM_INSTALL_DIR>/config/examples directory and execute the following command to set the environment:

  For Microsoft Windows:

  setExamplesEnv.cmd 

  For Unix:

  . ./setExamplesEnv.sh

  The following message will display:

  "Your environment has been set."

Step 3: Generate and Build Source (Optional)

The WebLogic JAM samples provide generated source. The samples also provide classes to run the samples. If you want to see how the source is generated and the classes are built, change to the <BEA_HOME>/<JAM_INSTALL_DIR>/samples/examples/transactional/IMS/
outbound/gateway directory and complete the following steps.

Warning: Using the following options will overwrite files that are installed with the WebLogic JAM samples.

• Run the build.cmd (.sh) script to build the client classes and put them in the <BEA_HOME>/<JAM_INSTALL_DIR>/config/examples/clientclasses/
  examples/transactional/IMS/outbound/gateway directory.

• Run egencobol to use the eGen Application Code Generator on:

  • ivtno.egen to generate IvtnoInRecord.java and IvtnoOutRecord.java

  • baseClient.egen to generate BaseClient.java, IvtnoInRecord.java, and IvtnoOutRecord.java

  This option will generate the source. To compile the source, use the previous option to run the build.cmd (sh) script.

  For information about running the eGen Application Code Generator, see the BEA WebLogic Java Adapter for Mainframe Programming Guide.

Running the Sample

To run the sample, type the following command at the command prompt:

java examples.transactional.IMS.outbound.gateway.Client
[-m hostname] [-p port] [-r]

In this command, the following definitions apply:

• The first pair of command line switches are optional, and represent the hostname and port for a remote machine on which the WebLogic JAM Gateway is running in WebLogic Server. If you are running the client on the same machine as the Gateway and the WebLogic Server port is 7001, then these options are not required.

• The third command line switch, which is also optional, indicates whether a rollback will be done or not. If -r is present at the command prompt, then the creation of the record on the database will be rolled back.

The following command is an example of a command that you might enter:

 java examples.transactional.IMS.outbound.gateway.Client -r