![]() |
![]() |
![]() |
![]() |
![]() |
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.To change the configuration file without shutting down the TMA TCP for IMS system, refer to “Dynamically Configuring TMA TCP for IMS” section.
• A 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.Listing 4‑1 SYSTEM Statement SyntaxSYSTEM,
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 XCF group name for IMS and TMA TCP. This parameter is 1-8 characters and the same as GRNAME parameter in the IMS system. 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.Listing 4‑2 HOST Statement SyntaxHOST,TYPE=IMS,
IMSID=IMS-system-logical-identifier,
OTMANAME=IMS-clientname,
OTMAINPIPE=server-request-name,
OTMAOUTPIPE=client-request-name]
[,NUMTPIPES=(nnnn|1)]
MAXRSPLEN=nnnnThe HOST statement uses the following parameters.
This parameter is not related to the IMSID parameter specified in the IMS sysgen or on IMS region JCL statements. 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).Listing 4‑3 contains the parameter syntax for the local gateway.Listing 4‑3 Local Gateway SyntaxGATEWAY,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.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.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.Listing 4‑4 Remote Gateway SyntaxGATEWAY,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.
TUX - The remote gateway is an TMA TCP Gateway gateway.IMS -The remote gateway is an TMA TCP for IMS gateway.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.CICSCPT - The remote gateway is an TMA TCP for CICS gateway that uses the Interlink CPT product for TCP/IP access. 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 account ID (1-8 characters) to be used to establish a connection with the remote gateway. If an account ID is not used, ACCOUNT=* should be specified. The account ID for connection validation is obsolete. Specifies the password (1-8 characters) to be used to establish a connection with the remote gateway. If a password is not used, PASSWORD=* should be specified. The password for connection validation is obsolete. 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.Listing 4‑5 contains the parameter syntax for the SERVICE TYPE=REMOTE statement.Listing 4‑5 Remote Services SyntaxSERVICE,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.
Specifies the name (1-16 characters) by which the service is known on this machine. This is the name which must be used by an IMS client to request the service. Specifies the name (1-16 characters) by which the service is known on the remote machine. This name is the name used to invoke the service on the remote machine. 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.Listing 4‑6 Local Service SyntaxSERVICE,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 the name (1-16 characters) by which the service is known on this machine. This name is the name passed to IMS as the transaction name. Specifies the name (1-16 characters) by which the service is known on the remote machine. This name is the name passed by the remote client to invoke this service. Specifies a symbolic name that uniquely identifies an IMS system definition. This name must match a logical IMS ID (IMSID) specified in a HOST, TYPE=IMS statement. Specifies whether this service is a FastPath transactions. Specify Yes to enable FastPath transactions or No to disable FastPath transactions.Default value: No. Specifies whether to enable or disable security for this service. Specify Yes to enable security or No to disable security.Default value: No.
Note: This parameter is only valid for local service requests with a NOREPLY response. 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.Default value: No.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:
• Listing 4‑7 MOD SYSTEM Command ExampleTo 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 ExampleTo 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 ExampleYou 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.
•
•
•
•
•
•
• Listing 4‑10 ADD GATEWAY Command ExampleTo 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 ExampleTo 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 ExampleTo 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.
•
•
•
• Listing 4‑13 MOD GATEWAY Command ExampleYou 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.
•
•
• Listing 4‑14 ADD HOST Command ExampleTo 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
2. 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.Listing 4‑16 MOD HOST Command ExampleTo 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 ExampleYou 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.
•
•
•
• Listing 4‑18 ADD SERVICE Command (RemoteService) ExampleTo 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
2. 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) ExampleTo 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) ExampleYou 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.Listing 4‑22 ADD SERVICE Command (Local Service) ExampleTo 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
2. Then use the MOD SERVICE command to change any supported parameters.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) ExampleTo 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) ExampleUse 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:
•
•
•
•
• Listing 4‑26 STATUS Command Response Example