Oracle Audio Technologies Oracle Tuxedo manual

Orac le® T uxedo® Mainframe Adapter f or TCP CICS User Guide Release 10.0 June 20 08[...]

Tuxedo® Mainframe Adapt er for TCP CICS U ser Guide, Release 10.0 Copyright © 2007, 20 08, Oracle and/or its affilia tes. All rights reserved. This software and related documentation are prov ided under a lic ense agreement containing restri ctions on us e and disclosu re and are protected by intellectual property laws. Except as expr essl y perm[...]

OracleTuxedo Mainframe Ad apter for TCP CICS User Guid e iii Contents Introducing T uxedo Mainfr ame Adapter for TCP (CICS) What You Need to Know . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1 Oracle TMA TCP for CICS Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .[...]

iv OracleTuxedo Mainf rame Adapte r for TCP CICS User Guide Getting Started with TMA TCP for CICS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-10 Understanding How Oracle TMA TCP for CICS W o rks Starting the Listener Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1[...]

OracleTuxedo Mainframe Ad apter for TCP CICS User Guid e v Securing Outbound Connections from CIC S to CICS . . . . . . . . . . . . . . . . . . . . . . . . 3-5 Securing Outbound Connections from CIC S to IMS . . . . . . . . . . . . . . . . . . . . . . . . . 3-5 Securing Outbound Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .[...]

vi OracleTuxedo Mainf rame Adapte r for TCP CICS User Guide Insert Outbound Servi ce Information Screen (S1) . . . . . . . . . . . . . . . . . . . . . . . . . . 4-26 Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-27 Update Outbound Service Information Screen (S2) . . . . . [...]

OracleTuxedo Mainframe Ad apter for TCP CICS User Guid e vii Delete Inbound Service Information Screen (I4) . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-45 Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-46 The Browse Inbound Service Screen (I5) . . . . . . . . . [...]

viii OracleTuxedo Ma inframe Adapte r for TCP CICS User Guide 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 E[...]

Oracle Tuxe do Mainframe Ad apter for TCP CICS User Guid e 1-1 CHAPTER 1 Introducing Tuxedo Mainframe Adapter for TCP (CICS) Oracle Tuxedo Main fr am e Adapter for TCP (CICS ) (h ereafter referenced as TMA TCP for CICS) is a gateway connectivity feature that ma kes it possible for non-transactional tasks within Oracle Tuxedo regions to access serv [...]

1-2 Oracle Tuxedo Ma inframe Adapt er for TCP CI CS User Guide Programmers who work wit h TMA TCP should be familiar with CICS applications devel opment. System administ rators who work with TMA TCP should be fam iliar with the followin g concepts, tools, and procedures: z TCP/IP networking z IBM CICS Sockets Interface z Defining new resources to C[...]

Oracle TMA TCP for CICS Components Oracle Tuxedo Mainf rame Adap ter for TCP CICS User Guide 1-3 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 tr ansactions or link to program s. Oracle Tuxedo provides the user ID to the TMA TCP product to ch eck for [...]

1-4 Oracle Tuxedo Ma inframe Adapt er for TCP CI CS User Guide z Pre-requester z Requester Two administrative tool s are also available: z An online CICS administrative tool for configurin g an d mai ntaining the TMA TCP for CICS gateway z An administrative tool ( BDWN ) for term in ating the four programs listed above The TMA TCP for CICS Handler [...]

Oracle TMA TCP for CICS Components Oracle Tuxedo Mainf rame Adap ter for TCP CICS User Guide 1-5 The TMA TCP for CICS Pre-requester The Pre-Requestor program is us ed 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 re[...]

1-6 Oracle Tuxedo Ma inframe Adapt er for TCP CI CS User Guide transaction’s primary functio n is to shut down al l the active Requesters, but one of its secondary functions is to remove all the entries from the Connectio n file. The Connection file m ust be empty before initializing activity. Processing Scenarios This section describes the TMA T[...]

Processing Scenarios Oracle Tuxedo Mainf rame Adap ter for TCP CICS User Guide 1-7 Figure 1-1 Oracle Tuxedo to TMA TCP for CICS Routing As Figure 1-1 shows, TMA TCP for CICS fits between the CICS user appl icati on and TCP/IP. When Oracle Tuxedo client programs send reques ts to remote systems (in this case, CIC S) TMA TCP gateway transforms those [...]

1-8 Oracle Tuxedo Ma inframe Adapt er for TCP CI CS User Guide to the remote system. Also, when remote syst ems respond, TMA TCP g ateway transforms these responses into replies that local client pro gram s can process. The TMA TCP for CICS software is implemented as an ordinary CICS program which communicates with the Socket s Interface. It accept[...]

Processing Scenarios Oracle Tuxedo Mainf rame Adap ter for TCP CICS User Guide 1-9 Figure 1-2 Oracle TMA Client Gateway Configuration Figure 1-2 show s the confi guratio n of th e Oracle TMA client gateway. A client prog ram (your CICS program) issues an EXEC CICS LINK command to the Pre-requester. The Pre-requester verifies that the service name i[...]

1-10 Oracle Tuxedo Mainframe Adap ter for TCP CI CS User Guide Getting Started with TMA TCP for CICS The following list describes all the ta sks you mu st perform before you can begin using TMA TC P for CICS. z Ensure that MVS TCP/IP is installed and configured. z Ensure that the Sockets for CICS interf ace and supplied listener are installed and c[...]

Oracle Tuxe do Mainframe Ad apter for TCP CICS User Guid e 2-1 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 perform s the following functions: z Starting the Li stener Program z [...]

2-2 Oracle Tuxedo Ma inframe Adapt er for TCP CI CS User Guide Note: Before you can use TMA TCP for CICS, you must install and co nfigure 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 requ ests at a particular network address and port[...]

Running Oracl e TMA TCP for CI CS Oracle Tuxedo Mainf rame Adap ter for TCP CICS User Guide 2-3 2. If the multiplex count is 1 and securit y is disabled, or if the service request came from a version of TMA TCP gateway prior to V ersion 3.0, then the following tasks occur . a. The Handler issues a CICS LINK command to execute the pr ogram specified[...]

2-4 Oracle Tuxedo Ma inframe Adapt er for TCP CI CS User Guide Using BDWN to Shut Down the Handler You can use the BDWN transaction in a CICS regi on with the following parameters to shut down Handlers in various ways. The command li ne syntax for BDWN is illustrated in the followi ng listing. Listing 2-1 BDWN Command Line Syntax for Handlers BDWN [...]

Running Oracl e TMA TCP for CI CS Oracle Tuxedo Mainf rame Adap ter for TCP CICS User Guide 2-5 Starting the Requester Program The Requester is started automatically when the fi rst service request for it is made by a CICS client program. At that point, the Requester esta blishes a connection with its remote endpoint and updates its control tables [...]

2-6 Oracle Tuxedo Ma inframe Adapt er for TCP CI CS User Guide z Use the supplied shutdown transaction BD WN . 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 t he person wh o installed TMA TC P fo r CICS at your site. Using BDWN to Shut [...]

Translating Data wi th TMA TCP gateway Oracle Tuxedo Mainf rame Adap ter for TCP CICS User Guide 2-7 T ranslating Data with TMA TCP gateway Due to the way TMA TCP gateway translates an d 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 sy[...]

2-8 Oracle Tuxedo Ma inframe Adapt er for TCP CI CS User Guide Data T ranslation Rules The following table lists the data translation rules that TMA TCP gateway follow s. T able 2-1 Oracle Tuxedo T erminology Term Definition STRING A buffer of character data th at is terminated by the first null character in the buffer. Typically, char acter string[...]

Translating Data wi th TMA TCP gateway Oracle Tuxedo Mainf rame Adap ter for TCP CICS User Guide 2-9 Note: Oracle Tuxedo provides a field type named d ec_t that supports decimal values within VIEW s. The TMA TCP gateway product translates these fields into machine independent representations of packed decimals. For example, dec_t(m,n) becomes S9(2*[...]

2-10 Oracle Tuxedo Mainframe Adap ter for TCP CI CS User Guide Strings and Numeric Data: A Closer Look This subsection provides suggestions that hel p you develop VIEW definitions for input and outp ut buffers and records. It also expl ains how string data and numeric data are treated in the TMA TCP gateway environment. Including NULL Characters in[...]

Oracle Tuxe do Mainframe Ad apter for TCP CICS User Guid e 3-1 CHAPTER 3 Configuring the TMA TCP Security The TMA TCP product support s a security featur e that allows a reques ter from Oracle Tuxedo services to pass a user ID through the CICS server interfaces for verification through a third-party security package. The following topics explain th[...]

3-2 Oracle Tuxedo Ma inframe Adapt er for TCP CI CS User Guide Security Checking from UNIX to Mainframe Figure 3-1 depicts the process flow for security veri fications from TMA TCP for CICS on UNIX to a mainframe. Figure 3-1 Security Checking for UNIX to Mainframe Transactions 1. When the TMA TCP gateway cli ent program performs a tpi nit() , the u[...]

Service Request Process ing with Security Oracle Tuxedo Mainf rame Adap ter for TCP CICS User Guide 3-3 5. The Application Handler calls the specified service using system security to check authorization. Note: You may need to update your surrogate security definiti ons to all ow the successful invocation of the CICS application program ( EXEC CICS[...]

3-4 Oracle Tuxedo Ma inframe Adapt er for TCP CI CS User Guide 4. The TMA TCP gateway maps the mainframe user ID to a T uxedo user ID and issues the service request on behalf of that user . 5. The T u xedo 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[...]

Setting Up Security for TMA TCP for CI CS Oracle Tuxedo Mainf rame Adap ter for TCP CICS User Guide 3-5 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 PAS SWORD values on the appr[...]

3-6 Oracle Tuxedo Ma inframe Adapt er for TCP CI CS User Guide Securing Outbound Services Complete the following tasks to enable th e security feature for each outbound service. 1. Enable security for the corresponding outbound connection . 2. Specify SECURITY=Y on th e app ropriate Outbound Service screen. 3. Set up security for the appropriate us[...]

Oracle Tuxe do Mainframe Ad apter for TCP CICS User Guid e 4-1 CHAPTER 4 Configuring and Administering Oracle TMA TCP for CICS It is the responsibility of the Oracle Tuxedo administ rato r to set up the configuration file, but close coordination with the Oracle Tuxed o appl i cation developer and the CICS programmer is necessary. The following subs[...]

4-2 Oracle Tuxedo Ma inframe Adapt er for TCP CI CS User Guide To start the administration syst em, 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 maintainin[...]

The Main Menu Oracle Tuxedo Mainf rame Adap ter for TCP CICS User Guide 4-3 Usage Use the Main menu to access the screens that make up the maintenance sy stem. To move from the Main menu to a sub-menu, enter the appropriat e two-character code. The first character in the code denotes the area in which you want to oper ate; the second character deno[...]

4-4 Oracle Tuxedo Ma inframe Adapt er for TCP CI CS User Guide The following table lists the code s for the allowa ble operations. Because some operations are not av ailable in all three areas, the following table lists the valid combination s. . I Inbound Service Information H Handler Configuratio n T able 4-3 Main Menu (BEAM) Operation Codes Code[...]

The Main Menu Oracle Tuxedo Mainf rame Adap ter for TCP CICS User Guide 4-5 You can use the maintenance system screens to vi ew and alter a connection, but not to insert ( create ) or delete a connection. Connections are created and d eleted by TMA TCP for CICS in its normal operation. The maintenance system checks the two-character selection code [...]

4-6 Oracle Tuxedo Ma inframe Adapt er for TCP CI CS User Guide The Connection Screens The three screens available for maintaining connect ion instances are labele d Update, Inquiry, an d 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 connecti[...]

The Connection Screens Oracle Tuxedo Mainf rame Adap ter for TCP CICS User Guide 4-7 Fields BE APC ON BE A TM A 1 0. 0 T CP F OR CI CS B EA M C 2 UPDATE CONNECTION LOGIC AL MACHINE NA ME: _________ _______ TYPE: _ STATU S: MAX M SG SIZE: REQUE STER TASK NUM BER: NUMBE R REQUESTS: NUMBE R SUCCESS REQ S: NUMBE R RECONNECTS: NUMBE R OPEN SOCKET S: NUM[...]

4-8 Oracle Tuxedo Ma inframe Adapt er for TCP CI CS User Guide Inquire Connection Screen (C3) Use this screen to inquire about a record from the Connection file . When the screen is initially displayed, the LOGICAL MA CHINE NAME and TYPE fields are unprotected. Enter a valid LOGICAL MACHINE NAME (gateway ID) and TYPE and press ENTE R . The screen i[...]

The Connection Screens Oracle Tuxedo Mainf rame Adap ter for TCP CICS User Guide 4-9 Fields BE A P C O N B E A T MA 1 0 . 0 T C P F O R C I C S BE A M C 3 INQUIRE CONNECTION LOGIC AL MACHINE NA ME: _________ _______ TYPE: _ STATU S: MAX M SG SIZE: REQUE STER TASK NUM BER: NUMBE R REQUESTS: NUMBE R SUCCESS REQ S: NUMBE R RECONNECTS: NUMBE R OPEN SOC[...]

4-10 Oracle Tuxedo Mainframe Adap ter for TCP CI CS User Guide Browse Connection Screen (C5) Use this screen to browse reco rds in the Connection file and to select individual records for further processing. If you access this screen fr om the Main menu, the first record on file is displayed at the top of the screen . If you access this screen from[...]

The Requester Screens Oracle Tuxedo Mainf rame Adap ter for TCP CICS User Guide 4-11 The Requester Screens A Requester is responsible for collecting request information to be sent to the remote Oracle Tuxedo domain. The Request er establishes ne twork connectivity, tran smits data to Oracle Tuxedo, and receives data from Oracle Tuxedo. Each Request[...]

4-12 Oracle Tuxedo Mainframe Adap ter for TCP CI CS User Guide PF Keys The following table lists function keys available o n various requester screens. Note: If you enter data and press PF3 or PF5 before pressing ENTER , the op erati on process is aborted and the appropriate screen is displayed. Insert Requester Screen (R1) Use this screen to confi[...]

The Requester Screens Oracle Tuxedo Mainf rame Adap ter for TCP CICS User Guide 4-13 Fields BE A P R E Q B E A T MA 1 0 . 0 T C P F O R C I C S BE A M R 1 INSERT REQUESTER LMID: ______ __________ MULTIPLEX_CNT : __ DNS: ___ ______________ _____________ _________________ _____________ ____ HOST ADD RESS: _____ __________ PORT NUM BER: _____ MIN TIME[...]

4-14 Oracle Tuxedo Mainframe Adap ter for TCP CI CS User Guide 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 Administ rator. Required if the re is an entry in the PASSWORD field. Example: (CICS001A) PASSWORD An eight-character password. This pass[...]

The Requester Screens Oracle Tuxedo Mainf rame Adap ter for TCP CICS User Guide 4-15 Update Requester Screen (R2) Use this screen to update a record from the Reques ter file. The fields are the same as the ones on the Requester Insert screen, but on th is s creen you can change the values. When the screen is first displayed, the LMID field is unpro[...]

4-16 Oracle Tuxedo Mainframe Adap ter for TCP CI CS User Guide Fields BE A P R E Q B E A T MA 1 0 . 0 T C P F O R C I C S BE A M R 2 UPDATE REQUESTER LMID: ______ __________ MULTIPLEX_CNT : __ DNS: ___ ______________ _____________ _________________ _____________ ____ HOST ADD RESS: _____ __________ PORT NUM BER: _____ MIN TIME (MIL LISEC): _ ____ S[...]

The Requester Screens Oracle Tuxedo Mainf rame Adap ter for TCP CICS User Guide 4-17 ACCOUNT ID An eight-character ID for conn ection security. This ID must be the same ID that is used on the Or acle Tuxedo-side configuration. Coordinate with the Oracle T uxedo Administrator. Required if there is an entry in the PASSWORD field. Example: (CICS001A) [...]

4-18 Oracle Tuxedo Mainframe Adap ter for TCP CI CS User Guide Inquire Requester Screen (R3) Use this screen to make an inquiry about a record from the Requester file. The screen is initially displayed with the LOGICAL MACH INE NAME field unprotected. Enter the logical machine name and press ENTER . The screen is re-displayed with the data from the[...]

The Requester Screens Oracle Tuxedo Mainf rame Adap ter for TCP CICS User Guide 4-19 Fields BE A P R E Q BE A T M A 10 . 0 TC P F O R CI C S BE A M R 3 INQUIRE REQUESTER LMID: ______ __________ MULTIPLEX_CNT : __ DNS: ___ ______________ _____________ _________________ _____________ ____ HOST ADD RESS: _____ __________ PORT NUM BER: _____ MIN TIME ([...]

4-20 Oracle Tuxedo Mainframe Adap ter for TCP CI CS User Guide ACCOUNT ID An eight-character ID. Th is ID must be the same ID that is used on the Oracle Tuxedo-side confi guration. Coordinate with the Oracle Tuxedo Administra tor. Required if there is an entry in the PASSWORD field. Example: ( CICS001A) PASSWORD An eight-character password. This pa[...]

The Requester Screens Oracle Tuxedo Mainf rame Adap ter for TCP CICS User Guide 4-21 Delete Requester Screen (R4) Use this screen to delete a r ecord from the Reques ter file. WARNING: Deleting a Requester record can have serious ramifications. Think carefully before performing this operati on. If there are any Service records that point to this GW[...]

4-22 Oracle Tuxedo Mainframe Adap ter for TCP CI CS User Guide Fields BEAPREQ BEA TMA 10.0 TCP FOR CICS BEAM R4 DELETE REQUESTER LMID: ______ __________ MULTIPLEX_CNT : __ DNS: ___ ______________ _____________ _________________ _____________ ____ HOST ADD RESS: _____ __________ PORT NUM BER: _____ MIN TIME (MIL LISEC): _ ____ SECURITY (Y/N): _ MAX [...]

The Requester Screens Oracle Tuxedo Mainf rame Adap ter for TCP CICS User Guide 4-23 ACCOUNT ID An eight-charac ter ID. This nam e must be the same ID that is used on the Oracle Tuxedo-side configuration. Coordinate with the Orac le Tuxedo Administrator. Required if the re is an entry i n the PASSWORD field. Example: (CICS001A ) PASSWORD An eight-c[...]

4-24 Oracle Tuxedo Mainframe Adap ter for TCP CI CS User Guide Browse Requester Screen (R5) Use this screen to browse a li st of the records in the Requester file. Additionally, you can select a record for further pro cessing by entering a valid selection code in the first column of that record’s row. If you access this screen from the Main menu,[...]

The Outbound Service Infor mation Screens Oracle Tuxedo Mainf rame Adap ter for TCP CICS User Guide 4-25 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 L OGICAL MACHIN E NAME field. The Outbound Service Information Screens A service is a name associated wit[...]

4-26 Oracle Tuxedo Mainframe Adap ter for TCP CI CS User Guide PF Keys The following table lists function keys available o n various outbound service screens. Note: If you enter data and press PF3 or PF5 before pressing ENTER , the op erati on process is aborted and the appropriate screen is displayed. Insert Outbound Service Information Screen (S1[...]

The Outbound Service Infor mation Screens Oracle Tuxedo Mainf rame Adap ter for TCP CICS User Guide 4-27 Fields BE A P S V C BE A T M A 10 . 0 TC P F O R CI C S BE A M S 1 INSERT OUTBOUND SER VICE INFORMATION SERVI CE NAME: ____________ ____ LOGIC AL MACHINE NA ME: ____________ ____ REMOT E SERVICE NAM E: ____________ ____ SERVI CE TIMEOUT(SE C): _[...]

4-28 Oracle Tuxedo Mainframe Adap ter for TCP CI CS User Guide 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 E NTER . The screen is then re-displayed with the data fro m th e re[...]

The Outbound Service Infor mation Screens Oracle Tuxedo Mainf rame Adap ter for TCP CICS User Guide 4-29 Inquire Outbound Service Information Screen (S3) Use this screen to make an i nquiry about a record from t he SERVICE NAME file. The screen is initially displayed with the SERVICE NAME field unprotected. Enter th e service name and press ENTER .[...]

4-30 Oracle Tuxedo Mainframe Adap ter for TCP CI CS User Guide Fields Delete Outbound Service Information Screen (S4) Use this screen to delete reco rds from the service name file . The screen is initially displayed with the SERVICE NAME field unprotected. Type the service name and press ENTER . The screen is re-displayed with the data from the rec[...]

The Outbound Service Infor mation Screens Oracle Tuxedo Mainf rame Adap ter for TCP CICS User Guide 4-31 Fields BE A P S V C BE A T M A 10 . 0 TC P F O R CI C S BE A M S 4 DELETE OUTBOUND SER VICE INFORMATION SERVI CE NAME: ____________ ____ LOGIC AL MACHINE NA ME: ____________ ____ REMOT E SERVICE NAM E: ____________ ____ SERVI CE TIMEOUT(SE C): _[...]

4-32 Oracle Tuxedo Mainframe Adap ter for TCP CI CS User Guide Browse Outbound Service Information Screen (S5) Use this screen to browse the r ecords 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 De[...]

The User Connection ACCOUNT Screens Oracle Tuxedo Mainf rame Adap ter for TCP CICS User Guide 4-33 PF Keys The following table lists function keys available on various user account screens. Note: If you enter data and press PF3 or PF5 before pressing ENTER , th e op eration process is aborted and the appropriate screen is displayed. Insert User Con[...]

4-34 Oracle Tuxedo Mainframe Adap ter for TCP CI CS User Guide Fields Update User Connection ACCOUNT Screen (U2) Use this screen to update a record on the account file. When the screen is first displayed, the ACCOUNT field is unprotected. Ente r the account ID, and press ENTER . The screen is then re-displayed with the data from the requested recor[...]

The User Connection ACCOUNT Screens Oracle Tuxedo Mainf rame Adap ter for TCP CICS User Guide 4-35 After the changes are validated and processed, the screen is re-displayed and the ACCOUNT field is unprotected. Fields Inquire User Connection ACCOUNT Screen (U3) Use this screen to make an inquiry about a reco rd from the account file. The screen is [...]

4-36 Oracle Tuxedo Mainframe Adap ter for TCP CI CS User Guide Fields Delete User Connection ACCOUNT Screen (U4) Use this screen to delete a record from the account file. The screen is initi ally displayed with the ACCOUNT field unprotected. Type the service name and press ENTER . The screen is re-displayed with the data from the record requ ested [...]

The User Connection ACCOUNT Screens Oracle Tuxedo Mainf rame Adap ter for TCP CICS User Guide 4-37 The following message is disp layed: TO CONFIRM DELET E, PRESS ENTER: AG AIN . After you press enter to confirm the deletion, the screen is re-displayed and the AC COUNT field is unprotected. Fields The Browse User Connection ACCOUNT Screen (U5) Use t[...]

4-38 Oracle Tuxedo Mainframe Adap ter for TCP CI CS User Guide the Insert, Update, Inquire, or Delete screens, the list starts wi th 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 selectio n code, [...]

The Inbound Service Information Screens Oracle Tuxedo Mainf rame Adap ter for TCP CICS User Guide 4-39 as to Oracle Tuxedo. For simpl icity, you can m ake both names the same; however, differen t names can be used. Changes to the inbound service file are only picked up when the Handl er is restarted. PF Keys The following table lists function keys [...]

4-40 Oracle Tuxedo Mainframe Adap ter for TCP CI CS User Guide Fields BE A P I S N BE A T M A 10 . 0 TC P F O R CI C S BE A M I 1 INSE RT INBOUND S ERVICE INFORMATIO N REMOT E SERVICE NAM E: ____________ ____ LOCAL SERVICE NAME : ____________ ____ TRANS ACTION NAME: ____ MAX M ESSAGE SIZE: _____ SECUR ITY (Y/N): _ ENTER: PR OCESS, PF3: ME NU, PF5: [...]

The Inbound Service Information Screens Oracle Tuxedo Mainf rame Adap ter for TCP CICS User Guide 4-41 Update Inbound Service Information Screen (I2) Use this screen to update a record in the inbound service name file. The screen is first d isplayed with the REMOTE SERVIC E NAME field unprotected. Enter the re mote service name and press ENTER . Th[...]

4-42 Oracle Tuxedo Mainframe Adap ter for TCP CI CS User Guide Fields BEAPISN BEA TMA 10.0 TCP FOR CI CS BEA M I2 UPDA TE INBOUND S ERVICE INFORMATIO N REMOT E SERVICE NAM E: ____________ ____ LOCAL SERVICE NAME : ____________ ____ TRANS ACTION NAME: ____ MAX M ESSAGE SIZE: _____ SECUR ITY (Y/N): _ ENTER: PR OCESS, PF3: ME NU, PF5: BROW SE Field Na[...]

The Inbound Service Information Screens Oracle Tuxedo Mainf rame Adap ter for TCP CICS User Guide 4-43 Inquire Inbound Service In formation Screen (I3) Use this screen to in quire about a record i n th e inbound service name file. The screen is first displayed with the REMOTE SER VICE NAME field unprotected. Enter the rem ote service name and press[...]

4-44 Oracle Tuxedo Mainframe Adap ter for TCP CI CS User Guide Fields BEAPISN BEA TMA 10.0 TCP FOR CI CS BEA M I3 INQU IRE INBOUND S ERVICE INFORMATIO N REMOT E SERVICE NAM E: ____________ ____ LOCAL SERVICE NAME : ____________ ____ TRANS ACTION NAME: ____ MAX M ESSAGE SIZE: _____ SECUR ITY (Y/N): _ ENTER: PR OCESS, PF3: ME NU, PF5: BROW SE Field N[...]

The Inbound Service Information Screens Oracle Tuxedo Mainf rame Adap ter for TCP CICS User Guide 4-45 Delete Inbound Service Information Screen (I4) Use this screen to delete a record in the inboun d service name file. The screen is first displayed with the REMOTE SERVIC E NAME field unprotected. Enter the re mote service name and press ENTER . Th[...]

4-46 Oracle Tuxedo Mainframe Adap ter for TCP CI CS User Guide Fields BEAPISN BEA TMA 10.0 TCP FOR CI CS BEAM I4 DELE TE INBOUND S ERVICE INFORMATIO N REMOT E SERVICE NAM E: ____________ ____ LOCAL SERVICE NAME : ____________ ____ TRANS ACTION NAME: ____ MAX M ESSAGE SIZE: _____ SECUR ITY (Y/N): _ ENTER: PR OCESS, PF3: ME NU, PF5: BROW SE Field Nam[...]

The Inbound Service Information Screens Oracle Tuxedo Mainf rame Adap ter for TCP CICS User Guide 4-47 The Browse Inbound Service Screen (I5) Use this screen to browse the records in the in bound serv ice name file. If you access this screen from the Main menu, the first reco rd on file is displayed at the to p of the screen. If you access this scr[...]

4-48 Oracle Tuxedo Mainframe Adap ter for TCP CI CS User Guide The Handler Configuration Screens A Handler is responsible for receiving service requests from the remote Oracle Tuxedo domain. The Handler Configuration screens allow for dynami c manipulation of th e configuration used by all Handler programs in the system. Note: To apply changes that[...]

The Handler Conf iguration Scr eens Oracle Tuxedo Mainf rame Adap ter for TCP CICS User Guide 4-49 Note: If you enter data and press PF3 before pressing ENTER , the op eration 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 fi le. If [...]

4-50 Oracle Tuxedo Mainframe Adap ter for TCP CI CS User Guide Fields Inquire Handler Configuration Screen (H3) Use this screen to make an inquiry about the con figuration record from th e user file. The screen is displayed with the data from the requested record and all fields are protect ed . Field Name Description SECURITY The status of gateway [...]

The Handler Conf iguration Scr eens Oracle Tuxedo Mainf rame Adap ter for TCP CICS User Guide 4-51 Fields BEAPUSR BEA TMA 10 .0 TCP FOR CICS BEAM H3 I NQUIRE HANDLE R CONFIGURATION SECURIT Y: Y MULTIPL EX COUNT: 9 9 MIN TIM E (MILLISECS) : 2 0 MAX TIM E (MILLISECS) : 3 0 DELTA T IME (MILLISEC S): 5 IDLE TI ME (SECONDS): 0 ENTER: PR OCESS, PF3: ME N[...]

4-52 Oracle Tuxedo Mainframe Adap ter for TCP CI CS User Guide Dynamically Configuring TMA TCP for CICS Dynamic config urat ion means th at new confi guration information affects cu rrently running Handlers or Requesters without shutt ing th em dow n. The new configuration information also affects Handlers and Requesters that are started after the [...]

Administering the Gateways Oracle Tuxedo Mainf rame Adap ter for TCP CICS User Guide 4-53 necessary task, U1 to insert, U2 to update, or U4 to delete. For field defi nitions, 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 Han[...]

4-54 Oracle Tuxedo Mainframe Adap ter for TCP CI CS User Guide[...]

Oracle Tuxedo Mainf rame Adapter for TCP - CICS User Guide 5-1 CHAPTER 5 Programming Oracle Tuxedo Mainframe Adapter for TCP (CICS) The following subsections identify issues that CI CS programmers should be aware of when they develop or modify ap plication programs that op erate with Oracle Tuxedo Mainframe Adapter for TCP (CICS) (hereaft e r ref e[...]

5-2 Oracle Tuxedo Ma inframe Adapt e r for TCP - CICS User Guide 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 vie[...]

Client Application Considerations Oracle Tuxedo Mainframe Adapt er for TCP - CICS User Guide 5-3 CLIENTHDR C ltHdr; / *HEADER */ char Reques t_data[MAX_DAT A_LENGTH]; / * REQUEST DATA */ } CMAREA; The variables in the previous COBOL an d C examples are defined as follows. DataLen The length of th e data in the Reque st_data field. SvcName The servi[...]

5-4 Oracle Tuxedo Ma inframe Adapt e r for TCP - CICS User Guide T able 5-2 Return Codes Code Value BEA-NORMAL +0. BEA-ERR-LENGT H +1. BEA-ERR-MISSI NG-SRV-NAME +2. BEA-ERR-REQ-C ODE +3. BEA-ERR-SRC-N OT-FOUND +4. BEA-ERR-READ- UMT +5. BEA-ERR-SERVE R +6. BEA-ERR-POST +7. BEA-ERR-CANCE L +8. BEA-ERR-WAIT +9. BEA-ERR-LMID- NOT-FOUND +10. BEA-ERR-STA[...]

Client Application Considerations Oracle Tuxedo Mainframe Adapt er for TCP - CICS User Guide 5-5 ReqReturnCd This code is the return code from th e Oracle Tuxedo Doma in. See the Tuxedo documentation for a comple te list of Tuxedo error cod e s Request_data This area is the area where request data ge ts placed and in which your returned data arrive[...]

5-6 Oracle Tuxedo Ma inframe Adapt e r for TCP - CICS User Guide MOVE 'TO LOWER' TO WC-SVCNAME . MOVE +5 TO WC-REQUEST CD. MOVE 'THIS IS A TEST' TO WC-REQDATA. EXEC CIC S LINK PROGRAM ('BEAPRERQ') COMMAREA(WS- COMMAREA) LENGTH(LENGT H OF WS-COMMA REA) END-EXEC . IF RETUR NCD = 0 MOVE 'SUCCESSFUL CALL, RETU RN DATA[...]

Client Application Considerations Oracle Tuxedo Mainframe Adapt er for TCP - CICS User Guide 5-7 EXEC CICS LIN K PROGRAM("PRE REQ") COMMAREA(&car ea) LENGTH(lmsg) RESP(resp) RESP2( resp2); if(carea.CltH dr.ReturnCd || carea.CltHdr .ReqReturnCd) pr ocess error; else su ccessful call, returned dat a is in Request_d ata; Note: C Programm[...]

5-8 Oracle Tuxedo Ma inframe Adapt e r for TCP - CICS User Guide detection of problems. This configuration para meter is set in the remote TM A TCP gateway system; discuss any changes you want to make with the administrator of th at system. Problems with requests that origin ate in the CICS region are also logged to the BEALOG file. Additionally, t[...]

Server Application Considerations Oracle Tuxedo Mainframe Adapt er for TCP - CICS User Guide 5-9 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 poin ter to the raw data; therefore, no header is sent. As a result, the request da[...]

5-10 Oracle Tuxedo Mainframe Adap te r for TCP - CICS User Guide[...]

Oracle Tuxe do Mainframe Ad apter for TCP CICS User Guid e A-1 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 Mes[...]

Error and Infor mational Message s A-2 Oracle Tuxedo Ma inframe Adapt er for TCP CI CS User Guide Goodbye. The disconnect process ha s completed successfully. Service svcna me not found. The requested se rvice was not found in the inbound service name file. Client has already lo gged in. A client process has attempted to establis h a connection whe[...]

Messages Written to the TMA TCP for CICS Log Oracle Tuxedo Mainf rame Adap ter for TCP CICS User Guide A-3 Messages Written to the TMA TCP for CICS Log Occasionally, messages are written directly to the CICS log configured specifically for TMA TCP for CICS. For more information about configu ring the CICS log, refer to the “Configuring and Admini[...]

Error and Infor mational Message s A-4 Oracle Tuxedo Ma inframe Adapt er for TCP CI CS User Guide Invalid password . The password specified in the TMA TCP gateway configuratio n file does not match the password specified when the CICS supplied listener was configured. Invalid client acco unt. The accoun t code specifi e d in the TMA TCP gateway con[...]

Messages Written to the TMA TCP for CICS Log Oracle Tuxedo Mainf rame Adap ter for TCP CICS User Guide A-5 fcntl (F_GETF L) Failed. ERRNO=errno The file control function with the F_GE TFL option failed in the connect socket function. Socket CREATE Failed. ERRNO=errno The Socket CREATE func tion failed. WRITE on Sock et Failed. ERRNO=errno The Socke[...]

Error and Infor mational Message s A-6 Oracle Tuxedo Ma inframe Adapt er for TCP CI CS User Guide Verifying Use r Account. The Handler is verifying that the account and password codes supplied by TMA TCP gateway on the remote Tuxedo gateway are valid. Handler initiali zation complete. The TMA TCP Handler has successfully init ialized. Normal shutdo[...]

Codes Returned to a CICS Client Program Oracle Tuxedo Mainf rame Adap ter for TCP CICS User Guide A-7 Codes Returned to a CICS Client Program The following codes are returned to a CICS clie nt program on return from a LINK to TMA TCP. For system level problems, pl ease notify your CICS administrator. Unable to sta rt transaction A CICS error occurr[...]

Error and Infor mational Message s A-8 Oracle Tuxedo Ma inframe Adapt er for TCP CI CS User Guide Message Description BEA_NORMAL Value 0 Successful Return F r om Se rvi ce Call. BEA_ERR_LENGT H Value 1 There was an error regarding th e len gth of the message sent or the length value specified. BEA_ERR_MISSI NG_SRV_NAME Value 2 A service request was[...]

Codes Returned to a CICS Client Program Oracle Tuxedo Mainf rame Adap ter for TCP CICS User Guide A-9 BEA_ERR_DISAB LE_NOT_FND Value 13 The service name provide d specifies an invalid LMID or is missing the LMID . BEA_ERR_DISAB LE_NOT_RESPOND Value 14 The Requester for handling this service name is not responding. BEA_ERR_DISAB LE Value 15 The LMID[...]

Error and Infor mational Message s A-10 Oracle Tuxedo Mainframe Adap ter for TCP CI CS User Guide Informational Process Messages Data Field Error Messages Message Description Action "RECORD READY FOR UPDATE" The record selected is rea dy to be updated. Make the changes and press ENTER to process. "UPDATE COMPLETE D" The changes [...]

Data Field Error Messages Oracle Tuxedo Mainf rame Adap ter for TCP CICS User Guide A-11 "INVALID LOGI CAL MACHINE NAME" The LOGICAL M ACHINE NAME entered is not valid. Enter a valid IN VALID LOGICAL MACHINE NAME (i.e., LMIDNJ ). Must not start with a space, null, or underscore. "INVALID HOST ADDRESS" The HOST ADDRE SS entered i[...]

Error and Infor mational Message s A-12 Oracle Tuxedo Mainframe Adap ter for TCP CI CS User Guide "INVALID MAX MSG SIZE OPTIONS=(1 -> 32000 )" The MAX MSG SI ZE entered is not valid. Enter a valid MA X MSG SIZE (i.e., 4096 ) Must not start with a space, null, or underscore and must be within the range (1 -> 32000) "INVALID CONN[...]

System Error Messages Oracle Tuxedo Mainf rame Adap ter for TCP CICS User Guide A-13 System Error Messages "INVALID SERV ICE TIMEOUT(SEC)" The SERVICE TIMEOUT (SEC) entered is not valid. Enter a valid SE RVICE TIMEOUT(SEC) (i.e. 30 ). Must not start with a space, null, or underscore. "INVALID STAT US OPTIONS=(E ENABL E, D DISABLE, A [...]

Error and Infor mational Message s A-14 Oracle Tuxedo Mainframe Adap ter for TCP CI CS User Guide "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[...]