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

• Roadmap for the Sample

• Using the Sample

 

---

About the Explicit APPC Sample

The following section provides an overview of the explicit APPC sample: Batch MVS COBOL Client to WebLogic EJB Sample. A detailed description of how the sample works and instructions for running the sample are provided in the Using the Sample section.

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:

1. Verify prerequisite tasks.

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

2. Prepare to use the explicit APPC sample.

   1. Start the CRM.

   2. Set Logical Unit VTAM definitions.

   3. Update the WebLogic JAM Configuration File

   4. Start the examples domain

   5. Configure the WebLogic JAM Gateway

3. Set up the Sample

   1. Configure Services

   2. Set the Environment

   3. Generate and Build Source (Optional)

   4. Complete Mainframe Tasks

4. Run the Sample

 

---

Using the Sample

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

• Preparing to Use the Explicit APPC Sample

• Using the Batch MVS COBOL Client to WebLogic EJB Sample

  • Understanding How the Sample Works

  • Setting up the Sample

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

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

 

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

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

1. Define a VTAM APPC Logical Unit to be used by the EJBAPI interface. The EJBAPI establishes an APPC conversation with the CRM. It must have access to an Logical Unit for this purpose.

2. Configure APPC to use the new Logical Unit. You must add an LUADD statement to the APPCPMxx PARMLIB member. See the example in VTAMDEFINITION.

   The EJBAPI does not set the name of the Logical Unit it uses, but relies on the default APPC Logical Unit. As a result, the LUADD statement that is added to the APPCMxx PARMLIB member should be the last in the member with the BASE attribute. Also, the ACBNAME must match the ACBNAME for the Logical Unit defined for the EJBAPI interface.

3. Define an APPC SYMDEST. Use the APPC administration facility to define the SYMDEST. See VTAMDEFINITION for an example.

   The Partner LU must match the Logical Unit defined for the CRM. The TP Name must be the name configured for the EJB in the WebLogic JAM configuration. For this example, the name is TOUPPER.

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:

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

   <BEA_HOME>/<JAM_INSTALL_DIR>/config/examples

2. Copy jamconfig_BATCH.xml to jamconfig.xml.

Step 4: 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 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.

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 Batch region, click Java Adapter for Mainframe —> Regions —> BATCH Regions in the left pane. In the right pane, click on Batch1 and enter the name of the Logical Unit that you set in Step 2. Click Apply to set the Logical Unit.

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

 

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

   
    

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

   
    

   
    

4. To start the 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 appears in the WebLogic Server log:

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

Using the Batch MVS COBOL Client to WebLogic EJB Sample

After completing the steps in the Preparing to Use the Explicit APPC Sample section, you are ready to set up and run the explicit APPC sample: 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

• ToupperServer

• ToupperServerBean

• ToupperServerHome

• ExtToupperServerBean

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

File Name	File Purpose
chardata.cpy	COBOL copybook that defines the structure of the string mainframe data.
chardata.egen	eGen script that generates the Chardata.java DataView class.
Chardata.java	DataView class that corresponds to the chardata.cpy COBOL copybook.
toupperServer.egen	eGen script that generates the Chardata.java DataView class, the ToupperServer.java, ToupperServerBean.java, ToupperServerHome.java bean classes, and the ToupperServer-jar.xml and wl-ToupperServer-jar.xml deployment descriptors.
ToupperServer.java	EJB remote interface generated by the eGen utility.
ToupperServerBean.java	EJB generated by the eGen utility.
ToupperServerHome.java	EJB home interface generated by the eGen utility.
ExtToupperServerBean.java	EJB that extends ToupperServerBean. The business logic of servicing the requests from the mainframe is actually implemented in this class.
build.cmd	Script that builds the Chardata, ToupperServer, ToupperServerBean, ToupperServerHome, and ExtToupperServerBean classes. It assembles the classes along with the necessary deployment descriptors to a .jar file. The resulting JAM_ToupperServer.jar file is in the <BEA_HOME>\<JAM_INSTALL_DIR>\config\examples\ applications\examples\explicitAPPC\gateway directory.
build.sh	Unix script that builds the Chardata, ToupperServer, ToupperServerBean, ToupperServerHome, and ExtToupperServerBean classes. It assembles the classes along with the necessary deployment descriptors to a .jar file. The resulting JAM_ToupperServer.jar file is in the <BEA_HOME>/<JAM_INSTALL_DIR>/config/examples/ applications/examples/explicitAPPC/gateway directory.
ToupperServer-jar.xml	Deployment descriptor generated by toupperServer.egen.
wl-ToupperServer-jar.xml	WebLogic deployment descriptor generated by toupperServer.egen.
ejb-jar.xml	ToupperServer-jar.xml deployment descriptor that has been modified and renamed for inclusion in the JAM_ToupperServer.jar.
weblogic-ejb-jar.xml	wl-ToupperServer-jar.xml WebLogic deployment descriptor renamed for inclusion in the JAM_ToupperServer.jar.

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

<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

File Name	File Purpose
ASEJBAPI	JCL that assembles the WebLogic EJB API interface module EJBAPI.
CLCLIENT	JCL to compile and link the batch client WLCLIENT.
EXCLIENT	JCL to execute the batch client WLCLIENT.
EJBAPI	The WebLogic EJB API interface module.
VTAMDEFINITION	Contains sample Logical Unit definitions, a sample SIDEINFO definition, and a sample SYMDEST definition.
WLCLIENT	MVS batch COBOL client that makes a request to a service provided by an EJB through WebLogic JAM to convert a string to uppercase. The response is displayed in SYSOUT.

Setting Up the Sample

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.

 

Step 2: Set the Environment

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

• 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/explicitAPPC/
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_ToupperServer.jar.

• Run egencobol to use the eGen Application Code Generator on toupperServer.egen to generate the code for the ToupperServer bean and its 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 where the batch client is to run:

1. Allocate a Partitioned Data Set (PDS) that will store the source and JCL for the sample. Allocate a PDS for the objects that are created for this sample. Both of these PDSs should be allocated with Record Format: FB and Record Length: 80.

2. Allocate a PDS for the executable that is built in this sample. This PDS should be allocated with Record Format: U and Record Length: 0.

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

   • ASEJBAPI

   • CLCLIENT

   • EJBAPI

   • EXCLIENT

   • WLCLIENT

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

   • Change the JOB statement.

   • Change the YOURHLQ.OBJECT to the PDS that you allocated for objects.

   • Change the YOURHLQ.SOURCE to the PDS that you allocated for source.

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

6. In the CLCLIENT JCL, make the following changes:

   • Change the JOB statement.

   • Change the YOURHLQ.OBJECT to the PDS that you allocated for objects.

   • Change the YOURHLQ.SOURCE to the PDS that you allocated for source.

   • Change the YOURHLQ.LOAD to the PDS that you allocated for executables.

   • Change STEPLIB, SYSLIB, CSSLIB, if necessary.

7. Submit the CLCLIENT JCL. Make sure that all the condition codes are 0.

8. In the EXCLIENT JCL, make the following changes:

   • Change the JOB statement.

   • Change the YOURHLQ.LOAD to the PDS that you allocated for executables.

   • Do not submit this JCL until you are ready to run the client.

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.