|
|
Oracle 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:
SYSTEM statement that defines the system configuration parameters (refer to the
System Configuration Parameters section)
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,
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]
The SYSTEM statement uses the following parameters.
Specifies the incremental amount of time (decimal, milliseconds) that TMA TCP for IMS uses to graduate from the minimum sleep time to the maximum sleep time.
TMA TCP for IMS periodically “polls” for new work. The TMA TCP for IMS product uses a graduated polling interval that is set to the minimum sleep time whenever new work is found. The polling interval is then incrementally increased by the delta time until one of the following occurs:
Avoid specifying values that cause the polling interval to be very small (or zero), or values smaller than 100 milliseconds. These values may result in polling too frequently. However, also avoid specifying values that cause the polling interval to be too large (greater than one second). These values may cause TMA TCP for IMS to be unresponsive. Varying the sleep time between 100 and 500 milliseconds in 5 millisecond increments is recommended.
|
||
|
The message level is cumulative. For example, if a message level of 4 is specified, all messages with a message level of 4 or less is logged (such as, security audit, informational, and error messages) and is also displayed on the z/OS console.
|
||
Specifies whether a
SHUTDOWN request can be made by a remote client request or as a response to a remote client request. For additional information for shutting down the system, refer to the
Monitoring Oracle TMA TCP for IMS section.
|
||
Specifies the name of the destination resolution User Exit routine in IMS that this client should use. The default is
DFSYDRU0. For a sample of the DFSYDRU0 user exit, refer to the
Sample JCL and User Exits section.
|
||
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.
The following listing contains the parameter syntax for the HOST statement.
HOST,TYPE=IMS,
IMSID=IMS-system-logical-identifier,
OTMANAME=IMS-clientname,
OTMAINPIPE=server-request-name,OTMAOUTPIPE=client-request-name]
[,NUMTPIPES=(nnnn|1)]
MAXRSPLEN=nnnn
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 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.
Listing 4-3 contains the parameter syntax for the local gateway.
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 Oracle 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.
Listing 4-4 contains the parameter syntax for the GATEWAY TYPE=REMOTE statement.
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.
CICS, tran-id - The remote gateway is an TMA TCP for CICS gateway. tran-id specifies the 1-4 character name of the TMA TCP for CICS transaction that is to be scheduled by CICS to handle incoming TCP/IP TMA requests. Refer to the Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide for more information.
|
||||
Specifies the IP address of the remote gateway. The IP address is specified using standard dotted-decimal notation (for example,
103.204.79.82). The hostname is specified as a 1-256 character string and must match the DNS entry.
|
||||
Specifies the minimum number of outbound sessions (decimal, 0-32,767) that are to be automatically started with this gateway during initialization of TMA TCP for IMS. Additional sessions (up to the maximum number of sessions specified) are started on a demand basis.
Remember that by specifying a minimum number (greater than 0) of outbound sessions for a remote gateway, you can cause outbound session to be automatically established with that gateway during initialization. This process can be helpful in verifying outbound connectivity without having to make use of test transactions.
|
||||
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.
Listing 4-5 contains the parameter syntax for the SERVICE TYPE=REMOTE statement.
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 TMA TCP for IMS as an OTMA client. |
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.
|
||||
Specifies whether the transaction specifically developed to run with version 2.1 or previous versions of TMA TCP. Specify
Yes to run transactions that were developed with version 2.1 or previous versions of TMA TCP for IMS. Specify No to run transactions that were not developed with version 2.1 of TMA TCP for IMS or previous versions of 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:
You can modify the following SYSTEM parameters dynamically using the MOD SYSTEM command.
The example in
Listing 4-7 uses the MOD SYSTEM command.
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.TMATCP.CONFIG1.
CHKPT CONFIG, FILE="BEA.TMATCP.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.TMATCP.TESTFILE1 file.
INFILE BEA.TMATCP.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.
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.
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.
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.
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.
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.
ADD HOST, TYPE=IMS,
IMSID=IMS3,
OTMANAME=IMS71SYS3,
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.
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.
MOD HOST, IMSID=IMS3, NUMTPIPES=6
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.
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.
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.
STOP SERVICE,
LMID=TUX1,
NAME=ECHO
The following tasks explain how to change an existing remote service definition.
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.
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.
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.
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.
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.
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.
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.
START SERVICE, IMSID=IMS1, NAME=ECHO
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:
|