Using the CRM Administration Commands

The topics in this section cover commands an administrator uses to start and stop the Communications Resource Manager (CRM). These commands may be entered on the command line for UNIX or NT systems or through Job Control Language (JCL) on OS/390MVS.

 

---

Action List

Before you use the CRM Administrative commands, 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 start or stop the CRM.	Starting and Stopping the CRM
3	Prepare for the next step.	What Do I Do Next? and Deploying Your Configuration

 

 

---

Prerequisites

Before you use the CRM Administrative commands, 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

 

---

Starting and Stopping the CRM

Before you learn how to start or stop the CRM for your specific operating system, you need to understand the start and stop command syntax and options. The two commands for starting and stopping the CRM are:

• CRM Command to launch the CRM

• crmdown Command to shut the CRM down

These commands can be entered from a command line or you may also use JCL on an OS/390 Multiple Virtual Storage (MVS) platform to set the invoke the CRM start and stop commands. Sample JCL is included in the samples.jar file, which is delivered with your JAM installation.

The following sections provide detailed descriptions of these commands and examples of JCL for each command. After you learn about the commands, you can then refer to the specific instructions for using them with your operating system in the sections following the command descriptions.

CRM Command

The CRM command launches the Communications Resource Manager. The CRM communicates between a JAM gateway and a remote application using SNA protocol.

When you start the CRM from the command line, the CRM Command Line Console puts its prompt in the window. If you exit the Command Line Console window, all of the active links are shut down.

You must configure one CRM for each JAM gateway, as well as configuring one stack for each CRM definition. Each stack can manage one or more SNA links. The CRM must be started and listening before the JAM gateway is booted.

The CRM has a BLOBLOG log file stored in $APPDIR. BLOBLOG stores session and link information. You can use the CRMLOGS command to display the contents and state of the CRM log file.

Example of the CRM command line:

CRM [ -t 0|1|2|3 ] [-s] [-p <nbr>] <addr> <group>

Descriptions of the command line options follow.

Command Line Options

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

Keyword	Default	Required/ Optional	Description
-t [0|1|2|3]	0	Optional	Turns tracing on and indicates the level of tracing. 0=No tracing. Setting this level effectively disables CRM tracing and closes the trace file, if there is one. If tracing is subsequently restarted, a new file is created with an incremental numerical suffix. 0 is the default trace level. 1=Minimum tracing. At this level, the CRM traces only major events and is sufficient only to determine the sequence of application conversations. 2=Medium tracing. At this level, the CRM also traces all I/O buffers. 3=Maximum tracing. At this level, the CRM also traces all APPC verbs. Note: Trace options for the CRM may also be set from the CRM Monitor. Refer to Using the CRM Monitor for more information about setting trace options from the CRM Monitor.
-s	Off (if parameter is not used)	Optional	Indicates APPC Stack API trace is turned on On OS/390 platforms, the General Trace Facility (GTF) is used to capture API trace records under user EID 2EA. The GTF must be active on the OS/390 platform to use the -s parameter. If the APPC Protocol Stack API trace is enabled, it generally shows the parameters and results of all API calls. Depending on the stack being used, other options (such as vendor-specified environment variables) may have to be activated for the CRM to enable the trace. Note: Trace options for the APPC Stack API trace may also be set from the CRM Monitor. Refer to Using the CRM Monitor for more information about setting trace options from the CRM Monitor.
-p <nbr>	100 threads	Optional	Turns on the performance option and indicates the number of threads to start. This value should correspond to the load of SNA requests that will be made concurrently. If the number of requests exceeds the number of threads, the request is still executed; however, the completion time could be affected. Do not exceed 200 threads. The CRM is tuned for a maximum of 200 threads. Lower the threads value if you have a restriction on the number of threads that can be active in your system.
<addr>	None	Required	Specifies a TCP/IP address using //hostname:port_addr or the sockaddr_in format of family, port, address: <0xFFFFPPPPAAAAAAAA> In this entry, arguments and options are defined in the following way: FFFF is the hex value of the protocol family, always 0x0002 for the INET family. PPPP is the hex value of an unused TCP/IP port. AAAAAAAA is the hex value of the IP address for the machine running the CRM.
<group>	None	Required	Indicates the JAM Gateway Group Name.

 

Environment Variables

You must set the following environment variables before starting the CRM:

• From the UNIX command line:

  APPDIR must be set to the application directory.

  For UNIX, the APPDIR indicates the directory for the files created by the CRM.

• From MVS:

  APPDIR=<High level qualifier for datasets to be created in APPDIR>

  For MVS, the APPDIR qualifies the dataset for the files created by the CRM.

Diagnostics

The CRM exits with a return code of 0 upon successful completion.

Examples

To launch the CRM with the console running in the background, enter the following command:

$ CRM //myhost:5587 GROUP2 std.out 2>std.err &

To launch the CRM with detailed tracing and APPC Stack API tracing turned on from the command line using the host/port address, enter the following command:

CRM -t 3 -s //myhost:5587 GROUP2

Sample CRM 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 CRM command.

SET STARTCMD

Sets the CRM command line parameters.

SET OBJLIB

Indicates the name of the PDSE library where the CRM 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 CRM. A sample member, ENV, is delivered with your product.

SET SIZE

Defines the region size for the running CRM task. The recommended setting for this option is 0M to allow the CRM to start up and level out to the size it requires.

SET ENV

Indicates the ENVFILE DD name. This value is pre-set and should not be changed.

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

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

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.

Listing 4-1 Sample crmstart.jcl for CRM Command

//*****************************************************************
//*  THIS JOB IS USED TO RUN THE SNACRM PROCESS.                  *
//*                                                               *
//* @(#)$Id: crmstart.jcl,v 1.3 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 SNACRM      *
//*****************************************************************
//*****************************************************************
//*  USE THE SET STATEMENTS TO SET THE APPROPRIATE VALUES         *
//*  STARTCMD IS THE CRM COMMAND LINE                             *
//*  OBJLIB IS THE LOAD LIBRARY CONTAINING THE PROGRAM EXECUTABLES*
//*  DATA IS THE DATASET THAT CONTAINS THE ENVIRONMENT VARIABLES  *
//*  ENVFILE NAMES THE MEMBER THAT CONTAINS THE ENVIRONMENT VARS  *
//*  RUNOPTS SETS ANY DESIRED LE RUNTIME OPTIONS (OPTIONAL)       *
//*  SIZE SETS THE REGION SIZE FOR THE SNACRM PROCESS. 0M SETS NO *
//*       LIMITS ON THE REGION SIZE                               *
//*  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 STARTCMD='"//<address>:<port>" <group>'
//  SET OBJLIB=
//  SET DATA=
//  SET ENVFILE=ENV
//  SET RUNOPTS=
//  SET SIZE=0M
   //SETENV='ENVAR("_CEE_ENVFILE=DD:ENV")'
  //*SETCEE=CEE,CBC=CBC
        //CRMEXECPGM=CRM,REGION=&SIZE,
//  PARM='POSIX(ON) &ENV &RUNOPTS/&STARTCMD'
    //STEPLIBDDDSN=&OBJLIB,DISP=SHR
          //*DDDSN=&CEE..SCEERUN,DISP=SHR
          //*DDDSN=&CBC..SCLBDLL,DISP=SHR
//MSGFILE  DD  SYSOUT=*
//TRACE    DD  SYSOUT=*
//SYSPRINT DD  SYSOUT=*
        //ENVDDDSN=&DATA(&ENVFILE),DISP=SHR
//                                           

crmdown Command

The crmdown command shuts down a CRM.

crmdown shuts down the CRM specified on the command line. crmdown can be used from any machine located on the same TCP/IP network as the machine running the CRM server. The command can also be used in a script and it returns 0 if the command could be sent to the target CRM or 1 if the command could not be sent to the target CRM.

Example of the crmdown command line:

crmdown -n<hostname:port> [-v -i]

Descriptions of the command line options follow.

Command Line Options

The following table provides descriptions of the valid options for the crmdown 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.

 

Diagnostics

crmdown only checks the syntax of the command. If the command could not be successfully sent to the CRM, crmdown prints an error message if in verbose mode and exits with error code 1. Upon successful completion, crmdown exits with exit code 0.

Example

To stop the CRM running on mach1 at port 5000:

crmdown -n mach1:5000

Sample crmdown 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 crmdown command.

SET STOPCMD

Sets the crmdown command line parameters.

SET OBJLIB

Indicates the name of the PDSE library where the crmdown 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 crmdown. A sample member, ENV, is delivered with your product.

SET SIZE

Defines the region size for the running crmdown task.

SET ENV

Indicates the ENVFILE DD name.

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

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 4-2 Sample crmdown.jcl for crmdown Command

//*****************************************************************
//*  THIS JOB IS USED FOR THE STAND-ALONE COMMAND USED            *
//*  TO SHUTDOWN THE SNACRM PROCESS. SEE USER GUIDE FOR MORE INFO *
//*                                                               *
//* @(#)$Id: crmdown.jcl,v 1.5 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 CRMDOWN     *
//*****************************************************************
//*****************************************************************
//*  STOPCMD INDICATES THE COMMAND LINE FOR CRMDOWN               *
//*  OBJLIB IS THE LOAD LIBRARY CONTAINING THE PROGRAM EXECUTABLES*
//*  RUNOPTS SETS ANY DESIRED LE RUNTIME OPTIONS (OPTIONAL)       *
//*  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 STOPCMD='-n<host name>:<port>'
//  SET OBJLIB=
//  SET RUNOPTS=
//  SET DATA=
//  SET ENVFILE=ENV
//  SET SIZE=1M
   //SETENV='ENVAR("_CEE_ENVFILE=DD:ENV")'
  //*SETCEE=CEE,CBC=CBC
    //CRMDOWNEXECPGM=CRMDOWN,REGION=&SIZE,
//  PARM='POSIX(ON) &ENV &RUNOPTS/&STOPCMD'
    //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=*

//

Starting the CRM on UNIX, OS/390 UNIX, or Windows NT

The CRM server communicates directly with the PU 2.1 server to provide SNA connectivity. These servers can be started manually. The PU 2.1 server must always be started before the CRM. Both servers must be started before starting the associated JAM gateway.

To ensure proper start up of the CRM, complete the following tasks:

1. Set the following environment variable in the environment where the CRM is started:

   APPDIR must be set to the application directory where the CRM will create its files.

2. Start the PU2.1 Server.

   Refer to the operational documentation provided by your SNA stack vendor for information about starting the PU2.1 server. The SNA stack must be running and active before you start the CRM.

3. Start the CRM.

   • To start the CRM on UNIX:

     Enter the CRM command with your required option arguments on the command line.

     When you start the CRM from the UNIX command line, the CRM Command Line Console puts its prompt in a window, and if exited, shuts down all of the active links.

   • To start the CRM from a Command Prompt Window on Windows NT:

     Open a Command Prompt window and navigate to the drive where the CRM executable is installed. Enter the CRM command with your required option arguments to start CRM.exe.

     On Windows NT, the CRM can be started in its own window; however, no prompt is displayed and no console commands are available.

     Refer to CRM Command for more detailed information about the CRM command.

Starting the CRM on OS/390 MVS

The OS/390 MVS platform sets the environment and invokes the CRM using Job Control Language (JCL).

1. Set the following environment variable in the environment where the CRM is started. A sample file is delivered (ENV) in the data library.

   APPDIR=<High level qualifier for datasets to be created in APPDIR>

   The high level qualifier is used for the datasets created by the CRM and must be unique for each running CRM.

   Note: For more information about the dataset names, refer to the information for installing the CRM on an MVS platform in the BEA WebLogic Java Adapter for Mainframe Installation Guide.

2. Run a CRM job using JCL written for your system.

   Refer to Sample CRM Command JCL for OS/390 MVS Platform for more information about the sample CRMstart.JCL.

Note: If the CRM is installed on an OS/390 MVS platform, it does not have to be restarted when the JAM gateway shuts down abnormally. The CRM continues running until it receives a normal termination command. Only the OS/390 MVS version and the OS/390 UNIX version of the CRM have this persistent feature. Refer to Stopping the CRM On All Platforms for more information about stopping the CRM on an OS/390 MVS platform.

Stopping the CRM On All Platforms

If the JAM gateway terminates, the persistent CRM feature allows the OS/390 CRM to continue running. You must explicitly shutdown the CRM if the JAM gateway has terminated and the CRM needs to be stopped.

• To stop the CRM from a UNIX or Windows NT system:

  Enter the crmdown command with your required option arguments on the command line.

• To stop the CRM from OS/390 MVS:

  Run a crmdown job using JCL written explicitly for your system.

Refer to crmdown Command for more information about the crmdown command and the sample crmdown JCL.

 

---

What Do I Do Next?

After you learn how to start and stop the CRM , you are ready to deploy your configuration file and verify that the JAM System is running correctly. Refer to Deploying Your Configuration for more information.