Administering the SNA Components

The topics in this section cover activities an administrator performs with the Communications Resource Manager (CRM) to maintain BEA eLink Adapter for Mainframe applications.

The interface to the stack administration and configuration is dependent on the stack provider and is not covered in this guide. Refer to vendor publications for the stack(s) used in your environment.

This section discusses the following topics:

Starting the CRM

The CRM is a server that 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 eLink Adapter for Mainframe Gateway.

You can start the CRM by:

Starting the CRM on UNIX

To ensure proper startup of the CRM, complete the following tasks. Use this mthod for starting the CRM only when you have a distributed configuration with the CRM on Solaris 8 or the mainframe.

CRM Command

The CRM command launches the Communictions Resource Manager. 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.

You must configure one CRM for each eLink Adapter for Mainframe Gateway, as well as configure one stack for each CRM definition. Each stack can manage one or more SNA links.

CRM has two types of log files stored in $APPDIR, RSTRTLOG, and BLOBLOG. RSTRTLOG is the transaction state log used during the recovery process, while the BLOBLOG log stores session and link information. Deleting the log files requires a cold start for each link involved. You can use the CRMLOGS command to display the contents and state of the CRM log files.

Example of the CRM command line:

CRM [ -t 0|1|2|3 ] [-p<nbr>] [-s] [-n <type>:#:#] [-u <keyfile>] <addr> <group>

Command Line Options

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

Examples

The following sections show three examples of different options for starting the CRM.

Starting the CRM and CRM Command Line Console

To start a CRM from a UNIX command line, use a command similar to the following one:

CRM -t 0 //myhost:5587 GROUP2 /dev/null>std.out 2>std.err &

When you start CRM from the UNIX command line, the following CRM command line console appears:

$ CRM -t 0 //myhost:5587 GROUP2
    A eLink Adapter for Mainframe Resource Manager started Thu Dec 11
       18:40:49.098 1997
       [CRM]
 
       Console active. Enter commands
       ?>
        da => Display active tasks
        dl => Display remote links
        ds => Display link statistics
        dt => Display trace status
        st => Start all links
        sh => Stop all links and terminate
        si => Terminate immediately (no quiesce)

Starting the CRM with CRM Command Line Console Running in Background

To launch the CRM with the console running in the background, use a command similar to the following one:

$ CRM -t 0 //myhost:5587 GROUP2 <dev/null>std.out 2>std.err &

Starting the CRM with Detailed Tracing and APPC Stack API Tracing

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

CRM -t 2 -s //myhost:5587

Diagnostics

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

Starting the CRM on z/OS or OS/390 MVS

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

Note: If the CRM is installed on a z/OS or OS/390 MVS platform, it does not have to be restarted if the eLink Adapter for Mainframe Gateway goes down abnormally. A tmshutdown will not cause the CRM to shut down. You must run the crmdown utility to shut down the CRM. Only the z/OS or OS/390 MVS version and the z/OS or OS/390 UNIX version of the CRM have this persistent feature.

Sample JCL for the CRM Command

This section provides an explanation of the SET commands and an example of JCL that can be used when you run the CRM command.

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

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 is installed with the Gateway, not on the mainframe.

Launching the CRM Monitor from the Windows Desktop

If the CRM Monitor is installed on Windows, a short cut is created in the Start menu of the Desktop when you install eLink Adapter for Mainframe.

To launch the CRM Monitor from the Desktop:

Launching the CRM Monitor from the Command Line

The CRM Monitor can also be started from the command line on UNIX

platforms.

To launch the CRM Monitor from the command line:

Setting CRM Monitor Options

Figure 2-1 CRM Monitor Display

Activating and De-Activating Links

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

You may also use Job Control Language (JCL) on a z/OS or 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 follows:

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

Descriptions of the command line options follow.

Command Line Options

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

Example

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

crmlkon -n mach1:5000 link2 cicstest

Diagnostics

Sample JCL for the crmlkon Command

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

SET OBJLIB

Indicates the name of the PDSE library where the crmlkon 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 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 2-2 Sample 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 ELINK ADAPTER FOR  *
//*  MAINFRAME 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
//  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=*

//

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 follows:

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

Command Line Options

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

Example

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

crmlkoff -n mach:5000 link1 cicstest

Diagnostics

Sample JCL for the crmlkoff Command

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

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 2-3 Sample 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 ELINK ADAPTER FOR  *
//*  MAINFRAME 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
//  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=*
//

Reviewing CRM Log Files

You can display the content and state of the CRM log files by using the CRMLOGS command or CRMLOGS JCL.

CRMLOGS Command

Use the CRMLOGS command to display the contents and state of the two CRM log files. RSTRTLOG is the transaction state log used during the recovery process and the BLOBLOG log stores session and link information. Deleting the log files requires a cold start for each link involved.

Command Line Options

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

Example

To display the contents and state of the CRM log file for dalvs5:8002 and GROUP2, use the following command:

CRMLOGS GROUP2 dalvs5:8002

Diagnostics

CRMLOGS exits with a return code of 0 upon successful completion.

Sample JCL for the CRMLOGS Command

The following section is an explanation of the SET commands and an example of JCL that can be used when you run the CRMLOGS command.

SET LNKCMD

Sets the CRMLOGS command line parameters.

SET OBJLIB

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

SET DATA1

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

SET DATA2

Indicates the dataset containing the ENVFILE.

SET ENVFILE

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

SET SIZE

Defines the region size for the running CRMLOGS 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 CRMLOGS.

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 2-4 Sample JCL for CRMLOGS Command

//***************************************************************
//*  THIS JOB IS USED TO CHECK THE RECOVERY LOGS FOR              *
//*  OUTSTANDING TRANSACTION DATA. SEE USER GUIDE FOR MORE INFO   *
//*                                                               *
//* @(#)$Id: crmlogs.jcl,v 1.6 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 CRMLOGS     *
//***************************************************************
//***************************************************************
//*  SNACMD IS USED TO SET THE DESIRED SNACRM GROUP NAME          *
//*  OBJLIB IS THE LOAD LIBRARY CONTAINING THE EAM PROGRAM OBJECTS*
//*  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             *
//*  ENV SETS THE ENVIRONMENT VARIABLES DD NAME                  *
//*  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 LOGSCMD=<group>
//  SET OBJLIB=
//  SET DATA=
//  SET ENVFILE=ENV
//  SET RUNOPTS=
//  SET SIZE=10M
//  SET ENV='ENVAR("_CEE_ENVFILE=DD:ENV")'
//* SET CEE=CEE,CBC=CBC
//CRMLOGS  EXEC  PGM=CRMLOGS,REGION=&SIZE,
//  PARM='POSIX(ON) &ENV &RUNOPTS/&LOGSCMD'
//STEPLIB  DD  DSN=&OBJLIB,DISP=SHR
//*        DD  DSN=&CEE..SCEERUN,DISP=SHR
//*        DD  DSN=&CBC..SCLBDLL,DISP=SHR
//MSGFILE  DD  SYSOUT=*
//SYSPRINT DD  SYSOUT=*
//ENV      DD  DSN=&DATA(&ENVFILE),DISP=SHR
//

Stopping the CRM

The z/OS or OS/390 CRM will persist through termination of the Gateway, regardless of whether the Gateway was terminated by abnormal conditions or a tmshutdown command.

You can stop the CRM by:

crmdown Command

The crmdown command 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. It can be used in a script and it 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 crmdown command line follows:

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

Command Line Options

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

Example

To stop the CRM running on mach1 at port 5000, use the following command:

crmdown -n mach1:5000

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.

Sample JCL for the CRMDOWN Command

This section provides an explanation of the SET commands and an example of JCL that can be used when you run the crmdown command.

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

Listing 2-5 Sample 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
//  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=*

//