Configuring the BEA WebLogic Java Adapter for Mainframe


	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

WebLogic Java Adapter for Mainframe Doc Home \| 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.

The following topics provide instructions and information for configuring JAM:

General Steps for Defining the Gateway Configuration

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:

Determine which keyword information needs to be used to define the gateway as appropriate for your system configuration.
Create or edit the jcrmgw.cfg file with the gateway information.

Refer to the following sections for general information about the JCRMGW configuration file and detailed information about the keywords you need to define in your configuration file.

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.

About the JCRMGW Configuration File

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

JCRMGW Configuration File Sections

The following sections describe the significant keywords 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.

Valid Keywords

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

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.

Valid Keywords

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

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.

Valid Keywords

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

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.

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.

Valid Keywords

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

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.

Valid Keywords

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

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.

Valid Keywords

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

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 3-1 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"

Post Configuration Requirements

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 CEMT I CON (*) Command to verify your connection is in the ACQuired state, indicating the link is ready for use.