Oracle Audio Technologies Oracle Tuxedo manual

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112

Go to page of

A good user manual

The rules should oblige the seller to give the purchaser an operating instrucion of Oracle Audio Technologies Oracle Tuxedo, along with an item. The lack of an instruction or false information given to customer shall constitute grounds to apply for a complaint because of nonconformity of goods with the contract. In accordance with the law, a customer can receive an instruction in non-paper form; lately graphic and electronic forms of the manuals, as well as instructional videos have been majorly used. A necessary precondition for this is the unmistakable, legible character of an instruction.

What is an instruction?

The term originates from the Latin word „instructio”, which means organizing. Therefore, in an instruction of Oracle Audio Technologies Oracle Tuxedo one could find a process description. An instruction's purpose is to teach, to ease the start-up and an item's use or performance of certain activities. An instruction is a compilation of information about an item/a service, it is a clue.

Unfortunately, only a few customers devote their time to read an instruction of Oracle Audio Technologies Oracle Tuxedo. A good user manual introduces us to a number of additional functionalities of the purchased item, and also helps us to avoid the formation of most of the defects.

What should a perfect user manual contain?

First and foremost, an user manual of Oracle Audio Technologies Oracle Tuxedo should contain:
- informations concerning technical data of Oracle Audio Technologies Oracle Tuxedo
- name of the manufacturer and a year of construction of the Oracle Audio Technologies Oracle Tuxedo item
- rules of operation, control and maintenance of the Oracle Audio Technologies Oracle Tuxedo item
- safety signs and mark certificates which confirm compatibility with appropriate standards

Why don't we read the manuals?

Usually it results from the lack of time and certainty about functionalities of purchased items. Unfortunately, networking and start-up of Oracle Audio Technologies Oracle Tuxedo alone are not enough. An instruction contains a number of clues concerning respective functionalities, safety rules, maintenance methods (what means should be used), eventual defects of Oracle Audio Technologies Oracle Tuxedo, and methods of problem resolution. Eventually, when one still can't find the answer to his problems, he will be directed to the Oracle Audio Technologies service. Lately animated manuals and instructional videos are quite popular among customers. These kinds of user manuals are effective; they assure that a customer will familiarize himself with the whole material, and won't skip complicated, technical information of Oracle Audio Technologies Oracle Tuxedo.

Why one should read the manuals?

It is mostly in the manuals where we will find the details concerning construction and possibility of the Oracle Audio Technologies Oracle Tuxedo item, and its use of respective accessory, as well as information concerning all the functions and facilities.

After a successful purchase of an item one should find a moment and get to know with every part of an instruction. Currently the manuals are carefully prearranged and translated, so they could be fully understood by its users. The manuals will serve as an informational aid.

Table of contents for the manual

  • Page 1

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

  • Page 2

    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[...]

  • Page 3

    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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .[...]

  • Page 4

    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[...]

  • Page 5

    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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .[...]

  • Page 6

    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) . . . . . [...]

  • Page 7

    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) . . . . . . . . . [...]

  • Page 8

    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[...]

  • Page 9

    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 [...]

  • Page 10

    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[...]

  • Page 11

    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 [...]

  • Page 12

    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 [...]

  • Page 13

    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[...]

  • Page 14

    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[...]

  • Page 15

    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 [...]

  • Page 16

    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[...]

  • Page 17

    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[...]

  • Page 18

    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[...]

  • Page 19

    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 [...]

  • Page 20

    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[...]

  • Page 21

    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[...]

  • Page 22

    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 [...]

  • Page 23

    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 [...]

  • Page 24

    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 [...]

  • Page 25

    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[...]

  • Page 26

    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[...]

  • Page 27

    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*[...]

  • Page 28

    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[...]

  • Page 29

    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[...]

  • Page 30

    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[...]

  • Page 31

    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[...]

  • Page 32

    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[...]

  • Page 33

    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[...]

  • Page 34

    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[...]

  • Page 35

    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[...]

  • Page 36

    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[...]

  • Page 37

    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[...]

  • Page 38

    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[...]

  • Page 39

    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 [...]

  • Page 40

    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[...]

  • Page 41

    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[...]

  • Page 42

    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[...]

  • Page 43

    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[...]

  • Page 44

    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[...]

  • Page 45

    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[...]

  • Page 46

    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[...]

  • Page 47

    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[...]

  • Page 48

    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[...]

  • Page 49

    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[...]

  • Page 50

    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[...]

  • Page 51

    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) [...]

  • Page 52

    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[...]

  • Page 53

    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 ([...]

  • Page 54

    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[...]

  • Page 55

    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[...]

  • Page 56

    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 [...]

  • Page 57

    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[...]

  • Page 58

    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,[...]

  • Page 59

    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[...]

  • Page 60

    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[...]

  • Page 61

    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): _[...]

  • Page 62

    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[...]

  • Page 63

    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 .[...]

  • Page 64

    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[...]

  • Page 65

    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): _[...]

  • Page 66

    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[...]

  • Page 67

    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[...]

  • Page 68

    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[...]

  • Page 69

    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 [...]

  • Page 70

    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 [...]

  • Page 71

    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[...]

  • Page 72

    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, [...]

  • Page 73

    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 [...]

  • Page 74

    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: [...]

  • Page 75

    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[...]

  • Page 76

    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[...]

  • Page 77

    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[...]

  • Page 78

    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[...]

  • Page 79

    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[...]

  • Page 80

    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[...]

  • Page 81

    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[...]

  • Page 82

    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[...]

  • Page 83

    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 [...]

  • Page 84

    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 [...]

  • Page 85

    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[...]

  • Page 86

    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 [...]

  • Page 87

    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[...]

  • Page 88

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

  • Page 89

    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[...]

  • Page 90

    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[...]

  • Page 91

    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[...]

  • Page 92

    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[...]

  • Page 93

    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[...]

  • Page 94

    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[...]

  • Page 95

    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[...]

  • Page 96

    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[...]

  • Page 97

    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[...]

  • Page 98

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

  • Page 99

    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[...]

  • Page 100

    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[...]

  • Page 101

    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[...]

  • Page 102

    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[...]

  • Page 103

    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[...]

  • Page 104

    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[...]

  • Page 105

    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[...]

  • Page 106

    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[...]

  • Page 107

    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[...]

  • Page 108

    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 [...]

  • Page 109

    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[...]

  • Page 110

    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[...]

  • Page 111

    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 [...]

  • Page 112

    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[...]