Corporate Info  |  News  |  Solutions  |  Products  |  Partners  |  Services  |  Events  |  Download  |  How To Buy
	http://www.oracle.com/technology/documentation/index.html   |   Search   |   PDF Files   |   Contact   |
eLink Adapter for Mainframe Doc Home   |   CRM Administration Guide   |   Previous Topic   |   Next Topic   |   Contents   |   Index

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

The interface to the stack administration and configuration is dependent on the stack provider and thus cannot be 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 on UNIX or Windows NT

• Starting the CRM on OS/390 MVS

• Using the CRM Monitor

• Setting CRM and Stack Traces

• Activating and De-Activating Links

• Stopping the CRM on OS/390

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 eAM gateway (GWSNAX).

To ensure proper start up of the CRM, complete the following tasks:

1. Set the following environment variables in the environment where the CRM is started:

   FIEDLTBLS32 must contain fmb.def

   FLDTBLDIR32 must contain the path to the eAM libraries directory

   APPDIR must be set 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.

   • To start the CRM on UNIX:

     Enter the SNACRM command on the command line.

     Refer to Appendix A, Command Reference Pages for more detailed information about the SNACRM command.

     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.

   • To start the CRM from a Command Prompt Window on Windows NT:

   1. Open a Command Prompt window.

   2. Navigate to the drive where the CRM executable is installed.

   3. Enter SNACRM to start SNACRM.exe.

      On Windows NT, the CRM can be started in its own window; however, no prompt is displayed and no console commands are available. Refer to Command Reference Pages, for more detailed information about the SNACRM command.

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

   FLDTBLDIR32=DD:FLDTBL
   FIELDTBLS32=FMB
   APPDIR=<High level qualifier for datasets to be created in APPDIR>

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

   Refer to Sample JCL for the SNACRM Command and Command Reference Pages, for more information about sample SNACRM JCL and the SNACRM command.

   Note: If the CRM is installed on an OS/390 MVS platform, it does not have to be restarted if the eAM gateway goes down abnormally. If a tmshutdown command is issued, the CRM will shut down.

   Only the OS/390 MVS version and the OS/390 UNIX version of the CRM have this persistent feature.

You can use the CRM monitor to set trace levels for a selected CRM and the associated APPC stacks. You also can observe link activity and display trace status, link status, and link statistics.

Note: The CRM monitor does not show trace data. This data is captured in a file under the APPDIR directory (where APPDIR is the variable name associated with the application directory). Please contact BEA Customer Support for help in locating the trace files and interpreting them.

The BEA eLink for Mainframe software includes two utilities that launch and execute the SNACRM monitor. The xsnacrm utility is designed for UNIX platforms and requires Motif libraries. The jsnacrm utility is designed for Windows NT platforms and supplies both a Java-based application and an applet.

Note: The jsnacrm utility can only be run from an Windows NT platform. It must be run on a UNIX or Windows NT platform to connect to an OS/390 CRM. The xsnacrm utility can only be run from the UNIX and Windows NT platform.

The xsnacrm utility provides realtime monitoring of the CRM and displays information describing the activity occurring in each CRM. The xsnacrm utility should be used by administrators and system operators only. Access to this utility may be restricted by setting the execute permissions during installation. The xsnacrm utility requires Motif libraries.

To launch and execute the CRM monitor using the xsnacrm utility, perform the following steps:

1. Determine and enter the appropriate trace level:

   • 0-No tracing. Setting this level effectively disables SNACRM tracing and closes the trace file if there is one. If tracing is subsequently restarted, a new file will be created with an incremented numerical suffix.

   • 1-Minimum tracing. At this level, the SNACRM traces only major events and is sufficient only to determine the sequence of application conversations.

   • 2-Medium tracing. At this level, SNACRM also traces all I/O buffers.

   • 3-Maximum tracing. At this level, SNACRM also traces all APPC verbs.

     The APPC Protocol Stack API trace is either enabled or disabled. If 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 SNACRM to enable the trace.

2. Use address to specify the host name and port number of a CRM to monitor. This value must match the corresponding parameter on the command line used to start the CRM you wish to monitor.

   At least one address must be specified. Multiple CRMs may be monitored by specifying all their associated addresses.

   The format of an address consists of two forward slashes (//) followed by a host name or address, a colon (:) , and a service name or decimal port number (containing no spaces).

   If a host name is used, it should be an entry in the file /etc/hosts. If a host address is used, it should be specified in the format nnn.nnn.nnn.nnn where each group of nnn represents a decimal number between 1 and 255. This host should identify the computer where the CRM you wish to monitor is running, not the host where xsnacrm is to run.

   If a service name is used, it should be an entry in the file /etc/services. If a decimal port number is used, it should be a decimal number in the range 4000 - 32767. This number must match the corresponding port number on the command line used to start the CRM you want to monitor. (If the CRM was started automatically, the address is specified in the DMCONFIG file).

3. Customize X Resources. The default X Resources for xsnacrm correspond to the distributed contents of the associated file xsnacrm. To customize the application, copy the xsnacrm file to your home directory and edit it.

4. Start the xsnacrm utility by entering the following command:

   xsnacrm [<X/Motif args>] <addr> [ <addr> ...]

   In the above command, the following definitions apply:

   <addr>

   The INET address of a CRM to monitor and <addr> is specified as either 0xHHHHHHHHHHHHHHHH or //<host>:<port>

   <host>

   Either a host name or an INET host address (e.g. 204.29.36.44) and

   <port>

   A service name or a decimal port number.

Figure 3-1 illustrates the xsnacrm screen.

Using the CRM Monitor and the jsnacrm Utility

The jsnacrm utility is written in Java as both an application and an applet. The application launches and executes like any other Java application and can be set up so it is accessible from the Windows desktop. The applet launches and executes from a network browser.

The BEA eLink Java Adapter for Mainframe software CD-ROM contains the following files associated with the jsnacrm utility:

• bealogo.gif

• jsnacrm.html

• jsnacrm.jar

• moncrm.jar

• moncrm.x509

Running the Java Applet Version

The following sections describe how to set up and run the Java applet version of the jsnacrm utility.

To run the Java applet version, you must complete the following tasks:

1. Verify that either Netscape Communicator 4.x or Internet Explorer 4.x or 5.x is installed on your Windows NT system.

2. Verify that the Java plug-in is installed on your system. You can download this plug-in from the following internet location:

   http://java.sun.com/products/plugin

   Note: If the Java plug-in is not already installed on your system when you attempt to open the jsnacrm.html file, the program prompts you for an automatic download of the plug-in by the browser.

3. Set your system to accept code signed by the identity, moncrm. To do this, perform the following steps:

   1. Create the moncrm identity in your JDK 1.2.2 identity database. Enter the parameter true to establish moncrm as a trusted identity.

      javakey -c moncrm true

   2. Import the moncrm certificate into your identity database. To associate the certificate with the identity, use the nickname moncrm as the first argument to the javakey command.

      javakey -ic moncrm %TUXDIR%\bin\moncrm.x509

To start the Java applet in an existing browser, open the file:

<tuxedo-path>\bin\jsnacrm.html

To build a shortcut to start the Java applet using a separate instance of your network browser, enter the following command:

<browser-pathname> %TUXDIR%\bin\jsnacrm.html

To run the Java applet version, perform the following tasks:

1. Set your applet version to monitor either a local or remote CRM by making selections on the Java Plug-in Properties control panel. This control panel is automatically downloaded with the plug-in and is initiated from the Windows Start Programs pop-up menu. Refer to online documentation about the control panel at the following Internet location:

   http://java.sun.com/products/plugin/1.1.1/docs

2. Enter the address of the CRM that you want to monitor in the field at the top of the screen when the Monitor screen displays (See Figure 3-2).

   1. To monitor a local CRM, select Applet Host from the Network Access drop-down menu. Type the following address in the Enter CRM Address panel:

      //localhost:port

      The following definitions apply to this address:

      localhost explicitly specifies the local host.

      port specifies the port number of the CRM on the local host.

   2. To monitor a remote CRM, select Unrestricted from the Network Access drop down menu. Type the following address in the Enter CRM Address panel:

      //remotehostname:address

      The following definitions apply to this address:

      remotehostname specifies the remote host.

      address specifies the network address of the CRM on the remote host.

The CRM Monitor contains two screen areas that require user entry and four screen areas that display information about the CRM being monitored. Status messages are displayed at the bottom of the screen. The screen functions are listed in Table 3-1 and shown in Figure 3-2.

Table 3-1 CRM Monitor Screen Functions

Display Section	Function
CRM Address	Enter the address of the CRM to be monitored.
Selected CRM	Displays the name of the CRM at the address entered in the address field.
Trace Status	Displays the currently selected trace options.
Trace Options	Stop CRM Trace disables CRM tracing and closes the trace file, if it exists. Set Minimum CRM Trace establishes tracing of only major events. This level is sufficient only to determine the sequence of application conversations. Set Medium CRM Trace establishes minimum tracing plus tracing of all I/O buffers. Set Maximum CRM Trace establishes medium tracing plus tracing of all APPC verbs. Start APPC Stack Trace establishes tracing of the APPC stack. 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. May be selected along with any of the previous Trace Options. Stop APPC Stack Trace disables APPC stack trace, if established.
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.

Figure 3-2 The CRM Monitor Running as an Applet on a Network Browser

Running the Java Application Version

The Java application version displays and operates identically to the applet version. Refer to screen definitions and functions discussed under "Running the Java Applet Version."

To build a shortcut for starting the Java application version, perform the following steps:

1. Enter the command:

   jrew -classpath %ClassPath%;jsnacrm.jar jsnacrm

2. Start the application in the directory %TUXDIR%\bin so it can find its files.

To run from a command window, perform the following steps:

1. Change directory to %TUXDIR%\bin.

2. Enter the command:

   jrew -classpath %ClassPath%;jsnacrm.jar jsnacrm

Trace capabilities are provided for the CRM process. To initiate stack tracing, include the -t option for the SNACRM command with a number to specify the level of tracing. Refer to Trace Options for the SNACRM command in Appendix A, Command Reference Pages.

The APPC Stack API trace is either enabled or disabled using the -s option of the SNACRM command. Refer to General Options for the SNACRM command in Appendix A, Command Reference Pages. When enabled, the trace 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 SNACRM to enable the trace. Consult the vendor publications for instructions on how to set up stack tracing.

Note: On OS/390 platforms, the General Trace Facility (GFT) 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.

The eAM gateway provides a command line tool to activate and de-activate links that have been defined in the DM_SNALINKS section of the dmconfig file. This tool consists of two commands and their associated parameters:

• crmlkon

  Start one or more SNA links with this command.

  • To activate the SNA links on UNIX or Windows NT, use the following syntax:
    crmlkon -n<hostname:port> [-v -i -h] <linkname> ...

    Refer to crmlkon in Appendix A, "Command Reference Pages" for more information on the crmlkon command.

  • To activate the SNA links on OS/390 MVS:

    Run a CRMLKON job using JCL written explicitly for your system. Refer to "Sample JCL for CRMLKON Command" and Appendix A, "Command Reference Pages" for more information about sample CRMLKON JCL and the crmlkon command.

    Note: You will not receive notification that the link(s) started with the crmlkon command are activated. Use the CRM monitor to verify a link is active. Refer to Using the CRM Monitor for more information.

• crmlkoff

  Stop one or more SNA links with this command.

  • To de-activate the SNA links on UNIX or Windows NT, use the following syntax:

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

    Refer to crmlkoff in Appendix A, "Command Reference Pages" for more information on the crmlkoff command.

  • To de-activate the SNA links on OS/390 MVS:

    Run a CRMLKOFF job using JCL written explicitly for your system. Refer to "Sample JCL for CRMLKOFF Command" and Appendix A, "Command Reference Pages" for more information about sample CRMLKOFF JCL and the crmlkoff command.

    Note: You will not receive notification that the links stopped with the crmlkoff command are de-activated. Use the CRM monitor to verify that a link is not active. Refer to Using the CRM Monitor for more information.

If a link to a remote host is deactivated and reactivated by the host, the eAM software normally re-establishes the link automatically. If this does not occur, use the crmlkon command to re-establish the link.

If the eAM gateway terminates abnormally, the persistent CRM feature allows the OS/390 CRM to continue running. (A tmshutdown command is considered a normal termination.) You must explicitly shutdown the CRM if the eAM gateway has terminated abnormally and the CRM needs to be stopped.

• To stop the CRM from a UNIX or Windows NT system:

  Enter the crmdown command on the command line. Refer to crmdown in Appendix A, "Command Reference Pages" for more detailed information about the crmdown command.

• To stop the CRM from OS/390 MVS:

  Run a CRMDOWN job using JCL written explicitly for your system. Refer to "Sample JCL for CRMDOWN Command" and Appendix A, "Command Reference Pages" for more information about sample CRMDOWN JCL and the crmdown command.

If the eAM gateway terminates abnormally, the persistent CRM feature allows the OS/390 MVS CRM to continue running. You must explicitly shutdown the CRM if you need to shut it down. The OS/390 MVS platform stops the CRM through the crmdown JCL.