Defining the JAM Gateway Configuration

 

BEA WebLogic Java Adapter for Mainframe (JAM) configuration is defined by the JAM configuration file, jcrmgw.cfg. The JAM gateway uses the jcrmgw.cfg file to control much of its operation. The jcrmgw.cfg configuration file defines the Communications Resource Manager (CRM), stack, links, and local and remote services that comprise the gateway environment.

The topics in this section describe the JAM gateway configuration file and how to create and verify your own configuration file.

 

---

Action List

Before you create your JAM gateway configuration file, see the following action list and refer to the appropriate information sources.

	Your action...	Refer to...
1	Complete all prerequisite tasks.	Prerequisites
2	Learn about the JAM gateway configuration file.	About the JAM Gateway Configuration File
3	Create a JAM gateway configuration file for your environment.	Creating a Configuration File
4	Check the JAM gateway configuration file.	Verifying the Configuration File with the Configuration Checker Utility
5	Prepare for the next step.	What Do I Do Next? and the next section, Putting It All Together

 

 

---

Prerequisites

Before you create your JAM gateway configuration file, you should complete the following tasks.

	Your action...	Refer to...
1	Verify that system requirements have been met.	BEA WebLogic Java Adapter for Mainframe Introduction and Release Notes
2	Determine which configuration your system requires and install the JAM product as appropriate for your configuration.	BEA WebLogic Java Adapter for Mainframe Installation Guide
3	Learn about mainframe configuration requirements for the CRM.	Preparing Mainframe Configurations for CRM Requirements

 

 

---

About the JAM Gateway Configuration File

A sample jcrmgw.cfg file is located in the JAM examples/samples.jar file. Edit this file to meet your configuration needs or create your own configuration file with any text editor. Refer to the following sections for information about each configuration file section and associated parameters.

Example of a JAM Gateway Configuration File

The following example illustrates a basic jcrmgw.cfg file.

Listing 2-1 Sample jcrmgw.cfg Configuration File

*JC_REMOTE_DOMAINS
#
CICS13       DOMAINID="13"
#
*JC_SNACRM
#
CRMAN	SNACRMADDR="//dalnt66:8650"
              GROUP="G1"

*JC_SNASTACKS
#
OS390         STACKTYPE="VTM28"
              LOCALLU="LUNT66B"
#
*JC_SNALINKS
#
CICS          RLUNAME="C410XB01"
              RDOM="CICS13"
              MODENAME="SMSNA100"
              MAXSESS=8
              MINWIN=6
#
*JC_LOCAL_SERVICES
#
TraderHome    RNAME="DPL1SVR"
#
*JC_REMOTE_SERVICES
DPLINIT	       RDOM="CICS13"
              RNAME="PRIM:DPLINIT"
              TRANTIME=10000
TOUPPER	       RDOM="CICS13"
              RNAME="TOUPDPLS"
              TRANTIME=10000
demoRead      RDOM="CICS13"
              RNAME="DPLDEMOR"
              TRANTIME=10000
demoUpdate    RDOM="CICS13"
              RNAME="DPLDEMOU"
              TRANTIME=10000
demoCreate    RDOM="CICS13"
              RNAME="DPLDEMOC"
              TRANTIME=10000
demoDelete    RDOM="CICS13"
              RNAME="DPLEMOD"
              TRANTIME=10000
imsInsert     RDOM="CICS13"
              FUNCTION=APPC
              RNAME="DPLDEMOC"

Format of the JAM Gateway Configuration File

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 section title line contains the name of the section immediately following the asterisk. 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.

• Each section may include sets of keywords for multiple domains, CRMs, stacks, links, home interfaces, or services. Therefore, each set of keywords must be identified with a label. The label is placed before the first keyword of the set of keywords as shown in the following example of two remote services labeled DPLINIT and TOUPPER:

  *JC_REMOTE_SERVICES
  DPLINIT RDOM="CICS410"
  RNAME="PRIM:DPLINIT"
  TRANTIME=10000
  TOUPPER RDOM="CICS410"
  RNAME="TOUPDPLS"
  TRANTIME=10000

• "#" 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.

JC_REMOTE_DOMAINS Section

This section of the jcrmgw.cfg file provides an alias for associating mainframe applications with services and links. A label identifying the domain must precede the first keyword in the set of keywords defining the domain.

Listing 2-2 shows an example of the JC_REMOTE_DOMAINS section. CICS410 is the label for the domain.

Listing 2-2 Example of JC_REMOTE_DOMAINS Section

*JC_REMOTE_DOMAINS
#
CICS410       DOMAINID="410"

The following table provides descriptions of valid keywords for the JC_REMOTE_DOMAINS section:

 

Keyword	Default	Required/ Optional	Description
DOMAINID	None	Required	Name of a partner system DOMAINID=<string> <string> is any name to be used for identifying a partner system. Example: CRCICS1 DOMAINID="TestCICS"

 

JC_SNACRM Section

This section of the jcrmgw.cfg file identifies the CRM that this gateway talks to. There is one CRM for each JAM gateway. A label identifying the CRM must precede the first keyword.

Listing 2-3 shows an example of the JC_SNACRM section. CRMAN is the label for the CRM.

Listing 2-3 Example of JC_SNACRM Section

*JC_SNACRM
#
CRMAN         SNACRMADDR="//dalnt66:8650"
               GROUP="G1"

The following table provides descriptions of valid keywords for the JC_SNACRM section:

 

Keyword	Default	Required/ Optional	Description
SNACRMADDR	None	Required	Symbolic TCP address SNACRMADDR=<string> <string> is a symbolic TCP address in the form of: "//hostname:port" hostname is the name of the machine that runs the CRM. Port is an available decimal port number that the CRM uses to talk to the Java gateway. In the case of a CRM that is started independently of the gateway, this address must match the address used on the CRM command line. When the gateway is started, it tries to contact the CRM at the address. Example: MYCRM SNACRMADDR="//dalhp55:6942" The gateway will look for a CRM on a machine named dalhp55 at port 6942.
GROUP	None	Required	Name of group correlating gateway with CRM GROUP=<string> <string> is any name to be used to correlate a gateway with a CRM. The name is used as part of the file name for the CRM logs. In the case of a CRM that is started independently of the gateway, this name must match the group name used on the CRM command line, even if the default name is used. The keyword/value pair has a default value of GROUP. Example: GROUP="CRAUTH" The CRM expects a gateway signon for group CRAUTH.

 

JC_SNASTACKS Section

This section of the jcrmgw.cfg file identifies the Local LU used for the CRM along with the stack identifier for the stack library to be used. Only one local LU and one stack can be specified for a CRM. A label identifying the Local LU and stack must precede the first keyword in the set of keywords defining the Local LU and stack.

Listing 2-4 shows an example of the JC_SNASTACKS section. OS390ST is the label for the Local LU and stack.

Listing 2-4 Example of JC_SNASTACKS Section

*JC_SNASTACKS
#
OS390ST      STACKTYPE="VTM28"
              LOCALLU="BEAAPPL1"

The following table provides descriptions of valid keywords for the JC_SNASTACKS section:

 

Keyword	Default	Required/ Optional	Description
LOCALLU	None	Required	Alias of local LU to be used with CRM LOCALLU=<string> <string> is an alias for the local LU to be used by the CRM. This must match a corresponding LU alias defined in the Stack configuration. This alias may or may not match the actual LU name. Example: LOCALLU="AUTHAPP" The CRM tries to use the local LU which has been defined in the stack configuration with an alias of AUTHAPP.
STACKTYPE	None	Required	Name of stack support library to load STACKTYPE=[ibm60 | spx62 | vtm28 ] One of the specified tokens must be used. These names determine which stack support library will be loaded. The following stacks can be identified: ibm60 = IBM Communications server 6.0 on WINNT spx62 = Data Connection Snapix 6.2 or 7.0 on Solaris vtm28 = VTAM on OS/390 Example: STACKTYPE="vtm28" The CRM loads the library for VTAM on OS/390.

 

JC_SNALINKS Section

This section of the jcrmgw.cfg file identifies partner mainframe application regions. Multiple links for a single CRM are supported. A label identifying the link must precede the first keyword in the set of keywords defining the link.

Listing 2-5 shows an example of the JC_SNALINKS section. C41XB01 is the label for the link.

Listing 2-5 Example of JC_SNALINKS Section

*JC_SNALINKS
#
C41XB01       RLUNAME="C410XB01"
              RDOM="CICS410"
              MODENAME="SMSNA100"
              MAXSESS=8
              MINWIN=6

The following table provides descriptions of valid keywords for the JC_SNALINKS section:

 

Keyword	Default	Required/ Optional	Description
MAXSESS	4	Optional	Maximum number of sessions that can be started for a link MAXSESS=nn (4) nn is the maximum number of 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 service manager mode. The lowest usable value is 4; it provides two sessions for the application and two sessions for the service manager. Example: MAXSESS=8 The maximum number of sessions on this link is set to 8 for all modes combined.
MINWIN	One half the number of MAXSESS	Optional	Minimum number of sessions that will be contention winners MINWIN=nn (MAXSESS/2) nn is the minimum number of sessions that will be contention winners for requests originating from the WebLogic Server side. This keyword defaults to one half the number of MAXSESS, which is suitable in most cases 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 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. Example: MINWIN=6 The number of contention winner sessions on this link is set to 6 for all modes combined.
MODENAME	None	Required	Name of mode definition MODENAME=<string> <string> is the name of a mode definition to be used for applications on this link. The string must match a corresponding mode name defined in the Stack configuration and the VTAM mode table. A valid mode name should be provided by mainframe support personnel. Example: MODENAME="SMSNA100" The CRM will use the SMSNA100 mode for applications on this link.
RDOM	None	Required	Name of remote domain RDOM=<string> <string> is a name previously defined as a remote domain om the JC_REMOTE_DOMAINS section of the configuration file. The remote domain name is used as a mechanism for grouping links. Example: RDOM="CRCICS410" This link is associated with the remote domain named CRCICS410.
RLUNAME	None	Required	Alias for remote LU RLUNAME=<string> <string> is an alias for the remote LU representing the partner application to be used by the CRM. Example: RLUNAME="C410XB01" The CRM routes all traffic for this link to a remote application defined with an alias of C410XB01. This alias must be defined in the stack configuration for a valid mainframe application name.
SECURITY	LOCAL	Optional	Indicates level of security SECURITY=[LOCAL | IDENTIFY | VERIFY] One of the specified tokens must be used and the mainframe connection must 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 user ID is passed on to the mainframe. This user ID can originate with the client application or it can be a default user ID supplied with the -u option on the gateway startup. VERIFY = A user ID and password are passed on to the mainframe. The user ID can originate with the client application or it can be a default user ID supplied with the -u option on the gateway startup. The password must be supplied by the client application. Refer to the BEA WebLogic Java Adapter for Mainframe Reference Guide for more information about security options. Example: SECURITY=IDENTIFY A user ID 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 of the jcrmgw.cfg file maps incoming mainframe program names to a Home interface for an EJB that will service the request. A label identifying the Home interface must precede the first keyword in the set of keywords defining the Home interface.

Listing 2-6 shows an example of the JC_LOCAL_SERVICES section. DPL1SVR is the name of the program that was invoked from the mainframe and StatelessSessions.TraderHome is the name of the Home interface that will be used to invoke the EJB that services this request.

Listing 2-6 Example of JC_LOCAL_SERVICES Section

*JC_LOCAL_SERVICES
#
StatelessSessions.TraderHome   RNAME="DPL1SVR"

The following table provides descriptions of valid keywords for the JC_LOCAL_SERVICES section:

 

Keyword	Default	Required/ Optional	Description
RNAME	None	Required	Name of remote resource associated with a service RNAME=<RRRRRRR> RNAME is the remote resource name associated with this service. For a CICS DPL, this is the actual program name that was invoked from the mainframe. For an IMS request, the resource name must conform to the Transaction ID. A CICS DPL Program is limited to eight characters and an IMS Transaction ID is limited to eight characters. The label on this entry must be the name of a valid home interface for an EJB registered with JNDI. This keyword/value pair is required and has no default value. Example: StatelessSessions.TraderHome RNAME="DPL1SVR"
SCHEMA	None	Required for use with WebLogic Process Integrator	Identifies the generated DataView. SCHEMA=<string> This keyword is used to identify the MFL format used for decoding or encoding data streams. SCHEMA is used by the JAM Plug-in and WebLogic XML/Non-XML Translator when integrating JAM with WebLogic Process Integrator. Example: SCHEMA=myschema

 

JC_REMOTE_SERVICES Section

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. These remote mainframe program names and associated method names are called remote services. A label identifying the remote service must precede the first keyword in the set of keywords defining the remote service.

Listing 2-7 shows an example of the JC_REMOTE_SERVICES section. DPLINIT and TOUPPER are the labels for the remote services.

Listing 2-7 Example of JC_REMOTE_SERVICES Section

*JC_REMOTE_SERVICES
DPLINIT       RDOM="CICS410"
              RNAME="PRIM:DPLINIT"
              TRANTIME=10000
TOUPPER       RDOM="CICS410"
              RNAME="TOUPDPLS"
              TRANTIME=10000

The following table provides descriptions of valid keywords for the JC_REMOTE_SERVICES section:

 

Keyword	Default	Required/ Optional	Description
FUNCTION	DPL	Optional	Method of request invocation accepted by the mainframe FUNCTION=[APPC | DPL] This keyword indicates the method of request invocation accepted by the mainframe. DPL is only valid when used with a CICS partner and an application that can be invoked using a DPL. APPC should be used when invoking services from an IMS server. Example: FUNCTION=APPC This remote service will be invoked as an IMS application rather than a program link.
RDOM	None	Required	Name of remote domain RDOM=<string> <string> is a name previously defined as a remote domain. Example: RDOM="CRCICS1" This service will be associated with the remote domain named CRCICS1.
RNAME	None	Required	Remote resource name associated with a service RNAME=<[MMMM:]RRRRRRRR> RNAME is the remote resource name associated with this service. For a CICS DPL, 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 an APPC style request, the resource name must conform to the Tran ID requirements of IMS. Example: RNAME="AUTH:DPLQRY" This Rname is a program named DPLQRY and will use an alternate mirror transaction name of AUTH.
SCHEMA or INPUTSCHEMA and/or OUTPUTSCHEMA	None	Optional	Identifies the generated DataView. SCHEMA=<string> INPUTSCHEMA=<string> OUTPUTSCHEMA=<string> These keywords are used to identify the MFL format used for decoding or encoding data streams. INPUTSCHEMA and OUTPUTSCHEMA are used by the JAM Plug-in and WebLogic XML/Non-XML Translator when integrating JAM with WebLogic Process Integrator. The INPUTSCHEMA translates the message sent to the mainframe. The OUTPUTSCHEMA translates the message received as a reply from the mainframe. If INPUTSCHEMA and OUTPUTSCHEMA represent the same MFL format, the SCHEMA keyword may be used in place of INPUTSCHEMA and OUTPUTSCHEMA. Do not use SCHEMA with INPUTSCHEMA and/or OUTPUTSCHEMA. The following example uses SCHEMA: SCHEMA=myschema The following example uses both INPUTSCHEMA and OUTPUTSCHEMA: INPUTSCHEMA=myinputschema OUTPUTSCHEMA=myoutputschema
TRANTIME	30000	Optional	Maximum number of milliseconds client will allow for a host request to respond TRANTIME=nnn (30000) nnn is the maximum number of milliseconds the client application will block before a host request is timed out. Example: TRANTIME=120000 This remote service will time out if the mainframe does not respond within 2 minutes (120 seconds).

 

 

---

Creating a Configuration File

To create a JAM gateway configuration file for your environment, use any text editor and perform one of the following procedures:

1. Edit the sample jcrmgw.cfg file located in the JAM examples/samples.jar file with your own configuration requirements.

   Or,

2. Create your own configuration file with any text editor.

Note: Refer to the previous section, About the JAM Gateway Configuration File for detailed information about the JAM gateway configuration file parameters.

 

---

Verifying the Configuration File with the Configuration Checker Utility

After you create or edit the jcrmgw.cfg file, you should verify the contents by invoking the gateway's Configuration Checker utility directly from a command line. This verification process allows you to discover and correct any errors prior to starting the gateway.

jcrmConfigurator is a Java class that is used to check the jcrmgw.cfg file. It is recommended that you place the command into a script file and run it with standard output redirected to a file. The resulting output is either diagnostic messages indicating syntax errors in the configuration file, or a formatted listing of the definitions as they are used by the gateway. There are no options for the jcrmConfigurator class and the only file that can be processed is the jcrmgw.cfg file in the current directory.

To run the jcrmConfigurator class:

1. Enter the following commands (assuming jam.jar is installed in the D:\jam42\lib directory):

   set classpath=%classpath%;D:\jam42\lib\jam.jar
   java  com.bea.sna.jcrmgw.jcrmConfigurator 

2. Review the output and correct any errors that are found.

3. Re-run the jcrmConfigurator class and make corrections until all errors are corrected.

 

---

What Do I Do Next?

After you create a JAM configuration file for your environment and check it, you can review an example of a mainframe configuration. Refer to Putting It All Together for more information. If you do not wish to review the example, you are ready to learn how to run the CRM so that you can deploy your configuration. Refer to Using the CRM Administration Commands for more information about starting the CRM.