Using the CICS Samples

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

About the CICS Samples

CICS Application to WebLogic Server Sample EJB

This sample demonstrates the functional capability provided by WebLogic JAM to invoke the services of an Enterprise Java Bean (EJB) deployed with WebLogic Server from a CICS client. The server EJB is similar to the Trader bean that is shipped with WebLogic Server. The COBOL CICS client program makes a series of requests to the EJB to buy shares of stock.

As in the WebLogic Server sample, the EJB will check the number of shares requested against a preconfigured trading limit to decide if the requested number of shares can be purchase. If the number of shares is too high, then it will actually buy the limit instead. A record of each sale is entered into the WebLogic Server log. The bean will return to the client the actual number of shares purchased as well as the stock symbol. The CICS client will report the result to the screen.

Java Client to CICS Sample Application

This sample illustrates the invoking of CICS services from requests that originate from a Java client. Four COBOL CICS programs are provided. These programs create, read, update, and delete records from a simulated database. These programs simulate a database through the use of Temporary Storage (TS) queues. Employee records are stored in the database by creating a TS queue with a name that is the first eight characters of the employee's name. The use of TS queues to simulate a database requires no configuration in the CICS region other than the definition of the programs.

The Java client receives a command and a record name from you. The command is one of the following: add, display, update, or delete. You may choose to enter a host address and port if the gateway is running on another machine. Depending on the command, the client may prompt you for additional information. The client then makes a service call to one of the provided CICS COBOL programs. The result displays.

Transactional Sample from WebLogic Server to CICS

This sample illustrates making calls to remote services located in a CICS region from a Java client. The service calls that alter 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 managed by CICS. This transaction uses a service call to add a record to a VSAM file. The key to the record is inserted on a JMS queue within the boundaries of the same transaction as a service call to create the record. The queuing of the record key and the creation of the record in VSAM will either be committed or rolled back together depending on the command line option you set.

Four COBOL CICS programs are provided. These programs create, read, update, and delete records from the VSAM file. Employee records are stored in the VSAM file using the employee's social security number as a key. The VSAM file is used as the recoverable resource in CICS because it is relatively easy to create and configure and CICS users will have VSAM.

Roadmap for the Samples

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

Specific tasks for each sample include:

Using the Samples

Preparing to Use the CICS Samples

The following steps are common to all the CICS samples. These steps only need to be performed once for all CICS 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 3-1 with the script in Listing 3-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 3-1 Fields for 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

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 3-1 with the JCL in Listing 3-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 3-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 located, 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 same directory to start the examples domain:

Step 4: Configure the WebLogic JAM Gateway

.

Note: This Logical Unit is the ACBNAME in the VTAM Logical Unit definition or the VTAM APPLID of the region. This Logical Unit is not the same as the Logical Unit for the CRM in (3a).

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

Using the CICS Application to WebLogic Server Sample EJB

Understanding How the Sample Works

This sample demonstrates the functional capability of WebLogic JAM to invoke the services of an EJB deployed in WebLogic Server from a CICS client. The server EJB is similar to the stateless session Trader bean that is shipped with WebLogic Server as an example. The COBOL CICS client program makes a series of requests to the EJB to buy shares of stock.

Understanding the Sample Configuration

The CICS COBOL client program TRADCLNT is defined to CICS in the standard way any program is defined to CICS. No changes are necessary to use this program as a client making requests through WebLogic JAM. TRADCLNT does a Distributed Program Link (DPL) to the remote service TRADSERV. TRADSERV is defined to the CICS region in the standard manner for defining remote services to a CICS region; however, the REMOTESYSTEM parameter in the definition must be set to the name of the connection defined to the CICS region for the CRM. The REMOTENAME in the definition of TRADSERV is also set to TRADSERV.

In the WebLogic JAM configuration, TRADSERV is the name of an EJBExport that is mapped to the JNDI name jam.TradeServer. jam.TradeServer is the value of the JNDI-name element in the WebLogic deployment descriptor weblogic-ejb-jar.xml for the TradeServer EJB.

The eGen Application Code Generator generates deployment descriptors when it generates the code for EJBs. However, to avoid name collisions that can occur when multiple EJBs are generated from a single eGen script, generated deployment descriptors are always given names that contain the stem name of the EJB that is being generated. In this sample, the generated deployment descriptors are named TradeServer-jar.xml and wl-TradeServer-jar.xml. Before these deployment descriptors can be used for an actual deployment in WebLogic Server, they have to be renamed ejb-jar.xml and weblogic-ejb-jar.xml. Because the generated EJB TradeServerBean is extended in this sample, the value of the ejb-class element in ejb-jar.xml must also be manually changed to the name of the extension class that contains the business logic, ExtTradeServerBean.

Understanding the Sample Programming

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

WebLogic Application

Five classes compose the WebLogic side of this sample application:

TradeRecord is a DataView class, generated by the eGen Application Code Generator. The data members in the TradeRecord class correspond to the data fields in the TRADRCRD copybook. The TradeRecord class is responsible for all data translation between the mainframe format of the data and the Java format of the data.

TradeServer, TradeServerBean, and TradeServerHome classes are generated by the eGen Application Code Generator. TradeServer is a remote interface that contains the definition of a single method: dispatch. dispatch is the essential method for server EJBs that are used in WebLogic JAM applications. This method is messaged by the Gateway when a mainframe client makes a request of the corresponding service. TradeServerHome is a standard home interface for a stateless session bean. It contains the definition of a create method that returns a TradeServer object to the caller. TradeServerBean extends EgenServerBean. TradeServerBean contains the implementation of the dispatch method that is a wrapper for the buy method. The implementation of the buy method that is given in TradeServerBean does not perform actual business logic. As it is defined in the eGen script that generates TradeServerBean, the buy method only receives a TradeRecord object and returns a TradeRecord object. To actually do any business logic, the TradeServerBean must be extended and the buy method overwritten.

The extension of the TradeServerBean class that is included with this sample is called ExtTradeServerBean. ExtTradeServerBean contains an implementation of the buy method containing the business logic. The number of shares that are requested is compared to a predefined limit. If the number of shares is greater than this limit, then the number of shares is reset to the limit. The purchase of the shares is recorded in the WebLogic Server log.

CICS Program

The program TRADCLNT is a simple COBOL CICS client program that creates several TRADRCRD records and does a DPL to the remote service TRADSERV for each record. Each one of the records represents a request to purchase some stock. No special considerations are required in this program as a result of linking through WebLogic JAM to a service offered by an EJB deployed in WebLogic Server.

Sample Files

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

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

The following table lists the sample files and their purpose:

Table 3-1 Files for the WebLogic Application

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

The following table lists the sample files and their purpose:

Table 3-2 Files for CICS Application

To set up the CICS application to WebLogic Server sample EJB, complete the following steps.

Step 1: Enable the Service

To enable the Exported EJB, click Java Adapter for Mainframe —> Exports—>ExportedEJBs in the left pane. In the right pane, click TRADSERV. Check Local Service Enabled—>Click Apply to enable the Local Service.

Step 2: Set the Environment

On the machine where the Gateway is installed, set the environment by completing the following step:

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/CICS/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: Complete Mainframe Tasks

On the machine with the CICS region:

Running the Sample

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

TRCL

TRCL is the transaction that is defined to the CICS region to execute the TRADCLNT program. You will see the buys being processed in the WebLogic Server log. The CICS terminal will report success or failure.

Using the Java Client to CICS Sample Application

Understanding How the Sample Works

This sample demonstrates requests from a Java client through WebLogic JAM to a remote service provided by a CICS application.

Understanding the Sample Configuration

This simple sample requires no special configuration. The Java client calls one of the services: sampleCreate, sampleRead, sampleUpdate, or sampleDelete. These DPL services are mapped to the CICS programs: DPLDEMOC, DPLDEMOR, DPLDEMOU, and DPLDEMOD. These programs are defined to CICS in the standard way any program is defined to CICS. No special considerations are necessary for using this program 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

Three classes compose the WebLogic side of this sample application:

EmployeeRecord is a DataView class that is generated by the eGen Application Code Generator. The data members in the EmployeeRecord class correspond to the data fields in the EMPREC copybook. The EmployeeRecord class is 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 newEmployee, readEmployee, upDateEmployee, and deleteEmployee methods of BaseClient are wrappers for calls to the callService method of the EgenClient class with sampleCreate, sampleRead, sampleUpdate, or sampleDelete, as service parameters 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 EmployeeRecord DataView is initialized with the input data. Depending on the command that you input, the doAdd, doDisplay, doUpdate, or doDelete method is called. These methods that are defined in the Client class are wrappers for the newEmployee, readEmployee, upDateEmployee, and deleteEmployee methods of BaseClient. The EmployeeRecord DataView that is returned as a result of the operation is displayed to you.

CICS Programs

Four CICS COBOL programs are included with this sample:

These programs imitate the four basic operations for database records: insert, read, update, and delete. Temporary Storage (TS) queues are used in this sample to simulate a database. For example, to imitate the operation of inserting a record in a table in a database, a TS queue is created with a key that is the first eight characters of the last name field in the data. To read the record, the TS queue is read. These programs are simple but ordinary CICS COBOL server programs that are linked to and passed a COMMAREA. The necessary TS queue operation is done using the data record in the COMMAREA. The structure of the data in the COMMAREA is given in the copybook EMPREC. No special considerations are required in this program as a result of being used in an application with a Java client making requests through WebLogic JAM.

Sample Files

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

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

The following table lists the sample files and their purpose:

Table 3-3 Files for WebLogic JAM Application

<BEA_HOME>/<JAM_INSTALL_DIR>/samples/examples/CICS/outbound/mainframe/source

The following table lists the sample files and their purpose:

Table 3-4 Files for CICS Application

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

Step 1: Enable the Services

To enable the DPL Services, click Java Adapter for Mainframe —> Services—>DPLService in the left pane. Click sampleCreate. Check Enabled—>and click Apply to enable the Local Service.

Repeat this process for each of the following DPL services:

Step 2: Set the Environment

On the machine where the Gateway is installed, set the environment by completing the following step:

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/CICS/outbound/
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: Complete Mainframe Tasks

On the machine with the CICS region:

Running the Sample

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

java examples.CICS.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.CICS.outbound.gateway.Client -c add -n Wilson

Note: Your CICS administrator may want to delete any TS queues that remain after running this sample.

Using the Transactional Sample from WebLogic Server to CICS

Understanding How the Sample Works

This sample demonstrates transactional requests made to a CICS application from a Java client through WebLogic JAM. This sample highlights client-initiated transactions that are distributed between a CICS-managed resource, a VSAM file, and a WebLogic Server-managed resource, a JMS queue.

Understanding the Sample Configuration

This simple sample requires no special configuration. The Java client calls one of the services: sampleCreateT, sampleReadT, sampleUpdateT, or sampleDeleteT. These DPL services are mapped to the CICS programs: DPLDEMVC, DPLDEMVR, DPLDEMVU, and DPLDEMVD. These programs are defined to CICS in the standard way any program is defined to CICS. The VSAM file used in this sample is created and defined in the standard manner. No special considerations need to be made 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

Three classes make up the WebLogic side of this sample application:

EmployeeRecord is a DataView class that is generated by the eGen Application Code Generator. The data members in the EmployeeRecord class correspond to the data fields in the EMPREC copybook. The EmployeeRecord class is 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 newEmployee, readEmployee, upDateEmployee, and deleteEmployee methods of BaseClient are wrappers for calls to the callService method of the EgenClient class with sampleCreateT, sampleReadT, sampleUpdateT, or sampleDeleteT, as service parameters in the call.

The Client class is the actual user interface. The Client class has a BaseClient member. It uses 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 be rolled back. If this command line option is not used, the distributed transaction will be committed.

The Client class first performs a check to make sure that the sample starts in a consistent state. The record that will later be added to the VSAM file is deleted by making a call to the deleteEmployee method of the BaseClient member. The Client then clears the JMS queue and then initiates the distributed transaction. The Client adds the record to the VSAM file by calling the newEmployee method of the BaseClient member. The Client queues the record key on the JMS queue. Depending on your input, the Client commits or rolls back the transaction. The Client class verifies the result by attempting to display the record from VSAM file and the key from the JMS queue. Calling the readEmployee method of the BaseClient member results in the reading of the record from the VSAM file.

CICS Programs

Four CICS COBOL programs are included with this sample:

These programs imitate the four basic operations that can be done with records in a database: insert, read, update, and delete. A VSAM file is used in this sample in place of a database. A VSAM file is used as the recoverable resource in CICS because it is relatively easy to create and configure. For example, to imitate the operation of inserting a record in a table in a database a record is created in the VSAM file with a key that is the social security number field in the data. These programs are simple but ordinary CICS COBOL server programs that are linked to and passed a COMMAREA. The necessary VSAM file operation is done using the data record in the COMMAREA. The structure of the data in the COMMAREA is given in the copybook EMPREC. No special considerations are required in this program as a result of being used in an application with a Java client making requests through WebLogic JAM.

Sample Files

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

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

The following table lists the sample files and their purpose:

Table 3-5 Files for WebLogic JAM Application

<BEA_HOME>/<JAM_INSTALL_DIR>/samples/examples/transactional/CICS/outbound/mainframe/source

The following table lists the samples files and their purpose:

Table 3-6 Files for CICS Application

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

Step 1: Enable the Services

To enable the DPL services, click Java Adapter for Mainframe —> Services—>DPLService in the left pane. Click sampleCreateT. Check Enabled—>and click—>Apply to enable the Local Service.

Repeat this step for each of the services:

Step 2: Set the Environment

On the machine where the Gateway is installed, set the environment by completing the following step:

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/CICS/outbound/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: Complete Mainframe Tasks

On the machine with the CICS region:

Running the Sample

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

java examples.transactional.CICS.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.CICS.outbound.gateway.Client -r