Verifying Your Installation

When you have completed the installation process, BEA WebLogic Java Adapter for Mainframe (WebLogic JAM) provides the following ways to verify your installation

• Verifying Installation of Files and Directories

• Using the Installation Verification Samples

 

---

Verifying Installation of Files and Directories

After you have installed WebLogic JAM, you can verify the files and directories that are installed on your system. For a list of these files, see BEA WebLogic Java Adapter for Mainframe Installation Files and Directories.

 

---

Using the Installation Verification Samples

After you have installed WebLogic JAM, run the installation verification sample that corresponds to your system:

• Installation verification sample for IMS

• Installation verification sample for CICS

About the Installation Verification Samples

As the name implies, the installation verification samples are designed to allow you to verify that WebLogic JAM is installed and running on your system. The samples allow a client to make a request of a mainframe server program on either IMS or CICS.

The samples are designed to run "out of the box" with very limited modification. The installation verification samples include:

• Java Files

  • Java .class files

  • Java source

  • eGen scripts

  • Build scripts

  • Preconfigured WebLogic Server domain

• Mainframe Files

  • Mainframe source

  • Sample JCL

  • IMS or CICS sample configurations

Note: JCL to compile the mainframe sample programs is included as examples to provide completeness. The JCL that is shipped may not conform to your standards or installations. The sample JCL may need to be modified or replaced to meet your needs.

Program definitions and other configuration for your IMS or CICS region may require coordination with the IMS or CICS system programmer.

Most configuration tasks are preconfigured or completed during the installation process. Working from the WebLogic Administration Console, you can make the modifications required for the sample to run on your system. When these modifications are complete, you can run the simple client supplied by the sample to verify that WebLogic JAM is installed and running properly. The installation verification sample runs in the supplied verify domain. The client uses the Gateway to send a request from the WebLogic Server environment to the mainframe. The mainframe server converts the supplied string from mixed case to uppercase.

The only difference between the IMS and the CICS sides of this sample is that for IMS, TOUPPER is an APPC Service that is mapped to an IMS transaction; for CICS, TOUPPER is a DPL Service that is mapped to a CICS program.

How to Use the Samples

While the WebLogic JAM samples contain precompiled source for the Java portion of the sample, you may choose to generate and compile source. Depending on your skill, experience, and time-constraints, you may choose to work with the Java portion of the samples in the following ways:

• Run the sample

  Because of the contents shipped with the samples, in most cases, you can simply run the sample with minimal configuration to run on your system. The sample will use the supplied .class files.

• Compile source and run the sample

  Each sample provides build scripts that allow you to compile the source. This option allows you to see how the source is compiled and run the sample.

• Generate source, compile, and run the sample

  Each sample provides eGen scripts. This option allows you to use eGen Application Code Generator to generate source. Afterward, the build scripts can be run. By using this option, you can see how the eGen utility generates source and run the sample.

Preconfigured WebLogic Server Domains

The WebLogic JAM installation includes a directory named config. This config directory contains subdirectories for two preconfigured WebLogic Server domains:

• verify

  WebLogic Server domain that is set up for running the installation verification. verify is the directory that contains the files necessary to configure and run the verify domain

• examples

  WebLogic Server domain that is set up for examples of WebLogic JAM running with WebLogic Server and mainframe applications

 

---

Roadmap for Installation Verification Samples

To run each of the installation verification samples, follow the roadmap listed below:

1. Verify prerequisite tasks.

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

2. Set up the sample.

   See the Setting Up the Samplefor IMS or the Setting Up the Samplesection for CICS.

   1. Start the CRM.

   2. Update the WebLogic JAM configuration file.

   3. Start the verify domain.

   4. Configure the WebLogic JAM Gateway.

   5. Enable services.

   6. Set the environment.

   7. Generate and build source (optional).

   8. Complete mainframe tasks.

3. Run the sample.

 

---

Before You Use the Samples

Before you run the samples, the following tasks must be completed:

• Install WebLogic Server.

  For information about installing WebLogic Server, see the BEA WebLogic Server documentation.

• Install WebLogic JAM.

  For information about installing WebLogic JAM, see the Installing WebLogic Java Adapter for Mainframe section of this guide.

• Define the Logical Unit for the CRM and vary it active.

  For information about defining the Logical Unit, see the BEA WebLogic Java Adapter for Mainframe Configuration and Administration Guide.

• If using IMS, verify that the APPC communication to IMS is active.

  For information about APPC communication with WebLogic JAM, see the BEA WebLogic Java Adapter for Mainframe Configuration and Administration Guide.

• If using CICS, the connection must be defined to the CICS region.

  For information about CICS connection with WebLogic JAM, see the BEA WebLogic Java Adapter for Mainframe Configuration and Administration Guide.

 

---

Using the Installation Verification Sample for IMS

After completing the tasks in the Before You Use the Samples section, you are ready to set up and run the sample.

How the Sample Works

The program TOUPIMS is a simple COBOL IMS server program that dequeues the request data, converts the data to uppercase, then inserts the data back on the message queue. The copybook CHARDATA provides the structure of the user data in the request and response messages. 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.

Understanding the Sample Configuration

For this simple sample, no special configuration is required. The Java client calls the service TOUPPER.

• Gateway

  The APPC Service TOUPPER is mapped to the name of the IMS transaction program, TOUPIMS.

• On the mainframe

  The server program TOUPIMS is defined to the IMS region in the usual way any program is defined to an IMS region.

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:

• Chardata

• BaseClient

• Client

Chardata is a DataView class that is generated by the eGen Application Code Generator. The data member in the Chardata class corresponds to the data field in the CHARDATA copybook. The Chardata class is responsible for all data translation between the mainframe format of the data and the Java format of the data.

The BaseClient class that is generated by the eGen Application Code Generator is an extension of the EgenClient class. BaseClient is the class that implements the actual calls to the TOUPPER mainframe service in its toupper method. The toupper method is a wrapper for the callService method of the EgenClient class with the TOUPPER service as a parameter.

The Client class is the actual user interface. The Client class has a BaseClient member. The Client class receives string input as a command line argument. You may also enter a URL 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, a Chardata DataView is initialized with the input data. The toupper method of the BaseClient member is called with this DataView as a parameter. The converted string value encapsulated in the returned DataView is then displayed.

IMS Program

The program TOUPIMS is a simple COBOL IMS server program that dequeues the request data, converts the data to uppercase, then inserts the data back on the message queue. The copybook, CHARDATA, provides the structure of the user data in the request and response messages. 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 side of the sample are installed in the following directory:

<BEA_HOME>/<JAM_INSTALL_DIR>/samples/verify/gateway/outbound

The following table lists the sample files and their purpose:

Table 5-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.
baseClient.egen	eGen script that generates the Chardata.java DataView class and the BaseClient.java EgenClient class.
BaseClient.java	Java class that extends EgenClient class that calls the TOUPPER service.
Client.java	The user-interface client class that receives the input string from the user, and displays the result of the TOUPPER service to the user. It invokes the TOUPPER service by calling the callService method of its BaseClient member.
build.cmd	Script that builds the Chardata, BaseClient, and Client classes. The built class files are under the <BEA_HOME>\<JAM_INSTALL_DIR>\config\verify\ clientclasses\verify\gateway\outbound directory.
build.sh	Unix script that builds the Chardata, BaseClient, and Client classes. The built class files are under the <BEA_HOME>/<JAM_INSTALL_DIR>/config/verify/ clientclasses/verify/gateway/outbound directory.

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

<BEA_HOME>/<JAM_INSTALL_DIR>/samples/verify/IMS/outbound/source

The following table lists the samples files and their purpose:

Table 5-2 Files for IMS Application

File Name	File Purpose
CHARDATA	COBOL copybook that defines the structure of the string input and output data.
COMPTOUP	JCL that compiles and links the TOUPIMS program.
JAMDEFI	Contains sample IMS stage 1 and PSBGEN input for the IMS configuration of the TOUPIMS program.
TOUPIMS	IMS server program that receives a string in mixed case and returns the string in uppercase.

Setting Up the Sample

To set up the installation verification sample for IMS, perform 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 5-1 Fields for the CRM

 

Listing 5-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 5-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_IMS.xml file in the following directory:

   <BEA_HOME>/<JAM_INSTALL_DIR>/config/verify

2. Copy jamconfig_IMS.xml to jamconfig.xml.

Step 3: Start the verify Domain

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

• For Microsoft Windows:

  startVerifyServer.cmd 

• For Unix:

  . ./startVerifyServer.sh 

Step 4: 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 installation verification sample for IMS 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 verify 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 IMS region, click Java Adapter for Mainframe —> Regions —> IMS Regions in the left pane. In the right pane, click VS10IMS. Enter the Logical Unit name that supplies your IMS control region with APPC communication. You will find this name with the DISPLAY APPC operator command in IMS. Do not enter the Logical Unit name for APPLID of the IMS control region. This APPLID does not support APPC communication. If your IMS control region does not currently support APPC communication, you will need to set up this communication in APPC/MVS. Then activate the communication within IMS using the START APPC Operator command. Click Apply to set the Logical Unit.

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


 

1. At the top of the right pane, click IMS Regions—>CRM1toIMS. In the new window, click CRM1toIMS. 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. Click Apply.

   
    

4. To start the 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)."

Step 5: Enable the Service

To enable the APPC service, click Services —> APPC Services in the left pane. In the right pane, click TOUPPER. On the General tab, check Enabled and click Apply.

 

Step 6: 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/verify directory and execute the following command to set the environment:

  For Microsoft Windows:

  setVerifyEnv.cmd 

  For Unix:

  . ./setVerifyEnv.sh

  The following message will display:

  "Your environment has been set."

Step 7: Generate and Build Source (Optional)

The WebLogic JAM samples provide generated source. Compiled .class files are also provided. If you want to see how the source is generated and the classes are built, change to the <BEA_HOME>/<JAM_INSTALL_DIR>/samples/verify/gateway/outbound 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. The build script puts the built .class files in the <BEA_HOME>/<JAM_INSTALL_DIR>/config/verify/clientclasses/
  verify/gateway/outbound directory.

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

  • chardata.egen to generate Chardata.java

  • baseClient.egen to generate BaseClient.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 8: Complete Mainframe Tasks

On the machine with the IMS region:

1. Create a Partitioned Data Set (PDS) to store the source and JCL for the installation verification sample.

2. From the machine where the gateway is installed, use FTP to send the following files from the <BEA_HOME>/<JAM_INSTALL_DIR>/samples/verify/IMS/outbound/source directory to the PDS that you created:

   • CHARDATA

   • COMPTOUP

   • JAMDEFI

   • TOUPIMS

3. In the COMPTOUP JCL, make the following changes:

   • Change the JOB statement.

   • Change YOURHLQ.SOURCE to the PDS you created.

   • Change YOUR.PGMLIB to a PGMLIB for your IMS region.

   • Change YOUR.PROCLIB to the location of CBLTDLI.

   • Change YOUR.RESLIB to the proper value.

   • Change RESLIB to SDFSRESL if you are using a newer IMS version. Refer to CBLTDLI in your PGMLIB to determine which library name your version uses. Make sure, if your IMS version requires this change, that you make the change to both the DD name and the library name.

4. Submit the COMPTOUP JCL. Make sure that all the condition codes are zero.

5. Define the program TOUPIMS to the IMS region. JAMDEFI contains sample IMS stage 1 and PSBGEN input. See your IMS systems programmer for assistance.

Running the Sample

To run the installation verification sample for IMS, type the following command in the window used in step 6:

java verify.gateway.outbound.Client hello

This command will convert the string 'hello' to uppercase: HELLO.

If the client is being run on a different machine than the Gateway or if the WebLogic Server instance is listening on a port other than 7001, you may enter a URL as a second command line argument. For example:

java verify.gateway.outbound.Client hello "t3://hostname:port"

In this statement, the following definitions apply:

hostname is the address of the machine where WebLogic Server is running.

port is the port for WebLogic Server.

If you have successfully run the installation verification sample for IMS, your installation is complete and verified. To complete the post-installation tasks, see the Performing Post-Installation Tasks section.

 

---

Using the Installation Verification Sample for CICS

After completing the tasks in the Before You Use the Samples section, you are ready to set up and run the sample.

How the Sample Works

The program TOUPCICS is a simple COBOL CICS server program that is linked to and passed a COMMAREA. The characters in the COMMAREA are converted to uppercase. The structure of the data in the COMMAREA is given in the copybook CHARDATA. 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.

Understanding the Sample Configuration

For this simple sample, no special configuration is required. The Java client calls the service TOUPPER.

• Gateway

  The DPL service TOUPPER is mapped to the name of the CICS program TOUPCICS.

• On the mainframe

  The server program TOUPCICS is defined to the CICS region, in this case using RDO, in the usual way any program is defined to a CICS region.

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:

• Chardata

• BaseClient

• Client

Chardata is a DataView class that is generated by the eGen Application Code Generator. The data member in the Chardata class corresponds to the data field in the CHARDATA copybook. The Chardata class is responsible for all data translation between the mainframe format of the data and the Java format of the data.

The BaseClient class that is generated by the eGen Application Code Generator is an extension of the EgenClient class. The BaseClient is the class that implements the actual calls to the TOUPPER mainframe service in its toupper method.The toupper method is a wrapper for the callService method of the EgenClient class with the TOUPPER service as a parameter.

The Client class is the actual user interface. The Client class has a BaseClient member. The Client class receives string input as a command line argument. You may also enter a URL 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 a Chardata DataView is initialized with the input data. The toupper method of the BaseClient member is called with this DataView as a parameter. The converted string value encapsulated in the returned DataView displays.

CICS Program

The program TOUPCICS is a simple COBOL CICS server program that is linked to and passed a COMMAREA. The characters in the COMMAREA are upper-cased. The structure of the data in the COMMAREA is given in the copybook CHARDATA. 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 side of the sample are installed in the following directory:

<BEA_HOME>/<JAM_INSTALL_DIR>/samples/verify/gateway/outbound

The following table lists the sample files and their purpose:

Table 5-3 Files for the WebLogic JAM

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.
baseClient.egen	eGen script that generates the Chardata.java DataView class and the BaseClient.java EgenClient class.
BaseClient.java	Java class that extends EgenClient class that calls the TOUPPER service.
Client.java	The user interface client class that receives the input string from the user, and displays the result of the TOUPPER service to the user. It invokes the TOUPPER service by calling the callService method of its BaseClient member.
build.cmd	Script that builds the Chardata, BaseClient, and Client classes. The built class files are under the <BEA_HOME>\<JAM_INSTALL_DIR>\config\verify\ clientclasses\verify\gateway\outbound directory.
build.sh	Unix script that builds the Chardata, BaseClient, and Client classes. The built class files are under the <BEA_HOME>/<JAM_INSTALL_DIR>/config/verify/ clientclasses/verify/gateway/outbound directory.

Application

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

<BEA_HOME>/<JAM_INSTALL_DIR>/samples/verify/CICS/outbound/source

The following table lists the sample files and their purpose:

Table 5-4 Files for CICS Application

File Name	File Purpose
CHARDATA	COBOL copybook that defines the structure of the string input and output data.
CMPPROC	Procedure used to compile and link the CICS programs.
COMPILE	JCL that executes the CMPROC for the program TOUPCICS.
CSDU	RDO cards to define TOUPCICS to the CICS region.
CSDUPD	JCL that executes CSDU.
TOUPCICS	CICS server program that receives a string in mixed case and returns the string in uppercase.

Setting Up the Sample

To set up the installation verification sample for CICS, perform 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  5-2 with the script in Listing  5-3. 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.

Listing 5-3 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  5-2 with the JCL in Listing  5-4. 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.

Figure 5-2 Fields for the CRM

 

 

Listing 5-4 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 in the following directory:

   <BEA_HOME>/<JAM_INSTALL_DIR>/config/verify

2. Copy jamconfig_CICS.xml to jamconfig.xml.

Step 3: Start the verify Domain

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

• For Microsoft Windows:

  startVerifyServer.cmd 

• For Unix:

  . ./startVerifyServer.sh 

Step 4: 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 installation verification sample for CICS 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 verify 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 name is the ACBNAME in the VTAM Logical Unit definition or the APPLID of the region.


 

1. At the top of the pane, click CICS Regions—>CRM1CICS3. In the new window, click CRM1CICS3. 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)."

Step 5: Enable the Service

To enable the DPL service, click Java Adapter for Mainframe —> Services—>DPL Services in the left pane. In the right pane, click TOUPPER under Service Name. Check Enabled and click Apply.

 

Step 6: 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/verify and execute the following command to set the environment:

  For Microsoft Windows:

  setVerifyEnv.cmd 

  For Unix:

  . ./setVerifyEnv.sh

  The following message will display:

  "Your environment has been set."

Step 7: 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/verify/gateway/outbound 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. The build script puts the built.class files in the <BEA_HOME>/<JAM_INSTALL_DIR>/config/verify/clientclasses/verify/gateway/outbound directory.

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

  • chardata.egen to generate Chardata.java

  • baseClient.egen to generate BaseClient.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 8: Complete Mainframe Tasks

On the machine with the CICS region:

1. Create a Partitioned Data Set (PDS) to store the source and JCL for the installation verification sample for CICS.

2. From the machine where the Gateway was installed, use FTP to send the following files from the <BEA_HOME>/<JAM_INSTALL_DIR>/samples/verify/CICS/outbound/source directory to the PDS that you created:

   • CHARDATA

   • CMPPROC

   • COMPILE

   • CSDU

   • CSDUPD

   • TOUPCICS

3. In the procedure, CMPPROC, you do not need to set LNKLIB, PDSSRC, and PROC. The values are supplied by the COMPILE JCL that will exec COMPROC. Set INDEX, COMPHLQ, COMPHL2. You may need to change OUTC and the unit of WORK.

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

   • Change the JOB statement.

   • Change the LNKLIB to a load lib for your CICS region.

   • Change the YOURHLQ.JCLLIB.ORDER to the PDS name containing CMPPROC.

5. Submit the COMPILE JCL. Make sure that the condition code is zero.

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

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

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

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

   • Change the STEPLIB, DFHCSD, and SYSIN DSNs.

   • You may need to change the unit of WORK.

8. Submit the CSDUPD JCL. Note that you may get a warning on the Delete step in the CSDU, because the TOUPCICS program probably was not defined before. The condition code should not be above 4.

9. Log on to your CICS region.

10. To install the WebLogic JAM installation verification GROUP:

    CEDA INSTALL GROUP(JAMVRFY)

11. To verify the CICS TOUPCICS program:

    CEMT INQUIRE PROG(TOUPCICS)

Running the Sample

To run the installation verification sample for CICS, type the following in the command prompt in the window you used to set the environment:

java verify.gateway.outbound.Client hello

This command will change the string, 'hello', to uppercase: HELLO.

If the client is being run on a different machine than the Gateway or if the WebLogic Server instance is listening on a port other than 7001, you may enter a URL as a second command line argument. For example:

java verify.gateway.outbound.Client hello "t3://hostname:port"

In this statement, the following definitions apply:

hostname is the address of the machine where WebLogic Server is running.

port is the port for WebLogic Server.

If you have successfully run the installation verification sample for CICS, your installation is complete and verified. To complete the post-installation tasks, see the Performing Post-Installation Tasks section.