5. Administering the Application Domain

The topics in this section cover activities an administrator performs to maintain BEA eLink for Mainframe SNA applications. More details about these activities can be found in BEA TUXEDO documentation. Before attempting the activities, it is essential that you become familiar with BEA TUXEDO configuration procedures.

This section covers the following administration topics:

• Administration Facilities

Administration Facilities

The administrative interface for eLink SNA software has two components:

• The interface to the eLink SNA stack administration and configuration, which 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.

• The interface to the administration and configuration of the BEA TUXEDO System portion of an eLink SNA application, which is provided by the command dmadmin, other shell-level commands, and by screens of the BEA TUXEDO Graphical Administrative Interface.

This subsection covers the following topics:

• The dmadmin Command Interpreter

• The SNACRM and PU 2.1 Servers

• The SNACRM Monitor

• Activating and De-Activating Links

The dmadmin Command Interpreter

The dmadmin interactive command interpreter is used for the administration of domain gateway groups defined for a BEA TUXEDO System/T application. It can operate in two modes, administration mode and configuration mode. Configuration mode allows you to change a configuration while the application is running. The dmadmin description in Appendix A, "Reference Pages," of this guide has been edited to include material and new subcommands that apply specifically to the eLink SNA gateway.

Note: The following four dmadmin commands are not applicable to eLink SNA because transactions, in the BEA TUXEDO System sense, are not supported:

• dsdmlog

• forgettrans

• indmlog

• printtrans

New subcommands have been added to dmadmin to support the entry of userids and passwords in the domain security table. These new commands can be entered only as subcommands of dmadmin:

• addumap [ options ]

• addusr (addu) [ options ]

• delumap [ options ]

• delusr (delu) [ options ]

• modusr (modu) [ options ]

The reference pages for these subcommands and other /Domain commands have been modified for the eLink SNA product. Use Appendix A, "Reference Pages," in preference to similar pages in the BEA TUXEDO Reference Manual.

The SNACRM and PU 2.1 Servers

The SNA Communications Resource Manager (SNACRM) is a server that communicates directly with the PU 2.1 server to provide SNA connectivity. These servers can be started manually or via the DMINIT server. In either case, the PU 2.1 server must always be started before the SNACRM. Both servers must be started before starting the associated SNA Domain gateway.

Starting the PU2.1 Server

Please refer to SNACRM in Appendix A, "Reference Pages," of this guide for information about starting the PU2.1 server.

Starting the SNACRM

You can manually start the SNACRM from the command line or during tmboot with the DMINIT server. Before starting the SNACRM, you should specify it as a BEA TUXEDO server (refer to "Specifying the SNACRM as a BEA TUXEDO Server"). You can either start all SNACRM processes with a single DMINIT process or individually start each one with a DMINIT server that is defined to each gateway server group.

When you start SNACRM from the UNIX command line, the SNACRM Command Line Console puts its prompt in this window, and if exited, shuts down all of the active links. When started from DMINIT, the console is redirected to the null device. In this case, you can use the xsnacrm command to monitor the console and enable/disable tracing of SNACRM and the SNA stack.

Please refer to SNACRM in Appendix A, "Reference Pages," of this guide for more detailed information.

Using DMINIT

Please refer to SNACRM in Appendix A, "Reference Pages," of this guide for information about using DMINIT.

Specifying the SNACRM as a BEA TUXEDO Server

You should specify the SNACRM as a BEA TUXEDO server. This is recommended for all platforms because it ensures that start-up and shut-down of the SNACRM is controlled by the BEA TUXEDO commands tmboot and tmshutdown. To do this, you must enter parameters defining the SNACRM as a server in the UBBCONFIG file, then provide a script to perform the startup and shutdown of the specific group that contains the server.

Note: This is required if eLink SNA software is installed on a Windows NT platform or if it is used with the BEA TAP for IBM CICS system.

Enter the UBBCONFIG Parameters

To specify the SNACRM as a BEA TUXEDO server, provide the equivalent UBBCONFIG parameters shown in the example in Figure 5-1.

Figure 5-1 Example UBBCONFIG File Entries Specifying SNACRM as BEA TUXEDO Server

Write the Script

The executable script rstsnagrp should reside in the APPDIR and contain the following lines:

# Filename = rstsnagrp
tmshutdown -g SNAGRP
tmboot -g SNAGRP

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

Note: The SNACRM monitor does not show trace data. This data is captured in a file under the /APPDIR directory. Please contact BEA Customer Support for help in locating the trace file(s) and interpreting them.

The BEA eLink for Mainframe SNA product software includes two utilities which 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.

The following discussion relates to the Windows NT-based SNACRM monitor only. Refer to xsnacrm in Appendix A, "Reference Pages," for detailed information about the UNIX-based SNACRM monitor.

The BEA eLink for Mainframe SNA software CDROM contains the following files related to the jsnacrm utility:

• bealogo.gif

• jsnacrm.html

• jsnacrm.jar

• moncrm.jar

• moncrm.x509

Prerequisite for Running the JSNACRM Utility on an NT Platform

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, either Netscape Communicator 4.0x or Internet Explorer 4.0x.

In order to run both the application and the applet, you must first have the Java Development Kit (JDK) 1.1 installed on your system. You can download this kit from the following internet location:

http://java.sun.com/products/jdk/1.1

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

PREREQUISITES for RUNNING the JAVA APPLET VERSION

You must have either Netscape Communicator 4.0x or Internet Explorer 4.0x installed on your NT Windows system. You also must have the Java plug-in 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.

Next, you must set up your system to accept code signed by the identity "moncrm." To do this, perform the following steps:

1. Create the identity moncrm in your JDK 1.1 identity database. By entering the parameter true, you establish moncrm to be 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

Set up your applet version to monitor either a local or a remote SNACRM. To do this, you make selections on the Java(TM) 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 on-line documentation about the control panel at the following internet location:

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

Once the Monitor screen displays (Figure 5-2), you enter in the field at the top of the screen the address of the SNACRM you want to monitor.

To monitor a local SNACRM, select Applet Host from the Network access drop-down menu. Type the following in the Enter SNACRM Address panel:

//localhost:port

where:

localhost

Explicitly specifies the local host.

port

Specifies the port number of the SNACRM on the local host.

To monitor a remote SNACRM, select Unrestricted from the Network access drop down menu. Type the following in the Enter SNACRM Address panel:

//remotehostname:address

where:

remotehostname

Specifies the remote host.

address

Specifies the network address of the SNACRM on the remote host.

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

Table 5-1 SNACRM Monitor Screen Functions

Display Section	Function
SNACRM Address	This is where you enter the address of the SNACRM to be monitored.
Selected SNACRM	Displays the name of the SNACRM at the address entered in the address field.
Trace Status	Displays the currently selected trace options.
Trace Options	Stop CRM Trace disables SNACRM 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 SNACRM. (Text may be scrolled.)
Link Statistics	Displays the current statistics for all remote links for the selected SNACRM. (Text may be scrolled.)
Message Line	Displays messages showing the either the results of automatic connection attempts or commands issued to change the trace options.

Figure 5-2 The SNACRM 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 to start 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

The eLink SNA gateway software provides a command line tool you can use 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 and crmlkoff.

Note: If a link to a remote host is de-activated and re-activated by the host, the eLink SNA software normally re-establishes the link automatically. If this does not occur, you can use the crmlkon command to re-establish the link.

Using the crmlkon Command

You can start one or more SNA links with this command. Use the following syntax:

crmlkon {-n} {hostname:port} {-v} {-i} {h} {linkname}...

where:

-n

indicates that the parameters immediately following are the hostname and port of the machine running the SNACRM where the linkname is located.

hostname:port

specifies the IP host name and port of the machine running the SNACRM where the linkname is located.

-v

specifies that this command displays verbose output.

-i

causes the command to ignore errors and attempt to start all links specified on the command line.

h

invokes a help screen which shows the syntax usage for this command.

linkname

specifies the link name(s) to start.

Note: There is no notification that the link(s) started with the crmlkon command are activated. Use the SNACRM monitor to verify a link is active. Refer to "The SNACRM Monitor."

You can stop one or more SNA links with this command. Use the following syntax:

crmlkoff {-n} {hostname:port} {-v} {-I} {-h} {linkname}...

where:

-n

indicates that the parameters immediately following are the hostname and port of the machine running the SNACRM where the linkname is located. This is required.

hostname:port

specifies the IP host name and port of the machine running the SNACRM where the linkname is located.

-v

specifies that this command displays verbose output.

-I

causes the command to ignore errors and attempt to stop all links specified on the command line.

h

invokes a help screen which shows the syntax usage for this command.

linkname

specifies the link name(s) to start.

Note: There is no notification that the link(s) stopped with the crmlkoff command are de-activated. Use the SNACRM monitor to verify a link is not active. Refer to "The SNACRM Monitor."