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

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:

Specific tasks for each sample include:

Using the Samples

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:

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:

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.

$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.

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.

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:

Step 3: Start the examples Domain

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

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.

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

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 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

<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

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.

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:

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.

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:

Running the Sample

To run the sample, complete the following steps:

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

IMSTOJMS JAMIMS01 quit

Using 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 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

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.

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.

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.

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 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

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 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

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.

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.

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.

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 following command is an example of a command that you might enter:

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