Configuring the Java Adapter for Mainframe Environment


	Corporate Info \| News \| Solutions \| Products \| Partners \| Services \| Events \| Download \| How To Buy
	http://www.oracle.com/technology/documentation/index.html \| Search \| PDF Files \| Contact \| Glossary

BEA eLink JAM Doc Home \| BEA eLink Java Adapter for Mainframe WLS Edition User Guide \| Previous Topic \| Next Topic \| Contents \| Index

The BEA eLink Java Adapter for Mainframe WLS Edition (JAM) software provides application developers bidirectional, transparent processing using native platform Application Programming Interfaces (APIs). Java application programmers can develop clients or servers using standard object oriented programming techniques without regard for mainframe protocols.

Customer Information Control System (CICS) programmers can develop servers or clients using the CICS Link command and the Distributed Program Link (DPL) subset API as a standard distributed CICS application. In addition, any existing CICS application designed to be invoked from a DPL can be used without modification. Implicit APPC support can be used to provide similar capabilities for IMS.

This section outlines the steps required to configure the JAM development environment to create a basic servlet that can execute a CICS DPL.

Configuring the JAM Environment

Prior to producing working Java code, it is recommended that you configure the JAM environment in this order:

Install and configure a supported SNA stack.
Install Java JDK 1.1.7B or 1.2 for the WebLogic Server platform.
Obtain the JDK from the OEM who provided the hardware on which WebLogic Server is to run. Follow the installation instructions provided with the JDK distribution.
Install WebLogic Server.
Install the Java Adapter for Mainframe.
Install the SNA Communications Resource Manager.
Establish Your Mainframe Environment.
Configure the Java Communication Resource Manager Gateway.
Start WebLogic Server.

Step 1 - Install a Supported SNA Stack

A properly configured SNA protocol stack is required for the SNACRM to communicate with a mainframe. The Java gateway requires the following parameters from the SNA stack configuration:

Local LU - The local name of the SNACRM that will be used by the mainframe application.
Remote LU - The name of the mainframe application that the SNACRM will use.
Mode Name - The SNA mode definitions provide session characteristics for a given local/remote LU pair.
Max sessions - Sessions are required for connections to be made between two LU. Max sessions should be high enough to handle the expected gateway traffic. This parameter is optional and defaults to 4.
Minimum Contention Winners - Determines the priority of the session activation. This parameter is optional and defaults to one half the value specified for max sessions.

Refer to the BEA eLink Java Adapter for Mainframe WLS Edition Release Notes for a list of supported SNA stacks.

Note: Refer to the SNA stack vendors documentation on how to configure for your environment. Ensure the stack is properly installed and the configuration can be activated.

Step 2 - Install the Java JDK

Obtain the JDK from the OEM who provided the hardware intended to run the WebLogic server. Follow the installation instructions provided with the JDK distribution.

Step 3 - Install WebLogic Server

The WebLogic application server provides the environment for running Java servlets and Enterprise Java Beans. The JCRMGW gateway is launched during the WLS startup using a startup class called gwboot. Configuration requirements for the server to start the gateway are limited to identifying the startup class along with any startup arguments in the weblogic.properties file. This file is located in the WebLogic installation directory generated for it.

The only WLS configuration requirement for the JCRMGW is in the weblogic.properties file and the WEBLOGICCLASSPATH environment variable, which is set in the start.weblogic startup script found in the WLS installation directory. The WEBLOGICCLASSPATH also requires the addition of the jam.jar file. In addition, the weblogic.properties file requires an entry for the gwboot startup class that launches the gateway when the server is started.

When the SNACRM is installed on a different machine from the JAM, you must specify the -r parameter on the weblogic.system.startupArgs.jcrmgw line of the weblogic.properties file. If the two JAM components are installed on the same machine, the -r parameter is optional since the gateway can spawn a SNACRM from the startup process.

The following listing contains an example of the entries to be added in the weblogic.properties file.

Listing 2-1 Sample weblogic.properties File

weblogic.system.startupClass.jcrmgw=bea.sna.jcrmgw.gwboot
weblogic.system.startupArgs.jcrmgw=[-t] [-r] [-u <userid>]

Where:

-t

will turn on tracing in the SNACRM.

-r

indicates that the SNACRM is remote. The SNACRM should be run on the same platform as the SNA stack. This can be the same machine as the WebLogic server, in which case -r can be omitted and the JCRMGW will spawn a new SNACRM using the address specified in the jcrmgw.cfg file. If -r is used, the SNACRM will not spawn, but is assumed to already be running at the address specified in the jcrmgw.cfg, even if this is the same machine running the gateway. In addition, the local SNACRM group identifier must match the group identifier specified on the command line used to start the remote SNACRM.

-u<userid>

<userid> is the mainframe userid that should be associated with all requests originating from this gateway. This is useful for IDENTIFY type security where the client cannot provide a userid.

Note: The WEBLOGICCLASSPATH must contain the fully-qualified name of the jam.jar file.

Step 4 - Install the Java Access for Mainframe

Refer to the BEA eLink Java Adapter for Mainframe WLS Edition Installation Guide and Release Notes for information on hardware and software requirements and instructions on installing the software.

Step 5 - Install the SNA Communications Resource Manager

The following environment variables must be set in the environment where the SNACRM is started.

FLDTBLDIR32=JAM Installation Directory/lib
FIELDTBLS32=JAM Installation Directory/fmb.def
APPDIR=<wherever>

These environment variables can be added as `set' or `export' commands in a script file used to start a SNACRM. Or they can be added to the startweblogic script for use when a SNACRM is spawned on startup.

Refer to the BEA eLink Java Adapter for Mainframe WLS Edition Installation Guide for information on hardware and software requirements and instructions on installing the software. For additional operational and administrative information, refer to the BEA eLink Adapter for Mainframe SNACRM Administration Guide.

Step 6 - Establish Your Mainframe Environment

The following configurations are required on the mainframe in order to conduct operations with the BEA TUXEDO/WLS environment:

Established VTAM configuration
CICS/ESA Logical Unit (LU) configured
- Creating connections
- Defining sessions
If using IMS, APPC and transaction definitions must exist for that environment

Step 7 - Start WebLogic Server

Start WebLogic Server and verify that the SnacTask Startup Complete message indicates the gateway is ready. Also you can verify that the CICS connection is acquired using the CICS CEMTI CON (*) Command to verify your connection is in the ACQuired state, indicating the link is ready for use.

Step 8 - Configure the Java Communication Resource Manager Gateway (JCRMGW)

The JCRMGW uses a jcrmgw.cfg configuration file that you create to control much of the operation of the JCRMGW. The JCRMGW configuration file defines the SNACRM, stack, links, and local and remote services that comprise the gateway environment. This file must be created and located in the WebLogic installation directory.

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

The file is made up of six sections. Lines beginning with an asterisk (*) indicate the beginning of a specific section. Each such line contains the name of the section immediately following the *.
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 paragraphs describe the significant parameters within specific sections of the jcrmgw.cfg file that define new gateway configurations.

JC_REMOTE_DOMAINS Section

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

Required Keywords

The following are required keywords.

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.

The following listing contains an example.

CRCICS1 DOMAINID="TestCICS"

JC_SNACRM Section

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

Required Keywords

The following are required keywords.

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.

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.

JC_SNASTACKS Section

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

Required Keywords

The following are required keywords.

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

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

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

The following listing contains an example.

ibmcsaix STACKTYPE="ibm50"

The SNACRM tries to load the library for IBM Communication Server 5.0.

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.

JC_SNALINKS Section

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

Required Keywords

The following are required keywords.

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.

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.

Optional Keywords

The following are optional 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.

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.

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.

JC_LOCAL_SERVICES Section

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

Required Keywords

The following are required keywords.

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.

JC_REMOTE_SERVICES Section

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

Required Keywords

The following are required keywords.

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.

Optional Keywords

The following are optional 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.

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

Sample Configuration File

The following example illustrates a basic jcrmgw.cfg file.

Listing 2-2 Sample jcrmgw.cfg Configuration 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"