BEA Home | Events | Solutions | Partners | Products | Services | Download | Developer Center | WebSUPPORT
eLink Adapter for Mainframe Documentation | eLink Adapter for Mainframe CRM Administration Guide | Previous Topic | Next Topic | Contents | Index

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

- Using the CRM Monitor

- Activating and De-Activating Links

- Reviewing CRM Log Files

- Stopping the CRM

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:

- Entering the CRM command on the command line for UNIX.

- Running a CRM job using JCL written explicitly for your z/OS or OS/390 MVS system.

- Using the Tuexedo startup command, tmboot if you have a local configuration.

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.

1. Set APPDIR to the application directory

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.

Enter the CRM command on the command line.

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:

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.
-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.
-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 eLink Adapter for Mainframe Gateway Group Name.

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

1. Set the following environment variables 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>

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

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.

  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 2-1 Sample crmstart.jcl for CRM Command

>     //***************************************************************
>     //*  THIS JOB IS USED TO RUN THE CRM 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
>     //  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
>     //

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:

- Choose Programs|BEA Weblogic E-Business Platform|eLink 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

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

Figure2-1 shows an example of the CRM Monitor display.

Figure 2-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.

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

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

- Set Maximum CRM Trace establishes tracing of major events and all I/O buffers, plus tracing of all APPC verbs. This option is trace level 3 as described in the Trace Options section for the CRM 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.

The time tag information in the CRM trace should reflect the current system time. In order to make use of the correct time zone information on UNIX and MVS systems, it is important that the TZ environment variable be set correctly. If this variable is not set correctly on your system, refer to your system documentation for further information.

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

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:

- crmlkon Command

- crmlkoff Command

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:

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 DM_SNALINKS entry in the gwsnax.cfg that defines this link. Multiple link names can be specified.
-u<keyfile> | None | Optional | Specify a key file containing the authentication name to be used with the CRM.

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

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

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

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
-h | None | Optional | Displays help for the command.
-u<keyfile> | None | Optional | Specifies a key file containing the authentication name to be used with the CRM.
<linkname> | None | Required | Names the link to be stopped. This is the DM_SNALINKS entry in the DMCONFIG 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, use the following command:

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

Sets the crmlkoff command line parameters. Refer to Sample JCL for the crmlkon Command 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 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:

Keyword | Default | Required/ Optional | Description
--- | --- | --- | ---
group | None | Required | SNA domain group name.
crm name | Default CRM | Optional | Name of CRM.

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:

- Entering the crmdown command on the command line for UNIX.

- Running a CRMDOWN job using JCL written explicitly for your z/OS or OS/390 MVS system.

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:

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
-h | None | Optional | Displays help for the command.
-u<keyfile> | None | Optional | Specifies a key file containing the authentication name to be used with the CRM.

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.

  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 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=*

>     //

Copyright © 2001 BEA Systems, Inc. All rights reserved. Required browser: Netscape 4.0 or higher, or Microsoft Internet Explorer 4.0 or higher.