bea.com | products | dev2dev | support | askBEA

Download Docs
Search

Configuration and Administration Guide

Configuring WebLogic JAM Connectivity

The WebLogic Administration Console provides you with the tools you need to configure connectivity between your mainframe and WebLogic Server.

This section provides information on the following subjects:

- Understanding WebLogic JAM Connectivity

- Step 1: Deploy WebLogic JAM in the WebLogic Server Environment

- Step 2: Define Where the CRM Will Run

- Step 3: Create a Logical Unit for the CRM

- Step 4: Connect the CRM to Back-End Systems on the Mainframe

- Step 5: Enter Connectivity Information into WebLogic Administration Console

- Step 6: Define a WebLogic JAM Gateway

- Step 7: Verify Your WebLogic JAM Connectivity Configuration

Understanding WebLogic JAM Connectivity

WebLogic JAM uses two distributed software components to connect to your back-end systems: the WebLogic JAM Gateway and the Communications Resource Manager (CRM). The WebLogic JAM Gateway component runs within an instance of WebLogic Server and serves as a proxy to other applications running within WebLogic Server.

The CRM runs as a native operating system process, and it connects to your back-end system using Advanced Program to Program Communications (APPC), also known as LU 6.2, using SNA network connections. The CRM and the WebLogic JAM Gateway communicate with each other using a TCP/IP socket. The CRM connects to your back-end system using an SNA network connection called a logical unit (LU).

A logical unit is an SNA network's way of providing access to the SNA network to end users and software programs. A logical unit is a unique, addressable part of an SNA network that manages data flows between network partners. A logical unit is somewhat like a TCP/IP address and port because software programs can use it to access the network and to communicate with other software programs that are distributed throughout the enterprise. Unlike TCP/IP connections, logical units must be defined prior to use. Figure 2-1 shows the CRM using APPC to establish communication with a back-end application.

Figure 2-1 CRM Using APPC

In order for software programs such as the CRM to communicate via APPC, each peer program must have access to a logical unit. The software programs then allocate a session between the two logical units to communicate and collaborate.

A session is a pipeline between two logical units that manages the exchange of data between the logical units. The two peer programs send data back and forth over the pair of logical units using a session. This exchange of data is called a conversation. The number of sessions that can exist simultaneously over a given logical unit pair is configured in the SNA network. Establishing WebLogic JAM connectivity involves allocating logical units and sessions in your SNA network, and recording this configuration in WebLogic JAM.

The WebLogic Administration Console allows you to define where WebLogic JAM components will run within your enterprise, and the network connections that they will establish. Once entered into the console, this configuration is persisted and distributed to WebLogic JAM components upon start-up.

Getting Started with WebLogic JAM Connectivity

The overall task of establishing WebLogic JAM connectivity involves asking administration personnel to allocate SNA network resources (logical units, sessions) and then recording these resources in WebLogic JAM configuration via the WebLogic Administration Console. This task has been organized into six primary steps:

- Step 1: Deploy WebLogic JAM in the WebLogic Server Environment

- Step 2: Define Where the CRM Will Run

- Step 3: Create a Logical Unit for the CRM

- Step 4: Connect the CRM to Back-End Systems on the Mainframe

- Step 5: Enter Connectivity Information into WebLogic Administration Console

- Step 6: Define a WebLogic JAM Gateway

- Step 7: Verify Your WebLogic JAM Connectivity Configuration

Your system administrators will configure your mainframe to communicate using SNA and then establish the actual connection to the CRM using the parameter information provided in the steps of this section.

When you have all of the appropriate parameters, you are ready to configure connectivity by entering them into the WebLogic Administration Console. Use the steps in this section to help you and your system administrators connect your systems correctly and to get the correct configuration information into the WebLogic Administration Console. Instructions are also provided to help you verify your configuration.

Note: The Mainframe Connectivity Worksheet is provided to help you prepare to configure connectivity between your mainframe system and your BEA WebLogic Server system. For a copy of the worksheet, see Mainframe Connectivity Worksheet.

Step 1: Deploy WebLogic JAM in the WebLogic Server Environment

After WebLogic JAM has been installed, it must be deployed in the WebLogic Server environment. The following tasks must be completed if you are not running a pre-configured sample.

You can deploy WebLogic JAM in the following ways:

- If you are creating applications, the example domain and the verify domain are examples of domains deployed in the WebLogic Server environment. You may want to use these domains as a starting point, adding other J2EE applications to meet your specific requirements.

- If you are adding WebLogic JAM to existing WebLogic Server applications, you need to manually deploy WebLogic JAM by completing the following steps:

- Adding the jam.jar File to the WebLogic Server CLASSPATH

- Deploying the jam.ear File

- Defining the WebLogic JAM Startup Class

Adding the jam.jar File to the WebLogic Server CLASSPATH

The jam.jar file adds classes to the WebLogic Server CLASSPATH. The jam.jar file must be added to the CLASSPATH in the WebLogic Server startup script for each server where it will run.

To manually add the jam.jar file to the WebLogic Server CLASSPATH, perform the following steps:

1. Using the text editor of your choice, locate the script you use to start WebLogic Server in your domain. For example, use the startWebLogic script in your config/mydomain directory mydomain is the name of your domain.

   - For example, on a Microsoft Windows platform, use your startWebLogic.cmd script in your config\mydomain directory where mydomain is the name of your domain and startWebLogic.cmd is the script to start WebLogic Server.

   - For example, on a Unix platform, use your startWebLogic.sh script in your config/mydomain directory where mydomain is the name of your domain and startWebLogic.sh is the script to start WebLogic Server.

2. Edit the startWebLogic script by adding the jam.jar file to the CLASSPATH setting as shown in the following examples:

   - For Microsoft Windows:

   >     set CLASSPATH=.;.\lib\weblogic_sp.jar;
   >     .\lib\weblogic.jar;e:\bea\wljam5.1\lib\jam.jar

   In this example, e:\bea\wljam5.1 is the install directory for WebLogic JAM.

   - For Unix:

   >     CLASSPATH=$WL_HOME:$WL_HOME/lib/weblogic_sp.jar:$WL_HOME/lib/weblogic.jar:./ext/weblogic-tags.jar:/bea/wljam5.1/lib/jam.jar

   In this example, /bea/wljam5.1 is the install directory for WebLogic JAM.

3. Save the file and close the text editor.

Deploying the jam.ear File

The jam.ear file deploys the WebLogic JAM applications and the WebLogic JAM extension to the WebLogic Administration Console. This file contains the following EJBs:

- jambeans

- jamtojms

- jam.war (for the console)

Deploy the jam.ear file on the appropriate servers using the WebLogic Administration Console. To manually deploy the jam.ear file, perform the following steps:

1. In the WebLogic Administration Console, select Deployments—>Applications to invoke the Applications page. Click on Configure a new Application.

2. Click upload it through your browser. Click Browse to locate the jam.ear file in wljam5.1\lib directory. Click Upload.

   Note: The Path field and the Browse button specify directories and files relative to the computer that the browser is running on.

The jam.ear file has been uploaded and WebLogic JAM applications and components are available in the left pane of the WebLogic Administration Console.

Defining the WebLogic JAM Startup Class

The WebLogic JAM startup class defines a class that is launched at WebLogic Server startup. To manually define the WebLogic JAM startup class using the WebLogic Administration Console, perform the following steps.

1. In the WebLogic Administration Console, select Deployments—>Startup & Shutdown to invoke the Startup & Shutdown page.

2. Click on Configure a new Startup Class to invoke the Create a new Startup Class page.

3. Fill in the fields.

   1. Assign a name for the Name field.

   2. The ClassName must be com.bea.jam.GatewayStartup.

4. Click Create to create the new startup class.

5. Select the Targets tab. Select the target server from the available list and click the arrow to add it to the chosen list. Click Apply to apply the new startup class.

Step 2: Define Where the CRM Will Run

The CRM should run on a mainframe that can access the desired back-end systems using your SNA network. The CRM can run on the mainframe as a job in an MVS region or as a process under z/OS or OS/390 Unix using Unix System Services (USS). As part of the WebLogic JAM installation process, you are instructed on how to install the CRM. For detailed information, see the BEA WebLogic JAM Installation Guide.

For this step, you need to determine where you want the CRM to run and then gather the configuration information that you will input into the WebLogic Administration Console in a later step. Table 2-1 provides a list of the parameters that you will use to configure connectivity with the CRM in the WebLogic Administration Console.

Table 2-1 CRM Definition Parameter in the WebLogic Administration Console

WebLogic Administration Console Parameters | Description | Parameter Syntax
--- | --- | ---
Name | The arbitrary name of the CRM. The CRM process uses this name to ensure the correct configuration between the WebLogic JAM Gateway and the CRM process. | Alpha-numeric string Ex. CRM1
Listen Address | The host name of the machine where the CRM runs, or the TCP/IP address of the machine where the CRM runs. | Alpha-numeric string or dotted IP address Ex. myhost or 123.4.5.678
Listen Port | The TCP/IP port that is used by the CRM to listen for connecting WebLogic JAM components. Ask your network administrator for an unused TCP/IP port on the machine where the CRM runs. | Numeric value Ex. 8002
Stack Type | The predefined name that the CRM uses to identify the supported SNA stack software release. Refer to the BEA WebLogic Java Adapter for Mainframe Release Notes for supported stacks. | Supported stack available in drop-down list. Ex. vtm28

Note: A worksheet is available to give you a central location for gathering various connection parameters before you sit down to enter them into the WebLogic Administration Console in Step 5: Enter Connectivity Information into WebLogic Administration Console. For a copy of the worksheet, see Mainframe Connectivity Worksheet.

Step 3: Create a Logical Unit for the CRM

The CRM component of WebLogic JAM uses an LUTYPE 6.2 logical unit to communicate with back-end systems running on the mainframe. Each back-end system must have its own logical unit, and sessions must be defined to allow the CRM to allocate sessions between its logical unit and the logical unit of the mainframe system. Each peer must be configured ahead of time to connect to the logical unit of its peer.

In this step, your VTAM administrator creates a logical unit within VTAM for the CRM. The logical unit defines the CRM to the SNA network. You will need to enter this logical unit parameter into the WebLogic Administration Console to finish WebLogic JAM configuration in a later step.

This step provides the following information:

- Parameters for Establishing the CRM Logical Unit

Provides the parameters that the VTAM administrator needs to create a logical unit for the CRM

- WebLogic Administration Console Parameter for the CRM Logical Unit

Provides the parameter that you need to enter into the WebLogic Administration Console to complete WebLogic JAM configuration as described in a later step.

Parameters for Establishing the CRM Logical Unit

The VTAM application program major node (VTAM APPLID) is also the CRM logical unit. You define the APPLID to VTAM and activate it in the VTAM network.

Listing 2-1 shows a sample VTAM APPLID definition node.

Listing 2-1 Sample VTAM APPLID Definition Node:

>     BEA   VBUILD TYPE=APPL             APPLICATION MAJOR NODE
>     BEAAPPL1 APPL  ACBNAME=BEAAPPL1,       ACBNAME FOR APPC
>                    APPC=YES,
>                    SYNCLVL=SYNCPT,
>                    PARSESS=YES

The following parameters represent the minimum requirements for defining the logical unit.

  Application Program Major Node Name

  This tag identifies the node to the network.

  TYPE=APPL

  Major node should be an Application Major Node type.

  ACBNAME=LU Name

  Logical unit name. This can be identical to the Application Major Node name. This is the logical unit name used in the CRM configuration.

  APPC=YES

  Defines this as an APPC logical unit.

  SYNCLVL=[CONFIRM | SYNCPT]

  Determines level of transactional support. CONFIRM supports non-transactional DPL and APPC service requests only, while SYNCPT will in addition, support transactional service requests. See Administering Transactions for information on these options.

  PARSESS=YES

  Allows multiple sessions between session partners.

  SRBEXIT=NO

  The CRM logical unit does not support the service request block (SRB) exit routines. This parameter must be set to NO (the default value if the parameter is not specified.)

WebLogic Administration Console Parameter for the CRM Logical Unit

Table 2-2 shows the parameter that you will use in the WebLogic Administration Console to configure connectivity with the CRM. Work closely with your VTAM administrator to get the CRM Logical Unit defined in your SNA network.

Table 2-2 CRM Logical Unit Definition Parameter in the WebLogic Administration Console

WebLogic Administration Console Parameter | Description | Parameter Syntax
--- | --- | ---
Logical Unit | The name of the logical unit defined in VTAM for the CRM. | Alpha-numeric string Ex. BEAAPPL1

Note: A worksheet is available to give you a central location for gathering various connection parameters before you sit down to enter them into the WebLogic Administration Console in Step 5: Enter Connectivity Information into WebLogic Administration Console. For a copy of the worksheet, see Mainframe Connectivity Worksheet.

Step 4: Connect the CRM to Back-End Systems on the Mainframe

To connect the CRM to your mainframe applications, you may need to connect to different types of regions that run on the mainframe. Instances of IMS and CICS systems are usually referred to as an IMS region or a CICS region respectively. APPC applications that do not run in CICS or IMS, but rather run under APPC/MVS as a started job, can also connect to WebLogic JAM. These applications are referred to in WebLogic JAM documentation as running in a batch region.

This section provides information on the following subjects:

- Determining Connection Characteristics

- Connecting to a CICS Region

- Connecting to an IMS Region

- Connecting to a Batch Region

Determining Connection Characteristics

When you define the connectivity of the CRM to the back-end application environment, you must identify characteristics of this connection. Connection characteristics determine the type of work and class of service used between the CRM and its partner. Speak with your system administrator ahead of time about these considerations so you may select the best choices for your configuration.

In order to connect to a back-end system using WebLogic JAM, you must configure your CRM with an APPC connection (or link) to the back-end system. These connections are referred to in WebLogic JAM as CRM Links. A CRM Link is a definition that WebLogic JAM uses to store the parameters of the connection (or link) between the CRM's logical unit and the logical unit of the back-end system. A CRM can only have a single CRM Link to a given region.

Discuss the following list of topics with your system administrator. These topics are relevant to both the CRM and back-end application environment.

- Logmode Name

- Sessions

- Security Level

Logmode Name

Mode name defines characteristics of the APPC sessions that the CRM establishes across this CRM Link.

The characteristics of different logon modes are tailored to support different types of applications. For example long-running batch applications might use different logon modes than short-lived online applications. Logon modes can define different logical unit protocols, classes of service, packet sizes, and pacing algorithms.

Use the same logon mode for both the CRM logical unit and the back-end application logical unit.

Sessions

When a CRM Link is created, a pool of sessions is allocated to handle requests for that link. The sessions in the pool are available for requests that originate on either side. The CRM requires a session for each request originating in WebLogic Server, while the back-end system requires a session for each request originating there. If a session is not available to a request, then the request will fail.

The following topics should be considered for setting up session connections:

- Maximum Session

The term "maximum sessions" refers to the number of sessions in the allocated pool. This value determines the number of concurrent requests that can be active at any given time. Both the CRM and the back-end system must configure their maximum sessions to the same value.

- Minimum Winner Sessions

Both the CRM and the back-end system are pre-allocated a number of sessions for their use. This number is referred to as "minimum winner sessions." The owner of these pre-allocated sessions has priority for its winner sessions; however, they may be reassigned depending on system load.

The total of the minimum sessions for both sides must be less than or equal to the maximum session value. If the total is higher than the maximum session value, you will be unable to activate the link.

For best results in determining minimum sessions, evaluate the number of sessions that are required for the CRM and for the back-end system to support concurrent requests.

Security Level

The security level of a CRM Link defines what security credentials are required for all requests that utilize this link.

- No security credentials provided

In the simplest case, no security credentials are provided with requests sent on the link. This implies that the user has been authenticated in the originating domain, and that no further authentication is required. The value for the CRM would be Local. The corresponding value for the back-end system must be defined in the connection definitions.

- User ID provided

It is possible that the application processing the request needs to identify the user making the request for access control to application resources. For this case, only a user ID is provided with the request. The value for the CRM would be Identify. The corresponding value for the back-end system must be defined in the connection definitions.

- User ID and password provided

A third possibility is that full security credentials are required for any requests sent on the link. In this case, a user ID and password are required for each request. These credentials are validated against the security configuration in the destination environment. The user ID can then be used for access control to application resources. The value for the CRM would be Verify. The corresponding value for the back-end system must be defined in the connection definitions.

The following sections describe the steps necessary to connect to each type of back-end system. Configuration that is required on the mainframe system is discussed, as well as capturing the parameters of the CRM Link that will be used to connect to the mainframe system. Each specific type of back-end system is discussed separately below.

Connecting to a CICS Region

Connecting to a CICS region is a process that requires you to work closely with your system administrator to establish the actual connection. First, you and your administrator define the CRM's logical unit to the CICS region with a CICS Connection Definition. Then you must define the connection characteristics of the CRM's connection to the CICS region with a CICS Session Definition. Once the connection has been defined in the CICS region, you need to enter the information into the WebLogic Administration Console as a CICS region definition and a CRM Link definition. This section provides information about the following:

- Parameters and Steps for Connecting to a CICS Region

A system administrator will most likely configure the CICS region and establish the CICS connections to the CRM. This section provides information to help the administrator establish those connections.

- WebLogic Administration Console Parameters for CICS Region Connectivity

You will need certain parameters created during the connectivity process when you sit down at the WebLogic Administration Console to finish WebLogic JAM configuration. This section provides information to help you understand and capture the parameters you will need to enter into the WebLogic Administration Console in a later step.

Parameters and Steps for Connecting to a CICS Region

For every CICS region that the CRM connects to, resource definitions for the CRM's logical unit must be configured in the CICS region. This configuration consists of CICS connection and session resource definitions. These CICS resource definitions must be installed in each CICS region to which the CRM connects. Use the following steps and parameters to establish CICS region connectivity:

- Step 1: Create a Logical Unit for the CICS Region

- Step 2: Add APPC to the CICS Region

- Step 3: Define the CICS Connection Definition

- Step 4: Define the CICS Session Definition

- Step 5: Install the CICS Connection and Session Definitions

- Step 6: Verify Connection and Session Status

Step 1: Create a Logical Unit for the CICS Region

The CICS application program major node is also the CICS logical unit. This application program major node is defined to VTAM when the CICS region is created. Ask your system administrator to provide the CICS VTAM APPLID of the created CICS region.

Step 2: Add APPC to the CICS Region

To enable the CICS region for APPC, start the region with the following system initialization parameter:

>     ISC=YES

This enables inter-system communication.

Step 3: Define the CICS Connection Definition

In each CICS region to which the CRM connects, a system administrator must define and install a connection resource definition and session resource definition in the region. The connection and session definitions should be defined in the same resource group. This group of definitions defines the CRM as a partner Logical Unit to the CICS region, and associates connection characteristics to the link between the CRM and CICS. Listing 2-2 shows an example CICS connection definition.

The following parameters represent the minimum requirements for defining the CICS connection.

  ACCESSMETHOD(VTAM)

  Indicates this resource is accessed via VTAM

PROTOCOL(APPC)

  Indicates that this connection is used for APPC

NETNAME(xxx)

  The name of the CRM's logical unit created in VTAM.

ATTACHSEC(xxx)

  The security protocol used for this connection. Set to LOCAL, IDENTIFY, or VERIFY. If security credentials are not passed between WebLogic Server and CICS, set this to LOCAL. If user IDs are required between WebLogic Server and CICS set this parameter to IDENTIFY. If user IDs and passwords are required, set this parameter to VERIFY.

AUTOCONNECT(NO)

  Sessions for this connection should not be automatically initialized when CICS is started. The CRM will initiate session acquisition.

Listing 2-2 Example CICS Connection Definition

>     DEFINE CONNECTION(BEA1)
>            GROUP(BEA)
>            DESCRIPTION(LOGICAL UNIT FOR CRM1 TO ACCESS THIS CICS)
>            ACCESSMETHOD(VTAM)
>            PROTOCOL(APPC)
>            NETNAME(BEAAPPL1)
>            ATTACHSEC(LOCAL)
>            AUTOCONNECT(NO)

Step 4: Define the CICS Session Definition

In each CICS region that the CRM connects to, a session resource definition must also be defined and installed in the region. Listing 2-3 shows an example CICS connection definition. The following parameters represent the minimum requirements for defining the CICS session:

  CONNECTION (xxx)

  Should be set to the CICS connection definition for CRM's logical unit.

  AUTOCONNECT (YES)

  Determines how the activation of the session is negotiated. YES enables the CICS/ESA host to negotiate its own winner sessions once the CRM starts the initiation of session acquisition.

  MODENAME(xxx)

  This is the VTAM LOGMODE name used for these sessions.

MAXIMUM(SESSNBR, WINNER)

  Defines the total number of sessions for this connection, and the number that are established by the CICS region. The SESSNBR number defines the total number of sessions allowed for this connection. The WINNER number defines the sessions that are established by the CICS region. It is recommended that you set the WINNER numbers to be the remainder of the MAXIMUM SESSIONS after you define the number of WINNER numbers needed by the CRM.

Listing 2-3 Example CICS Session Definition

>     DEFINE SESSION(BEA1)
>            GROUP(BEA)
>            CONNECTION(BEA1)
>            DESCRIPTION(SESSIONS FOR CRM1 TO ACCESS THIS CICS)
>            PROTOCOL(APPC)
>            AUTOCONNECT(YES)
>            MODENAME(SMSNA100)
>            MAXIMUM(20,10)

Step 5: Install the CICS Connection and Session Definitions

To install the resource definitions, put them on the host in a separate group. You may use the CEDA INSTALL command to install the group to CICS.

For example:

CEDA INSTALL GROUP(BEA)

Note: The CRM cannot connect to the CICS region until the resource definitions are installed and ready for service by CICS.

Step 6: Verify Connection and Session Status

After you have installed the resource definitions, you can verify the status of connections and sessions using the CICS/ESA system commands shown in Listing 2-4.

Listing 2-4 Example Commands for Viewing Connection and Session Status

>     CEMT I CONN(BEA1) **View the status of the connection
>     CEMT I NET(BEAAPPL1)     **View the status of the sessions
>     CEMT I MODENAME(SMSNA100)   **View the status of the mode

WebLogic Administration Console Parameters for CICS Region Connectivity

When you configure WebLogic JAM connectivity for a CICS region in the WebLogic Administration Console, you will need to supply the following parameters:

- CICS Region

- CRM Link for a CICS Region

Note: A worksheet is available to give you a central location for gathering various connection parameters before you sit down to enter them into the WebLogic Administration Console in Step 5: Enter Connectivity Information into WebLogic Administration Console. For a copy of the worksheet, see Mainframe Connectivity Worksheet.

CICS Region

Table 2-3 shows the parameters that you will use in the WebLogic Administration Console to configure a CICS region.

Table 2-3 CICS Region Logical Unit Definition Parameters in the WebLogic Administration Console

WebLogic Administration Console Parameters | Description | Parameter Syntax
--- | --- | ---
Name | The arbitrary name of the region to which the CRM connects. | Alpha-numeric string Ex. CICS3
Logical Unit | The CICS logical unit name. The application identifier (VTAM APPLID) of the CICS region to which the CRM connects. | Eight character alpha-numeric string Ex. CICSAPPL

CRM Link for a CICS Region

Table 2-4 shows the parameters that you will use in the WebLogic Administration Console to configure a CRM Link for a CICS region. WebLogic JAM uses a CRM Link definition to store the parameters of the connection (or link) between the CRM's logical unit and the logical unit of the back-end system. These parameters determine the characteristics of the logical connection made between the CRM and the CICS region.

These values override values provided in the CRM VTAM application definition. For information on determining these values, see Determining Connection Characteristics. For specific values, ask your system administrator to retrieve the values for your CICS connection and session definitions.

Table 2-4 CICS Region CRM Link Definition Parameters in the WebLogic Administration Console

WebLogic Administration Console Parameters | Description | Parameter Syntax
--- | --- | ---
Name | The arbitrary name of the CRM Link for this CICS region. | A nine character alpha-numeric string Ex. CRM1Link
Region Name | The name of the CICS region for which you are supplying this link. This should correspond to the arbitrary name provided for the CICS region. | Alpha-numeric string Ex. CICS3
Logmode Name | The class of services for this link. This should be the MODENAME on the CICS session definition. | Alpha-numeric string Ex. SMSNA100
Maximum Sessions | Defines the total number of sessions for this link. The first value of MAXIMUM (SESSNBR, WINNER) from the CICS session definition. | Numeric value Ex. 20
Minimum Winner Sessions | The number of winner sessions pre-allocated to the CRM for this link. This value should be less than or equal to the maximum session count minus the second value of MAXIMUM(SESSNBR, WINNER) from the CICS session definition. | Numeric value Ex. 10
Security Level | The security credentials required for requests on this link. This should match the parameter value provided in the ATTACHSEC() parameter of the CICS connection definition. | Supported values available in list (Local, Identify, Verify). Ex. Local
Default User ID | A user ID to be provided for requests from applications that do not provide security credentials. This parameter is for use only with Security Level IDENTIFY. | Alpha-numeric string Ex. USER01

Connecting to an IMS Region

Connecting to an IMS region is a process that requires you to work closely with your system administrator to establish the actual connection. In order for the CRM to connect to IMS, APPC/MVS must be installed and started, and APPC/MVS must be configured with a logical unit that points to the IMS region. Then you need to gather information about that connection to input into the WebLogic Administration Console in a later step. This section provides information about the following:

- Parameters and Steps for Connecting to an IMS Region

A system administrator will most likely configure the IMS region. This section details how to configure VTAM, APPC/MVS and an IMS region to allow the CRM to connect to the IMS region via APPC.

- WebLogic Administration Console Parameters for IMS Region Connectivity

You will need certain parameters created during the connectivity process to complete the WebLogic JAM configuration using the WebLogic Administration Console. This section provides information to help you understand and capture the parameters you will need to enter into the WebLogic Administration Console.

Parameters and Steps for Connecting to an IMS Region

Use the following steps and parameters to establish connectivity for an IMS region:

- Step 1: Create a Logical Unit for an IMS Region and Add it to APPC/MVS

- Step 2: Add APPC to Your IMS Region

Step 1: Create a Logical Unit for an IMS Region and Add it to APPC/MVS

You must create a logical unit for the IMS region. In addition to each IMS region having its own logical unit, sessions must be defined that allow the CRM to allocate sessions between its logical unit and the logical unit of the IMS region.

Listing 2-5 provides a sample VTAM definition of a logical unit for an IMS region and its application major node:

Listing 2-5 VTAM Definition of a Logical Unit for an IMS Region

>     IMS VBUILD TYPE=APPL                APPLICATION MAJOR NODE
>     IMSAPPL1 APPL   ACBNAME=IMSAPPL1,        ACBNAME FOR APPC
>                    APPC=YES,
>                    DLOGMOD=SMSNA100,
>                    PARSESS=YES,
>                    SRBEXIT=YES,
>                    DSESLIM=10,
>                    DMINWNL=5,
>                    SECACPT=NONE,
>                    SYNCLVL=SYNCPT

The following parameters represent the minimum requirements for creating a VTAM APPLID for an IMS region.

  Application Program Major Node Name

  This tag identifies the node to the network.

  TYPE=APPL

  A major node should be an Application Major Node.

  ACBNAME=LU Name

  Logical unit name. This can be identical to the Application Major Node name. This is the name used for the IMS logical unit.

  APPC=YES

  Defines an APPC logical unit.

  DLOGMOD=xxx

  This is the VTAM LOGMODE name used for these sessions. An example is SMSNA100, which is the default recommended for WebLogic JAM.

  PARSESS=YES

  Allows multiple sessions between session partners.

  SECACPT=[NONE | ALREADYV | CONV]

  This parameter sets the level of security and must match a corresponding value for the CRM.

  NONE means no security credentials are provided with requests sent on the link.

  ALREADYV means that the application processing the request needs to identify the user making the request for access control to application resources. A user ID is provided with the request.

  CONV means that full security credentials are required for any requests sent on the link. A user ID and password are required for each request.

  SYNCLVL=[CONFIRM | SYNCPT]

  Determines level of transactional support. CONFIRM supports non-transactional DPL and APPC service requests only, while SYNCPT will in addition, support transactional service requests. See Administering Transactions for information on these options.

  DSESLIM=n

  Defines the total number of sessions for this connection, and the number that are established by the IMS region.

  DMINWNL=n

  Defines the sessions that are established by the IMS region. It is recommended that you set the WINNER numbers to be the remainder of the MAXIMUM SESSIONS after you define the number of WINNER numbers needed by the CRM.

After you create an IMS logical unit (VTAM APPLID), you must add it to APPC/MVS. Listing 2-6is a sample for adding the IMS logical unit to APPC/MVS.

Listing 2-6 Sample Command for Associating the Logical Unit with an IMS Region

>     LUADD ACBNAME(IMSAPPL1) BASE SCHED(IMSREG) TPDATA(SYS1.APPCTP)
>     SIDEINFO DATASET(SYS1.APPCSI)

The following parameters represent the minimum requirements for adding a logical unit to APPC/MVS.

  ACBNAME(xxx)

  This should match the ACBNAME of the IMS logical unit's VTAM APPLID.

  SCHED(xxx)

  This specifies that the IMS region is the scheduler for all requests on this logical unit.

Step 2: Add APPC to Your IMS Region

Once APPC/MVS has been set up to schedule requests to your IMS region, IMS must also be configured to activate APPC within IMS. To activate APPC in IMS you must specify APPC=Y in the IMS start-up procedure or in IMS.PROCLIB member DFSPBxxx where xxx is your RGSUF= parameter.

Listing 2-7 shows an example of the DFSPBxxx member. Listing 2-8 shows an example of the IMS PROC member.

Listing 2-7 Example DFSPBxxx member (entire member not shown)

>     APPC=Y,
>     RES=Y,
>     FRE=00030,
>     QBUF=0005,

Listing 2-8 Example IMS PROC (entire member not shown)

>     //       PROC RGN=2000K,SOUT=A,DPTY='(14,15)',
>     //            SYS=,SYS1=,SYS2=,
>     //            RGSUF=IV1,PARM1=APPC=Y,PARM2=,APPLID1=IMS61CR1,AOIS=R
>     //IEFPROC EXEC PGM=DFSMVRC0,DPRTY=&DPTY,
>     //            REGION=&RGN,
>     //            PARM='CTL,&RGSUF,&PARM1,&PARM2,&APPLID1,&AOIS'

WebLogic Administration Console Parameters for IMS Region Connectivity

When you configure WebLogic JAM connectivity for an IMS region in the WebLogic Administration Console, you will need to supply the following parameters:

- IMS Region Logical Unit

- IMS Region CRM Link

Note: A worksheet is available to give you a central location for gathering various connection parameters before you sit down to enter them into the WebLogic Administration Console in Step 5: Enter Connectivity Information into WebLogic Administration Console. For a copy of the worksheet, see Mainframe Connectivity Worksheet.

IMS Region Logical Unit

Table 2-5 shows the parameters to use in the WebLogic Administration Console to configure IMS region's logical unit. Work closely with your administrator to get the CRM logical unit defined in your SNA network.

Table 2-5 IMS Region Logical Unit Definition Parameters in the WebLogic Administration Console

WebLogic Administration Console Parameters | Description | Parameter Syntax
--- | --- | ---
Name | The arbitrary name of the region to which the CRM connects. | Alpha-numeric string Ex. IMS1
Logical Unit | The IMS logical unit name. The logical unit ID of the APPC/MVS LU for the IMS region to which the CRM connects. | Eight character alpha-numeric string Ex. IMSAPPL1

IMS Region CRM Link

Table 2-6 shows the parameters to use in the WebLogic Administration Console to configure IMS region's CRM Link. WebLogic JAM uses a CRM Link definition to store the parameters of the connection (or link) between the CRM's logical unit and the logical unit of the back-end system. These parameters determine the characteristics of the logical connection made between the CRM and the IMS region.

Table 2-6 IMS Region CRM Link Definition Parameters in the WebLogic Administration Console

WebLogic Administration Console Parameters | Description | Parameter Syntax
--- | --- | ---
Name | The arbitrary name of the CRM Link for this IMS region. | Alpha-numeric string Ex. CRM1IMS1
Region Name | The name of the IMS region for this link. This should correspond to the arbitrary name provided for the IMS region. | Alpha-numeric string Ex. IMS1
Logmode Name | The class of services for this link. This should be the DLOGMOD on the IMS session definition. | Alpha-numeric string Ex. SMSNA100
Maximum Sessions | Defines the total number of sessions for this link. The value of DSESLIM from the IMS logical unit definition. | Numeric value Ex. 20
Minimum Winner Sessions | The number of winner sessions pre-allocated to the CRM for this link. This value should be less than or equal to the maximum session count minus the value of DMINWNL from the IMS logical unit definition. | Numeric value Ex. 10
Security Level | The security credentials required for requests on this link. This should be compatible with the corresponding value provided in the SECACPT(NONE | ALREADYV | CONV) parameter of the IMS connection definition. For more information, see Step 1: Create a Logical Unit for an IMS Region and Add it to APPC/MVS. | Supported values available in drop-down list (Local, Identify, Verify). Ex. Local
Default User ID | A user ID to be provided for requests from applications that do not provide security credentials. This parameter is for use only with Security Level IDENTIFY. | Alpha-numeric string Ex. USER01

Connecting to a Batch Region

Connecting to a batch region is a process that requires you to work closely with your system administrator to establish the actual connection. WebLogic JAM can connect to APPC applications that do not run in CICS or IMS, but rather run in MVS as a started job and use APPC/MVS.

Parameters and Steps for Connecting to a Batch Region

Use the following steps and parameters to establish connectivity for a batch region:

- Step 1: Create a Logical Unit for a Batch Region and Add it to APPC/MVS

- Step 2: Add a Logical Unit for a Batch Region to APPC/MVS

Step 1: Create a Logical Unit for a Batch Region and Add it to APPC/MVS

You must create a logical unit for the batch region. In addition to each batch region having its own logical unit, sessions must be defined that allow the CRM to allocate sessions between its logical unit and the logical unit of the batch region.

Listing 2-9 provides a sample VTAM definition of a logical unit for a batch region and its application major node:

Listing 2-9 VTAM Definition of a Logical Unit for a Batch Region

>     BATCH1 VBUILD TYPE=APPL                APPLICATION MAJOR NODE
>     MVSAPPL1 APPL   ACBNAME=MVSAPPL1,        ACBNAME FOR APPC
>                    APPC=YES,
>                    DLOGMOD=SMSNA100,
>                    PARSESS=YES,
>                    SRBEXIT=YES
>                    DSESLIM=10,
>                    DMINWNL=5,
>                    SECACPT=NONE,
>                    SYNCLVL=SYNCPT

The following parameters represent the minimum requirements for creating a VTAM APPLID for a batch region.

  Application Program Major Node Name

  This tag identifies the node to the network.

  TYPE=APPL

  A major node should be an Application Major Node.

  ACBNAME=LU Name

  Logical unit name. This can be identical to the Application Major Node name. This is the name used as the batch logical unit.

  APPC=YES

  Defines an APPC logical unit.

  DLOGMOD=xxx

  This is the VTAM LOGMODE name used for these sessions. An example is SMSNA100, which is the default WebLogic JAM recommends.

  PARSESS=YES

  Allows multiple sessions between session partners.

  SECACPT=[NONE | ALREADYV | CONV]

  This parameter sets the level of security and must match a corresponding value for the CRM.

  NONE means no security credentials are provided with requests sent on the link.

  ALREADYV means that the application processing the request needs to identify the user making the request for access control to application resources. A user ID is provided with the request.

  CONV means that full security credentials are required for any requests sent on the link. A user ID and password are required for each request.

  SYNCLVL=[CONFIRM | SYNCPT]

  Determines level of transactional support.CONFIRM supports non-transactional DPL and APPC service requests only, while SYNCPT will in addition, support transactional service requests. See Administering Transactions for information on these options.

  DSESLIM=n

  Defines the total number of sessions for this connection, and the number that are established by the batch region.

  DMINWNL=n

  Defines the sessions that are established by the APPC/MVS batch region. It is recommended that you set the WINNER numbers to be the remainder of the MAXIMUM SESSIONS after you define the number of WINNER numbers needed by the CRM.

Step 2: Add a Logical Unit for a Batch Region to APPC/MVS

After you create a batch logical unit (VTAM APPLID), you must add it to APPC/MVS. Listing 2-10 is a sample for adding the batch logical unit to APPC/MVS.

Listing 2-10 Sample Command for Associating the Logical Unit with a Batch Region

>     LUADD ACBNAME(MVSAPPL1) BASE SCHED(ASCH) TPDATA(SYS1.APPCTP)
>     SIDEINFO DATASET(SYS1.APPCSI)

The following parameters represent the minimum requirements for adding a logical unit to APPC/MVS.

  ACBNAME(xxx)

  This should match the ACBNAME of the batch logical unit's VTAM APPLID.

  SCHED(xxx)

  This specifies that the APPC/MVS scheduler is the scheduler for all requests on this logical unit.

WebLogic Administration Console Parameters for Batch Region Connectivity

When you configure WebLogic JAM connectivity for a batch region in the WebLogic Administration Console, you will need to supply the following parameters:

- Batch Region Logical Unit

- Batch Region CRM Link

Note: A worksheet is available to give you a central location for gathering various connection parameters before you sit down to enter them into the WebLogic Administration Console in Step 5: Enter Connectivity Information into WebLogic Administration Console. For a copy of the worksheet, see Mainframe Connectivity Worksheet.

Batch Region Logical Unit

Table 2-7 shows the parameters to use in the WebLogic Administration Console to configure a batch region's logical unit. Work closely with your administrator to get the CRM logical unit defined in your SNA network.

Table 2-7 Batch Region Logical Unit Definition Parameters in the WebLogic Administration Console

WebLogic Administration Console Parameters | Description | Parameter Syntax
--- | --- | ---
Name | The arbitrary name of the region to which the CRM connects. | Alpha-numeric string Ex. Batch1
Logical Unit | The batch logical unit name. The application identifier of the APPC/MVS logical unit name of the batch region to which the CRM connects. | Eight character alpha-numeric string Ex. MVSAPPL1

Batch Region CRM Link

Table 2-8 shows the parameters to use in the WebLogic Administration Console to configure batch region's CRM Link. WebLogic JAM uses a CRM Link definition to store the parameters of the connection (or link) between the CRM's logical unit and the logical unit of the back-end system. These parameters determine the characteristics of the logical connection made between the CRM and the batch region.

Table 2-8 Batch Region CRM Link Definition Parameters in the WebLogic Administration Console

WebLogic Administration Console Parameters | Description | Parameter Syntax
--- | --- | ---
Name | The arbitrary name of the CRM Link for this batch region. | Alpha-numeric string Ex. CRM1Batch1
Region Name | The name of the batch region for which you are supplying this link. This should correspond to the arbitrary name provided for the batch region. | Alpha-numeric string Ex. Batch1
Logmode Name | The class of services for this link. This should be the DLOGMOD on the batch session definition. | Alpha-numeric string Ex. SMSNA100
Maximum Sessions | Defines the total number of sessions for this link. The value of DSESLIM from the batch logical unit definition. | Numeric value Ex. 20
Minimum Winner Sessions | The number of winner sessions pre-allocated to the CRM for this link. This value should be less than or equal to the maximum session count minus the value of DMINWNL from the batch logical unit definition. | Numeric value Ex. 10
Security Level | The security credentials required for requests on this link. This should be compatible with the corresponding value provided in the SECACPT(NONE | ALREADYV | CONV) parameter of the batch connection definition. For more information, see Step 1: Create a Logical Unit for a Batch Region and Add it to APPC/MVS. | Supported values available in console list (Local, Identify, Verify). Ex. Local
Default User ID | A user ID to be provided for requests from applications that do not provide security credentials. This parameter is for use only with Security Level IDENTIFY. | Alpha-numeric string Ex. USER01

Step 5: Enter Connectivity Information into WebLogic Administration Console

At this point you and your system administrators should have established all of the connections to your back-end systems using steps 1-3. You are now ready to enter this information into the WebLogic Administration Console so that WebLogic JAM components will connect to your CICS, IMS or batch regions upon startup. Use the following steps to enter connectivity parameters into the WebLogic Administration Console:

- Step 5.1: Create Region Definitions

- Step 5.2: Create CRM Definitions

- Step 5.3: Create CRM Link Definitions

Step 5.1: Create Region Definitions

The process for creating and modifying region definitions is similar for all three types of regions. For the purposes of demonstration, the steps in this section show the process of creating a CICS region.

To create a region definition, perform the following steps:

1. From the WebLogic JAM home page, click on the type of region for which you want to create a definition (batch, CICS, IMS). The List Regions Page displays.

2. Click Create a new CICS Region.

3. Enter the configuration parameters in the appropriate fields. Click Create to submit your parameters and create your CICS region.

4. Click CICS Regions in the top navigation bar to return to the Regions page.

5. Verify that your new region definition appears in the Regions page.

Note: The Service and CRM Link parameters for your new region definition are not defined yet. You will have to define these to establish connectivity. Continue to follow the steps in this section to complete the connectivity process; however, for immediate information and instructions for defining a CRM link, see Step 5.3: Create CRM Link Definitions.

Services are set up as part of integrating WebLogic applications with Mainframe applications after you have finished configuring connectivity. For detailed information about application integration with WebLogic JAM, included configuration for services, see Exposing Mainframe Applications to J2EE Clients.

Step 5.2: Create CRM Definitions

To create a CRM definition, perform the following steps:

1. From the WebLogic JAM home page, click CRMs. The List CRM page displays.

2. Click Create a new CRM.

3. Enter the configuration parameters from your Mainframe Connectivity Worksheet in the appropriate fields. Click Create to submit your parameters.

Note: Notice that the status of your newly created CRM is down. Continue to follow the steps in this section to complete the connectivity process; however, for information on starting and stopping a CRM, see Starting the CRM.

1. Click CRMs in the top navigation bar to return to the CRM page.

2. Verify that your new CRM definition appears in the CRM page.

Note: Notice that the CRM Link parameter for your new CRM definition is not defined yet. Continue to follow the steps in this section to complete the connectivity process; however, for immediate information and instructions for defining a CRM link, see Step 5.3: Create CRM Link Definitions.

Step 5.3: Create CRM Link Definitions

To create a CRM Link definition, perform the following steps:

1. From the WebLogic JAM home page, click CRMs. The List CRM page displays.

2. Click the existing CRM for which you want to establish a CRM link.

3. Click the Links tab. A page listing all of the CRM Links established for the selected CRM displays.

4. Click Create a link to a region for this CRM.

   Note: A CRM Link cannot be created unless a region exists that is not linked to this CRM.

5. Enter the configuration parameters in the appropriate fields. Click the Deployed check box if you want the link to be configured and usable at startup. Click Create to submit your parameters.

Note: Notice that the status of your newly created CRM Link is down. Continue to follow the steps in this section to complete the connectivity process.

Step 6: Define a WebLogic JAM Gateway

Once you have created definitions for the CRM, CRM Link, and region information, you need to define a WebLogic JAM Gateway. When you define a WebLogic JAM Gateway you define where the Gateway runs in your WebLogic domain, and to which CRM it will connect.

A WebLogic JAM Gateway requires a CRM; therefore, the Gateway cannot be created until a CRM exists. Also, the Gateway requires an instance of WebLogic Server that does not already have a Gateway defined for it.

A WebLogic JAM Gateway can run on any instance of WebLogic Server within your WebLogic domain. However, you can only have one Gateway defined for each instance of WebLogic Server. Multiple WebLogic JAM Gateways can be defined to connect to the same CRM, to enable features such as load balancing and failover. For detailed information on using WebLogic JAM in a multi-Gateway environment, see Connecting Multiple Gateways to a Single CRM.

To define a Gateway, follow these steps:

1. From the WebLogic JAM home page, click Gateways. The List Gateways page displays.

2. Click Create a new Gateway.

3. Enter the configuration parameters in the appropriate fields. Click the Deployed check box so it is checked.

4. Click Create to submit your parameters.

Note: A Gateway can be marked as active or inactive by selecting (or deselecting) the Deployed check box.

Note: Notice that the status of your newly created Gateway is down. Continue to follow the steps in this section to complete the connectivity process; however, for information on starting and stopping a Gateway, see Starting and Stopping a Gateway.

Step 7: Verify Your WebLogic JAM Connectivity Configuration

Now that connectivity has been configured, you may verify your configuration using the following steps:

1. Start the CRM. For detailed information and steps for starting the CRM, see Starting the CRM.

2. Start the Gateway. For detailed information and steps for starting the Gateway, see Starting and Stopping a Gateway.

3. Check CRM Link status on the List CRM Links page to see that it came up. Its status should now be up. For detailed information and steps for checking CRM links, see Modifying Your Configuration.