Using the Explicit APPC Sample

The explicit APPC sample demonstrates how BEA WebLogic Java Adapter for Mainframe (WebLogic JAM) integrates the WebLogic applications with batch MVS COBOL applications. This section provides the following information:

About the Explicit APPC Sample

Batch MVS COBOL Client to WebLogic EJB Sample

This sample demonstrates the functional capability of BEA WebLogic Java Adapter for Mainframe (WebLogic JAM) to invoke the services of an Enterprise Java Bean (EJB) deployed with WebLogic Server from a mainframe application, specifically a batch MVS client using explicit APPC. This invocation is facilitated by the EJB API assembler interface that is delivered as part of this sample.

The MVS COBOL client receives a string of text as input. In this sample, the business function of the EJB is to convert the string of text to uppercase and return the result to the client. The string displays in the WebLogic Server log by the EJB before and after conversion. The client displays the result on the system output device.

Roadmap for the Sample

To run the explicit APPC sample, follow the roadmap listed below:

Using the Sample

Preparing to Use the Explicit APPC Sample

To use the Explicit APPC Sample, you must complete the following steps.

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 4-1 with the script in Listing 4-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 4-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

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 4-1 with the JCL in Listing 4-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 4-2 The STARTCMD parameter in the CRMSTART JCL

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

Step 2: Set Logical Unit VTAM Definitions

This sample uses a Batch MVS client and requires a partner Logical Unit to be defined. Extra steps are required to make the necessary VTAM definitions for this sample. For information about Logical Unit definition and VTAM definition, see the BEA WebLogic Java Adapter for Mainframe Configuration and Administration Guide. In addition to defining an Logical Unit for the CRM to use, complete the following steps. The file VTAMDEFINITION in the <BEA_HOME>/<JAM_INSTALL_DIR>/samples/examples/explicitAPPC/
mainframe/source directory contains examples of the necessary VTAM definitions and configuration. See your VTAM specialist for assistance.

Step 3: 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 4: Start the examples Domain

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

Step 5: Configure the WebLogic JAM Gateway

Most configuration tasks were 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 IMS Installation Verification Sample to run on your system. These changes can be made in the WebLogic Administration Console in the following way.

Using the Batch MVS COBOL Client to WebLogic EJB Sample

Understanding How the Sample Works

This sample demonstrates the functional capability of WebLogic JAM to invoke a service offered by an EJB deployed in WebLogic Server from a mainframe application, specifically a batch MVS COBOL client using explicit APPC. This invocation is facilitated by the EJBAPI assembler interface that is delivered as part of the sample.

Understanding the Sample Configuration

When using WebLogic JAM to integrate with CICS or IMS applications, you must define an Logical Unit for the CRM. This sample consists of a batch program using explicit APPC and requires a partner Logical Unit to be defined. A partner Logical Unit must be defined for use by the EJBAPI. Note that the EJBAPI does not set the name of the Logical Unit that it uses. It relies on the default APPC Logical Unit. Therefore, the LUADD statement that is added to the APPCPMxx PARMLIB member, corresponding to the Logical Unit defined for the EJBAPI interface to use, must be the last in the member with the BASE attribute.

The EJBAPI also makes use of a symbolic destination or SYMDEST to establish an APPC conversation with the CRM. The Partner LU in the SYMDEST must be the Logical Unit defined for the CRM. The TP Name must be the name of the EJBExport element in the WebLogic JAM configuration, in this case TOUPPER.

In the WebLogic JAM configuration, an EJBExport element is defined with the name that matches the TP Name in the SYMDEST for the EJBAPI, TOUPPER. The JNDI-name attribute of this EJBExport element jam.ToupperServer is the value of the JNDI-name element in the WebLogic deployment descriptor weblogic-ejb-jar.xml for the ToupperServer 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 ToupperServer-jar.xml and wl-ToupperServer-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 ToupperServerBean 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, ExtToupperServerBean.

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:

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

ToupperServer, ToupperServerBean, and ToupperServerHome classes are generated by the eGen Application Code Generator. ToupperServer 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. ToupperServerHome is a standard home interface for a stateless session bean. It contains the definition of a create method that returns a ToupperServer object to the caller. ToupperServerBean extends EgenServerBean. ToupperServerBean contains an implementation of the dispatch method that is a wrapper for the toupper method. The implementation of the toupper method that is given in ToupperServerBean does not perform actual business logic. As it is defined in the eGen script that generates ToupperServerBean, the toupper method only receives a Chardata object and returns a Chardata object. To actually do any business logic, the ToupperServerBean must be extended and the toupper method overwritten.

The extension of the ToupperServerBean class that is included with this sample is called ExtToupperServerBean. ExtToupperServerBean contains an implementation of the toupper method containing the business logic. The string data member in the received Chardata object is written to the WebLogic log. The string is converted to uppercase, and the resulting string is written to the WebLogic Server log and returned to the client.

MVS Program

WLCLIENT is a simple COBOL batch client program that makes a synchronous request of a service offered by an EJB deployed in WebLogic Server by calling the EJBAPI assembler interface. The request consists of the string, "This is a string of text." The EJB will convert the string to uppercase and return it to the client. The response string that is returned to WLCLIENT is displayed in SYSOUT.

EJBAPI is an assembler interface that is called for use by programs to invoke the services of an EJB deployed in a WebLogic Server instance. EJBAPI establishes an APPC conversation with the CRM. The EJBAPI sends the request data to the CRM that then forwards the information to the WebLogic JAM Gateway. The EJBAPI issues a receive to retrieve the response data.

Sample Files

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

<BEA_HOME>/<JAM_INSTALL_DIR>/samples/examples/explicitAPPC/
gateway

The following table lists the samples files and their purpose:

Table 4-1 Files for the WebLogic JAM Application

<BEA_HOME>/<JAM_INSTALL_DIR>/samples/examples/explicitAPPC/
mainframe/source

The following table lists the samples files and their purpose:

Table 4-2 Files for Mainframe Application

To set up the batch MVS COBOL client to WebLogic EJB sample, 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. Click TOUPPER. Check Local Service Enabled—>Click Apply to enable the Local Service.

On the machine where the Gateway is installed, set the environment in the following way:

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/explicitAPPC/
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 where the batch client is to run:

Running the Sample

To run the sample, submit the EXCLIENT JCL. Make sure that the condition code is 0.

You will see the request string in the WebLogic Server log before and after the conversion to uppercase. The converted string will also be displayed in SYSOUT.