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

BEA WebLogic Java Adapter for Mainframe (JAM) is configured with the JCRMGW configuration file. Configuration parameters define remote domains, the SNACRM, Local LU and SNA stack library, SNA links, and local and remote services.

JAM may be administered through the JAM Administration Servlet, which allows you to start and stop the gateway through a graphical user interface.

The following topics provide instructions and information for configuring and administering JAM:

• General Steps for Defining the Gateway Configuration

• About the JCRMGW Configuration File

• JCRMGW Configuration File Sections

• Sample Configuration File

• Special Configuration Considerations for WebLogic Server 6.0

• Post Configuration Requirements

• JAM Administration Servlet

Whether you are defining a new gateway configuration or modifying an existing one, both processes are similar. Defining a gateway configuration requires the following steps:

1. Determine which keyword information needs to be used to define the gateway as appropriate for your system configuration.

2. Create or edit the jcrmgw.cfg file with the gateway information.

   Note: Refer to About the JCRMGW Configuration File and its sub-sections for detailed information about the keywords you need to define in your configuration file.

3. If you are running JAM with WebLogic Server 6.0, there are several other configuration tasks you must complete:

   If you use the default startup script for WebLogic Server 6.0, you must make sure the jcrmgw.cfg file is located in the directory where WebLogic Server 6.0 is installed.

   Note: Refer to Locating the Gateway Configuration File for more information.

   You must add the JAM startup class to the WebLogic Server configuration file, config.xml.

   Note: Refer to Adding the JAM Startup Class to the WebLogic Server Configuration File for more information.

After you perform these steps, you are ready to start the WebLogic Server and verify that the gateway is ready. Refer to Post Configuration Requirements for more information about verifying that the gateway is ready.

The JAM Gateway, JCRMGW, uses the jcrmgw.cfg file to control much of its operation. The JCRMGW configuration file defines the SNACRM, stack (if required), links, and local and remote services that comprise the gateway environment. This file must be created and located in the WebLogic installation directory. A sample jcrmgw.cfg file is located in the JAM examples/sample.jar referred to in the BEA WebLogic Java Adapter for Mainframe Installation Guide.

The general format of the jcrmgw.cfg configuration file is as follows:

• The file is made up of six sections containing parameters. Lines beginning with an asterisk (*) indicate the beginning of a specific section. Each such line contains the name of the section immediately following the *. The following sections are defined:

  • JC_REMOTE_DOMAINS Section

  • JC_SNACRM Section

  • JC_SNASTACKS Section

  • JC_SNALINKS Section

  • JC_LOCAL_SERVICES Section

  • JC_REMOTE_SERVICES Section

• Parameters are generally specified by: KEYWORD = value. This sets KEYWORD to value. Valid keywords are described in the following sections. KEYWORDS are reserved. They cannot be used as values unless they are quoted.

• Input fields are separated by at least one space (or tab) character.

• "#" introduces a comment. A new line ends a comment.

• Blank lines and comments are ignored.

• Comments can be freely attached to the end of any line.

The following sections describe the significant keywords within specific sections of the jcrmgw.cfg file that define new gateway configurations.

This section of the jcrmgw.cfg file provides an alias for associating mainframe applications with services and links. Any given entry in this section must be named. A name is provided by using a label on any one of the keywords that comprise the entry. Code examples will use a label on the first keyword of a given entry.

Following is a list of valid keywords for the JC_REMOTE_DOMAINS section:

Keyword	Required/Optional	Description
DOMAINID	Required	Name of a partner system

Keyword Definitions

Following is more detailed information about the JC_REMOTE_DOMAINS section keyword:

     DOMAINID=<string>

<string> is any name to be used for identifying a partner system. This keyword/value pair is required and has no default value.

Following is an example.

CRCICS1 DOMAINID="TestCICS"

This section of the jcrmgw.cfg file identifies the SNACRM that this gateway talks to. There is one SNACRM for each JCRMGW. Any given entry in this section must be named. A name is provided by using a label on any one of the keywords that comprise the entry. Code examples will use a label on the first keyword of a given entry.

Following is a list of valid keywords for the JC_SNACRM section:

Keyword	Required/Optional	Description
GROUP	Required	Name of group correlating gateway with SNACRM
SNACRMADDR	Required	Symbolic TCP address

Keyword Definitions

Following is more detailed information about the JC_REMOTE_DOMAINS section keywords:

     GROUP=<string>

<string> is any name to be used to correlate a gateway with a SNACRM. The name is used as part of the file name for the SNACRM logs. In the case of a SNACRM that is started independently of the gateway, this name must match the group name used on the SNACRM command line, even if the default name is used. The keyword/value pair is optional and has a default value of "SNAGROUP".

The following listing contains an example.

GROUP="CRAUTH"

The SNACRM expects a gateway signon for group CRAUTH.

     SNACRMADDR=<string>

<string> is a symbolic TCP address in the form of: "//hostname:port"

Host name is the name of the machine that runs the SNACRM. Port is an unused decimal port number that the SNACRM uses to talk to the Java gateway. In the case of a SNACRM that is started independently of the gateway, this address must match the address used on the SNACRM command line. When the gateway is started, it tries to contact the SNACRM at the address.

The following listing contains an example.

MYSNACRM SNACRMADDR="//dalhp55:6942"

The gateway will look for a SNACRM on a machine named dalhp55 at port 6942.

This section of the jcrmgw.cfg file identifies the Local LU used for the SNACRM along with the stack identifier for the SNA stack library to be used. Only one local LU and one stack can be specified for a SNACRM. Any given entry in this section must be named. A name is provided by using a label on any one of the keywords that comprise the entry. Code examples will use a label on the first keyword of a given entry.

Following is a list of valid keywords for the JC_SNASTACKS section:

Keyword	Required/Optional	Description
LOCALLU	Required	Alias of local LU to be used with SNACRM
STACKTYPE	Required	Name of SNA stack support library to load

Keyword Definitions

Following is more detailed information about the JC_SNASTACKS section keywords:

     LOCALLU=<string>

<string> is an alias for the local LU to be used by the SNACRM. This must match a corresponding LU alias defined in the SNA Stack configuration. This alias may or may not match the actual LU name. This keyword/value pair is required and has no default value.

The following listing contains an example.

LOCALLU="AUTHAPP"

The SNACRM tries to use the local LU which has been defined in the SNA stack configuration with an alias of AUTHAPP.

     STACKTYPE=[ hp60 | ibm50 | ibm60 | ms40 | spx60 | sun91 | vtm28 ]

One of the specified tokens must be used. These names determine which SNA stack support library will be loaded.

The following stacks can be identified:

- hp60 = Hewlett Packard SNA 2 Plus 6.0 on HP-UX

- ibm50 = IBM Communications server 5.0 on WINNT or AIX

- ibm60 = IBM Communications server 6.0 on WINNT

- ms40 = Microsoft SNA Server 4.0 SP3 on WINNT

- spx60 = Data Connection Snapix 6.0 on Solaris

- sun91 = Sunlink 9.1 on Solaris

- vtm28 = VTM28 OpenEdition on MVS OS/390

This keyword/value pair is required and has no default value.

The following listing contains an example.

ibmcsaix STACKTYPE="ibm50"

The SNACRM loads the library for IBM Communication Server 5.0.

This section of the jcrmgw.cfg file identifies partner mainframe application regions. Multiple links for a single SNACRM are supported. Any given entry in this section must be named. A name is provided by using a label on any one of the keywords that comprise the entry. Code examples will use a label on the first keyword of a given entry.

Following is a list of valid keywords for the JC_SNALINKS section:

Keyword	Required/Optional	Description
MAXSESS	Optional	Maximum number of SNA sessions that can be started for a link
MINWIN	Optional	Minimum number of SNA sessions that will be contention winners
MODENAME	Required	Name of mode definition
RDOM	Required	Name of remote domain
RLUNAME	Required	Alias for remote LU
SECURITY	Optional	Indicates level of security

Keyword Definitions

Following is more detailed information about the JC_SNALINKS section keywords:

     MAXSESS=nn (4)

nn is the maximum number of SNA sessions that can be started for this link. The actual value used is negotiated with the partner and can be lower than this value if the partner is configured with a lower value. This value includes two sessions for the SNA Service manager mode. The lowest usable value is 4; it provides two sessions for the application and two sessions for the service manager. This keyword/value pair is optional and has a default value of 4.

The following listing contains an example.

MAXSESS=16

The maximum number of sessions on this link is set to 16 for all modes combined.

     MINWIN=nn (MAXSESS/2)

nn is the minimum number of SNA sessions that will be contention winners for the SNACRM. This keyword is not required and defaults to one half the number of MAXSESS. In most cases this is suitable unless asymmetric winners are desired due to application requirements. Also, the default value may not be appropriate if the maximum is negotiated down to a value lower than half of the specified maximum. This value includes one session for the SNA Service Manager mode. In general, the lowest practical value is 2, which provides one session for the application and one session for the service manager. See IBM's SNA documentation for a complete discussion of session limits and contention winners. The keyword/value pair is optional and has a default value of half the value of MAXSESS.

The following listing contains an example.

MINWIN=8

The number of contention winner sessions on this link is set to 8 for all modes combined.

     MODENAME=<string>

<string> is the name of a mode definition to be used for applications on this link. This must match a corresponding mode name defined in the SNA Stack configuration and the VTAM mode table. A valid mode name is provided by mainframe support personnel. This keyword/value pair is required and has no default value.

The following listing contains an example

MODENAME="SMSNA100"

The SNACRM will use the SMSNA100 mode for applications on this link.

     RDOM=<string>

<string> is a name previously defined as a remote domain. The remote domain naming is a mechanism for grouping links. This keyword/value pair is required and has no default value.

The following listing contains an example.

RDOM="CRCICS1"

This link is associated with the remote domain named CRCICS1.

     RLUNAME=<string>

<string> is an alias for the remote LU representing the partner application to be used by the SNACRM. This must match a corresponding partner/remote LU alias defined in the SNA Stack configuration. This alias may or may not match the actual remote LU name. This keyword/value pair is required and has no default value.

The following listing contains an example.

RLUNAME="AUTHAPPL"

The SNACRM routes all traffic for this link to a remote application defined with an alias of AUTHAPPL. This alias must be defined in the SNA stack configuration for a valid mainframe application name.

     SECURITY=[LOCAL | IDENTITY | VERIFY] (LOCAL)

This is an optional keyword. If entered, one of the specified tokens must be used, and the mainframe connection be configured to match.

The meaning of the values are:

LOCAL = All security is handled by the local system and the link itself has no security requirement.

IDENTIFY = A userid will be passed on to the mainframe. This userid can originate with the client application or it can be a default userid supplied with the -u option on the gateway startup.

VERIFY = A userid and password will be passed onto the mainframe. The userid can originate with the client application or it can be a default userid supplied with the -u option on the gateway startup. The password must be supplied by the client application.

This keyword/value pair is optional and has a default value of LOCAL.

Refer to Security, for more information about security options.

The following listing contains an example.

SECURITY=IDENTIFY

A userid is required for all requests made on this link. Note that the mainframe configuration for the remote LU (i.e., a CICS connection definition) must have a security level that matches.

This section of the jcrmgw.cfg file maps incoming mainframe program names to a Home interface for an EJB that will service the request. Any given entry in this section must be named. A name is provided by using a label on any one of the keywords that comprise the entry. Code examples will use a label on the first keyword of a given entry.

Following is a list of valid keywords for the JC_LOCAL_SERVICES section:

Keyword	Required/Optional	Description
RNAME	Required	Name of remote resource associated with a service
SCHEMA	Required for use with WebLogic Process Integrator	Identifies the generated dataview.

Keyword Definitions

Following is more detailed information about the JC_LOCAL_SERVICES section keyword:

     RNAME=<RRRRRRR>

RNAME is the remote resource name associated with this service. For a CICS Distributed Program Link, this is the actual program name that was invoked from the mainframe. For a DTP style request, the resource name must conform to the TP ID requirements of the originating system. A CICS DPL Program and an IMS Transaction ID are limited to eight characters.

The label on this entry must be the name of a valid home interface for an Enterprise Java Bean registered with JNDI. This keyword/value pair is required and has no default value.

The following listing contains an example.

StatelessSession.TraderHome RNAME="DPL1SVR"

DPL1SVR is the name of the program that was invoked from the mainframe and StatelessSessions.TraderHome is the name of the home interface which will be used to invoke the EJB that will service this request.

     SCHEMA=<string>

This keyword is used to identify the generated dataview for use in decoding or encoding data streams. SCHEMA is used by the JAMTOJMS or AppView EJB's when integrating with WebLogic Process Integrator.

This section of the jcrmgw.cfg file maps remote mainframe program names to method names that can be used by a local application to invoke the remote request. Any given entry in this section must be named. A name is provided by using a label on any one of the keywords that comprise the entry. Code examples will use a label on the first keyword of a given entry.

Following is a list of valid keywords for the JC_REMOTE_SERVICES section:

Keyword	Required/Optional	Description
FUNCTION	Optional	Method of request invocation accepted by the mainframe
RDOM	Required	Name of remote domain
RNAME	Required	Remote resource name associated with a service
SCHEMA	Required for use with WebLogic Process Integrator	Identifies the generated dataview.
TRANTIME	Optional	Maximum number of milliseconds client will allow for a host request to respond

Keyword Definitions

Following is more detailed information about the JC_REMOTE_SERVICES section keywords:

     FUNCTION=[DTP | DPL] (DPL)

This is an optional keyword used to indicate the method of request invocation accepted by the mainframe. DPL is the default and is only valid when used with a CICS partner and an application that can be invoked using a Distributed Program Link. DTP should be used when invoking services from an IMS server.

This keyword/value pair is optional and has a default value of DPL.

The following listing contains an example.

FUNCTION=DTP

This remote service will be invoked as an IMS application rather than a program link.

     RDOM=<string>

<string> is a name previously defined as a remote domain. This keyword/value pair is required and has no default value.

The following listing contains an example

RDOM="CRCICS1"

This service will be associated with the remote domain named CRCICS1.

     RNAME=<[MMMM:]RRRRRRRR>

Rname is the remote resource name associated with this service. For a CICS Distributed Program Link, this is the actual program name to be invoked. The first portion of this value (MMMM:) is optional and can be an alternate mirror transaction identifier. An alternate mirror transaction is useful for some mainframe database deployments as well as security or charge back systems. The alternate mirror transaction cannot exceed 4 characters in length. The second portion (RRRRRRRR) is the program name to invoke for a CICS DPL. For a DTP style request, the resource name must conform to the Tran ID requirements of IMS.

The following listing contains an example.

RNAME="AUTH:DPLQRY"

This Rname is a program named DPLQRY and will use an alternate mirror transaction name of AUTH.

     SCHEMA=<string>

This keyword is used to identify the generated dataview for use in decoding or encoding data streams. SCHEMA is used by the JAMToJMS or AppView EJB's when integrating with WebLogic Process Integrator.

     TRANTIME=nnn (30000)

nnn is the maximum number of milliseconds the client application will block before a host request is timed out. This keyword/value pair is optional and has a default value of 30000.

The following listing contains an example.

TRANTIME=120000.

This remote service will time out if the mainframe does not respond within 2 minutes (120 seconds).

The following example illustrates a basic jcrmgw.cfg file.

*JC_REMOTE_DOMAINS
#
CICS410		DOMAINID="410"
#
*JC_SNACRM
#
SNACRMAN		SNACRMADDR="//dalnt66:8650"
		GROUP="SNAG1"

*JC_SNASTACKS
#
IBMCSAIX		STACKTYPE="IBM50"
		LOCALLU="LUNT66B"
#
*JC_SNALINKS
#
C41XB01		RLUNAME="C410XB01"
		RDOM="CICS410"	
		MODENAME="SMSNA100"
		MAXSESS=8
		MINWIN=6
#
*JC_LOCAL_SERVICES
#
TraderHome		RNAME="DPL1SVR"
#
JC_REMOTE_SERVICES
DPLINIT		RDOM="CICS410"
		RNAME="PRIM:DPLINIT"
		TRANTIME=10000
TOUPPER		RDOM="CICS410"
		RNAME="TOUPDPLS"
		TRANTIME=10000
demoRead		RDOM="CICS410"
		RNAME="DPLDEMOR"
		TRANTIME=10000
demoUpdate		RDOM="CICS410"
		RNAME="DPLDEMOU"
		TRANTIME=10000
demoCreate		RDOM="CICS410"
		RNAME="DPLDEMOC"
		TRANTIME=10000
demoDelete		RDOM="CICS410"
		RNAME="DPLEMOD"
		TRANTIME=10000

imsInsert		RDOM="IMS51"
		FUNCTION=DTP
		RNAME="IMSSVR12"

If you are running JAM with WebLogic Server 6.0,you must make sure the jcrmgw.cfg file is available to the default startup script for WebLogic Server 6.0 and you must add the JAM startup class to the WebLogic Server configuration file.

WebLogic Server 6.0 supports multiple configured domains. The locations of the XML files that comprise the configuration are kept in the following location:

<bea_home>/<wls_install>/config/<domain_name>

If you use the default startup script for WebLogic Server 6.0, startWebLogic, the jcrmgw.cfg file must be located in the installation directory from which WebLogic Server is started. This script is located in the following installation directory:

<bea_home>/<wls_install>/

The JAM Startup Class, com.bea.sna.jcrmgw.gwboot, must be added to the WebLogic Server 6.0 configuration file called config.xml before you start JAM. Refer to the BEA WebLogic Server Administration Guide at http://download.oracle.com/docs/cd/E13222_01/wls/docs60/adminguide/index.html for detailed information about administration of the WebLogic Server. Specific instructions for adding a Startup Class to the configuration can be found at http://download.oracle.com/docs/cd/E13222_01/wls/docs60/ConsoleHelp/startupclass.html.

XML similar to the following for specifying the JAM Startup Class, com.bea.sna.jcrmgw.gwboot,should be added to the WebLogic Server 6.0 config.xml file:

<StartupClass
      Arguments="-r -noexit"
      ClassName="com.bea.sna.jcrmgw.gwboot"
      Name="jcrmgw"
      Targets="myserver"
    />

This XML illustrates a gateway using a remote SNACRM through the "-r" argument as well as making use of a JAM 4.1.1 -noexit feature that prevents the WebLogic Server from exiting when the gateway ends.

For WebLogic Server 5.1, the corresponding weblogic.properties entry is as follows:

weblogic.system.startupClass.jcrmgw=com.bea.sna.jcrmgw.gwboot
weblogic.system.startupArgs.jcrmgw=-r -noexit

The essential elements remain the same for WebLogic Server 5.1 and WebLogic Server 6.0, although the actual syntax for WebLogic Server 6.0 is now XML.

The XML code as illustrated in Listing 3-2 can be manually added to the config.xml file located in BEA/HOME/config/yourdomain, or it can be added through the WebLogic Server 6.0 Administration Console as shown in Figure 3-1.

You can click the jcrmgw link to display detail about the class as shown in Figure 3-2.

Notice that the -noexit argument is used and the Abort startup on failure option is not selected.

Start WebLogic Server and verify that the SnacTask Startup Complete message indicates the gateway is ready. You can also confirm that the CICS connection is acquired by using the CICS CEMT I CON (*) command to verify that your connection is in the ACQuired state, indicating the link is ready for use.

The JAM Administration Servlet allows you to stop or start the JAM gateway through a graphical interface that displays in your Web browser. Following is an example of the JAM Administration Servlet window:

Before you start the JCRMGW gateway, you must configure the servlet by adding an entry to the weblogic.properties file if you are using WebLogic Server 5.1 or the web.xml file if you are using WebLogic Server 6.0.. Then you can display the JAM Administration Servlet window in your browser; if required, select several options for starting JAM; and click a command button to start or stop JAM.

To configure the JAM Administration Servlet, add the following entry to the weblogic.properties file:

weblogic.httpd.register.jamAdmin=com.bea.sna.jcrmgw.JamAdmin

Note: This entry is case sensitive. If you are planning to start and stop the gateway without restarting WebLogic Server, you should consider specifying the -noexit option in the weblogic.system.startupArgs.jcrmgw property.

For example, use the following command:

weblogic.system.startupArgs.jcrmgw=-r -noexit

To configure the JAM Adminstration Servlet, modify the web.xml file located in the config/mydomain/application/DefaultWebApp_myserver/WEB-INF/ directory of your WebLogic Server installation. After modification, your web.xml file should look similar to the example shown in Listing 3-4. The lines marked in bold should be added to your existing file. Your file might also contain other entries not related to JAM.

<?xml version="1.0" ?>
<!DOCTYPE web-app (View Source for full doctype...)>
<web-app>
    <servlet>
        <servlet-name>JamAdmin</servlet-name>
        <servlet-class>com.bea.sna.jcrmgw.JamAdmin</servlet-class>
    </servlet>
    <servlet-mapping>
        <servlet-name>JamAdmin</servlet-name>
        <url-pattern>JamAdmin</url-pattern>
    </servlet-mapping>
</web-app>

To bring the JAM Administration Servlet up in a browser window, enter the following URL:

http://<host>:<port>/jamAdmin

In this example, <host> and <port> specify the WebLogic listen address.

You may set several boot options to be used when the JCRMGW gateway is started from the JAM Administration Servlet window. These options correspond to options used with the GWBOOT command. For more detailed information about the GWBOOT options, refer to the "Configuration Checker Utility" section in the BEA WebLogic Java Adapter for Mainframe User Guide.

The following options may be set in the JAM Administration Servlet window before you start the JCRMGW gateway:

Option	Corresponding GWBOOT Option	Description
Trace on	-t	Turns on level 3 CRM tracing
Remote CRM	-r	Specifies a remote CRM
Default user	-u <name>	Specifies a user ID

Note that when the servlet is started, the options selected, Trace on, Remote CRM, and Default user, reflect what is contained in the weblogic.system.startupArgs.jcrmgw property in the weblogic.properties file.

The following command buttons on the JAM Administration Servlet window allow you to start or stop JAM:

Command Button	Description
Start	Initializes the gateway with the specified options. The message 'JAM has been successfully started' appears if the operation succeeds.
Stop	Stops the gateway if it is currently running. The message 'JAM has been successfully stopped' appears if the operation succeeds.