IMS User Guide

Get Adobe Reader

Configuring BEA TMA TCP for IMS

BEA Tuxedo Mainframe Adapter for TCP (IMS) (hereafter referenced as TMA TCP for IMS) makes use of a configuration file that is read and processed at runtime to establish the processing environment. The configuration file is a simple, plain-text file that a systems programmer can edit easily to define and alter the configuration.

The configuration is defined in terms of the local (IMS) gateways, one or more remote gateways (for example, CICS), and one or more remote services offered by various remote gateways to which TMA TCP for IMS can have access. When using the OTMA client, you must configure local services as well.

To change the configuration file without shutting down the TMA TCP for IMS system, refer to Dynamically Configuring TMA TCP for IMS section.

The configuration file includes the following information:

• A SYSTEM statement that defines the system configuration parameters (refer to the System Configuration Parameters section)
• Statements that define one or more IMS host systems (OTMA only) with which TMA TCP for IMS establishes communications (refer to the Defining the Local Host section)
• Statements that define one or more local gateways (refer to the Defining the Local Gateway section)
• Statements that define one or more remote gateways with which TMA TCP for IMS can establish connections and exchange requests and responses (refer to the Defining Remote Gateways section)
• Statements that define one or more services offered by remote gateways that can be requested by IMS clients of TMA TCP for IMS (refer to the Defining Remote Services section)
• Statements that define one or more services offered by local IMS Hosts (OTMA only) that can be requested by remote clients of TMA TCP for IMS (refer to the Defining Local Services section)
• Security information when running as an OTMA client (refer to the Dynamically Configuring TMA TCP for IMS section)

 

---

System Configuration Parameters

System configuration parameters are defined by the SYSTEM statement. Only one SYSTEM statement is allowed, and it should be the first statement in the configuration file. See Listing 4-1 for parameter syntax.

Syntax of the SYSTEM Statement

The following listing contains the parameter syntax for the SYSTEM statement.

Listing 4-1 SYSTEM Statement Syntax

SYSTEM,
	SLEEPTIME=(sleep-min,sleep-max,sleep-delta),
	OTMACLIENT=TMA-clientname],
	OTMAGROUP=XCF-groupname]
	[,OTMASECURITY={Yes|No}]
	[,MSGLEVEL={msg-level|4}]
	[,CLIENTSHUTDOWN={Yes|No}]
	[,IDLETIMEOUT={nn|0}]
	[,DRUEXIT=exit-name|DFSYDRU0]
	[,SPARESOCKETS=nn|0]

Description of SYSTEM Parameters

The SYSTEM statement uses the following parameters.

 

 

---

Defining the Local Host

IMS host systems that service IMS requests are defined with the HOST TYPE=IMS statement. This statement is only used when running TMA TCP for IMS as an OTMA client.

Syntax of the HOST Statement

The following listing contains the parameter syntax for the HOST statement.

Listing 4-2 HOST Statement Syntax

HOST,TYPE=IMS,
	IMSID=IMS-system-logical-identifier,
	OTMANAME=IMS-clientname,
	OTMAINPIPE=server-request-name,
	OTMAOUTPIPE=client-request-name] 
	[,NUMTPIPES=(nnnn|1)]
	MAXRSPLEN=nnnn

Description of the Parameters

The HOST statement uses the following parameters.

 

 

---

Defining the Local Gateway

The local (IMS) gateway defines the access points that remote gateways can use to connect to the IMS gateway.

The local gateway can be defined as having a single physical IP address and port number, or multiple physical IP addresses and/or port numbers. Furthermore, each physical port can be defined as accepting one or more concurrent inbound TCP/IP connections from remote gateways.

One or more GATEWAY TYPE=LOCAL statements must exist in the configuration file to define the local gateways. Each GATEWAY TYPE=LOCAL statement defines a specific IP address and port number through which TMA TCP for IMS accepts inbound connection requests from remote gateways. Inbound connections are used by a remote gateway to send client requests to the IMS gateway for processing by IMS server transactions. Each local gateway (as defined by a GATEWAY TYPE=LOCAL statement) must have a unique logical machine ID (a symbolic name used to identify a gateway).

Remote systems attempting to establish an inbound session with the local gateway can optionally be required to supply a valid account ID and/or password.

For sample configurations, refer to the Example Configuration Files section.

Syntax of the GATEWAY TYPE=LOCAL Statement

Listing 4-3 contains the parameter syntax for the local gateway.

Listing 4-3 Local Gateway Syntax

GATEWAY,TYPE=LOCAL,
	LMID=logical-machine-id,
	PORT=port-number,
	ACCOUNT={account-id|*},
	PASSWORD={password|*}
	[,HOSTADDR=(ip-address|hostname)]
	[,MAXMSGLEN={max-message-length|2048}]
	[,SESSIONS={(startup-sessions,max-sessions)|1}]
	[,IDLETIMEOUT={nn|0}]
	[,MULTIPLEX={nn|1}]

Description of GATEWAY TYPE=LOCAL Parameters

The GATEWAY TYPE=LOCAL statement uses the following parameters.

 

 

---

Defining Remote Gateways

A remote gateway is another BEA Tuxedo Mainframe Adapter gateway (TUX, CICS, or IMS) to which TMA TCP for IMS can be connected by one or more TCP/IP connections. A remote gateway definition defines the access points that TMA TCP for IMS uses to connect to the remote gateway.

The remote gateway is defined by its IP address and port number. The remote gateway may be defined as accepting one or more concurrent outbound TCP/IP connections initiated by the local (IMS) gateway. Outbound connections are used by the IMS gateway to send IMS client requests to a remote gateway for processing by the requested service.

One or more GATEWAY TYPE=REMOTE statements are used in the configuration file to define remote gateways. Each GATEWAY TYPE=REMOTE statement defines the IP address and port number that TMA TCP for IMS uses to establish an outbound connection with a remote gateway. The GATEWAY TYPE=REMOTE statement also identifies a remote gateway by a unique logical machine ID.

The configuration file may contain multiple GATEWAY TYPE=REMOTE statements, each defining a different remote gateway. If no GATEWAY TYPE=REMOTE statements are present, then TMA TCP for IMS cannot establish outbound connections with remote gateways, and therefore cannot process IMS client requests.

The TMA TCP for IMS software can optionally be configured to supply a valid account ID and valid password when establishing an outbound session with a remote gateway.

For examples of the GATEWAY TYPE=REMOTE statement, refer to the Example Configuration Files section.

Syntax of the GATEWAY TYPE=REMOTE Statement

Listing 4-4 contains the parameter syntax for the GATEWAY TYPE=REMOTE statement.

Listing 4-4 Remote Gateway Syntax

GATEWAY,TYPE=(REMOTE,{TUX|IMS|CICS,tran-id|CICSCPT}),
       LMID=logical-machine-id,
       HOSTADDR=(ip-address|hostname),
       PORT=port-number,
       ACCOUNT={account-id,*},
       PASSWORD={password,*}
       [,MAXMSGLEN=max-message-length|2048]
       [,SESSIONS=(min-sessions),(max-sessions)]
       [,MULTIPLEX={nn|0}]
       [,IDLETIMEOUT={nn|0}]

Description of GATEWAY TYPE=REMOTE Parameters

The GATEWAY TYPE=REMOTE statement uses the following parameters.

 

 

---

Defining Remote Services

A remote service is a service offered by a remote gateway to which TMA TCP for IMS has access. IMS client transactions can make requests for services offered by remote gateways.

One or more SERVICE TYPE=REMOTE statements are used in the configuration file to define remote services. Each SERVICE TYPE=REMOTE statement defines the local service name (used by the IMS client transaction to request the service), the remote service name (used to invoke the service on the remote system), and the logical machine ID of a remote gateway that offers the service. There must be a corresponding GATEWAY TYPE=REMOTE statement in the configuration file for the specified logical machine ID.

The configuration file can contain multiple SERVICE TYPE=REMOTE statements for a given (local) service name, each pointing to a different logical machine ID (that is, remote gateway). In this case, TMA TCP for IMS distributes requests for the service among the available service providers, thus maximizing throughput during busy periods.

For examples of this statement, refer to the Example Configuration Files section.

Syntax of the SERVICE TYPE=REMOTE Statement

Listing 4-5 contains the parameter syntax for the SERVICE TYPE=REMOTE statement.

Listing 4-5 Remote Services Syntax

SERVICE,TYPE=REMOTE,
       NAME=(local-service-name,remote-service-name),
       LMID=logical-machine-id
       [,TIMEOUT={timeout|30}]

Description of SERVICE TYPE=REMOTE Parameters

The SERVICE TYPE=REMOTE statement uses the following parameters.

 

 

---

Defining Local Services

A service offered by a local IMS host is defined by a SERVICE TYPE=LOCAL statement. There can be multiple SERVICE TYPE=LOCAL statements and multiple statements defining the same service, provided each specifies a different local IMSID.

Syntax of the SERVICE TYPE=LOCAL Statement

Listing 4-6 contains the parameter syntax for the SERVICE TYPE=LOCAL statement.

Note: SERVICE TYPE=LOCAL statements are only used when running TMA TCP for IMS as an OTMA client.

Listing 4-6 Local Service Syntax

SERVICE,TYPE=LOCAL,
       NAME=(local-service-name,remote-service-name),
       IMSID=logical-IMS-id,
	[,V21COMPAT={Yes|No}]
	[,FASTPATH={Yes|No}]
	[,SECURITY={Yes|No}]
	[,RESPONSE=remote-service-name]

Description of Parameters

The LOCAL SERVICES statement uses the following parameters.

 

 

---

Dynamically Configuring TMA TCP for IMS

The TMA TCP for IMS product makes use of a configuration file that is read and processed at runtime to establish the processing environment. The configured parameters can be modified while the gateway is running. You can make the following changes to the TMA TCP for IMS gateway configuration dynamicallyby entering the commands on TCP Outstanding WTOR:

• Modifying SYSTEM Parameters
• Writing the Configuration to a File
• Processing a File
• Changing Gateway Configurations
• Changing Remote Service Definitions
• Display Status Information

Modifying SYSTEM Parameters

You can modify the following SYSTEM parameters dynamically using the MOD SYSTEM command.

• SLEEPTIME
• MSGLEVEL
• CLIENTSHUTDOWN

The example in Listing 4-7 uses the MOD SYSTEM command.

Listing 4-7 MOD SYSTEM Command Example

MOD SYSTEM, SLEEPTIME=(150,500,5), MSGLEVEL=4, CLIENTSHUTDOWN=NO

For parameter descriptions and syntax, refer to the Description of SYSTEM Parameters section.

Writing the Configuration to a File

To write the current configuration to a file, use the CHKPT CONFIG command with a fully qualified file name. The example in Listing 4-8 saves the current configuration to a file named BEA.TMATCP.CONFIG1.

Listing 4-8 CHKPT CONFIG Command Example

CHKPT CONFIG, FILE="BEA.TMATCP.CONFIG1"

Processing a File

To process a file containing commands, use the INFILE command with a fully qualified file name. The example in Listing 4-9 processes the BEA.TMATCP.TESTFILE1 file.

Listing 4-9 INFILE Command Example

INFILE BEA.TMATCP.TESTFILE1

Changing Gateway Configurations

You can dynamically change gateway configurations by adding a new gateway, modifying an existing gateway definition, starting a gateway, and stopping a gateway. For parameter descriptions and syntax, refer to the Description of GATEWAY TYPE=LOCAL Parameters and Description of GATEWAY TYPE=REMOTE Parameters sections.

Adding a Gateway

To add a gateway to the current configuration, use the ADD GATEWAY command. The following GATEWAY statement parameters are supported with this command.

• TYPE
• LMID
• PORT
• ACCOUNT
• PASSWORD
• HOSTADDR
• MAXMSGLEN
• SESSIONS
• MULTIPLEX

The example in Listing 4-10 uses the ADD GATEWAY command.

Listing 4-10 ADD GATEWAY Command Example

ADD GATEWAY, TYPE=LOCAL,
    LMID=IMS1,
    PORT=4500,
    ACCOUNT=ACCT101,
    PASSWORD=PSWD101,
    HOSTADDR=128.0.0.1,
    MAXMSGLEN=2048,
    SESSIONS=5,
    MULTIPLEX=3

Starting a Gateway

To start a gateway, use the START GATEWAY command with the LMID parameter. The example in Listing 4-11 starts the OS3901 gateway.

Listing 4-11 START GATEWAY Command Example

START GATEWAY, LMID=OS3901

Stopping a Gateway

To stop a gateway, use the STOP GATEWAY command with the LMID parameter. Use the IMMED=YES parameter to stop the gateway immediately without waiting for requests in progress to complete. Outstanding requests are sent an error message and all gateway connections are closed. Use the IMMED=NO to allow the gateway to complete transaction processing and then shutdown. While waiting, the gateway does not accept any new requests. IMMED=NO is the default. The example in Listing 4-12 stops the OS3901 gateway after transaction processing completes.

Listing 4-12 STOP GATEWAY Command Example

STOP GATEWAY, LMID=OS3901

Modifying an Existing Gateway

To change an existing gateway, stop the gateway first. Then use the MOD GATEWAY command to change any supported parameter definitions. You must specify an existing LMID for the MOD GATEWAY command. The following GATEWAY statement parameters are supported with this command.

• LMID
• ACCOUNT
• PASSWORD
• MAXMSGLEN
• SESSIONS

The example in Listing 4-13 uses the MOD GATEWAY command.

Listing 4-13 MOD GATEWAY Command Example

MOD GATEWAY, LMID=SUN2, ACCOUNT=ACCT102, PASSWORD=PSWD102, MAXMSGLEN=2048

Changing IMS Host Configurations

You can dynamically change IMS host configurations by adding a new host, modifying an existing host definition, starting a host, and stopping a host. For parameter descriptions and syntax, refer to the Description of GATEWAY TYPE=LOCAL Parameters and Description of GATEWAY TYPE=REMOTE Parameters sections.

Adding a Host

To add a host to the current configuration, use the ADD HOST command. The following HOST TYPE=IMS statement parameters are supported with this command.

• TYPE
• IMSID
• OTMANAME
• OTMAINPIPE
• OTMAOUTPIPE
• NUMTPIPES

The example in Listing 4-14 uses the ADD HOST command.

Listing 4-14 ADD HOST Command Example

ADD HOST, TYPE=IMS,
    IMSID=IMS3,
    OTMANAME=IMS71SYS3,
    OTMAINPIPE=SYS3,
    OTMAOUTPIPE=SYS3OUT,
    NUMTPIPES=5

Starting a Host

To start a host, use the START HOST command with the IMSID parameter. The example in Listing 4-15 starts the IMS3 host.

Listing 4-15 START HOST Command Example

START HOST, IMSID=IMS3

Modifying an Existing Host

The following tasks explain how to change an existing host.

Stop the host first.
Then use the MOD HOST command to change any supported parameter definitions. You must specify an IMSID for the MOD HOST command.

The following HOST statement parameters are modifiable with this command.

• OTMAINPIPE
• OTMAOUTPIPE
• NUMTPIPES

The example in Listing 4-16 uses the MOD HOST command.

Listing 4-16 MOD HOST Command Example

MOD HOST, IMSID=IMS3, NUMTPIPES=6

Stopping a Host

To stop a host, use the STOP HOST command with the IMSID parameter with a value matching the IMSID specification on the HOST, TYPE=IMS statement. Refer to the Defining the Local Gateway section. Use the IMMED=YES parameter to stop the host immediately without waiting for requests in progress to complete. Outstanding requests are sent an error message. (For a description of error messages, refer to the Error and Informational Messages section.) Use the IMMED=NO to allow the host to complete processing outstanding requests and then shutdown. While waiting, the host does not accept any new requests. IMMED=NO is the default. The example in Listing 4-17 stops the IMS3 host after transaction processing completes.

Listing 4-17 STOP HOST Command Example

STOP HOST, IMSID=IMS3

Changing Remote Service Definitions

You can dynamically change remote service definitions by adding a new service, modifying an existing service definition, or starting and stopping services. Existing services must be stopped prior to modifying them. For parameter descriptions and syntax, refer to the Description of SERVICE TYPE=REMOTE Parameters section.

Adding a Remote Service

To add a remote service to the current configuration, use the ADD SERVICE command. The following SERVICE TYPE=REMOTE statement parameters are supported with this command. TYPE, LMID, and NAME are required parameters.

• TYPE
• LMID
• NAME
• TIMEOUT

The example in Listing 4-18 uses the ADD SERVICE command to add a remote service.

Listing 4-18 ADD SERVICE Command (RemoteService) Example

ADD SERVICE, TYPE=REMOTE,
    LMID=TUX1,
    NAME=(ECHO,ECHO),
    TIMEOUT=60

Stopping a Remote Service

To stop a remote service, use the STOP SERVICE command with the LMID and NAME parameters. In this case, the NAME parameter only specifies the local name, rather than the fully qualified (local name, remote name) syntax. Use the IMMED=YES parameter to stop the service immediately without waiting for requests in progress to complete. Outstanding requests are sent an error message. Use the IMMED=NO to allow the requests to complete processing. While waiting, the gateway does not accept any new requests. IMMED=NO is the default. The example in Listing 4-19 stops ECHO on the TUX1 gateway.

Listing 4-19 STOP SERVICE Command (Remote Service) Example

STOP SERVICE, 
    LMID=TUX1,
    NAME=ECHO

Modifying an Existing Remote Service

The following tasks explain how to change an existing remote service definition.

Stop the service first.
Then use the MOD SERVICE command to change the service information. Use the LMID and NAME parameters to specify the service you want to modify. The TIMEOUT parameter in the SERVICE TYPE=REMOTE statement is the only parameter that can be modified with this command and is required.

The example in Listing 4-20 uses the MOD SERVICE command. In this case, the NAME parameter only specifies the local name, rather than the fully qualified (local name, remote name) syntax.

Listing 4-20 MOD SERVICE Command (Remote Service) Example

MOD SERVICE,
    LMID=TUX1,
    NAME=ECHO,
    TIMEOUT=60

Starting a Remote Service

To start a service, use the START SERVICE command with the LMID and NAME parameters. In this case, the NAME parameter only specifies the local name rather than the fully qualified (local name, remote name) syntax. The example in Listing 4-21 starts the TUX1 service.

Listing 4-21 START SERVICE Command (Remote Service) Example

START SERVICE, 
    LMID=TUX1, 
    NAME=ECHO

Changing Local Service Definitions

You can dynamically change local service definitions by adding a new service, modifying an existing service definition, or starting and stopping services. Existing services must be stopped prior to modifying them. For parameter descriptions and syntax, refer to the Defining Local Services section.

Adding a Local Service

To add a local service to the current configuration, use the ADD SERVICE command. The TYPE, IMSID, and NAME are required parameters when adding a local service. The following SERVICE TYPE=LOCAL statement parameters are supported with this command.

• TYPE
• IMSID
• NAME
• SECURITY
• FASTPATH
• V21COMPAT

The example in Listing 4-22 uses the ADD SERVICE command.

Listing 4-22 ADD SERVICE Command (Local Service) Example

ADD SERVICE, TYPE=LOCAL,
    IMSID=IMS1,
    NAME=(BEASVR01,ECHO),
    SECURITY=YES,
    FASTPATH=NO,
    V21COMPAT=NO

Stopping a Local Service

To stop a local service, use the STOP SERVICE command with the IMSID and NAME parameters. In this case, the NAME parameter only specifies the remote name, rather than the fully qualified (local name, remote name) syntax. Use the IMMED=YES parameter to stop the service immediately without waiting for requests in progress to complete. Outstanding requests are sent an error message. Use the IMMED=NO to allow the requests to complete processing. While waiting, the gateway does not accept any new requests. IMMED=NO is the default. The example in Listing 4-23 stops ECHO on the IMS1 host.

Listing 4-23 STOP SERVICE Command (Local Service) Example

STOP SERVICE, IMSID=IMS1, NAME=ECHO

Modifying an Existing Local Service

The following tasks explain how to change an existing local service definition.

Stop the service first.
Then use the MOD SERVICE command to change any supported parameters.

The following SERVICE TYPE=LOCAL statement parameters can be modified with this command.

• SECURITY
• FASTPATH
• V21COMPAT

The example in Listing 4-24 uses the MOD SERVICE command. In this case, the NAME parameter only specifies the remote name, rather than the fully qualified (local name, remote name) syntax.

Listing 4-24 MOD SERVICE Command (Local Service) Example

MOD SERVICE, IMSID=IMS1, NAME=ECHO, SECURITY=YES

Starting a Local Service

To start a local service, use the START SERVICE command with the IMSID and NAME parameters. In this case, the NAME parameter only specifies the remote name, rather than the fully qualified (local name, remote name) syntax. The example in Listing 4-25 starts the ECHO service for IMS1.

Listing 4-25 START SERVICE Command (Local Service) Example

START SERVICE, IMSID=IMS1, NAME=ECHO

Display Status Information

Use the STATUS command to display the status of the TMA TCP gateway. The command displays XCF status with all IMS hosts, the number of messages processed, the number of XCF messages received, message control block usage, and service counts. The following status codes for IMS hosts can result:

• ACTIVE
• ERROR
• RESTART
• BID SENT
• UNKNOWN

Listing 4-26 STATUS Command Response Example

BEA2128I      XCF Status with IMS Client IMS71CR1 = Active
BEA2128I      XCF Status with IMS Client IMS71CR2 = Active
BEA2184I      XCF Messages Received = 4
BEA2183I      Messages Processed = 0
BEA2185I      MCBs: Allocated = 771 Assigned = 0
BEA2186I      Services: Remote = 7 Local = 6

Contact BEA    Feedback    Privacy    © 2004 BEA Systems