bea.com | products | dev2dev | support | askBEA |
|
e-docs > WebLogic Java Adapter for Mainframe > Configuration and Administration Guide > CRM Administration |
Configuration and Administration Guide |
CRM Administration
The CRM establishes and monitors communication links between the WebLogic JAM Gateway and mainframe systems, such as CICS, IMS, and batch. The CRM also provides support for the coordination of transactional resources using the two-phase commit protocol. For more information about how the CRM functions within WebLogic JAM, see WebLogic JAM Architecture.
With WebLogic JAM, you may administer and run the CRM in two environments: an environment or a z/OS or OS/390 Unix environment. This section provides information and steps for administering the CRM in both environments.
This section provides information on the following subjects:
Starting the CRM
The CRM command launches the Communications Resource Manager. You can start the CRM from either a z/OS or OS/390 MVS or z/OS or OS/390 Unix platform. The CRM may be started from the command line or from a shell script. You can enter the CRM command from a Unix command line or you may also use JCL on a z/OS or OS/390 MVS platform to run the CRM. Sample JCL is included with your WebLogic JAM installation.
To start the CRM:
Table 7-1 Arguments for the CRM command
or
Setting CRM Trace Level at CRM Startup
The CRM trace option can be enabled by using the -t option. For example, for full tracing:
CRM -t3 //myhost:7011 CRMB
The list in Table 7-1describes the three levels of tracing that can be set, and the functionality corresponding to each level.
On z/OS or OS/390 Unix systems, traces are written to a file in the directory in which the CRM was started. If the environment variable SNACRMWORKDIR is set, the trace is written to the directory it specifies. The file name is specified as:
CRM.<pid>.trace.<seq>
Where <pid> is the process ID of the CRM process, and <seq> is the sequence number of the trace file, which is always 0.
On MVS systems, traces are written to the file identified by DD:TRACE.
Note: Trace options for the CRM may also be set from the WebLogic Administration Console. See Modifying CRM Trace Level Settings for more information about setting trace options from the WebLogic Administration Console.
Setting APPC API Tracing at Startup
You can capture the VTAM APPC API by enabling the APPC API tracing. The API trace shows the parameters and values passed and returned to the VTAM APPC stack. The API trace is captured to the GTF tracing facility. The GTF tracing facility must be active in the mainframe region to capture the API traces.
The CRM APPC API trace option can be enabled by using the -s option. For example:
CRM -s //myhost:7011 CRMB
After capturing the traces, you must format the print using GTF formatting procedures such as IPCS. The APPC API trace is written to GTF as user ID 2EA. You may use this ID to filter the GTF print to include only the APPC API traces.
Note: Trace options for the CRM may also be set from the WebLogic Administration Console. See Setting APPC API Tracing in the WebLogic Administration Console for more information about setting trace options from the WebLogic Administration Console.
Starting the CRM in an MVS Environment
To start the CRM in an MVS environment, you use JCL. A JCL sample is included with your WebLogic JAM installation in member CRMSTART.
To start the CRM, follow these steps:
APPDIR=<High level qualifier for data sets to be created in APPDIR>
Table 7-2 JCL set Commands for the Sample CRMSTART
Listing 7-1 Sample JCL for the CRM Command
//***************************************************************
//* THIS JOB IS USED TO RUN THE CRM PROCESS. *
//* *
//* @(#)$Id: crmstart.jcl,v 1.3 2001/05/07 23:41:27 jsmith Exp $
//* Copyright (c)2000 BEA Systems, Inc., all rights reserved. *
//***************************************************************
//* YOU MUST SET THE ENVIRONMENT VARIABLES NEEDED BY CRM *
//***************************************************************
//***************************************************************
//* 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 CRM 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='"//<hostname>:<port>" <crm name>'
// SET OBJLIB=
// SET DATA=
// SET ENVFILE=ENV
// SET RUNOPTS=
// SET SIZE=0M
// SET ENV='ENVAR("_CEE_ENVFILE=DD:ENV")'
//* SET CEE=CEE,CBC=CBC
//CRM EXEC PGM=CRM,REGION=&SIZE,
// PARM='POSIX(ON) &ENV &RUNOPTS/&STARTCMD'
//STEPLIB DD DSN=&OBJLIB,DISP=SHR
//* DD DSN=&CEE..SCEERUN,DISP=SHR
//* DD DSN=&CBC..SCLBDLL,DISP=SHR
//MSGFILE DD SYSOUT=*
//TRACE DD SYSOUT=*
//SYSPRINT DD SYSOUT=*
//ENV DD DSN=&DATA(&ENVFILE),DISP=SHR
//
Starting CRM in z/OS or OS/390 Unix Environment
You may start the CRM in either console mode or as a background task. In console mode you may interact with the console to perform or monitor different tasks. In background mode, you must use the CRMDOWN command to stop the CRM. This task is described in Stopping the CRM in a z/OS or OS/390 Unix Environment. You must also disable the interactive dialog from STDIN.
When you start the CRM in z/OS or OS/390 Unix environment, the CRM command line console prompt displays. You may choose to start the CRM in background mode, in which case, no console prompt displays.
To start the CRM in z/OS or OS/390 Unix:
A sample file, uss.env, is delivered with the installation of WebLogic JAM.
For example, if you installed the CRM into the directory /work/bea/crm, the following commands will set your PATH and LIBPATH variables appropriately:
export PATH=$PATH: /work/bea/crm/bin
export LIBPATH=$PATH: /work/bea/crm/lib
export APPDIR=/home/bea/jam
CRM [ -t 0|1|2|3 ] [-s] [-p <nbr>] <hostname>:<port> <crm name>
For example: To start the CRM running on the machine myhost listening on port 5587 with the CRM name of MYCRM, enter the following on the command line. This example disables standard input, pipes the std.out and std.err to files, and runs in background mode rather than console mode. The STDIN capability is disabled by piping from the /dev/null directory.
$ CRM //myhost:5587 MYCRM </dev/null >std.out 2>std.err &
Stopping the CRM
The crmdown command shuts down a CRM. You must explicitly shut down the CRM if the WebLogic JAM Gateway is stopped and the CRM needs to be stopped. You can stop the CRM in a z/OS or OS/390 MVS environment or in a z/OS or OS/390 Unix environment.
To stop the CRM:
Table 7-3 Command Line Options for crmdown
or
Stopping the CRM in an MVS Environment
To stop the CRM in an MVS environment, you use JCL. A JCL sample, CRMDOWN, is included with your WebLogic JAM installation.
Table 7-4 JCL set Commands for the Sample CRMDOWN
Listing 7-2 Sample JCL for crmdown Command
//***************************************************************
//* THIS JOB IS USED FOR THE STAND-ALONE COMMAND USED *
//* TO SHUTDOWN THE CRM PROCESS. *
//* *
//* @(#)$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 CRM 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
// SET ENV='ENVAR("_CEE_ENVFILE=DD:ENV")'
//* SET CEE=CEE,CBC=CBC
//CRMDOWN EXEC PGM=CRMDOWN,REGION=&SIZE,
// PARM='POSIX(ON) &ENV &RUNOPTS/&STOPCMD'
//STEPLIB DD DSN=&OBJLIB,DISP=SHR
//* DD DSN=&CEE..SCEERUN,DISP=SHR
//* DD DSN=&CBC..SCLBDLL,DISP=SHR
//ENV DD DSN=&DATA(&ENVFILE),DISP=SHR
//MSGFILE DD SYSOUT=*
//SYSPRINT DD SYSOUT=*
//
Stopping the CRM in a z/OS or OS/390 Unix Environment
You can stop the CRM in a z/OS or OS/390 Unix environment by running crmdown from a command line. If the command could not be successfully sent to the CRM, crmdown prints an error message and exits with error code 1. Upon successful completion, crmdown exits with exit code 0.
To stop the CRM from a command line:
For example: To stop the CRM running on mach1 at port 5000:
crmdown -n mach1:5000
Activating and De-Activating CRM Links
The crmlkon and crmlkoff commands are used to activate or de-activate CRM links. You can activate and de-activate links from either a z/OS or OS/390 MVS or z/OS or OS/390 Unix platform
Note: You can also start and stop a CRM link from the WebLogic Administration Console. For instructions, see Modifying CRM Link Definitions.
This section provides information on the following subjects:
Activating CRM Links
The crmlkon command is responsible for activating CRM links. You can activate CRM links in the z/OS or OS/390 MVS environment or the z/OS or OS/390 Unix environment. This is useful if one or more individual links needs to be restarted after the CRM is connected.
To activate CRM links in any environment:
Table 7-5 Command Line Options for crmlkon
or
Activating CRM Links in an MVS Environment
To activate CRM links in an MVS environment, you use JCL. A JCL sample, crmlkon, is included with your WebLogic JAM installation. Refer to your system administrator for more information about your particular setup.
To activate CRM links in an MVS environment, follow these steps:
Table 7-6 JCL set Commands for the Sample CRMLKON
Listing 7-3 Sample JCL for crmlkon Command
//*****************************************************************
//* THIS JOB IS USED FOR THE STAND-ALONE LINK COMMAND *
//* TO ACTIVATE A REMOTE LINK. *
//* *
//* @(#)$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 CRM 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 CRM 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
// SET ENV='ENVAR("_CEE_ENVFILE=DD:ENV")'
//* SET CEE=CEE,CBC=CBC
//CRMLKON EXEC PGM=CRMLKON,REGION=&SIZE,
// PARM='POSIX(ON) &ENV &RUNOPTS/&LINKCMD'
//STEPLIB DD DSN=&OBJLIB,DISP=SHR
//* DD DSN=&CEE..SCEERUN,DISP=SHR
//* DD DSN=&CBC..SCLBDLL,DISP=SHR
//ENV DD DSN=&DATA(&ENVFILE),DISP=SHR
//MSGFILE DD SYSOUT=*
//SYSPRINT DD SYSOUT=*
//
Activating CRM Links from a z/OS or OS/390Unix Environment
The crmlkon command starts all of the CRM links named on the command line. If the command could not be successfully sent to the CRM, crmlkon prints an error message and exits with error code 1. Upon successful completion, crmlkon exits with exit code 0.
To activate CRM links from a Unix command line:
For example, to start links, link2 and cicstest, owned by the CRM running on mach1 at port 5000:
crmlkon -n mach1:5000 link2 cicstest
De-Activating CRM Links
The crmlkoff command is responsible for de-activating CRM links. You can de-activate CRM links in the z/OS or OS/390 MVS environment or the z/OS or OS/390 Unix environment. This is useful if one or more individual links needs to be stopped after the CRM is connected.
To de-activate CRM links in any environment:
Table 7-7 Command Line Options for crmlkoff
or
De-Activating a CRM Link in an MVS Environment
To de-activate CRM links in an MVS environment, you use JCL. A JCL sample, crmlkoff, is included with your WebLogic JAM installation.
Table 7-8 JCL set Commands for the Sample CRMLKOFF
Listing 7-4 Sample JCL for crmlkoff Command
//***************************************************************//* THIS JOB IS USED FOR THE STAND-ALONE LINK COMMAND *
//* TO DEACTIVATE A REMOTE LINK. *
//* *
//* @(#)$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 CRM 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 CRM 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
// SET ENV='ENVAR("_CEE_ENVFILE=DD:ENV")'
//* SET CEE=CEE,CBC=CBC
//CRMLKOFF EXEC PGM=CRMLKOFF,REGION=&SIZE,
// PARM='POSIX(ON) &ENV &RUNOPTS/&LINKCMD'
//STEPLIB DD DSN=&OBJLIB,DISP=SHR
//* DD DSN=&CEE..SCEERUN,DISP=SHR
//* DD DSN=&CBC..SCLBDLL,DISP=SHR
//ENV DD DSN=&DATA(&ENVFILE),DISP=SHR
//MSGFILE DD SYSOUT=*
//SYSPRINT DD SYSOUT=*
//
De-Activating a CRM Link in a z/OS or OS/390 Unix Environment
The crmlkoff command stops all of the CRM links named on the command line. If the command could not be successfully sent to the CRM, crmlkoff prints an error message and exits with error code 1. Upon successful completion, crmlkoff exits with exit code 0.
To de-activate CRM links from a Unix command line:
For example: To stop links link1 and cicstest owned by the CRM running on mach at port 5000:
crmlkoff -n mach:5000 link1 cicstest
CRM Console Commands
When you run the CRM from the z/OS or OS/390 Unix command line, you are presented with a CRM prompt. Table 7-9 lists the commands the you can enter at the CRM prompt and the tasks to perform. Some of the functionality for these commands is also available from the WebLogic Administration Console. For these cases, the corresponding location in the WebLogic Administration Console is provided.
Table 7-9 CRM Commands and Corresponding WebLogic Administration Console Functions