bea.com | products | dev2dev | support | askBEA

Download Docs
Search

Samples Guide

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

- Roadmap for the Samples

- Using the Samples

About the CICS Samples

The following section provides a brief overview of each of the CICS 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.

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:

1. Verify prerequisite tasks.

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

2. Prepare to use the CICS 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 CICS samples is presented in the following sections:

- Preparing to Use the CICS Samples

- Using the CICS Application to WebLogic Server Sample EJB

- Understanding How the Sample Works

- Setting up the Sample

- Running the Sample

- Using the Java Client to CICS Sample Application

- Understanding How the Sample Works

- Setting up the Sample

- Running the Sample

- Using the Transactional Sample from WebLogic Server to CICS

- Understanding How the Sample Works

- Setting up the Sample

- Running the Sample

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:

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

Listing 3-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 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.

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

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

   >     <BEA_HOME>\<JAM_INSTALL_DIR>\config\examples

2. Copy jamconfig_CICS.xml to jamconfig.xml.

Step 3: Start the examples Domain

From the command prompt, execute the following command from the same 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 were 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. Make the following configuration changes for the CICS Sample 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 CICS Region, click Java Adapter for Mainframe —> Regions —> CICS Regions in the left pane. In the right pane, click on CICS3 and enter the name of the Logical Unit. Click Apply to set the Logical Unit.

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

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

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

1. To start the WebLogic JAM 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 is recorded 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 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

After completing the steps in the Preparing to Use the CICS Samples section, you are ready to set up and run 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

- TradeServer

- TradeServerBean

- TradeServerHome

- ExtTradeServerBean

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

File Name | File Purpose
--- | ---
TradeRecord.cpy | COBOL copybook that defines the structure of the mainframe data.
tradeserver.egen | eGen script that generates the TradeRecord.java DataView class, the TradeServer.java, TradeServerBean.java, TradeServerHome.java bean classes, and the TradeServer-jar.xml and wl-TradeServer-jar.xml deployment descriptors.
TradeRecord.java | DataView class that corresponds to the TradeRecord.cpy COBOL copybook.
TradeServer.java | EJB remote interface generated by the eGen utility.
TradeServerBean.java | EJB generated by the eGen utility.
TradeServerHome.java | EJB home interface generated by the eGen utility.
ExtTradeServerBean.java | EJB that extends TradeServerBean. The business logic of servicing the requests from the mainframe is implemented in this class.
build.cmd | Script that builds the TradeRecord, TradeServer, TradeServerBean, TradeServerHome, and ExtTradeServerBean classes. It assembles the classes along with the necessary deployment descriptors into a .jar file. The resulting JAM_TradeServer.jar file is under the <BEA_HOME>\<JAM_INSTALL_DIR>\config\examples\ applications\examples\CICS\inbound\gateway directory.
build.sh | Unix script that builds the TradeRecord, TradeServer, TradeServerBean, TradeServerHome, and ExtTradeServerBean classes. It assembles the classes along with the necessary deployment descriptors into a .jar file. The resulting JAM_TradeServer.jar file is under the <BEA_HOME>/<JAM_INSTALL_DIR>/config/examples/ applications/examples/CICS/inbound/gateway directory.
TradeServer-jar.xml | Deployment descriptor generated by tradeserver.egen.
wl-TradeServer-jar.xml | WebLogic deployment descriptor generated by tradeserver.egen.
ejb-jar.xml | TradeServer-jar.xml deployment descriptor that has been modified and renamed for inclusion in the JAM_TradeServer.jar.
weblogic-ejb-jar.xml | wl-TradeServer-jar.xml WebLogic deployment descriptor renamed for inclusion in the JAM_TradeServer.jar.

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

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

File Name | File Purpose
--- | ---
TRADRCRD | COBOL copybook that defines the structure of the mainframe data.
CMPPROC | Procedure used to compile and link the CICS programs.
COMPTRCL | JCL that executes the CMPROC for the program TRADCLNT.
CSDUPDTR | RDO cards to define TRADCLNT and the service TRADSERV to the CICS region.
CSDUTRCL | JCL that executes CSDUPDTR.
TRADCLNT | CICS client program that makes requests to purchase several stocks to the TRADSERV service. This service is mapped to the buy method of the ExtTradeServerBean by WebLogic JAM.

Setting Up the Sample

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:

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

- Run the build.cmd (.sh) script to build the bean classes and put them in the JAM_TradeServer.jar at <BEA_HOME>/<JAM_INSTALL_DIR>/config/examples/applications.

- Run egencobol to use the eGen Application Code Generator on tradeserver.egen to generate the code for the TradeServer bean and it deployment descriptors.

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

On the machine with the CICS 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/CICS/inbound/
   mainframe/source directory into the PDS that you created:

   - CMPPROC

   - COMPTRCL

   - CSDUPDTR

   - CSDUTRCL

   - TRADCLNT

   - TRADRCRD

3. In the procedure CMPPROC, do not set LNKLIB, PDSSRC, and PROG. These settings are supplied by the COMPTRCL JCL that will exec COMPROC. Do set INDEX, COMPHLQ, COMPHL2. You may need to change OUTC and the unit of WORK.

4. In the COMPTRCL JCL, make the following changes:

   - Change the JOB statement.

   - Change the JCLLIB ORDER and the PDSSRC to the PDS you created.

   - Change the LNKLIB to a LOADLIB for your CICS region.

5. Submit the COMPTRCL JCL. Make sure that the condition code is 0.

6. In the RDO script CSDUTRCL, make the following changes:

   - Change the name of the LIST to a valid list name for your CICS region.

   - Change the value of REMOTESYSTEM to the connection defined for the CRM.

   - If you change the GROUP name, make sure you change it everywhere.

7. In the CSDUPDTR JCL, make the necessary changes to these statements:

   - JOB

   - STEPLIB

   - DFHCSD

   - SYSIN DSN

8. Submit the CSDUPDTR JCL.

   You may get a warning on the DELETE step, because the program TRADCLNT probably was not defined before. The condition code should not be more than 4.

9. Log on to your CICS region.

10. Install the WebLogic JAM sample.

    To install the WebLogic JAM sample, type the following command at the command prompt:

    >      CEDA INSTALL GROUP(JAMEXMPL)

11. Verify the CICS sample program.

    To verify the CICS sample program, type the following command at the command prompt:

    >     CEMT INQUIRE PROG(TRADCLNT)

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

After completing the steps in the Preparing to Use the CICS Samples section, you are ready to set up and run 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

- BaseClient

- Client

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:

- DPLDEMOC

- DPLDEMOR

- DPLDEMOU

- DPLDEMOD

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

File Name | File Purpose
--- | ---
emprec.cpy | COBOL copybook that defines the structure of the mainframe employee record.
emprec.egen | eGen script that generates the EmployeeRecord.java DataView class.
EmployeeRecord.java | DataView class that corresponds to the emprec.cpy COBOL copybook.
baseClient.egen | eGen script that generates the EmployeeRecord.java DataView class and the BaseClient.java EgenClient class.
BaseClient.java | Java class that extends EgenClient class that calls the various mainframe services.
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 mainframe service calls to the user. It invokes the mainframe services by calling the callService method of its BaseClient member.
build.cmd | Script that builds the EmployeeRecord, BaseClient, and Client classes. The built class files are under the <BEA_HOME>\<JAM_INSTALL_DIR>\config\examples\ clientclasses\examples\CICS\outbound\gateway directory.
build.sh | Unix script that builds the EmployeeRecord, BaseClient, and Client classes. The built class files are under the <BEA_HOME>/<JAM_INSTALL_DIR>/config/examples/ clientclasses/examples/CICS/outbound/gateway directory.

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

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

File Name | File Purpose
--- | ---
EMPREC | COBOL copybook that defines the structure of the employee record data.
DPLDEMOC | CICS server program that imitates the insertion of a record on a database by creating a TS queue.
DPLDEMOR | CICS server program that imitates the reading of a record on a database by reading a TS queue.
DPLDEMOU | CICS server program that imitates the update of a record on a database by updating a TS queue.
DPLDEMOD | CICS server program that imitates the deletion of a record on a database by deleting a TS queue.
CMPPROC | Procedure used to compile and link the CICS programs.
COMPCRUD | JCL that executes the CMPROC for the programs DPLDEMOC, DPLDEMOR, DPLDEMOU, and DPLDEMOD.
CSDUCRUD | RDO cards to define DPLDEMOC, DPLDEMOR, DPLDEMOU, and DPLDEMOD to the CICS region.
CSDUPDCO | JCL that executes CSDUCRUD.

Setting Up the Sample

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:

- sampleRead

- sampleUpdate

- sampleDelete

Step 2: Set the Environment

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

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

"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/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.

- 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/CICS/outbound/gateway directory.

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

- emprec.egen to generate EmployeeRecord.java

- baseClient.egen to generate BaseClient.java and EmployeeRecord.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: Complete Mainframe Tasks

On the machine with the CICS 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/CICS/outbound/
   mainframe/source directory into the PDS that you created:

   - EMPREC

   - DPLDEMOC

   - DPLDEMOR

   - DPLDEMOU

   - DPLDEMOD

   - CMPPROC

   - COMPCRUD

   - CSDUCRUD

   - CSDUPDCO

3. In the procedure CMPPROC, do not set LNKLIB, PDSSRC, and PROG. The values are supplied by the COMPCRUD JCL that will execute COMPROC. Do set INDEX, COMPHLQ, and COMPHL2. You may need to change OUTC and the unit of WORK.

4. In the COMPCRUD JCL, make the following changes:

   - Change the JOB statement.

   - Change the JCLLIB ORDER and the source to the PDS you created.

   - Change the LOADLIB to a load lib for your CICS region.

5. Submit the COMPCRUD JCL. Make sure that the condition code is 0.

6. In the RDO script, CSDUCRUD, make the following changes:

   - Change the name of the LIST to a valid list name for your CICS region.

   - You can also change the GROUP name, but make sure you change it everywhere.

7. In the CSDUPDCO JCL, make the following changes:

   - Change the JOB statement.

   - Change the STEPLIB.

   - Change the DFHCSD.

   - Change the SYSIN DSN.

8. Submit the CSDUPDCO JCL.

   You may get a warning on the DELETE step, because the programs probably were not defined before. The condition code should not be higher than 4.

9. Log on to your CICS region.

10. Install the WebLogic JAM sample.

    To install the WebLogic JAM sample, type the following command at the command prompt:

    >     CEDA INSTALL GROUP(JAMEXMPL)

11. Verify the CICS sample programs.

    To verify the CICS sample programs, type the following command at the command prompt:

    >     CEMT INQUIRE PROG(DPLDEMOC)

    Repeat for DPLDEMOR, DPLDEMOU, and DPLDEMOD.

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 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, these options are not required.

- The second pair of command line switches are mandatory.

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

After completing the steps in the Preparing to Use the CICS Samples section, you are ready to set up and run 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

- BaseClient

- Client

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:

- DPLDEMVC

- DPLDEMVR

- DPLDEMVU

- DPLDEMVD

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

File Name | File Purpose
--- | ---
emprec.cpy | COBOL copybook that defines the structure of the mainframe employee record.
emprec.egen | eGen script that generates the EmployeeRecord.java DataView class.
EmployeeRecord.java | DataView class that corresponds to the emprec.cpy COBOL copybook.
baseClient.egen | eGen script that generates the EmployeeRecord.java DataView class and the BaseClient.java EgenClient class.
BaseClient.java | Java class that extends EgenClient class that calls the various mainframe services.
Client.java | The user interface client class. It receives a command line option to roll back or commit from the user. All invocations of the mainframe services 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 checking the contents of the JMS queue.
build.cmd | Script that builds the EmployeeRecord, BaseClient, and Client classes. The built class files are under the <BEA_HOME>\<JAM_INSTALL_DIR>\config\examples\ clientclasses\examples\transactional\CICS\outbound\gateway directory.
build.sh | Unix script that builds the EmployeeRecord, BaseClient, and Client classes. The built class files are under the <BEA_HOME>/<JAM_INSTALL_DIR>/config/examples/ clientclasses/examples/transactional/CICS/outbound/gateway directory.

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

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

File Name | File Purpose
--- | ---
EMPREC | COBOL copybook that defines the structure of the employee record data.
DPLDEMVC | CICS server program that inserts a record in a VSAM file.
DPLDEMVR | CICS server program that reads a record in a VSAM file.
DPLDEMVU | CICS server program that updates a record in a VSAM file.
DPLDEMVD | CICS server program that deletes a record in a VSAM file.
CMPPROC | Procedure used to compile and link the CICS programs.
COMPILEV | JCL that executes the CMPROC for the programs DPLDEMVC, DPLDEMVR, DPLDEMVU, and DPLDEMVD.
JVSAMRDO | RDO cards to define DPLDEMVC, DPLDEMVR, DPLDEMVU, and DPLDEMVD programs and the BEAJAMTV VSAM file to the CICS region.
CSDUPDCT | JCL that executes JVSAMRDO.
JAMVSAMC | Delete/Define cards for the VSAM file.
BLDVSAM | JCL that invokes IDCAMS for JAMVSAMC.

Setting Up the Sample

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:

- sampleReadT

- sampleUpdateT

- sampleDeleteT

Step 2: Set the Environment

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

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

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

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

- emprec.egen to generate EmployeeRecord.java

- baseClient.egen to generate BaseClient.java and EmployeeRecord.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: Complete Mainframe Tasks

On the machine with the CICS 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/transactional/
   CICS/outbound/mainframe/source directory into the PDS that you created:

   - EMPREC

   - DPLDEMVC

   - DPLDEMVR

   - DPLDEMVU

   - DPLDEMVD

   - CMPPROC

   - COMPILEV

   - JVSAMRDO

   - CSDUPDCT

   - JAMVSAMC

   - BLDVSAM

3. In the procedure CMPPROC, do not set LNKLIB, PDSSRC, and PROG. The values are supplied by the COMPILEV JCL that will execute COMPROC. Do set INDEX, COMPHLQ, and COMPHL2. You may need to change OUTC and the unit of WORK.

4. In the COMPILEV JCL, make the following changes:

   - Change the JOB statement.

   - Change the JCLLIB ORDER and the SOURCE to the PDS you created.

   - Change the LOADLIB to a load lib for your CICS region.

5. Submit the COMPILEV JCL. Make sure that the condition code is 0.

6. In the JAMVSAMC member, make the following changes:

   - Change all occurrences of YOURHLQ.JAM.VSAMFILE to the name you choose for the VSAM file used in this sample.

   - Change YOURVOL to an appropriate volume ID.

7. In the BLDVSAM JCL, make the following changes:

   - Change the JOB statement.

   - Change YOURHLQ.JAM.WORKFILE to the PDS you created in (1).

8. Submit the BLDVSAM JCL. Verify the results. One data set should be created with no extension, one data set created with DATA as the extension, and one data set with the INDEX extension.

   Note: A condition code of 8 is acceptable on the DELETE step; however, the condition code should be 0 on the DEFINE step.

9. In the RDO script, JVSAMRDO, make the following changes:

   - Change the name of the LIST to a valid list name for your CICS region.

   - You can also change the GROUP name, but make sure it is changed everywhere.

   - In the DEFINE statement for the VSAM file BEAJAMTV, change the DSNAME to match the name for the VSAM file set in JAMVSAMC.The value to which YOURHLQ.JAM.VSAMFILE is changed must be the same in both JVSAMRDO and JAMVSAMC.

10. In the CSDUPDCT JCL, make the following changes:

    - Change the JOB statement.

    - Change the STEPLIB.

    - Change the DFHCSD.

    - Change the SYSIN DSN.

11. Submit the CSDUPDCT JCL.

    You may get a warning on the DELETE steps, because the programs and file were not previously defined. Make sure the condition code is not higher than 4.

12. Log on to your CICS region.

13. Install the WebLogic JAM sample.

    To install the WebLogic JAM sample, type the following command at the command prompt:

    >     CEDA INSTALL GROUP(JAMEXMPL)

14. Verify the CICS sample programs.

    To verify the CICS sample programs, type the following command at the command prompt:

    >     CEMT INQUIRE PROG(DPLDEMVC)

    Repeat for DPLDEMVR, DPLDEMVU, and DPLDEMVD.

    Also make sure that the VSAM file is open:

    >     CEMT INQUIRE FILE(BEAJAMTV)

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 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, 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.CICS.outbound.gateway.Client -r