CRM Administration Guide

Administering the SNA Components

The topics in this section cover activities an administrator performs with the Communications Resource Manager (CRM) to maintain Oracle Tuxedo Mainframe Adapter for SNA 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 Oracle Tuxedo Mainframe Adapter for SNA 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 MVS system.
Using the Tuxedo 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 method for starting the CRM only when you have a distributed configuration with the CRM on HP-UX 11.23 or the mainframe.

Set APPDIR to the application directory
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.

Start the CRM.

Enter the CRM command on the command line.

CRM Command

The CRM command launches the Communications 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 Oracle Tuxedo Mainframe Adapter for SNA 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]

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

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 Oracle Tuxedo Mainframe Adapter for SNA 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 Oracle Tuxedo Mainframe Adapter for SNA 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 MVS

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

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>

Run a CRM job using JCL written for your system.

Note: If the CRM is installed on a z/OS MVS platform, it does not have to be restarted if the Oracle Tuxedo Mainframe Adapter for SNA 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 MVS version and the z/OS 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 3-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
//

Having Separate CRM Configurations on Mainframe

TMA provides the flexibility for you to store and manage CRM related configurations (CICSLINKS and SNASTACKS) independently on mainframe.

More specifically, TMA automatically checks if DM_SNASTACKS is configured in DMCONFIG. If positive, TMA will use DM_SNASTACKS and DM_SNALINKS configurations in DMCONFIG; otherwise, TMA will use the CRM configurations on mainframe. If there are no CRM configurations on mainframe, TMA will be shut down with errors in ULOG.

To use the flexibility, do the following steps on both CRM side and TMA SNA side.

After all configurations on both CRM side and TMA SNA side, start CRM firstly, then TMA SNA Gateway. You can use ULOG to check whether TMA SNA Gateway successfully connects to CRM.

Configurations on CRM Side

On this side, do the followings.

For each CRM, define its configuration name and location by adding command lines like below.

...

// SET STARTCMD='-t 3 "//zsvr:8001" CRM8001'

//CFG      DD  DSN=&DATA(&CFGFILE),DISP=SHR

//SET CFGFILE=CFG

...

CFG is the DD card, specifying separate CRM configurations on mainframe.

SET CFGFILE indicates the name of the PDS member that contains STACK and LINK configurations on CRM.

Create dataset member (CFG) for each CRM, and set LINK and STACK parameters. Table 3-2 lists all available parameters for CRM configuration; Listing 3-2 is a sample for CRM configuration.

Table 3-2 Parameters for CRM Configuration
Section	Parameter	Notes
`STACK`	`STACKTYPE=VT210`	The same as `STACKTYPE` in `*DM_SNASTACKS` in `DMCONFIG`; however, its value can only be `VT210`.
	`LOCALLU`	The same as `LOCALLU` in `*DM_SNASTACKS` in `DMCONFIG`.
	`LTPNAME`	The same as `LTPNAME` in `*DM_SNASTACKS` in `DMCONFIG`.
	`STACKPARMS`	The same as `STACKPARMS` in `*DM_SNASTACKS` in `DMCONFIG`.
`LINK`	`RDOM`	The same as `RDOM` in `*DM_SNALINKS` in `DMCONFIG`. The value of `RDOM` must match the domain name of `DM_REMOTE` in `DMCONFIG`, so that `SNAGW` can map configurations.
	`LSYSID`	The same as `LSYSID` in `*DM_SNALINKS` in `DMCONFIG`.
	`RSYSID`	The same as `RSYSID` in `*DM_SNALINKS` in `DMCONFIG`.
	`RLUNAME`	The same as `RLUNAME` in `*DM_SNALINKS` in `DMCONFIG`.
	`MODENAME`	The same as `MODENAME` in `*DM_SNALINKS` in `DMCONFIG`.
	`STARTTYPE`	The same as `STARTTYPE` in `*DM_SNALINKS` in `DMCONFIG`.
	`MAXSESS`	The same as `MAXSESS` in `*DM_SNALINKS` in `DMCONFIG`.
	`MINWIN`	The same as `MINWIN` in `*DM_SNALINKS` in `DMCONFIG`.
	`MAXSYNCLVL`	The same as `MAXSYNCLVL` in `*DM_SNALINKS` in `DMCONFIG`.

Listing 3-2 CRM Configuration Sample

...

[STACK]

STACKTYPE=VT210

LOCALLU=CRMLU05

LTPNAME=*

STACKPARMS=wasa

[LINK]

RDOM=MVSDOM

LSYSID=CR05

RSYSID=CICS

RLUNAME=CICSA

MODENAME=SMSNA100

SECURITY=LOCAL

STARTTYPE=COLD

MAXSESS=8

MINWIN=4

MAXSYNCLVL=2

...

Below is a JCL sample for CRM command (separate CRM configurations on mainframe).

Listing 3-3 JCL Sample for CRM Command (Separate CRM Configurations on Mainframe)

//***************************************************************

//*  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 CFGFILE=CFG

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

//CFG      DD  DSN=&DATA(&CFGFILE),DISP=SHR

//

Configurations on TMA SNA Side

On this side, configure TMA SNA gateway according to Configuring the Oracle Tuxedo Mainframe Adapter for SNA Gateway, except for its Add the *DM_SNASTACKS Section and Add the *DM_SNALINKS Section in Option A: Edit the DMCONFIG File.

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 Oracle Tuxedo Mainframe Adapter for SNA.

To launch the CRM Monitor from the Desktop:

Choose Programs|BEA Weblogic E-Business Platform|Oracle Tuxedo Mainframe Adapter for SNA 10g R3|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 JRE or JDK interpreter:

java -jar crmmon.jar

Setting CRM Monitor Options

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

Figure 3-1 CRM Monitor Display

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

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.

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 Oracle Customer Support for help in locating the trace file(s) and interpreting them.

Note:

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.

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.

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.

Multiple SNA Gateways Connecting to a Single CRM

Overview

TMA CRM permits multiple Gateways to connect and use the resources provided by a single CRM process. This feature considerably reduces the processing load required on the computer hosting the CRM while supporting distribution of workload at SNA Gateway level.

The multiple Gateways provide mainframe to Tuxedo application load balancing and failover.

Advantages of Multi-Gateway Support

The primary advantage of Multi-Gateway support is the ability for the CRM to host concurrent connections from one or more SNA Gateways. The advantages of this approach include:

Overall, a single CRM consumes less system resources than multiple CRMs.
The resulting configuration is much easier for you to configure, administer, and operate.
The CRM can load balance mainframe requests for services provided by the connected Tuxedo application.

Multi-Gateway Connection

The CRM offers a single point of contact - that is, a single listener socket (identified by host IP address and port number) to which components (such as SNA Gateways) can address their connection requests. Each new connection request is handed off to a server socket dedicated to servicing that component connection.

The CRM attaches significance to the following component connect/disconnect scenarios:

First Tuxedo SNA Gateway Connection

The first (or only) Gateway to connect to the CRM, the CRM accepts configuration information from the GWSNAX to initialize the VTAM interface and to establish links with mainframe systems, such as CICS and IMS.

When CRM configuration is complete, the GWSNAX receives a response indicating that the CRM is ready to begin processing requests.

Subsequent Tuxedo SNA Gateway Connections

If the client is a Tuxedo SNA Gateway and there are other Gateways currently connected to the CRM, the GWSNAX bypass the configuration upload operation. In this case, the first Tuxedo SNA Gateway client has already supplied the CRM configuration information and configuration information is not required.

Multi-Gateway Shutdown

Oracle Tuxedo SNA gateway provides support for the following orderly disconnection and shutdown procedures.

Shutdown Processing (All Gateways Except the Last)

During shutdown, a Gateway disconnects (closes the socket connection), Phase 1 shutdown processing is initiated for that connection only. Phase 1 shutdown is a "shutdown pending" state in which the following is true:

Sends and receives in progress are permitted to complete.
In-flight transactions are aborted.

The CRM will not proceed to Phase 2 shutdown processing if other Gateways are still connected. Links to mainframe systems will remain active and the CRM will continue normal processing for other connected Gateways.

Shutdown Processing (Last Gateway)

When the last (or only) Gateway requests shutdown or closes its connection with the CRM, the CRM executes Phase 1 shutdown processing for that Gateway as described in Shutdown Processing (All Gateways Except the Last). However, when Phase 1 shutdown processing is complete, the CRM proceeds to Phase 2 shutdown processing, in which the following occurs:

Links to mainframe systems are stopped.
The current configuration is discarded.
The CRM returns to a "reset" state pending connection by another client.

Load Balancing for Inbound Request

TMA SNA adapter takes advantage of the load balancing features to dispatch a request from mainframe to current active SNA gateways that are connecting to CRM. The request from mainframe to GWSNAX is always load balanced via round-robin method

Transaction Affinity

When a request from mainframe to a GWSNAX(s) invoking at a transaction context, then this request is always be dispatched into same GWSNAX until the transaction is aborted or committed.

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

Table 3-3 crmlkon Command Options
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 3-4 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 TUXEDO MAINFRAME *
//*  ADAPTER FOR SNA 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:

Table 3-4 crmlkoff Command Options
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 3-5 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 TUXEDO MAINFRAME *
//*  ADAPTER FOR SNA 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:

Table 3-5 CRMLOGS Command Options
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 3-6 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 TMA SNA 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 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 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:

Table 3-6 crmdown Command Options
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 3-7 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=*

//