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 Linux/Unix 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
  
• Command Line Options
  
• Environment Variables
  
• Examples
  
• Diagnostics
  

The z/OS 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.

• Sample JCL for the CRM Command
  

On this side, do the following:

1. For each CRM, define its configuration name and location by adding the following command lines:

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

2. Create dataset member (CFG) for each CRM, and set LINK and STACK parameters. The following table lists all available parameters for CRM configuration; the following Listing is a sample for CRM configuration.

Listing 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 JCL Sample for CRM Command (Separate CRM Configurations on Mainframe)

//***************************************************************
//* THIS JOB IS USED TO RUN THE CRM PROCESS.                            *
//*                                                                     *
//* Copyright (c)2023 ORACLE 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 
// 

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 in the Configuring the Oracle Tuxedo Mainframe Adapter for SNA Gateway.

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

The following figure 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 Oracle 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.

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

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.

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

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.

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> -S <ssl_config_file> -N <type>:<min>:<max>] <linkname>
      ...

Descriptions of the command line options follow.

• Command Line Options
  
• Example
  
• Diagnostics
  
• Sample JCL for the crmlkon 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> -S <ssl_config_file> -N <type>:<min>:<max>] <linkname>
      ...

• Command Line Options
  
• Example
  
• Diagnostics
  
• Sample JCL for the crmlkoff 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
  
• Example
  
• Diagnostics
  
• Sample JCL for the CRMLOGS 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.

crmdown -n <hostname:port> [-v -i -h -u <keyfile> -S <ssl_config_file> -N <type>:<min>:<max>]

• Command Line Options
  
• Example
  
• Diagnostics
  
• Sample JCL for the CRMDOWN Command