Oracle® Tuxedo® Mainframe Adapter for TCP CICS User Guide Release 10.
Tuxedo® Mainframe Adapter for TCP CICS User Guide, Release 10.0 Copyright © 2007, 2008, Oracle and/or its affiliates. All rights reserved. This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws.
Contents Introducing Tuxedo Mainframe Adapter for TCP (CICS) What You Need to Know. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1 Oracle TMA TCP for CICS Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2 Oracle TMA TCP Functionality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2 Domains-based Gateway Connectivity. . . . . . . . . . . . . . . . . . . . . . . . . . . .
Getting Started with TMA TCP for CICS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-10 Understanding How Oracle TMA TCP for CICS Works Starting the Listener Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1 Running Oracle TMA TCP for CICS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2 Initializing the Handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Securing Outbound Connections from CICS to CICS . . . . . . . . . . . . . . . . . . . . . . . . 3-5 Securing Outbound Connections from CICS to IMS . . . . . . . . . . . . . . . . . . . . . . . . . 3-5 Securing Outbound Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-6 Configuring and Administering Oracle TMA TCP for CICS Menu Navigation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Insert Outbound Service Information Screen (S1). . . . . . . . . . . . . . . . . . . . . . . . . . 4-26 Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-27 Update Outbound Service Information Screen (S2) . . . . . . . . . . . . . . . . . . . . . . . . 4-28 Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-28 Inquire Outbound Service Information Screen (S3) . . . .
Delete Inbound Service Information Screen (I4) . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-45 Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-46 The Browse Inbound Service Screen (I5) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-47 The Handler Configuration Screens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-48 PF Keys . . . . . . . . . . . . . . . . . . . . . . .
Modifying the Length of the Return Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-9 Modifying Return Message Lengths for C Programs . . . . . . . . . . . . . . . . . . . . . 5-9 Modifying Return Message Lengths for COBOL Programs . . . . . . . . . . . . . . . 5-9 Error and Informational Messages Messages Returned to the Remote Gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-1 Messages Written to the TMA TCP for CICS Log . . . . . . . . . . . . . . . .
CHAPTER 1 Introducing Tuxedo Mainframe Adapter for TCP (CICS) Oracle Tuxedo Mainframe Adapter for TCP (CICS) (hereafter referenced as TMA TCP for CICS) is a gateway connectivity feature that makes it possible for non-transactional tasks within Oracle Tuxedo regions to access services provided by CICS application programs and vice-versa. An Oracle Tuxedo region, or administrative domain, is a single computer or network of computers that shares a single Oracle Tuxedo configuration.
Programmers who work with TMA TCP should be familiar with CICS applications development.
Oracle TMA TCP for CICS Components Security The TMA TCP product grants access to Tuxedo services based on a user name supplied by CICS. The TMA TCP for CICS product can start CICS transactions or link to programs. Oracle Tuxedo provides the user ID to the TMA TCP product to check for appropriate security prior to initiating the transactions. Domain Name Server Support The TMA TCP product supports domain name server (DNS) resolution of IP addresses.
z Pre-requester z Requester Two administrative tools are also available: z An online CICS administrative tool for configuring and maintaining the TMA TCP for CICS gateway z An administrative tool (BDWN) for terminating the four programs listed above The TMA TCP for CICS Handler A TMA TCP Handler is a CICS program that communicates with the TMA TCP gateway over TCP/IP. Specifically, the Handler communicates Oracle Tuxedo requests to a CICS region.
Oracle TMA TCP for CICS Components The TMA TCP for CICS Pre-requester The Pre-Requestor program is used as an interface between your CICS client program and the TMA TCP for CICS Requester. The CICS Requester, which is described in the next section, is the program that talks with the remote Oracle Tuxedo domain. From your CICS client program you call the Pre-requester by issuing an EXEC CICS LINK.
transaction’s primary function is to shut down all the active Requesters, but one of its secondary functions is to remove all the entries from the Connection file. The Connection file must be empty before initializing activity. Processing Scenarios This section describes the TMA TCP for CICS processing scenarios.
Proces sing Sce nari os Figure 1-1 Oracle Tuxedo to TMA TCP for CICS Routing Tuxedo TMA TCP Gateway TCP/IP Network TCP/IP for MVS CICS TCP/IP Listener TMA TCP for CICS TCP/CICS Handler TCP/CICS Application Handler User App1 TCP/CICS Application Handler User App2 User App3 As Figure 1-1 shows, TMA TCP for CICS fits between the CICS user application and TCP/IP.
to the remote system. Also, when remote systems respond, TMA TCP gateway transforms these responses into replies that local client programs can process. The TMA TCP for CICS software is implemented as an ordinary CICS program which communicates with the Sockets Interface. It accepts connection requests from the TMA TCP gateway and returns standard replies.
Proces sing Sce nari os Figure 1-2 Oracle TMA Client Gateway Configuration User Program EXEC CICS LINK Pre-Requester Read CSA Read/Write TSQ TS Q User Program EXEC CICS LINK Pre-Requester Read CSA Read/Write TSQ TS Q User Program EXEC CICS LINK Pre-Requester Read CSA Read/Write TSQ Read/Set CSA GW Tuxedo BEA Control Table TS Q TS Q Requester BEA Control Table TS Q BEA Requester Common Storage Area Read/Set CSA (CSA) GW Tuxedo Figure 1-2 shows the configuration of the Oracle TMA client
Getting Started with TMA TCP for CICS The following list describes all the tasks you must perform before you can begin using TMA TCP for CICS. 1-10 z Ensure that MVS TCP/IP is installed and configured. z Ensure that the Sockets for CICS interface and supplied listener are installed and configured. The listener product comes with the Sockets for CICS interface. z From the MVS TCP/IP administrator, find out at which port and address your supplied listener should listen.
CHAPTER 2 Understanding How Oracle TMA TCP for CICS Works To understand how the Oracle Tuxedo Mainframe Adapter for TCP (CICS) (hereafter referenced as TMA TCP for CICS) product works, you should know how the product performs the following functions: z Starting the Listener Program z Running Oracle TMA TCP for CICS – Initializing the Handler – Processing Remote Service Requests – Shutting Down the Handler – Starting the Requester Program – Processing TMA TCP for CICS Originated Service Requests – Shut
Note: Before you can use TMA TCP for CICS, you must install and configure both IBM TCP/IP and the Sockets for CICS product as outlined in the documentation that accompanies those products. The Listener’s job is to wait for connection requests at a particular network address and port of your choosing. When the Listener receives a connection request it invokes the appropriate CICS program automatically, based on the name supplied as part of the Listener’s connection protocol buffer.
Ru nn ing Or acl e TM A TCP fo r CI CS 2. If the multiplex count is 1 and security is disabled, or if the service request came from a version of TMA TCP gateway prior to Version 3.0, then the following tasks occur. a. The Handler issues a CICS LINK command to execute the program specified in the TMA TCP protocol header. With the LINK command it also passes along any request data provided by the client application that made the original Oracle Tuxedo service request. b.
Using BDWN to Shut Down the Handler You can use the BDWN transaction in a CICS region with the following parameters to shut down Handlers in various ways. The command line syntax for BDWN is illustrated in the following listing. Listing 2-1 BDWN Command Line Syntax for Handlers BDWN [ALL | CLEANUP | HANDLER I | HANDLER] BDWN Shuts down all Handlers or all Requesters or both. It also frees shared memory that was allocated by a Handler that has abended without freeing the shared memory that it allocated.
Ru nn ing Or acl e TM A TCP fo r CI CS Starting the Requester Program The Requester is started automatically when the first service request for it is made by a CICS client program. At that point, the Requester establishes a connection with its remote endpoint and updates its control tables with run-time information for use by subsequent requests. If the connection with the remote endpoint is lost for any reason, the Requester attempts to re-establish the connection automatically.
z Use the supplied shutdown transaction BDWN. This method causes ALL Requesters to shut down gracefully. The name of the BDWN transaction may have been changed at your site during installation. Check with the person who installed TMA TCP for CICS at your site. Using BDWN to Shut Down the Requester You can use the BDWN transaction in a CICS region with the following parameters to shut down Requesters in various ways. The command line syntax for BDWN is illustrated in the following listing.
Transl ating Data wi th TMA TCP gatew ay Translating Data with TMA TCP gateway Due to the way TMA TCP gateway translates and converts data on the remote Oracle Tuxedo system, the CICS programmer does not need to do anything to prepare data that is destined for the remote Oracle Tuxedo system. The key to this high degree of transparency is the TMA TCP gateway configuration.
Table 2-1 Oracle Tuxedo Terminology Term Definition STRING A buffer of character data that is terminated by the first null character in the buffer. Typically, character string buffers undergo translation when sent to a system that is different from the sending system. CARRAY A CARRAY is a buffer of raw data that contains no terminating character and that undergoes no conversion or translation; the data is sent from one system to another without modification.
Transl ating Data wi th TMA TCP gatew ay Table 2-2 Data Translation Rules Field Type Translation Rules LONG Translated to S9(9) COMP FLOAT Translated to COMP-1 DOUBLE Translated to COMP-2 Note: Oracle Tuxedo provides a field type named dec_t that supports decimal values within VIEWs. The TMA TCP gateway product translates these fields into machine independent representations of packed decimals. For example, dec_t(m,n) becomes S9(2*m-(n+1))V9(n) COMP-3.
Strings and Numeric Data: A Closer Look This subsection provides suggestions that help you develop VIEW definitions for input and output buffers and records. It also explains how string data and numeric data are treated in the TMA TCP gateway environment. Including NULL Characters in String Length Calculations When you create VIEW definitions for input and output records that are used by CICS applications, do not specify an extra position for the terminating NULL characters that are used in string fields.
CHAPTER 3 Configuring the TMA TCP Security The TMA TCP product supports a security feature that allows a requester from Oracle Tuxedo services to pass a user ID through the CICS server interfaces for verification through a third-party security package.
Security Checking from UNIX to Mainframe Figure 3-1 depicts the process flow for security verifications from TMA TCP for CICS on UNIX to a mainframe. Figure 3-1 Security Checking for UNIX to Mainframe Transactions UNIX Mainframe 3 2 BEA TMA TCP Gateway Tuxedo Client 1 Handler 4 Application Handler 5 Remote Server 1. When the TMA TCP gateway client program performs a tpinit(), the user’s Tuxedo identity is validated against the tpusr file. 2.
Se rvi ce Re quest Pro cess ing wi th Securi ty 5. The Application Handler calls the specified service using system security to check authorization. Note: You may need to update your surrogate security definitions to allow the successful invocation of the CICS application program (EXEC CICS START TRANSID). See your mainframe security administrator if your site has this requirement.
4. The TMA TCP gateway maps the mainframe user ID to a Tuxedo user ID and issues the service request on behalf of that user. 5. The Tuxedo server performs access checks (based on the tpacl file) to verify that the user has access to the requested service. Setting Up Security for TMA TCP for CICS The TMA TCP for CICS product supports enhanced security.
Se tt in g Up S ecu ri ty f or TM A TCP fo r CI CS Securing Outbound Connections from CICS to UNIX Complete the following tasks to enable the security feature for each outbound connection. 1. Specify SECURITY=Y on the appropriate Requester screen. 2. Enter ACCOUNT and PASSWORD values on the appropriate Requester screen. Verify that the parameter values for ACCOUNT and PASSWORD in the Requester screen match the RMTACCT and PASSWORD values in the *FOREIGN section of the TMA TCP gateway GWICONFIG file.
Securing Outbound Services Complete the following tasks to enable the security feature for each outbound service. 1. Enable security for the corresponding outbound connection. 2. Specify SECURITY=Y on the appropriate Outbound Service screen. 3. Set up security for the appropriate users on the target system.
CHAPTER 4 Configuring and Administering Oracle TMA TCP for CICS It is the responsibility of the Oracle Tuxedo administrator to set up the configuration file, but close coordination with the Oracle Tuxedo application developer and the CICS programmer is necessary. The following subsections describe the Oracle Tuxedo Mainframe Adapter for TCP (CICS) (hereafter referenced as TMA TCP for CICS) Maintenance System.
To start the administration system, enter the transaction code as defined to CICS in the installation procedure. If the name was not changed during installation, the name of the transaction is BEAM. Menu Navigation You can access any of the following six groups of menus for maintaining connections, requesters, outbound services, the user connection account, inbound services, and Handler configuration. The following table describes how you can use each group of menus.
The Main Menu BEAPMNU BEA TMA 10.0 TCP FOR CICS BEAM M1 SELECTION SCREEN TABLE ---------------- OPERATION ----------- C R S U I H 1 2 3 4 5 - CONNECTION REQUESTER OUTBOUND SERVICE INFORMATION USER CONNECTION ACCOUNT INBOUND SERVICE INFORMATION HANDLER CONFIGURATION SELECTION: __ - INSERT UPDATE INQUIRE DELETE BROWSE (e.g. R3) ENTER: PROCESS, PF3: EXIT Usage Use the Main menu to access the screens that make up the maintenance system.
Table 4-2 Main Menu (BEAM) Sub-menu Codes Code Area of Operation I Inbound Service Information H Handler Configuration The following table lists the codes for the allowable operations. Table 4-3 Main Menu (BEAM) Operation Codes Code Allowable Operation 1 Insert 2 Update 3 Inquire 4 Delete 5 Browse Because some operations are not available in all three areas, the following table lists the valid combinations. .
The Main Menu Enter This Code To Access This Screen R5 Browse Requester S1 Insert Outbound Service Information S2 Update Outbound Service Information S3 Inquire Outbound Service Information S4 Delete Outbound Service Information S5 Browse Outbound Service Information U1 Insert User Connection Account U2 Update User Connection Account U3 Inquire User Connection Account U4 Delete User Connection Account U5 Browse User Connection Account I1 Insert Inbound Service Information I2 Upda
The Connection Screens The three screens available for maintaining connection instances are labeled Update, Inquiry, and Browse. The respective screens allow you to make an inquiry concerning a specific connection, to browse a list of all connections, or to disable/enable a connection. A connection instance is an established TCP/IP connection between a remote endpoint and a Requester or a Handler.
T he Connectio n Screens BEAPCON BEA TMA 10.0 TCP FOR CICS UPDATE BEAM C2 CONNECTION LOGICAL MACHINE NAME: ________________ TYPE: _ STATUS: MAX MSG SIZE: REQUESTER TASK NUMBER: NUMBER REQUESTS: NUMBER SUCCESS REQS: NUMBER RECONNECTS: NUMBER OPEN SOCKETS: NUMBER SESSIONS ACTIVE: ENTER: PROCESS, PF3: MENU, PF5: BROWSE Fields Field Name Description LOGICAL MACHINE NAME This field name is the gateway ID. Give it a unique name up to 16 characters.
Field Name Description MAX MSG SIZE The largest message allowed to be sent across this connection. The maximum is 32000. Example: (31000) REQUESTER TASK NUMBER The task number of the Requester that is currently associated with the LOGICAL MACHINE NAME. If there is not an active Requester, the task number is for the Requester most recently associated with that LMID. For a Handler, this field is blank; the task number is part of the LMID.
T he Connectio n Screens BEAPCON BEA TMA 10.0 TCP FOR CICS BEAM C3 INQUIRE CONNECTION LOGICAL MACHINE NAME: ________________ TYPE: _ STATUS: MAX MSG SIZE: REQUESTER TASK NUMBER: NUMBER REQUESTS: NUMBER SUCCESS REQS: NUMBER RECONNECTS: NUMBER OPEN SOCKETS: NUMBER SESSIONS ACTIVE: ENTER: PROCESS, PF3: MENU, PF5: BROWSE Fields Field Name Description LOGICAL MACHINE NAME This name is the gateway ID. Specify a unique name up to 16 characters.
Field Name Description MAX MSG SIZE The largest message allowed to be sent across this connection. The maximum is 32000. Example: (31000) REQUESTER TASK NUMBER The task number of the Requester that is currently associated with the LOGICAL MACHINE NAME. If there is not an active Requester, the task number is for the Requester most recently associated with that LMID. For a Handler, this field is blank; the task number is part of the LMID.
T he Reques ter Screens BEAPCON BEA TMA 10.
PF Keys The following table lists function keys available on various requester screens. Function Key Function ENTER Process the selection code entered PF3 Transfer to Main menu PF5 Transfer to Requester Browse screen PF7 Display the previous page of records PF8 Display the next page of records Note: If you enter data and press PF3 or PF5 before pressing ENTER, the operation process is aborted and the appropriate screen is displayed.
T he Reques ter Screens BEAPREQ BEA TMA 10.
4-14 Field Name Description ACCOUNT ID An eight-character ID. This ID must be the same ID that is used on the Oracle Tuxedo-side configuration. Coordinate with the Oracle Tuxedo Administrator. Required if there is an entry in the PASSWORD field. Example: (CICS001A) PASSWORD An eight-character password. This password must be the same as on the Oracle Tuxedo-side configuration. Coordinate with the Oracle Tuxedo Administrator. Required if there is an entry in the ACCOUNT ID field.
T he Reques ter Screens Field Name Description IDLE TIME The amount of time in seconds that a connection is idle before it is closed. IDLE TIME should be a smaller amount of time than REQ IDLE TIME. A typical setting is 30 seconds. REQ IDLE TIME The amount of time in seconds that a Requester is idle before it terminates. A typical setting is 120 seconds. LATENCY TIME Network time and system processing time added to give a true system wait time (in seconds).
BEAPREQ BEA TMA 10.
T he Reques ter Screens Field Name Description ACCOUNT ID An eight-character ID for connection security. This ID must be the same ID that is used on the Oracle Tuxedo-side configuration. Coordinate with the Oracle Tuxedo Administrator. Required if there is an entry in the PASSWORD field. Example: (CICS001A) PASSWORD An eight-character password for connection security. This password must be the same as on the Oracle Tuxedo-side configuration. Coordinate with the Oracle Tuxedo Administrator.
Field Name Description REQ IDLE TIME The amount of time in seconds that a Requester is idle before it terminates. A typical setting is 120 seconds. LATENCY TIME Network time and system processing time added to give a true system wait time (in seconds). MAX CONNS The maximum number of connections the Requester opens. The maximum value is 50 for IBM TCP/IP. QUEUE NAME 1 The unique name of a TS Q that is used for communications between the Pre-requester and the Requester.
T he Reques ter Screens BEAPREQ BEA TMA 10.
Field Name Description ACCOUNT ID An eight-character ID. This ID must be the same ID that is used on the Oracle Tuxedo-side configuration. Coordinate with the Oracle Tuxedo Administrator. Required if there is an entry in the PASSWORD field. Example: (CICS001A) PASSWORD An eight-character password. This password must be the same as the password used on the Oracle Tuxedo-side configuration. Coordinate with the Oracle Tuxedo Administrator. Required if there is an entry in the ACCOUNT ID field.
T he Reques ter Screens Field Name Description REQ IDLE TIME The amount of time in seconds that a Requester is idle before it terminates. A typical setting is 120 seconds. LATENCY TIME Network time and system processing time added to give a true system wait time (in seconds). MAX CONNS The maximum number of connections the Requester opens. The maximum value is 50 for IBM TCP/IP. QUEUE NAME 1 The unique name of a TS Q that is used for communications between the Pre-requester and the Requester.
BEAPREQ BEA TMA 10.
T he Reques ter Screens Field Name Description ACCOUNT ID An eight-character ID. This name must be the same ID that is used on the Oracle Tuxedo-side configuration. Coordinate with the Oracle Tuxedo Administrator. Required if there is an entry in the PASSWORD field. Example: (CICS001A) PASSWORD An eight-character password. This password must be the same as on the Oracle Tuxedo-side configuration. Coordinate with the Oracle Tuxedo Administrator. Required if there is an entry in the ACCOUNT ID field.
Field Name Description IDLE TIME The amount of time in seconds that a connection is idle before it is closed. IDLE TIME should be a smaller amount of time than REQ IDLE TIME. A typical setting is 30 seconds. REQ IDLE TIME The amount of time in seconds that a Requester is idle before it terminates. A typical setting is 120 seconds. LATENCY TIME Network time and system processing time added to give a true system wait time (in seconds). MAX CONNS The maximum number of connections the Requester opens.
The Outbound Se rv ice Inf or mat io n S cr een s After the entry in the SEL CDE field is validated and processed, the screen for that process is displayed and the record key appears in the LOGICAL MACHINE NAME field. BEAPREQ BEA TMA 10.
PF Keys The following table lists function keys available on various outbound service screens. Table 4-5 Function Keys Function Key Function ENTER Process the selection code entered PF3 Transfer to Main menu PF5 Transfer to Browse screen PF7 Display the previous page of records PF8 Display the next page of records Note: If you enter data and press PF3 or PF5 before pressing ENTER, the operation process is aborted and the appropriate screen is displayed.
The Outbound Se rv ice Inf or mat io n S cr een s BEAPSVC BEA TMA 10.0 TCP FOR CICS INSERT BEAM S1 OUTBOUND SERVICE INFORMATION SERVICE NAME: ________________ LOGICAL MACHINE NAME: ________________ REMOTE SERVICE NAME: ________________ SERVICE TIMEOUT(SEC): _____ SECURITY(Y/N): _ ENTER: PROCESS, PF3: MENU, PF5: BROWSE Fields Field Name Description SERVICE NAME The service name as it is known to the CICS programmer.
Update Outbound Service Information Screen (S2) Use this screen to update a record from the service name file. When the screen is first displayed, the SERVICE NAME field is unprotected. Enter the service name and press ENTER. The screen is then re-displayed with the data from the requested record and the LOGICAL MACHINE NAME, REMOTE SERVICE NAME, SERVICE TIMEOUT(SEC), and SECURITY fields are unprotected. The following message is displayed: RECORD READY FOR UPDATE.
The Outbound Se rv ice Inf or mat io n S cr een s Field Name Description REMOTE SERVICE NAME The name as it is known in the remote Oracle Tuxedo domain. SERVICE TIMEOUT The number of seconds to wait for timing out this service request. SECURITY The status of security. Y specifies that security is on and N denotes that security is off. Inquire Outbound Service Information Screen (S3) Use this screen to make an inquiry about a record from the SERVICE NAME file.
Fields Field Name Description SERVICE NAME The service name as it is known to the CICS programmer. LOGICAL MACHINE NAME This name is a symbolic name as it was defined on the Inquire Outbound Service Information screen. It denotes the remote machine on which this service should be processed. REMOTE SERVICE NAME The name as it is known in the remote Oracle Tuxedo domain. SERVICE TIMEOUT The number of seconds to wait for timing out this service request. SECURITY The status of security.
The Outbound Se rv ice Inf or mat io n S cr een s BEAPSVC BEA TMA 10.0 TCP FOR CICS DELETE BEAM S4 OUTBOUND SERVICE INFORMATION SERVICE NAME: ________________ LOGICAL MACHINE NAME: ________________ REMOTE SERVICE NAME: ________________ SERVICE TIMEOUT(SEC): _____ SECURITY(Y/N): _ ENTER: PROCESS, PF3: MENU, PF5: BROWSE Fields Field Name Description SERVICE NAME The service name as it is known to the CICS programmer.
Browse Outbound Service Information Screen (S5) Use this screen to browse the records in the service name file. If you access this screen from the Main menu the first record on file is displayed at the top of the screen. If you access this screen from the Insert, Update, Inquire, or Delete screens, the list starts with the record key received from that screen. To select a record for processing, enter a valid selection code. For example, to make an inquiry about a record, enter “3”.
The User Connection ACCOUNT Screens PF Keys The following table lists function keys available on various user account screens. Table 4-6 Function Keys Function Key Function ENTER Process the selection code entered PF3 Transfer to Main menu PF5 Transfer to Browse screen PF7 Display the previous page of records PF8 Display the next page of records Note: If you enter data and press PF3 or PF5 before pressing ENTER, the operation process is aborted and the appropriate screen is displayed.
BEAPUSR BEA TMA 10.0 TCP FOR CICS BEAM U1 INSERT USER CONNECTION ACCOUNT ACCOUNT: ________ PASSWORD: ________ ENTER: PROCESS, PF3: MENU, PF5: BROWSE Fields Field Name Description ACCOUNT An eight-character ID. This name must be the same ID that is used on the Oracle Tuxedo-side configuration. Coordinate with the Oracle Tuxedo Administrator. Required if there is an entry in the PASSWORD field. Example: (CICS001A) PASSWORD An eight-character password.
The User Connection ACCOUNT Screens After the changes are validated and processed, the screen is re-displayed and the ACCOUNT field is unprotected. BEAPUSR BEA TMA 10.0 TCP FOR CICS BEAM U2 UPDATE USER CONNECTION ACCOUNT ACCOUNT: ________ PASSWORD: ________ ENTER: PROCESS, PF3: MENU, PF5: BROWSE Fields Field Name Description ACCOUNT An eight-character ID. This name must be the same ID that is used on the Oracle Tuxedo-side configuration. Coordinate with the Oracle Tuxedo Administrator.
BEAPUSR BEA TMA 10.0 TCP FOR CICS BEAM U3 INQUIRE USER CONNECTION ACCOUNT ACCOUNT: ________ PASSWORD: ________ ENTER: PROCESS, PF3: MENU, PF5: BROWSE Fields Field Name Description ACCOUNT An eight-character ID. This name must be the same ID that is used on the Oracle Tuxedo-side configuration. Coordinate with the Oracle Tuxedo Administrator. Required if there is an entry in the PASSWORD field. Example: (CICS001A) PASSWORD An eight-character password.
The User Connection ACCOUNT Screens The following message is displayed: TO CONFIRM DELETE, PRESS ENTER: AGAIN. After you press enter to confirm the deletion, the screen is re-displayed and the ACCOUNT field is unprotected. BEAPUSR BEA TMA 10.0 TCP FOR CICS BEAM U4 DELETE USER CONNECTION ACCOUNT ACCOUNT: ________ PASSWORD: ________ ENTER: PROCESS, PF3: MENU, PF5: BROWSE Fields Field Name Description ACCOUNT An eight-character ID.
the Insert, Update, Inquire, or Delete screens, the list starts with the record key received from that screen. To select a record for processing, enter a valid selection code. For example, to make an inquiry about a record, enter “3”. If you enter more than one selection code, the first one is used, and the others are ignored. BEAPUSR BEA TMA 10.
T he I nb o u nd Se rv i c e I nf o r m at i o n S c r e e n s as to Oracle Tuxedo. For simplicity, you can make both names the same; however, different names can be used. Changes to the inbound service file are only picked up when the Handler is restarted. PF Keys The following table lists function keys available on various inbound service screens.
BEAPISN BEA TMA 10.0 TCP FOR CICS INSERT INBOUND SERVICE INFORMATION REMOTE SERVICE NAME: ________________ LOCAL SERVICE NAME: ________________ TRANSACTION NAME: ____ MAX MESSAGE SIZE: _____ SECURITY (Y/N): _ ENTER: PROCESS, PF3: MENU, PF5: BROWSE Fields 4-40 Field Name Description REMOTE SERVICE NAME The service name as it is known in the remote Oracle Tuxedo domain. LOCAL SERVICE NAME The service name as it is known to the CICS programmer.
T he I nb o u nd Se rv i c e I nf o r m at i o n S c r e e n s Field Name Description TRANSACTION NAME The name of the CICS transaction that is started to process this service request. This transaction is usually the transaction for the Application Handler program which is BEAA by default. For information about programming services without a reply, refer to the “Programming Oracle Tuxedo Mainframe Adapter for TCP (CICS)” section.
BEAPISN BEA TMA 10.0 TCP FOR CICS UPDATE INBOUND SERVICE INFORMATION REMOTE SERVICE NAME: ________________ LOCAL SERVICE NAME: ________________ TRANSACTION NAME: ____ MAX MESSAGE SIZE: _____ SECURITY (Y/N): _ ENTER: PROCESS, PF3: MENU, PF5: BROWSE Fields 4-42 Field Name Description REMOTE SERVICE NAME The service name as it is known in the remote Oracle Tuxedo domain. LOCAL SERVICE NAME The service name as it is known to the CICS programmer.
T he I nb o u nd Se rv i c e I nf o r m at i o n S c r e e n s Field Name Description TRANSACTION NAME The name of the CICS transaction that is started to process this service request. This transaction is usually the transaction for the Application Handler program which is BEAA by default. For information about programming services without a reply, refer to the “Programming Oracle Tuxedo Mainframe Adapter for TCP (CICS)” section.
BEAPISN BEA TMA 10.0 TCP FOR CICS INQUIRE INBOUND SERVICE INFORMATION REMOTE SERVICE NAME: ________________ LOCAL SERVICE NAME: ________________ TRANSACTION NAME: ____ MAX MESSAGE SIZE: _____ SECURITY (Y/N): _ ENTER: PROCESS, PF3: MENU, PF5: BROWSE Fields 4-44 Field Name Description REMOTE SERVICE NAME The service name as it is known in the remote Oracle Tuxedo domain. LOCAL SERVICE NAME The service name as it is known to the CICS programmer.
T he I nb o u nd Se rv i c e I nf o r m at i o n S c r e e n s Field Name Description TRANSACTION NAME The name of the CICS transaction that is started to process this service request. This transaction is usually the transaction for the Application Handler program which is BEAA by default. For information about programming services without a reply, refer to the “Programming Oracle Tuxedo Mainframe Adapter for TCP (CICS)” section.
BEAPISN BEA TMA 10.0 TCP FOR CICS DELETE INBOUND SERVICE INFORMATION REMOTE SERVICE NAME: ________________ LOCAL SERVICE NAME: ________________ TRANSACTION NAME: ____ MAX MESSAGE SIZE: _____ SECURITY (Y/N): _ ENTER: PROCESS, PF3: MENU, PF5: BROWSE Fields 4-46 Field Name Description REMOTE SERVICE NAME The service name as it is known in the remote Oracle Tuxedo domain. LOCAL SERVICE NAME The service name as it is known to the CICS programmer.
T he I nb o u nd Se rv i c e I nf o r m at i o n S c r e e n s Field Name Description TRANSACTION NAME The name of the CICS transaction that is started to process this service request. This service request is usually the transaction for the Application Handler program. For information about programming services without a reply, refer to the “Programming Oracle Tuxedo Mainframe Adapter for TCP (CICS)” section.
BEAPISN BEA TMA 10.
The Han dle r Conf ig ur at io n S cr een s Table 4-8 Function Keys Function Key Function ENTER Process the data entered PF3 Transfer to Main menu Note: If you enter data and press PF3 before pressing ENTER, the operation process is aborted and the appropriate screen is displayed. Update Handler Configuration Screen (H2) Use this screen to update the configuration record on the user file. If a record does not exist, one is inserted into the user file.
Fields Field Name Description SECURITY The status of gateway security. Y denotes that security is activated and N denotes that security is not activated. If this field is set to N, the ACCOUNT and PASSWORD fields are not verified prior to establishing a connection. MULTIPLEX CNT The number of concurrent incoming service requests for each Handler. MIN TIME The minimum length of time (in milliseconds) for a socket read to wait for data to be processed.
The Han dle r Conf ig ur at io n S cr een s BEAPUSR BEA TMA 10.0 TCP FOR CICS BEAM H3 INQUIRE HANDLER CONFIGURATION SECURITY: Y MULTIPLEX COUNT: 99 MIN TIME (MILLISECS): 20 MAX TIME (MILLISECS): 30 DELTA TIME (MILLISECS): 5 IDLE TIME (SECONDS): 0 ENTER: PROCESS, PF3: MENU Fields Field Name Description SECURITY The status of gateway security. Y denotes that security is activated and N denotes that security is not activated.
Field Name Description DELTA TIME The time increase (in milliseconds) from MIN TIME to MAX TIME. IDLE TIME The amount of time in seconds a program is idle before it terminates. Dynamically Configuring TMA TCP for CICS Dynamic configuration means that new configuration information affects currently running Handlers or Requesters without shutting them down. The new configuration information also affects Handlers and Requesters that are started after the information is entered.
Administering the Gateways necessary task, U1 to insert, U2 to update, or U4 to delete. For field definitions, refer to the “The User Connection ACCOUNT Screens” section. Note: Changes to the User Connection Accounts do not affect Handlers that are currently connected, but only Handlers that connect after the change is made. Modifying Connections You can dynamically configure the status of a connection.
4-54 Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide
CHAPTER 5 Programming Oracle Tuxedo Mainframe Adapter for TCP (CICS) The following subsections identify issues that CICS programmers should be aware of when they develop or modify application programs that operate with Oracle Tuxedo Mainframe Adapter for TCP (CICS) (hereafter referenced as TMA TCP for CICS): z Client Application Considerations z Server Application Considerations Client Application Considerations The following sections identify issues that CICS programers should be aware of when they
Making Calls from a CICS Client Program To make a service call from a CICS program to a remote Oracle Tuxedo domain, make an EXEC CICS LINK call to the Pre-requester. The service you want to access must be configured by the Oracle TMA Administrator, but from a programming point of view the LINK call is all you need. The following COBOL record is in the COBOL copybook client.cbl. Listing 5-1 COBOL Record 01 REQUEST-RECORD. 05 REQUEST-HEADER. 10 DATALEN PIC S9(08) COMP.
Cli ent Applic ation Considerations CLIENTHDR CltHdr; /*HEADER */ char Request_data[MAX_DATA_LENGTH]; } CMAREA; /* REQUEST DATA */ The variables in the previous COBOL and C examples are defined as follows. DataLen The length of the data in the Request_data field. SvcName The service request name (ask the administrator for the names). RequestCd A predefined numeric value that indicates the type of call this is. BEA_REQUEST_NORESPONSE - Value is 7. A No Reply Service Request.
Table 5-2 Return Codes 5-4 Code Value BEA-NORMAL +0. BEA-ERR-LENGTH +1. BEA-ERR-MISSING-SRV-NAME +2. BEA-ERR-REQ-CODE +3. BEA-ERR-SRC-NOT-FOUND +4. BEA-ERR-READ-UMT +5. BEA-ERR-SERVER +6. BEA-ERR-POST +7. BEA-ERR-CANCEL +8. BEA-ERR-WAIT +9. BEA-ERR-LMID-NOT-FOUND +10. BEA-ERR-START-TRANSID +11. BEA-ERR-DISABLE-ACQUIRING +12. BEA-ERR-DISABLE-NOT-FND +13. BEA-ERR-DISABLE-NOT-RESPOND +14. BEA-ERR-DISABLE +15. BEA-ERR-ALLOC +16. BEA-ERR-TIMEOUT +17. BEA-ERR-TSQ +18.
Cli ent Applic ation Considerations ReqReturnCd This code is the return code from the Oracle Tuxedo Domain. See the Tuxedo documentation for a complete list of Tuxedo error codes Request_data This area is the area where request data gets placed and in which your returned data arrives. The length depends on how long this particular service is configured. Check with the administrator for each service. The maximum value is 32000. Examples The following sample is an example of a COBOL CICS client program.
MOVE 'TOLOWER' TO WC-SVCNAME. MOVE +5 TO WC-REQUESTCD. MOVE 'THIS IS A TEST' TO WC-REQDATA. EXEC CICS LINK PROGRAM('BEAPRERQ') COMMAREA(WS-COMMAREA) LENGTH(LENGTH OF WS-COMMAREA) END-EXEC. IF RETURNCD = 0 MOVE 'SUCCESSFUL CALL, RETURN DATA IS IN WC-DATA' TO MSG-DATA ELSE MOVE 'PROCESS ERROR OCCURRED, RETURN CODE EQUAL ' TO MSG-DATA MOVE RETURNCD TO M-RCDE END-IF. EXEC CICS SEND TEXT FROM(MSG-AREA) LENGTH(47) ERASE TERMINAL FREEKB CURSOR(0) END-EXEC. A200-EXIT. EXEC CICS RETURN END-EXEC.
Cli ent Applic ation Considerations EXEC CICS LINK PROGRAM("PREREQ") COMMAREA(&carea) LENGTH(lmsg) RESP(resp) RESP2(resp2); if(carea.CltHdr.ReturnCd || carea.CltHdr.ReqReturnCd) process error; else successful call, returned data is in Request_data; Note: C Programmers, do not include the NULL terminator on any strings. In the previous example, the memxxx calls were used instead of the strxxx calls. This example is typical when using C and CICS together.
detection of problems. This configuration parameter is set in the remote TMA TCP gateway system; discuss any changes you want to make with the administrator of that system. Problems with requests that originate in the CICS region are also logged to the BEALOG file. Additionally, time-out periods for these requests can be tuned using the TMA TCP for CICS administration tool. For more information about the blocking time-out parameter, refer to the Oracle TMA TCP gateway User Guide.
S e r v e r A pp l i c at i o n C o n s i d e r at i o n s Programming Services with a Response Service programs expected to send a response to the client use the EXEC CICS LINK command to execute. The COMMAREA option contains a pointer to the raw data; therefore, no header is sent. As a result, the request data is available to the service programs in the COMMAREA.
5-10 Oracle Tuxedo Mainframe Adapter for TCP - CICS User Guide
APPENDIX A Error and Informational Messages The following topics describe TMA TCP for CICS messages: z Messages Returned to the Remote Gateway z Messages Written to the TMA TCP for CICS Log z Codes Returned to a CICS Client Program z Informational Process Messages z Data Field Error Messages z System Error Messages Messages Returned to the Remote Gateway Most of the messages produced from Oracle Tuxedo Mainframe for TCP (CICS) (hereafter referenced as TMA TCP for CICS) are sent back to the re
Er r or an d Inf or mat ion al Me ssa ge s Message Description Goodbye. The disconnect process has completed successfully. Service svcname not found. The requested service was not found in the inbound service name file. Client has already logged in. A client process has attempted to establish a connection when a connection already existed. (The connection request protocol was resent.) Client has not logged in.
M e s s ag e s W ri tt e n t o t he T M A T C P f o r C I C S L o g Message Description Application Handler abnormally terminated. The Application Handler terminated prior to completing the service request. This message usually occurs when a service has timed out. Verify that you are not expecting a reply from a service that does not send one. Requested Service timed out. The requested service did not complete within the time provided in the message header from the remote Tuxedo gateway.
Er r or an d Inf or mat ion al Me ssa ge s Message Description Invalid password. The password specified in the TMA TCP gateway configuration file does not match the password specified when the CICS supplied listener was configured. Invalid client account. The account code specified in the TMA TCP gateway configuration file does not match the account code specified when the CICS supplied listener was configured. Data too long, please check message header.
M e s s ag e s W ri tt e n t o t he T M A T C P f o r C I C S L o g Message Description fcntl (F_GETFL) Failed. ERRNO=errno The file control function with the F_GETFL option failed in the connect socket function. Socket CREATE Failed. ERRNO=errno The Socket CREATE function failed. WRITE on Socket Failed. ERRNO=errno The Socket WRITE function failed. initapi Failed. ERRNO=errno The Socket initialization function failed. RETRIEVE Failed.
Er r or an d Inf or mat ion al Me ssa ge s Message Description Verifying User Account. The Handler is verifying that the account and password codes supplied by TMA TCP gateway on the remote Tuxedo gateway are valid. Handler initialization complete. The TMA TCP Handler has successfully initialized. Normal shutdown requested, x requests pending. The TMA TCP Handler shuts down after the currently pending requests complete. Handler exceeded maximum idle time.
Co d e s Re turne d to a CICS Client Program Message Description Unable to start transaction A CICS error occurred attempting to start the transaction. Security Violation: Invalid user for this transaction The user ID sent with a request by the client does not match the user ID set in the mainframe security for this transaction. The Handler is designed to run in the background. A user has attempted to start the Handler from a terminal. The appHandler is designed to run in the background.
Er r or an d Inf or mat ion al Me ssa ge s Message Description BEA_NORMAL Value 0 Successful Return From Service Call. BEA_ERR_LENGTH Value 1 There was an error regarding the length of the message sent or the length value specified. BEA_ERR_MISSING_SRV_NAME Value 2 A service request was made but no service name was provided. BEA_ERR_REQ_CODE Value 3 A service call was made with an invalid or missing request code.
Co d e s Re turne d to a CICS Client Program Message Description BEA_ERR_DISABLE_NOT_FND Value 13 The service name provided specifies an invalid LMID or is missing the LMID. BEA_ERR_DISABLE_NOT_RESPOND Value 14 The Requester for handling this service name is not responding. BEA_ERR_DISABLE Value 15 The LMID associated with the requested service is not enabled. BEA_ERR_ALLOC Value 16 The Pre-requester was unable to allocate the memory necessary to process a request.
Er r or an d Inf or mat ion al Me ssa ge s Informational Process Messages Message Description Action "RECORD READY FOR UPDATE" The record selected is ready to be updated. Make the changes and press ENTER to process. "UPDATE COMPLETED" The changes made to the record selected for update have been processed. Select another record to update, or press PF3 or PF5. "TO CONFIRM DELETE, PRESS ENTER:AGAIN" The record selected is ready to be deleted.
Data F ield Error Mess ages Message Description Action "INVALID LOGICAL MACHINE NAME" The LOGICAL MACHINE NAME entered is not valid. Enter a valid INVALID LOGICAL MACHINE NAME (i.e., LMIDNJ). Must not start with a space, null, or underscore. "INVALID HOST ADDRESS" The HOST ADDRESS entered is not valid. Enter a valid HOST ADDRESS (i.e., 1234.1234.99).Must not start with a space, null, or underscore. "HOST ADDRESS or DNS NAME REQUIRED" Neither the HOST ADDRESS nor the DNS NAME have been entered.
Er r or an d Inf or mat ion al Me ssa ge s Message Description Action "INVALID MAX MSG SIZE OPTIONS=(1 -> 32000)" The MAX MSG SIZE entered is not valid. Enter a valid MAX MSG SIZE (i.e., 4096) Must not start with a space, null, or underscore and must be within the range (1 -> 32000) "INVALID CONNECT RETRY LIMIT" The CONNECT RETRY LIMIT entered is not valid. Enter a valid CONNECT RETRY LIMIT (i.e., 10) Must not start with a space, null, or underscore.
System Error Mess ages Message Description Action "INVALID SERVICE TIMEOUT(SEC)" The SERVICE TIMEOUT(SEC) entered is not valid. Enter a valid SERVICE TIMEOUT(SEC) (i.e. 30). Must not start with a space, null, or underscore. "INVALID STATUS OPTIONS=(E ENABLE, D DISABLE, A ABORT)" The STATUS entered is not valid. Enter a valid STATUS. See OPTIONS=. "INVALID OPTION=(E ENABLE, D DISABLE)" The AUTO ENABLE LMID (E|D) option entered is not valid or is empty. Enter a valid option (E or D).
Er r or an d Inf or mat ion al Me ssa ge s Message Description Action "INVREQ" Refer to the CICS Application Reference Manual. Contact your system administrator. "IOERR" Refer to the CICS Application Reference Manual. Contact your system administrator. "LENGERR" Refer to the CICS Application Reference Manual. Contact your system administrator. "MAPFAIL" Refer to the CICS Application Reference Manual. Contact your system administrator. Check the Mapset status via CEMT.
