Using JAM Administration Utilities

The BEA WebLogic Java Adapter for Mainframe (JAM) product includes the following administration utilities for managing the Communications Resource Manager (CRM) and the JAM gateway:

• Administrative commands allow you to activate and deactivate links.

• The CRM Monitor allows you to monitor the CRM server that provides SNA connectivity, select trace options, and monitor link status.

• The JAM Administration Servlet allows you to start or stop the gateway when the system requires administration or maintenance and you do not want to stop or restart your WebLogic Server.

The CRM Monitor and JAM Administration Servlet are used when the CRM is running on Windows or UNIX operating systems. If your CRM is running on an OS/390 UNIX operating system, you must enter administrative commands from the command line.

 

---

Action List

Before you use the JAM administration utilities, see the following action list and refer to the appropriate information sources.

	Your action...	Refer to...
1	Complete all prerequisite tasks.	Prerequisites
2	Learn how to activate and de-activate links with administrative commands.	Activating and De-Activating Links
3	Learn about the CRM Monitor.	Using the CRM Monitor
4	Start the CRM Monitor as appropriate for your operating system.	Launching the CRM Monitor from the Windows NT Desktop and Launching the CRM Monitor from the Command Line
5	Set the CRM Monitor options.	Setting CRM Monitor Options
6	Learn about the JAM Administration Servlet.	Starting and Stopping the Gateway with the JAM Administration Servlet
7	Start the JAM Administration Servlet.	Launching the JAM Administration Servlet
8	Set the JAM Administration Servlet options.	Setting JAM Administration Servlet Options
9	Start or stop the JAM gateway using the JAM Administration Servlet.	Using JAM Administration Servlet Start and Stop Commands
10	Determine what you want to do next.	What Do I Do Next?, Shutting Down the System for Planned Outages, BEA WebLogic Java Adapter for Mainframe Workflow Processing Guide, or BEA WebLogic Java Adapter for Mainframe Programming Guide

 

 

---

Prerequisites

Before you use the JAM administration utilities, you should complete the following tasks.

	Your action...	Refer to...
1	Verify that system requirements have been met.	BEA WebLogic Java Adapter for Mainframe Introduction and Release Notes
2	Determine which configuration your system requires and install the JAM product as appropriate for your configuration.	BEA WebLogic Java Adapter for Mainframe Installation Guide
3	Verify that your mainframe configuration has been properly set up for the CRM.	Preparing Mainframe Configurations for CRM Requirements
4	Create a JAM configuration file and verify that the gateway has been properly configured.	Defining the JAM Gateway Configuration
5	Learn how to start or stop the CRM with the CRM administration commands.	Using the CRM Administration Commands
6	Deploy your configuration and verify that the gateway is working properly.	Deploying Your Configuration

 

 

---

Activating and De-Activating Links

You can activate and de-activate CRM links that have been defined in the JC_SNALINKS section of the jcrmgw.cfg file by executing one of the link commands from the command line. There are two commands used to activate and de-activate links:

• crmlkon Command

• Sample crmlkon Command JCL for OS/390 MVS Platform

You may also use Job Control Language (JCL) on an OS/390 Multiple Virtual Storage (MVS) platform to set the environment and invoke link commands. The following sections provide descriptions of the link commands and samples of JCL that may be used for your MVS operating system.

crmlkon Command

The crmlkon command starts one or more named CRM links.

crmlkon starts all of the CRM links named on the command line. This command is useful if one or more individual links failed to start when the CRM server booted. It can be used from any machine located on the same TCP/IP network as the machine running the CRM server. It can be used in a script and returns 0 if the command could be sent to the target CRM. It returns 1 if the command could not be sent to the target CRM.

Example of the crmlkon command line:

crmlkon -n<hostname:port> [-v -i] <linkname> ... 

Descriptions of the command line options follow.

Command Line Options

The following table provides descriptions of the valid options for the crmlkon command:

Keyword	Default	Required/ Optional	Description
-n<hostname:port>	None	Required	Names the machine and port running the CRM server.
-v	Off	Optional	Specifies verbose. Normally the command will not produce any messages, facilitating use in a script.
-i	Off	Optional	Ignores errors. When specifying multiple links, any error encountered when issuing CRM commands causes crmlkon to stop processing links and return. Errors can be ignored for individual links and processing continues with the next named link
<linkname>	None	Required	Names the link to be started. This is the JC_SNALINKS entry in the jcrmgw.cfg that defines this link. Multiple link names can be specified.

 
 

Example

To start links, link2 and cicstest, owned by the CRM running on mach1 at port 5000:

crmlkon -n mach1:5000 link2 cicstest

Diagnostics

crmlkon only checks the syntax of the command. Use the CRM Monitor to determine if the link actually became active. Refer to Setting CRM Monitor Options for more information. If the command could not be successfully sent to the CRM, crmlkon prints an error message if in verbose mode and exits with error code 1. Upon successful completion, crmlkon exits with exit code 0.

Sample crmlkon Command JCL for OS/390 MVS Platform

This section provides an explanation of the SET commands and an example of JCL that can be used when you run the crmlkon command. The sample SET commands may not reflect the configuration of your system. You must customize the SET commands for your environment. Refer to your System Administrator for more information about your particular setup.

SET LINKCMD

Sets the crmlkon command line parameters. Refer to crmlkon Command for more information about the command line parameters.

SET OBJLIB

Indicates the name of the PDSE library where the crmlkon executable is installed.

SET DATA1

Indicates the name of the PDS library where the crmlkon required parameter file FMB was installed.

SET DATA

Indicates the dataset containing the ENVFILE.

SET ENVFILE

Indicates the name of the PDS member that contains the environment variables for the CRMLKON. A sample member, ENV, is delivered with your product.

SET SIZE

Defines the region size for the running crmlkon task.

SET ENV

Indicates the ENVFILE DD name. This value is pre-set.

SET CEE

Specifies the high-level qualifier for the LE runtime library. CEE should be set to the prefix of the IBM Language Environment data sets. Language Environment is required to run crmlkon.

SET CBC

Specifies the high-level qualifier for the C/C++ runtime library. CBC should be set to the prefix of the IBM C++ data sets.

Note: Uncomment the SET CBC line and tailor the STEPLIB concatenation if these libraries are not in your system link library concatenation.

Listing 6-1 Sample crmlkon,jcl for crmlkon Command

//*****************************************************************
//*  THIS JOB IS USED FOR THE STAND-ALONE LINK COMMAND            *
//*  TO ACTIVATE A REMOTE LINK. SEE USER GUIDE FOR MORE INFO      *
//*                                                               *
//* @(#)$Id: crmlkon.jcl,v 1.10 2001/05/07 23:41:27 crount Exp $
//* Copyright (c)2000 BEA Systems, Inc., all rights reserved.     *
//*****************************************************************
//*  YOU MUST SET THE ENVIRONMENT VARIABLES NEEDED BY CRMLKON     *
//*****************************************************************
//*****************************************************************
//*  LINKCMD INDICATES THE DISTRIBUTED SNACRM ADDRESS AND LINKNAME*
//*  OBJLIB IS THE LOAD LIBRARY CONTAINING THE EAM PROGRAM OBJECTS*
//*  RUNOPTS SETS ANY DESIRED LE RUNTIME OPTIONS                  *
//*  DATA IS THE DATASET THAT CONTAINS THE ENVIRONMENT VARIABLES  *
//*  ENVFILE NAMES THE MEMBER THAT CONTAINS THE ENVIRONMENT VARS  *
//*  SIZE SETS THE REGION SIZE FOR THE SNACRM PROCESS             *
//*  TAILOR YOUR JCL FOR THE BELOW IF THESE LIBRARIES ARE NOT     *
//*  IN YOUR SYSTEM LINK LOAD LIBRARY CONCATENATION               *
//*  CEE IS THE HLQ FOR THE LE RUNTIME LIBRARY                    *
//*  CBC IS THE HLQ FOR THE C/C++ RUNTIME LIBRARY                 *
//*****************************************************************
//  SET LINKCMD='-n<host name>:<port> <linkname>'
//  SET OBJLIB=
//  SET RUNOPTS=
//  SET DATA=
//  SET ENVFILE=ENV
//  SET SIZE=1M
   //SETENV='ENVAR("_CEE_ENVFILE=DD:ENV")'
  //*SETCEE=CEE,CBC=CBC
    //CRMLKONEXECPGM=CRMLKON,REGION=&SIZE,
//  PARM='POSIX(ON) &ENV &RUNOPTS/&LINKCMD'
    //STEPLIBDDDSN=&OBJLIB,DISP=SHR
          //*DDDSN=&CEE..SCEERUN,DISP=SHR
          //*DDDSN=&CBC..SCLBDLL,DISP=SHR
        //ENVDDDSN=&DATA(&ENVFILE),DISP=SHR
//MSGFILE  DD  SYSOUT=*
//SYSPRINT DD  SYSOUT=*

//

crmlkoff Command

The crmlkoff command stops one or more named CRM links.

crmlkoff stops all of the CRM links named on the command line. This is useful if one or more individual links need to be stopped after the CRM server booted. It can be used from any machine located on the same TCP/IP network as the machine running the CRM server. It can be used in a script and returns 0 if the command could be sent to the target CRM. It returns 1 if the command could not be sent to the target CRM.

Example of the crmlkoff command line:

crmlkoff -n<hostname:port> [-v -i] <linkname> ...

Command Line Options

The following table provides descriptions of the valid options for the crmlkoff command:

Keyword	Default	Required/ Optional	Description
-n<hostname:port>	None	Required	Names the machine and port running the CRM server.
-v	Off	Optional	Specifies verbose. Normally the command will not produce any messages, facilitating use in a script.
-i	Off	Optional	Ignores errors. When specifying multiple links, any error encountered when issuing CRM commands causes crmlkon to stop processing links and return. Errors can be ignored for individual links and processing continues with the next named link
<linkname>	None	Required	Names the link to be stopped. This is the JC_SNALINKS entry in the jcrmgw.cfg that defines this link. Multiple link names can be specified.

 

Example

To stop links link1 and cicstest owned by the CRM running on mach at port 5000:

crmlkoff -n mach:5000 link1 cicstest

Diagnostics

crmlkoff only checks the syntax of the command. Use the CRM Monitor to determine if the link actually became active. Refer to Setting CRM Monitor Options for more information. If the command could not be successfully sent to the CRM, crmlkoff prints an error message if in verbose mode and exits with error code 1. Upon successful completion, crmlkoff exits with exit code 0.

Sample crmlkoff Command JCL for OS/390 MVS Platform

This section provides an explanation of the SET commands and an example of JCL that can be used when you run the crmlkoff command. The sample SET commands may not reflect the configuration of your system. You must customize the SET commands for your environment. Refer to your System Administrator for more information about your particular setup.

SET LINKCMD

Sets the crmlkoff command line parameters. Refer to Sample crmlkon Command JCL for OS/390 MVS Platform for more information about the command line parameters.

SET OBJLIB

Indicates the name of the PDSE library where the crmlkoff executable is installed.

SET DATA

Indicates the dataset containing the ENVFILE.

SET ENVFILE

Indicates the name of the PDS member that contains the environment variables for the crmlkoff. A sample member, ENV, is delivered with your product.

SET SIZE

Defines the region size for the running crmlkoff task.

SET ENV

Indicates the ENVFILE DD name.

SET CEE

Specifies the high-level qualifier for the Language Environment (LE) runtime library. CEE should be set to the prefix of the IBM LE data sets. Language Environment is required to run crmlkoff.

SET CBC

Specifies the high-level qualifier for the C/C++ runtime library. CBC should be set to the prefix of the IBM C++ data sets.

Note: Uncomment the SET CBC line and tailor the STEPLIB concatenation if these libraries are not in your system link library concatenation.

Listing 6-2 Sample crmlkoff.jcl for crmlkoff Command

//*****************************************************************
//*  THIS JOB IS USED FOR THE STAND-ALONE LINK COMMAND            *
//*  TO DEACTIVATE A REMOTE LINK. SEE USER GUIDE FOR MORE INFO    *
//*                                                               *
//* @(#)$Id: crmlkoff.jcl,v 1.10 2001/05/07 23:41:27 crount Exp $
//* Copyright (c)2000 BEA Systems, Inc., all rights reserved.     *
//*****************************************************************
//*  YOU MUST SET THE ENVIRONMENT VARIABLES NEEDED BY CRMLKOFF    *
//*****************************************************************
//*****************************************************************
//*  LINKCMD INDICATES THE DISTRIBUTED SNACRM ADDRESS AND LINKNAME*
//*  OBJLIB IS THE LOAD LIBRARY CONTAINING THE EAM PROGRAM OBJECTS*
//*  RUNOPTS SETS ANY DESIRED LE RUNTIME OPTIONS                  *
//*  DATA IS THE DATASET THAT CONTAINS THE ENVIRONMENT VARIABLES  *
//*  ENVFILE NAMES THE MEMBER THAT CONTAINS THE ENVIRONMENT VARS  *
//*  SIZE SETS THE REGION SIZE FOR THE SNACRM PROCESS             *
//*  TAILOR YOUR JCL FOR THE BELOW IF THESE LIBRARIES ARE NOT     *
//*  IN YOUR SYSTEM LINK LOAD LIBRARY CONCATENATION               *
//*  CEE IS THE HLQ FOR THE LE RUNTIME LIBRARY                    *
//*  CBC IS THE HLQ FOR THE C/C++ RUNTIME LIBRARY                 *
//*****************************************************************
//  SET LINKCMD='-n<host name>:<port> <linkname>'
//  SET OBJLIB=
//  SET RUNOPTS=
//  SET DATA=
//  SET ENVFILE=ENV
//  SET SIZE=1M
   //SETENV='ENVAR("_CEE_ENVFILE=DD:ENV")'
  //*SETCEE=CEE,CBC=CBC
   //CRMLKOFFEXECPGM=CRMLKOFF,REGION=&SIZE,
//  PARM='POSIX(ON) &ENV &RUNOPTS/&LINKCMD'
    //STEPLIBDDDSN=&OBJLIB,DISP=SHR
          //*DDDSN=&CEE..SCEERUN,DISP=SHR
          //*DDDSN=&CBC..SCLBDLL,DISP=SHR
        //ENVDDDSN=&DATA(&ENVFILE),DISP=SHR
//MSGFILE  DD  SYSOUT=*
//SYSPRINT DD  SYSOUT=*
//

 

---

Using the CRM Monitor

The CRM Monitor is a Java application that allows you to connect to and monitor the CRM server through a graphical user interface (GUI). You can use the CRM Monitor to monitor link status and activity and start or stop diagnostic tracing of the CRM server. The CRM Monitor makes a network connection to the remote CRM server through a TCP/IP network connection. The CRM Monitor application file is the crmmon.jar file.

Launching the CRM Monitor from the Windows NT Desktop

If the CRM Monitor is installed on Windows NT, a short cut is created in the Start menu of the Desktop when you install JAM.

To launch the CRM Monitor from the Desktop:

• Choose Programs|BEA Weblogic E-Business Platform|Java Adapter for Mainframe|CRM Monitor from the Start menu.

Launching the CRM Monitor from the Command Line

The CRM Monitor can also be started from the command line on UNIX and Windows platforms.

To launch the CRM Monitor from the command line:

• Enter the following command for the Java 1.2.2 interpreter:

  java -jar crmmon.jar

Setting CRM Monitor Options

Figure 6-1 shows an example of the CRM Monitor display.

Figure 6-1 CRM Monitor Display

 

After you launch the CRM Monitor, use the following instructions to set CRM Monitor options:

1. To monitor a CRM, type the CRM address in the Enter CRM Address text box using the following format:

   //host:port

   where host explicitly specifies the CRM host machine and port specifies the port number of the CRM on the CRM host machine.

   This value may only be entered once per started instance of a CRM Monitor.

2. Select one of the following trace options for the CRM:

   • Stop CRM Trace disables CRM tracing and closes the trace file, if it exists. This option is trace level 0 as described in the Trace Options section for the CRM Command command.

   • Set Minimum CRM Trace establishes tracing of only major events. This level is sufficient only to determine the sequence of application conversations. This option is trace level 1 as described in the Trace Options section for the CRM Command command.

   • Set Medium CRM Trace establishes minimum tracing plus tracing of all I/O buffers. This option is trace level 2 as described in the Trace Options section for the CRM Command command.

   • Set Maximum CRM Trace establishes medium tracing plus tracing of all APPC verbs. This option is trace level 3 as described in the Trace Options section for the CRM Command command.

   Note: The CRM Monitor does not show trace data. This data is captured in a file under the APPDIR directory of the CRM server (APPDIR is the variable name associated with the CRM directory). Please contact BEA Customer Support for help in locating the trace file(s) and interpreting them.

3. Select one of the following APPC stack trace options:

   • Start APPC Stack Trace establishes tracing of the APPC stack. This option generally shows the parameters and results of all API calls. Depending on the stack being used, other options such as vendor-specified environment variables also may have to be activated. This option may be selected along with any of the previous Trace Options. This option corresponds to the -s option as described in the CRM Command section.

   • Stop APPC Stack Trace disables APPC stack trace, if established.

   Note: Trace options for the CRM and APPC Stack API trace options may also be set from the CRM command. Refer to the CRM Command section for more information about trace options.

4. After you enter a CRM address and select trace options, the following fields display information about the CRM you are monitoring:

   Display Field	Description
   Selected CRM	Displays the name of the CRM at the address entered in the address field.
   Trace Status	Displays the currently selected trace options.
   Link Status	Displays the current status of all remote links for the selected CRM. (Text may be scrolled.)
   Link Statistics	Displays the current statistics for all remote links for the selected CRM. (Text may be scrolled.)
   Message Line	Displays messages showing either the results of automatic connection attempts or commands issued to change the trace options.

   
    

 

---

Starting and Stopping the Gateway with the JAM Administration Servlet

Figure 6-2 shows an example of the JAM Administration Servlet window:

Figure 6-2 JAM Administration Servlet Window

 
 

The JAM Administration Servlet is packaged in the jam.ear file from the JAM distribution. The servlet is available on any system where the JamAdmin Web application is deployed from the jam.ear file.

Launching the JAM Administration Servlet

To display the JAM Administration Servlet in a browser window, enter the following URL:

http://<host>:<port>/jam/JamAdmin

In this example, <host> and <port> specify the WebLogic listen address.

Setting JAM Administration Servlet Options

You may set several boot options to be used when the JAM gateway is started from the JAM Administration Servlet window. These options correspond to options used with the GWBOOT command. For more detailed information about the GWBOOT command options, refer to the Adding the JAM Startup Class to the WebLogic Server Configuration File section.

The following options may be set in the JAM Administration Servlet window before you start the JCRMGW gateway:

Option	Corresponding GWBOOT Option	Description
Trace on	-t	Turns on level 3 CRM tracing if started as a local CRM (no -r option)
Remote CRM	-r	Specifies a remote CRM
Default user	-u <name>	Specifies a user ID

 

Note: When the JAM Administration Servlet is started, the options selected, Trace on, Remote CRM, and Default user, reflect the current configuration as established by either the WebLogic Server Console or this servlet.

Using JAM Administration Servlet Start and Stop Commands

The following command buttons on the JAM Administration Servlet window allow you to start or stop JAM:

Command Button	Description
Start	Initializes the gateway with the options specified. The message 'JAM has been successfully started' appears if the operation succeeds.
Stop	Stops the gateway if it is currently running. The message 'JAM has been successfully stopped' appears if the operation succeeds.

 

 

---

What Do I Do Next?

In the normal course of operations your JAM system may occasionally need to be shut down for planned outages of your remote environment. Refer to the next section, Shutting Down the System for Planned Outages, for more information. Otherwise, you can begin using JAM for workflow processing or generating Java source code. If you want to perform workflow processing between Java applications and the mainframe, refer to the BEA WebLogic Java Adapter for Mainframe Workflow Processing Guide. If you want to develop Java applications by generating Java source code from COBOL copybooks, refer to the BEA WebLogic Java Adapter for Mainframe Programming Guide.