HOME | SEARCH | CONTACT | PDF FILES | WHAT'S NEW
TABLE OF CONTENTS | PREVIOUS TOPIC | NEXT TOPIC | GLOSSARY | INDEX
|
|
|
BEA eLink TCP for IMS 3.1 Information Center |
|
HOME | SEARCH | CONTACT | PDF FILES | WHAT'S NEW |
||
|
TABLE OF CONTENTS | PREVIOUS TOPIC | NEXT TOPIC | GLOSSARY | INDEX |
||
BEA eLink for Mainframe TCP for IMS (hereafter referenced as eLink 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 eLink 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 eLink TCP for IMS system, refer to "Dynamically Configuring eLink TCP for IMS" section.
The configuration file includes the following information:
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.
The following listing contains the parameter syntax for the SYSTEM statement.
System Configuration Parameters
Syntax of the SYSTEM Statement
Listing 4-1
SYSTEM Statement Syntax
SYSTEM,
SLEEPTIME=(sleep-min,sleep-max,sleep-delta),
OTMACLIENT=eLink-clientname],
OTMAGROUP=XCF-groupname]
[,OTMASECURITY={Yes|No}]
[,MSGLEVEL={msg-level|4}]
[,CLIENTSHUTDOWN={Yes|No}]
[,IDLETIMEOUT={nn|0}]
[,CHKPFREQ={nn|0}]
[,DRUEXIT=exit-name|DFSYDRU0]
[,SPARESOCKETS=nn|0]
Note: The CHKPFREQ parameter is for BMP only and cannot be used with OTMACLIENT, OTMAGROUP, and OTMASECURITY.
The OTMACLIENT and OTMAGROUP parameters are only required when using eLink TCP for IMS as an OTMA client. Do not specify these parameters at all if you are running eLink TCP for IMS as a BMP.
The SYSTEM statement uses the following parameters.
IMS host systems that service IMS requests are defined with the HOST TYPE=IMS statement. This statement is only used when running eLink TCP for IMS as an OTMA client.
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)]
The HOST statement uses the following parameters.
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 gateway. Each GATEWAY TYPE=LOCAL statement defines a specific IP address and port number through which eLink 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 "Example Configuration Files."
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}]
The GATEWAY TYPE=LOCAL statement uses the following parameters.
A remote gateway is another BEA eLink gateway (TUX, CICS, or IMS) to which eLink TCP for IMS can be connected by one or more TCP/IP connections. A remote gateway definition defines the access points that eLink 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 eLink 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 eLink TCP for IMS cannot establish outbound connections with remote gateways, and therefore cannot process IMS client requests.
The eLink TCP for IMS software can optionally be configured to supply a valid account ID and/or password when establishing an outbound session with a remote gateway.
For examples of the GATEWAY TYPE=REMOTE statement, refer to "Example Configuration Files."
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}]
The GATEWAY TYPE=REMOTE statement uses the following parameters.
A remote service is a service offered by a remote gateway to which eLink 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, eLink 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 "Example Configuration Files."
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}]
The SERVICE TYPE=REMOTE statement uses the following parameters.
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.
Listing 4-6 contains the parameter syntax for the SERVICE TYPE=LOCAL statement.
Note: SERVICE TYPE=LOCAL statements are only used when running eLink 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]
The LOCAL SERVICES statement uses the following parameters.
The eLink 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 eLink TCP for IMS gateway configuration dynamically:
You can modify the following SYSTEM parameters dynamically using the MOD SYSTEM command.
Modifying SYSTEM Parameters
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.
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.ELINK.CONFIG1.
Listing 4-8 CHKPT CONFIG Command Example
CHKPT CONFIG, FILE="BEA.ELINK.CONFIG1"
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.ELINK.TESTFILE1 file.
Listing 4-9 INFILE Command Example
INFILE BEA.ELINK.TESTFILE1
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.
To add a gateway to the current configuration, use the ADD GATEWAY command. The following GATEWAY statement parameters are supported with this command.
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
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
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
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.
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
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.
Note: The HOST commands apply for running OTMA only.
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.
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=IMS61SYS3,
OTMAINPIPE=SYS3,
OTMAOUTPIPE=SYS3OUT,
NUMTPIPES=5
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
The following tasks explain how to change an existing host.
The following HOST statement parameters are modifiable with this command.
The example in Listing 4-16 uses the MOD HOST command.
Listing 4-16
MOD HOST Command Example
MOD HOST, IMSID=IMS3, NUMTPIPES=6
To stop a host, use the STOP HOST command with the IMSID parameter. 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"Error and Informational Messages." ) 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
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.
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.
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
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
The following tasks explain how to change an existing remote service definition.
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
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
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.
Note: The local service commands apply for running OTMA only.
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.
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
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
The following tasks explain how to change an existing local service definition.
The following SERVICE TYPE=LOCAL statement parameters can be modified with this command.
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
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
Use the STATUS command to display the status of the eLink 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:
Listing 4-26
STATUS Command Response Example
BEA2128I XCF Status with IMS Client IMS61CR1 = Active
BEA2128I XCF Status with IMS Client IMS61CR2 = Active
BEA2184I XCF Messages Received = 4
BEA2183I Messages Processed = 0
BEA2185I MCBs: Allocated = 771 Assigned = 0
BEA2186I Services: Remote = 7 Local = 6