Home

Oracle Audio Technologies 12.2 Server User Manual

1. ULTIPLEX CNT The number of concurrent incoming service requests for each Handler IN TIME The minimum length of time in milliseconds for a socket read to wait for data to be processed AX TIME The maximum length of time in milliseconds for a socket read to wait for data to be processed DELTA TIME The time increase in milliseconds from MIN TIME to MAX TIME IDLE TIME The amount of time in seconds a Handler is idle before it terminates Inquire Handler Configuration Screen H3 Use this screen to make an inquiry about the configuration record from the user file The screen is displayed with the data from the requested record and all fields are protected Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide The Handler Configuration Screens Ww EAPUSR BEA TMA 10 0 TCP FOR CICS BEAM H3 INQUIRE HANDLER CONFIGURATION SECURITY YS 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 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
2. 0 000 1 6 Requests from within CICS ienie ar cee eee 1 8 OracleTuxedo Mainframe Adapter for TCP CICS User Guide iii Getting Started with TMA TCP for CICS 0 00 0 eee eee eee 1 10 Understanding How Oracle TMA TCP for CICS Works Starting the Listener Program 1 0 eens 2 1 Running Oracle TMA TCP for CICS 0 0 0 eee eee 2 2 Initializing the Handler 20 ED NEN cee een n eee 2 2 Processing Remote Service Requests 0 0 00 cece ee eens 2 2 Shutting Down the Handler 0 0 00 eee ee eee 2 3 Using BDWN to Shut Down the Handler 004 2 4 Starting the Requester Program 2 0 eee eee 2 5 Processing TMA TCP for CICS Originated Service Requests 2 5 Shutting Down the Requester 0 eee eee ee eee 2 5 Using BDWN to Shut Down the Requester 004 2 6 Translating Data with TMA TCP gateway 0 0 eee ee 2 7 Oracle Tuxedo Terminology 0 cece eee eee 2 7 Data Translation Rules 0 0 cee eee eee 2 8 Strings and Numeric Data A Closer Look 0 0 0 0 ce eee eee ee 2 10 Including NULL Characters in String Length Calculations 2 10 Converting Numeric Data sess sss csont eee E eee 2 10 Configuring the TMA TCP Security Service Request Processing with Security 0 0 00 eee eee eee 3 1 Security Checking from UNIX to Mainframe 0 000 000 00008 3 2 Se
3. F P SECURITY Y N ACCOUNT ID PASSWORD MAX QUEUE SIZE MAX MSG SIZE RETRY LIMIT LMID TYPE START TRAN ID CICS DATA ENTER PROCESS MIN TIME MAX TIME ELTA TIME MILLISEC IDLE TIME SECONDS EQ IDLE TIME SECONDS LATENCY TIME SECONDS MAX CONNS MILLISEC MILLISEC ATT QUEUE NAM QUEUE NAM AUTO ENABLE LMID E D _ Ae 23 SE SE PF3 MENU PF5 BROWSE Fields Field Name Description LMID This name is the logical machine name or gateway ID Give it a unique name up to 16 characters Example bankmach1 DNS The host name that the domain name service recognizes HOST ADDRESS The TCP IP dot address Example 199 99 99 99 PORT NUMBER The TCP port Check with the TCP IP administrator for available ports Example 1234 SECURITY The status of connection level security Y specifies that security is on and N denotes that security is off Note For additional security information refer to the Configuring the TMA TCP Security section Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide 4 13 4 14 Field Name ACCOUNT ID Description 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 f
4. When SECURITY y the gateway attempts to start user programs with the username that initiated the request as reported by the remote system If SECURITY N the gateway starts user programs using the gateway s user ID as controlled by the socket listener Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide Setting Up Security for TMA TCP for CICS Securing Outbound Connections from CICS to UNIX Complete the following tasks to enable the security feature for each outbound connection 1 2 Specify SEC URITY yY on the appropriate Requester screen 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 When SECURITY yY the requester program sends the ACCOUNT and PASSWORD to the remote UNIX system on connection initiation When SECURITY N the gateway attempts to make a connection without any verification Securing Outbound Connections from CICS to CICS Complete the following tasks to enable the security feature for each outbound connection l 2 Specify SECURITY y on the appropriate Requester screen 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 ACCOUNT and PASSWORD values in the User Con
5. attempts the system makes to reestablish the connection before marking the connection disabled Example 5 LMID TYPE The type of gateway the remote system is running C for CICS I for IMS T for Tuxedo START TRANID The ID of the transaction to be started if the remote system type is CICS CICS DATA A string to be passed to the IBM TCP IP Listener for use with the TMA TCP for CICS gateway The default is ULTIPLEX CNT The number of concurrent requests for each connection IN TIME The minimum length of time in milliseconds for a socket read to wait for data to be processed AX TIME The maximum length of time in milliseconds for a socket read to wait for data to be processed DELTA TIME The time increase in milliseconds from MIN TIME to MAX TIME 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 Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide The Requester Screens Field Name REQ IDLE TI Description 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 v
6. Contact your system administrator Reference Manual Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide A 13 Error and Informational Messages Message Description Action INVREQ Refer to the CICS Application Contact your system administrator Reference Manual IOERR Refer to the CICS Application Contact your system administrator Reference Manual LENGERR Refer to the CICS Application Contact your system administrator Reference Manual MAPFAIL Refer to the CICS Application Contact your system administrator Check the Mapset Reference Manual status via CEMT NOSPACE Refer to the CICS Application Contact your system administrator Reference Manual NOTAUTH Refer to the CICS Application Contact your system administrator Reference Manual PGMIDERR Refer to the CICS Application Contact your system administrator Check the Program Reference Manual status via CEMT RECORD NOT FOUND The record selected is not in the file Verify the data you entered for the record key SYSIDERR Refer to the CICS Application Contact your system administrator Reference Manual UNKNOWN Refer to the CICS Application Contact your system administrator ERROR Reference Manual A 14 Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide
7. ED E hence ante tan beue tance E hth ghey Oe batten O AE 4 33 Insert User Connection ACCOUNT Screen U1 0 00 00 cee eee 4 33 1S soci aie de cas BE Ae BR GORE T RITE OF Gch RG Bh ge OL Dea eat Aline A 4 34 Update User Connection ACCOUNT Screen U2 0 0 00 e eee eee 4 34 Fields rna tects Cop e R a EROS REESE es FREE arse eck E eect 4 35 Inquire User Connection ACCOUNT Screen U3 0 0 eee eee ee 4 35 6 eae na a ART FFs Er RESORT E ia 4 36 Delete User Connection ACCOUNT Screen U4 0 0 0 ee eee eee 4 36 Fields 42 teh titanate ath Sahat E edhe Wate eae 4 37 The Browse User Connection ACCOUNT Screen U5 200000 4 37 The Inbound Service Information Screens 0 eee eee eee eee eee 4 38 PE KEYS pa r id ewer 33 ate a 8 Medeski seed Aste wake E ges 4 39 Insert Inbound Service Information Screen I1 00 cee eee eee 4 39 Fieldsin n oe a E N A A a ee 4 40 Update Inbound Service Information Screen 12 0 0 0 e ee eee ee eee 4 41 Fields isi atau SE NESS doth ae A REE EG REE 4 42 Inquire Inbound Service Information Screen 13 0 00 cece ee eee eee 4 43 e Ca bt aa ga bs dede E 4 44 vi OracleTuxedo Mainframe Adapter for TCP CICS User Guide Delete Inbound Service Information Screen I4 00 0 4 45 Fields susie tlds eet ahaha OR sods has ai aches RAT 4 46 The Browse Inbound Service Screen I5 0 0 0 0 0 0 cee eens 4 47 The H
8. EST UL CALL RETURNCD TO M RCDI I EC CICS SEND TEXT FROM ERASE T ERMINAL ERROR OCCURRED R O WC REQDATA BEAPRERQ AREA WS COMMAREA R iy TURN DATA IS IN WC DATA URN CODE EQUAL SG AREA LENGTH 47 FREEKB CURSOR 0 Fl ND EXEC A200 EXIT EXEC CICS RETURN END EXEC The following is an example of a C CICS client program Listing 5 4 C CICS Client Program Example long resp resp2 unsigned short int lms struct CMAREA carea carea CltHdr DataLen CltHdr Sv RequestCd Request_d memcpy carea carea CltHdr memcpy carea imsg sizeof carea g strlen sendbuf cName BEA REQUEST RESPONSE ata ECHO This is a test 4 14 Use the name defined during installation Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide Client Application Considerations EXEC CICS LINK PROGRAM PREREQ COMMAREA amp 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 st rxxx calls This example is typical when using C and CICS together For more information see your C for CICS documentatio
9. Field Name IDLE TIME Description 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 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 QUEUE NAME 2 The unique name of a TS Q that is used for communications between the Pre requester and the Requester AUTO ENABLE LMID E D Enter E to automatically enable a disabled Requester LMID for TMA TCP for CICS gateway Enter D to disable the automatic enabling of a disabled Requester LMID for TMA TCP for CICS gateway Browse Requester Screen R5 Use this screen to browse a list of the records in the Requester file Additionally you can select a record for further processing 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 first record on file is displayed at the top of the screen If you access this screen from the Insert
10. Handler Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide 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 The TMA TCP for CICS Requester The Requester program is responsible for making and maintaining the sockets connection with the remote Oracle Tuxedo region After receiving request information from the Pre requester the Requester sends that information to Oracle Tuxedo The Requester then receives any response data returned by Oracle Tuxedo and sends it back to the Pre requester which in turn gives the information back to the client program that had called it IBM TCP IP Sockets Interface The sockets interface must be enabled before TMA TCP for CICS can communicate over TCP IP This procedure is true for any CICS program which uses the sockets API The IBM TCP IP Sockets Interface is not supplied by Oracle Systems Inc You can purchase it directly from IBM The supplied transaction that accompanies the IBM TCP IP Sockets for CICS product is used to enable the sockets interface under CICS Complete documentation is provided with the IBM product Using Other Supported TCP IP Socke
11. INQ 4 DI td HN INVALID SELCDE OPTIONS 2 UPD 3 INQ INVALID SELECTION OPTIONS C2 3 C5 R1 5 S1 5 U2 3 11 5 The SELCDE entered is not valid The SELCDE entered is not valid The SELECTION entered is not valid Enter a valid SELCDE See OPTIONS Enter a valid SELCDE See OPTIONS Enter a valid SELECTION See the list of valid options in the message INVALID SERVICE NAME The SERVICE NAME entered is not valid Enter a valid SERVICE NAME i e EMPLSRV Must not start with a space null or underscore INVALID REMOTE SERVICE NAME The REMOTE SERVICE NAME entered is not valid Enter a valid REMOTE SERVICE NAME i e EMPLSRV Must not start with a space null or underscore INVALID LMID TYPE The LMID TYPE entered is not Enter a valid LMID TYPE See Options OPTIONS C CICS I valid IMS CP STAR RAN CODE No START TRAN CODE has been Enter a valid START TRAN CODE REQUIRED FOR LMID TYPE C CICS entered and the LMID TYPE is CICS INVALID TYPE I INCOMING O OUTGOING The TYPE entered is not valid Enter a valid TYPE INVALID SECURITY FLAG Y N The SECURITY FLAG entered is not valid Enter a valid SECURITY FLAG Y or N A 12 Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide System Error Me
12. NAME Description 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 Note Services sending requests using a tpacall with the TPNOREPLY flag set must have a unique TRANSACTION NAME associated with it Do not use the TRANSACTION NAME for the Application Handler program or an error message results MAX MESSAGE SIZE SECURITY The largest message allowed to be sent across this connection The maximum is 32000 This size is the size of the actual data TMA TCP manages additional message size through its internal headers The status of security Y enables security for the specified service and N disables security for the specified service Update Inbound Service Information Screen 12 Use this screen to update a record in the inbound service name file The screen is first displayed with the REMOTE SERVICE NAME field unprotected Enter the remote service name and press ENTER The screen is re displayed with the data from the requested record and the LOCAL SERVICE NAME TRANSACTION NAME MAX MESSAGE SIZE and SECURITY fields unprotected The following message displays RECORD READY FOR UPDATE After the changes are validated and proc
13. OPTIONS INVALID FUNCTION KEY OPTIONS ENTER PF3 PET PES this operation The PFKey pressed is not valid in Press a valid PFKey See OPTIONS A 10 Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide Data Field Error Messages Message INVALID LOGICAL MACHINE NAME Description The LOGICAL MACHINE NAME entered is not valid Action 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 Enter either a valid HOST ADDRESS or DNS NAME CANNOT HAVE BOTH HOST ADDRESS AND DNS NAME Both HOST ADDRESS and DNS NAME have been entered Enter either a valid HOST ADDRESS or DNS NAME INVALID MULTIPLEX COUNT OPTIONS 1 99 The MULTIPLEX COUNT entered is not valid Enter a valid number for MULTIPLEX COUNT INVALID MAX CONNECTIONS OPTIONS 1 99 The MAX CONNECTIONS entered is not valid Enter a valid number for MAX CONNECTIONS TRAN CODE INVALID FOR LMID TYPE I IMS T TCP A START TRAN CODE has been entered and the LMID TYPE is not CICS Rem
14. Oracle TMA TCP gateway User Guide Application Errors If an error occurs that makes the Handler unable to execute a certain program such as the program does not exist or is disabled the Handler sends a message back to the TMA TCP gateway gateway If any other type of error occurs within an application program and the Handler is not notified of the problem a time out message is sent from the Handler back to the remote gateway For requests originating with CICS Oracle Tuxedo returns information about specific problems if possible If there are network problems that prohibit the transmission of data the request receives a timeout error Server Application Considerations 5 8 The following subsections identify issues that CICS programmers should be aware of when they develop or modify application programs that interoperate with TMA TCP for CICS as servers A CICS application program that processes requests originating from a remote Oracle Tuxedo domain is written like a CICS application program that is invoked with the CICS LINK command The CICS programs that work best for satisfying Oracle Tuxedo requests are the ones that perform a certain operation and return information to the caller The CICS services requested by a Oracle Tuxedo client program must entail a single request response scenario CICS service programs that are called from Oracle Tuxedo clients must be careful if they give up control as when performing an EXEC CICS
15. PORT NUMBER The TCP port Check with the TCP IP administrator for available ports Example 1234 SECURITY The status of security Y specifies that security is on and N denotes that security is off Note For additional security information refer to Configuring the TMA TCP Security 4 16 Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide The Requester Screens Field Name ACCOUNT ID Description 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 Required if there is an entry in the ACCOUNT ID field Example LETMEIN1 MAX QUEUE SIZE Specifies the size of the local queue where requests are stored for servicing A typical setting is 200 MAX MSG SIZI Ea The largest message allowed to be sent across this connection The maximum is 32000 Example 4096 W ETRY LIMIT If the connection fails this number determines how many attempts the system makes to reestablish the connection before marking the connection disabled Example 5 LMID TYPE The type of gateway the remote system is r
16. Requesters Each socket connection is established automatically when a new TMA TCP gateway Requester in the Oracle Tuxedo domain establishes communication with the TMA TCP for CICS gateway Requests from within CICS The mechanism used to send requests initiated from a CICS program to a remote Oracle Tuxedo domain is invisible to the user and significantly abstracted from the CICS programmer Your company s CICS program issues an EXEC CICS LINK command to the Oracle TMA gateway In the data passed with the EXEC CICS LINK command the programmer supplies the name of the service and the data to be used as input to that service When the EXEC CICS LINK command returns the reply to the request is placed in that same data area If there was a problem satisfying the service request meaningful return codes are sent back Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide Processing Scenarios Figure 1 2 Oracle TMA Client Gateway Configuration User Program User Program User Program EXEC CICS LINK EXEC CICS LINK EXEC CICS LINK BEA Control Table Pre Requester Pre Requester Pre Requester E Read CSA Read CSA Read CSA EER Read Write TSQ Read Write TSQ Read Write TSQ Co 7 CO CT BEA TS TS Control Q Q Table Requester Read Set CSA BEA Common Storage Requester Area Read Set CSA CSA GW Tuxedo GW Tu
17. Screen R1 1 2 cee eee ene eens 4 12 Fields ican es ee OR A Rh Bp Pee Ee SAR oa atone 4 13 Update Requester Screen R2 ccoooa norane cece eee 4 15 Fieldsi inne iina e dated indus eink aes re ee Re ae 4 16 Inquire Requester Screen R3 0 20 2 0 eee eee 4 18 Fields finn sie 1 ee ds see eee cate She So cw ete ee babe beet at 4 19 Delete Requester Screen R4 0 cee cece eens 4 21 PIGlds eben Tr ba what eaten hae EEN E E Wade ates aes tat de 4 22 Browse Requester Screen R5 1 0 0 0 cece eect eens 4 24 The Outbound Service Information Screens 0 0 0 0 c eee eee eee eee 4 25 PE KYS 05 0 sos gested 5 ete cle Be Be Sek ER eed eed ghee tue Sell RAR 4 26 OracleTuxedo Mainframe Adapter for TCP CICS User Guide Insert Outbound Service Information Screen S1 00 0 eee eee ee 4 26 Piel dsy tsi SAD se tonal taea s wha Rik te eh Ae Na aides ate eh andthe 4 27 Update Outbound Service Information Screen S2 0 e ee eee eee 4 28 C 6 N RRE ne en e a a 4 28 Inquire Outbound Service Information Screen S3 0 0 c eee eee eee 4 29 ICIS LSE RW ED eS AR A rare 4 30 Delete Outbound Service Information Screen S4 0 00 0 e ee eee 4 30 Fieldsin rengan te aes eke We eco Gh BOON Geeta be eh ee eR asd BRS a 4 31 Browse Outbound Service Information Screen S5 0 000 c ee eee 4 32 The User Connection ACCOUNT Screens 1 0 0 0 cee eee ee eee eee 4 32 PP Rey Swish
18. 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 Insert User Connection ACCOUNT Screen U1 Use this screen to add a new Connection ACCOUNT by inserting a new record into the user file When the screen is first displayed all the fields are unprotected Type the required data as described in the table below then press ENTER After the data is validated and processed the screen is re displayed and all the fields are unprotected Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide 4 33 EAPUSR BEA TMA 10 0 TCP FOR CICS BEAM U1 w 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 This password must be the same as on the Oracle Tux
19. Tuxedo issues the first service request destined for that CICS region The Handler is responsible for accepting a connection request taking control of the socket connection and continuing communication with the Requester in the Oracle Tuxedo domain for the life of the socket connection The Handler interfaces as necessary with the Application Handler to process service requests originating from the TMA TCP gateway Requester If multiplexing or security is enabled the Handler starts the Application Handler and waits for the next service request The Handler periodically checks for completed requests When a request has been completed the Handler retrieves the response data from the Application Handler and transmits that data back to the Requester The Handler also periodically checks to ensure that no active service requests have timed out If the multiplex count is 1 and security is disabled or if the service request originated from a version of TMA TCP gateway prior to Version 3 0 the Handler executes the target user application waits for the application to return data transmits that data back to the TMA TCP gateway then waits for the TMA TCP gateway to send another service request The TMA TCP for CICS Application Handler The Application Handler is started by and receives request information from the Handler The Application Handler executes the target user application waits for the application to return data and returns the data to the
20. Update Inquire or Delete screens the key received from that screen determines which records are displayed To choose a record enter a valid selection code in the SEL CDE field next to that record 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 Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide The Outbound Service Information Screens 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 0 TCP FOR CICS BEAM R5 BROWSE REQUESTER SEL LOGICAL MACHINE HOST PORT MAXM CONN LMID START CDE NAME ADDRESS NUM SIZE R LIM TYPE TRNID SELCDE 1 INS 2 UPD 3 INQ 4 DEL ENTER PROCESS PF3 MENU PF7 PREV PF8 NEXT RECORD NOT FOUND The Outbound Service Information Screens A Service is a name associated with some component of work That component of work might be a banking transaction an airline flight reservation or an order for a dozen widgets In Oracle Tuxedo a client program that needs work done makes a service request A process called a server performs the work described in the service request on behalf of the client then returns the results of its efforts back to the client In MVS this proc
21. code entered PF3 Transfer to Main Menu PFS Transfer to Connections 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 current operation process is aborted and the new screen is displayed Update Connection Screen C2 Use the UPDATE CONNECTION screen to update a record from the Connection file When the screen initially displays the LOGICAL MACHINE NAME and TYPE fields are unprotected Enter a valid LOGICAL MACHINE NAME gateway ID and TYPE and press ENTER The screen re displays showing the data from the record you specified and the STATUS field is unprotected The message RECORD READY FOR UPDATE displays You can now make changes to the record Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide The Connection Screens Ww EAPCON ENTER PROCESS Fields Ww EA TMA 10 0 TCP FOR CICS UPDATE CONNECTION LOGICAL MACHINE NAME TYPE STATUS AX MSG SIZE REQUESTER TASK NUMBER UMBER REQUESTS UMBER SUCCESS REQS UMBER RECONNECTS UMBER OPEN SOCKETS UMBER SESSIONS ACTIVE PF3 MENU PF5 BROWSE Field Name LOGICAL MACHIN NAME Description This field name is the gateway ID Give it a unique name up to 16 characters Example bankmach1 For Requesters th
22. enter this unique transaction name rather than using the transaction name that starts the Application Handler Shutting Down the Handler When the network connection is lost the Handler process automatically shuts down The next service request sent causes the Listener to automatically start a new Handler if necessary Use the supplied shutdown transaction BDWN to terminate active TMA TCP for CICS programs Depending on the options specified this causes all Handlers to shut down gracefully The name of the BDWN transaction may have been changed at your site during installation so verify the name Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide 2 3 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 Bown 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 You can specify optional parameters with the BDWN transaction to shut down Handlers immediately or after the processing of all requests has completed The default is ALL ALL Shuts down all Handlers and Requesters gracefully allowing them to complete all p
23. file you must restart the Handler PF Keys The following table lists the function keys available on various user account screens 4 48 Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide The Handler Configuration Screens 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 When the screen first displays all fields are unprotected After the changes are validated and processed the screen is re displayed BEAPUSR BEA TMA 10 0 TCP FOR CICS BEAM H2 UPDATE 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 UPDATE COMPLETED Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide 4 49 4 50 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
24. in the TMA TCP gateway configuration file does not match the account code specified when the CICS supplied listener was configured The mode command was executed through the tmadmin tool on Tuxedo and the administrative request specified is not available in the CICS region Data too long message header please check A message received is larger than the maximum allowable message length Data too short please check message header A message was received and was smaller than the smallest expected message Message header is incorrect An invalid protocol header was received This can occur if there was a transmission error or if a message was sent to the gateway without having gone through the TMA TCP gateway gateway on the remote Tuxedo node This transaction is not defined in CICS A CICS transaction code was mapped to a service name in the TMA TCP gateway configuration file for a transaction code that is unknown to CICS A 2 Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide Messages Written to the TMA TCP for CICS Log Message Application Handler abnormally terminated Description 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 pr
25. the actual size of the return message the system sends over the gateway on a per request basis This is different than simply limiting the message size for a particular service using the MAX MESSAGE field of the Inbound Service Information screen To limit the size of the return message per request the service program must ADDRESS the TWA using the copybook or the include file delivered in the YOURHLQ BEATCPC INCLUDE file Modifying Return Message Lengths for C Programs To modify the return message length on a per request basis specify the message length in the rtnMsgSize field in a TWA CONNECT structure defined in the TWAINCL file Modifying Return Message Lengths for COBOL Programs To modify the return message length on a per request basis specify the message length in the RIN MSG S1ZE field in a TWA CONNECT record layout in the copybook TWACOPY Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide 5 9 5 10 Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide APPENDIX Error and Informational Messages The following topics describe TMA TCP for CICS messages e Messages Returned to the Remote Gateway e Messages Written to the TMA TCP for CICS Log e Codes Returned to a CICS Client Program e Informational Process Messages e Data Field Error Messages e System Error Messages Messages Returned to the Remote Gateway Most of the messages produced from Oracle Tuxedo Mainframe for TCP CICS hereafter referen
26. 2000 This is the size of the actual data TMA TCP manages additional message size through its internal headers SECURITY The status of security Y enables security for the specified service and N disables security for the specified service Inquire Inbound Service Information Screen 13 Use this screen to inquire about a record in the inbound service name file The screen is first displayed with the REMOTE SERVICE NAME field unprotected Enter the remote service name and press ENTER The screen is re displayed with the data from the requested record and the REMOTE SERVICE NAME field unprotected Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide 4 43 BEAPISN 4 44 R BEA TMA 10 0 TCP FOR CICS BEAM I3 INQUIRE INBOUND SERVICE INFORMATION EMOTE SERVICE NAME LOCAL SERVICE NAME TRANSACTION NAME MAX MESSAGE SIZ n gt ECURITY Y N ENTER PROCESS PF3 MENU PF5 BROWSE Fields 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 Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide The Inbound Service Information Screens 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 t
27. A 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 The Handler waits for the CICS program to finish and receives any returned data from the CICS program The Handler transmits the response to the remote TMA TCP gateway gateway The Handler stays connected to the remote gateway awaiting another service request 3 Ifthe multiplex count is greater than 1 or security is enabled then the following tasks occur a The Handler issues an EXEC CICS START TRANS call with the transaction specified in the Inbound Service File for the service specified in the TMA TCP protocol header The transaction should be the same as the Application Handler program Note If security is enabled the EXEC CICS START TRANSID call uses the user ID specified in the TMA TCP protocol header For any completed service requests the Handler retrieves the response data from the Application Handler The Handler transmits the response to the remote TMA TCP gateway gateway The connection between the Handler and the gateway remains and the Handler waits for another service request For tpacall TPNOREPLY requests the remote program is invoked by a CICS START TRANSID command and no data is returned to the original caller In this case a unique transaction must be defined for the service Use the Inbound Service Information screen to
28. As Figure 1 1 shows TMA TCP for CICS extends this transparent access by routing Oracle Tuxedo s requests for CICS program services through TCP IP network software 1 6 Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide Processing Scenarios 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 TCP CICS Application Application Handler Handler ee FE User App3 As Figure 1 1 shows TMA TCP for CICS fits between the CICS user application and TCP IP When Oracle Tuxedo client programs send requests to remote systems in this case CICS TMA TCP gateway transforms those requests into messages formatted appropriately for transmission Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide 1 7 1 8 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 Simultaneous socket connections can exist between one TMA TCP for CICS gateway a set of TMA Handlers within a single CICS region and all remote TMA TCP gateway
29. BEAPREQ EA TMA 10 0 TCP FOR CICS BEAM R4 DELETE REQUESTER LMID MULTIPLEX_CNT DNS HOST ADDRESS PORT NUMBER MIN TIME MILLISEC SECURITY Y N MAX TIME MILLISEC ACCOUNT ID DELTA TIME MILLISEC PASSWORD IDLE TIME SECONDS REQ IDLE TIME SECONDS MAX QUEUE SIZE LATENCY TIME SECONDS MAX MSG SIZE MAX CONNS panan RETRY LIMIT LMID TYPE QUEUE NAME 1 START TRAN ID QUEUE NAME 2 CICS DATA AUTO ENABLE LMID E D _ ENTER PROCESS PF3 MENU PF5 BROWSE Fields Field Name Description LMID This name is the logical machine name or gateway ID This name is a unique name up to 16 characters Example bankmach1 DNS The host name that the domain Name Service recognizes HOST ADDRESS The TCP IP dot address Example 199 99 99 99 PORT NUMBER The TCP IP port Check with the TCP IP administrator for available ports Example 1234 SECURITY The status of security Y specifies that security is on and N denotes that security is off Note For additional security information refer to the Configuring the TMA TCP Security section 4 22 Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide The Requester Screens Field Name ACCOUNT ID Description 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 charact
30. D exactly 4 The remote TMA TCP for CICS gateway Handler initiates an Application Handler to act on behalf of the specified user ID Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide Service Request Processing with Security 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 Security Checking from Mainframe to UNIX Figure 3 2 depicts the process flow for security verifications from a mainframe to TMA TCP gateway on UNIX Figure 3 2 Security Checking for Mainframe to UNIX Transactions UNIX Mainframe Remote Gateway BEA TMA TCP Gateway 1 The user ID established at mainframe log in is checked by system security to verify that the user has permission to start a client transaction 2 The user ID is checked by system security to verify that the user has permission to send a request to the gateway 3 With each request the gateway passes the user ID to the Tuxedo gateway Note To pass authority checking the user s Tuxedo identity must match the mainframe user ID exactly Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide 3 3 4 The TMA TCP gateway maps the mainframe user ID to a Tuxedo user
31. ICS Originated Service Requests Shutting Down the Requester e Translating Data with TMA TCP gateway Each of these operations is described in the following sections Additionally this document describes some programming considerations that may be useful when you develop or change programs that interoperate with TMA TCP for CICS Starting the Listener Program The Listener program is supplied by IBM and is part of the Sockets for CICS software product which must be purchased from IBM Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide 2 1 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 For example if the Listener receives a connection request from TMA TCP gateway running on a remote Oracle Tuxedo node it processes the connection and invokes the TMA TCP Handler Running Oracle TMA TCP for CICS 2 2 The TMA TCP Handler is invoked automatically by the Listener process Once invoked the Handler takes control of the socket connection and retains control until either the Handler is shut down or un
32. ICS programers should be aware of when they develop or modify application programs that interoperate with TMA TCP for CICS as clients To make requests to remote Oracle Tuxedo domains from CICS application programs use the EXEC CICS LINK command The exact layout of the request response data area is discussed in a later section Buffer Layout Issues The layout of the data buffer sent between CICS and Oracle Tuxedo should be agreed upon by the CICS applications programmer the Oracle Tuxedo applications developer and the Oracle Tuxedo administrator to ensure consistency and proper configuration There are no limitations on the CICS programmer concerning native COBOL or C data types Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide 5 1 5 2 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 10 SVCNAME 16 PIC X 16 10 REQUESTCD PIC S9 08 COMP 10 RETURNCD PIC S9 08 COMP 10 REQRETURNCD PIC S9 08 COMP 05 REQUEST DATA 10 DATA AREA PIC X DATALEN The lay
33. ID and issues the service request on behalf of that user 5 The Tuxedo server performs access checks based on the tpac1 file to verify that the user has access to the requested service Setting Up Security for TMA TCP for CICS 3 4 The TMA TCP for CICS product supports enhanced security This interface allows a requester from Oracle Tuxedo services to pass a User ID through the CICS server interface for authorization through your security package For field definitions refer to the Configuring and Administering Oracle TMA TCP for CICS section Securing User Connections Complete the following tasks to enable the security feature for each connection 1 Specify SECURITY Y in the Handler Configuration screen 2 Enter values for the ACCOUNT and PASSWORD fields in the User Connection Account screen When sEcuRITY y TMA TCP for CICS verifies the ACCOUNT and PASSWORD values from the User Connection Account match the RMTACCT and PASSWORD values in the TMA TCP gateway GWICONFIG file FOREIGN section If these values do not match and SECURITY yY a security error occurs If SECURITY N the gateway allows a connection without any verification Securing Inbound Services Complete the following tasks to enable the security feature for each inbound service 1 Set up transaction security through the mainframe with the security administrator 2 Specify SECURITY y in the Inbound Services screen for each service you want to secure
34. Information Screen 5 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 If you enter more than one selection code the first one is used and the others are ignored After the selection code is validated and processed the screen for that process is displayed and the record key appears in the SERVICE NAME field BEAPSVC BEA TMA 10 0 TCP FOR CICS BEAM S5 BROWSE SERVICE NAME SEL SERVICE LOGICAL MACHINE REMOTE SERVICE SERVICE CDE NAME NAME NAME TIMEOUT SEC SELCDE 1 INS 2 UPD 3 INQ 4 DEL ENTER PROCESS PF3 MENU PF7 PREV PF8 NEXT RECORD NOT FOUND The User Connection ACCOUNT Screens A Handler is responsible for receiving service requests from the remote Oracle Tuxedo domain The User Connection ACCOUNT screens allow for dynamic manipulation of accounts allowed to connect with a Handler when a Handler is configured with security enabled 4 32 Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide The User Connection ACCOUNT Screens PF Keys
35. LETE INBOUND SERVICE INFORMATION EMOTE SERVICE NAME LOCAL SERVICE NAME TRANSACTION NAME MAX MESSAGE SIZ n gt ECURITY Y N ENTER PROCESS PF3 MENU PF5 BROWSE Fields 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 Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide The Inbound Service Information Screens 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 WARNING Services sending requests using a tpacall with the TPNOREPLY flag set must have a unique TRANSACTION NAME associated with it Do not use the TRANSACTION NAME for the Application Handler program or an error message results MAX MESSAGE SIZE The largest message allowed to be sent across this connection The maximum is 32000 This is the size of the actual data TMA TCP manages additional message size through its internal headers SECURITY The status of security Y specifies that security is on and N denotes that security is off The Browse Inbou
36. MIN TIME The minimum length of time in milliseconds for a socket read to wait for data to be processed MAX TIME The maximum length of time in milliseconds for a socket read to wait for data to be processed Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide 4 51 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 4 52 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 You can make the following changes to the TMA TCP for CICS gateway configuration dynamically e Modifying Outbound Services e Modifying User Connection Accounts e Modifying Connections e Deleting Requester LMIDs All other configuration tasks are not dynamic including Inbound Service Information and Handler Configuration To process configuration information in these cases the corresponding Requesters and Handlers must be shut down Modifying Outbound Services You can dynamically configure outbound services by inserting a new record into the service name file modifying an existing record in the service name file or deleting a record in the service
37. NSE 5 BEA REQUEST NORESPONSE 7 ReturnCd This code is the return code from the CICS Requester All return codes are listed in the following table Notify the administrator if any of the return codes indicate a processing or network problem Note For a complete description of these codes refer to the Codes Returned to a CICS Client Program section in Appendix A Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide 5 3 5 4 Table 5 2 Return Codes 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 BEA ERR SOCKET FAILURE 19 BEA ERR PROTOCOL 20 BEA ERR QUEUE OVERF LOW 21 Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide Client Application 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 g
38. Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide Release 10 0 June 2008 ORACLE Tuxedo Mainframe Adapter for TCP CICS User Guide Release 10 0 Copyright O 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 Except as expressly permitted in your license agreement or allowed by law you may not use copy reproduce translate broadcast modify license transmit distribute exhibit perform publish or display any part in any form or by any means Reverse engineering disassembly or decompilation of this software unless required by law for interoperability is prohibited The information contained herein is subject to change without notice and is not warranted to be error free If you find any errors please report them to us in writing If this software or related documentation is delivered to the U S Government or anyone licensing it on behalf of the U S Government the following notice is applicable U S GOVERNMENT RIGHTS Programs software databases and related documentation and technical data delivered to U S Government customers are commercial computer software or commercial technical data pursuant to the applicable Federal Acquisition Regulation and agency specific supplemental regulations As such the use duplication disclosu
39. P2 hexcode A CICS START command failed when the Handler tried to issue a START on the specified user program Link Program Failed RESP hexcode RESP2 hexcode Q TMAIN Failed SP2 hexcode RESP hexcode amp ii W A CICS LINK command failed The Handler was unable to LINK to the specified user program The CICS GETMAIN command failed Take Socket Failed ERRNO errno The TMA TCP Handler was unable to take control of the TCP IP socket Error on Select ERRNO errno The Sockets SELECT function failed Read on Socket Failed ERRNO errno An error was encountered while attempting to read from the active socket Socket SEND Failed RC rc ERRNO errno Handler connected successfully An error was encountered while issuing a send over the active socket The client request is allowed because the account and password codes are authorized to use the TMA TCP gateway BEA TMA TCP Server CTOS is hutting down un The TMA TCP gateway Handler is shutting down Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide A 5 Error and Informational Messages Message Verifying User Account Description 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 pe
40. RING Value 12 There was a problem getting an LMID to use for this service request A 8 Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide Codes Returned to a CICS Client Program Message BEA ERR DISABLE NOT FND Description Value 13 The service name provided specifies an invalid LMID or is missing the LMID y BEA_ERR_DISABLE_NOT_RESPOND Value 14 The Requester for handling this service name is not responding BEA_ERR_DISABL PI BEA ERR ALLOC Value 15 The LMID associated with the requested service is not enabled Value 16 The Pre requester was unable to allocate the memory necessary to process a request BEA ERR TIMEOUT Value 17 The Pre requester has timed out the request This could occur either during processing by the Pre requester before the request is sent or because the Pre requester did not receive a response in time BEA ERR TSQ Value 18 The Pre requester was unable to write the request to the appropriate TS queue BEA ERR SOCKET FAILURE Value 19 The Requester closed a socket because the socket was in a state inconsistent with the requested operation BEA ERR PROTOCOL Value 20 The Requester closed a socket because the session data was corrupt BEA_ERR_QUEUE_OV ERF LOW Value 21 The Requester has aborted a request because the pending request queue for the Requester is t
41. S lookup function failed for the given host name Dotted IP address malformed address There was an erroneous IP address passed into the ConvertAddress function Invalid data pointer pointer There was an invalid data buffer pointer passed into the BufferHeader function Socket CONNECT Failed ERRNO errno The Socket CONNECT function failed fentl F_SETFL Failed ERRNO errno FLAGS hexcode The file control function with the F_SETFL option failed in the connect socket function A 4 Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide Messages Written to the TMA TCP for CICS Log Message fcntl F_GETFL Failed ERRNO errno Description 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 TRIEVE Failed RESP hexcode SP2 hexcode m m The CICS RETRIEVE command failed when it tried to access the buffer passed to the TMA TCP gateway Handler from the Sockets for CICS Listener Load Control Failed RESP hexcode RESP2 hexcode A CICS LOAD PROGRAM command failed The Handler was unable to load the control programs OTPCICS01 or OTPCICS02 Start Task Failed RESP hexcode RES
42. T Screen U3 Use this screen to make an inquiry about a record from the account file The screen is initially displayed with the ACCOUNT field unprotected Enter the ACCOUNT and press ENTER The screen is re displayed with the data from the requested record and the AccounrT field is unprotected Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide 4 35 EAPUSR BEA TMA 10 0 TCP FOR CICS BEAM U3 w 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 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 Example LETMEIN1 Delete User Connection ACCOUNT Screen U4 Use this screen to delete a record from the account file The screen is initially displayed with the ACCOUNT field unprotected Type the service name and press ENTER The screen is re displayed with the data from the record requested and all the fields protected 4 36 Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide The User Connection ACCOUNT Screens The
43. Table 4 2 Main Menu BEAM Sub menu Codes Code Area of Operation G Connections R Requesters S Outbound Service Information U User Connection Account Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide 4 3 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 Enter This Code To Access This Screen C2 Update Connection c3 Inquire Connection C5 Browse Connection R1 Insert Requester R2 Update Requester R3 Inquire Requester R4 Delete Requester 4 4 Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide 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 Ul Insert User Connection Account U2 Update User Connection Account U3 Inquire User Connection Account U4 Delete User Connection Account U5 Browse User Connection A
44. The Requester file however is persistent Deleting Requester LMIDs Each instance of the Requester is given a logical machine name LMID You can give a Requester any unique LMID that is meaningful to you Every service name is associated with one or more LMIDs This method allows the Requester to identify which remote machine is responsible for a particular service You can dynamically delete an LMID using the Update Requester screen R2 This dynamic change only affect Pre requesters immediately Note Requesters that are currently running do not read the information in the requester file and are not affected by this dynamic change Administering the Gateways Oracle Tuxedo has a set of tmadmin and dmadmin commands for the administration of the TMA TCP gateways For detailed information about these commands refer to the Oracle Tuxedo documentation Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide 4 53 4 54 Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide CHAPTER 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 e Client Application Considerations e Server Application Considerations Client Application Considerations The following sections identify issues that C
45. XCTL operation To ensure that the response data is returned to the client chaining programs must pass the original COMMAREA during the XCTL so that it may be RETURNed to the TMA TCP for CICS Handler by the final program in the chain Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide Server Application Considerations 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 Programming Services without a Response Service programs that do not send replies back to the requester execute using transactions started by the EXEC CICS START command The FROM option of this command contains a pointer to the raw data therefore no header is sent As a result such service programs must use an EXEC CICS RETRIEVE command with the SET option containing a pointer to the raw data Note Define a unique transaction for each service that does not send a reply and enter the name of that transaction in the TRANSACTION NAME field of the Inbound Service Information screen for the corresponding service An example of a service sending no reply is one requested by a client using a tpacall with the TPNOREPLY flag set Modifying the Length of the Return Message You can manage
46. alue 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 QUEUE NAME 2 The unique name of a TS Q that is used for communications between the Pre requester and the Requester AUTO ENABLE LMID E D Enter E to automatically enable a disabled Requester LMID for TMA TCP for CICS gateway Enter D to disable the automatic enabling of a disabled Requester LMID for TMA TCP for CICS gateway Delete Requester Screen R4 Use this screen to delete a record from the Requester file WARNING Deleting a Requester record can have serious ramifications Think carefully before performing this operation If there are any Service records that point to this GWID any client calls to those services are rejected because Oracle TMA does not know to which remote machine the request should go The screen is initially displayed with the LOGICAL MACHINE NAME field unprotected Enter the logical machine name and press ENTER The screen is then re displayed with the data from the requested record and the LOGICAL MACHINE NAME field is protected The following message is displayed TO CONFIRM DELETE PRESS ENTER AGAIN Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide 4 21
47. ame and press ENTER The screen is re displayed with the data from the record requested and all the fields protected 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 SERVICE NAME field is unprotected 4 30 Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide The Outbound Service Information Screens w EA TMA 10 0 TCP FOR CICS BEAM S4 BEAPSVC DELETE OUTBOUND SERVICE INFORMATION SERVICE NAME LOGICAL MACHINE NAME a EMOTE 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 LOGICAL MACHINE This name is a symbolic name as it was defined on the Delete NAME Outbound Service Information screen It denotes the remote machine on which this service should be processed REMOTE SERVICE The name as it is known in the remote Oracle Tuxedo domain NAME 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 Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide 4 31 Browse Outbound Service
48. andler Configuration Screens 0 eee eee eee ee 4 48 PE KEYS sa ets or ia E Ee Nee a ee Ak we ON OR Ee es deem ee StS 4 48 Update Handler Configuration Screen H2 0 0 00 eee eee eee 4 49 Feld i odc tbe iuiha SES a ea ths Oe ate see EL Ca Ree eS Bid Bee de SES 4 50 Inquire Handler Configuration Screen H3 00 0 0 02 eee eee 4 50 Fields 25 E sao E fad Males ee Ree Gite eee 4 51 Dynamically Configuring TMA TCP for CICS 00 00 0002 eee eee 4 52 Modifying Outbound Services 02 0 0 0 cee eee eee 4 52 Modifying User Connection Accounts 2 0 0 0 0 eee eee eee eee 4 52 Modifying Connections 0 0 eee cee eee eens 4 53 Deleting Requester LMIDs SAREEN ERROR AE ERR eee 4 53 Administering the Gateways 00 0 cece rure 4 53 Programming Oracle Tuxedo Mainframe Adapter for TCP CICS Client Application Considerations 0 0 0 eee ce eee eee 5 1 Buffer Layout ISSUES scan o4u seca teeta ee eee ee aR 5 1 Making Calls from a CICS Client Program 0 000000 e ee eee 5 2 Examples a2 cia wines dash au dain wae ea ata a eee ee aie By 5 5 Error Handling es ssh eye cee Ged Go ees Ge ete VN Rb ee oes eS 5 7 Gateway ELrors mep eaire see bts ele Sate E en ones SSG bs Atte Ne hat 5 7 MVS or CICS Erfors enee hsp Oh A Dae aie 5 7 Application Errors iura egckbarei ig ces Wane ee Coad betes 5 8 Server Application Considerations 0 0 00 eee
49. ator 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 The Oracle TMA TCP for CICS Maintenance System is an online CICS application for use in configuring maintaining and administering the TMA TCP for CICS gateway The following topics explain the Maintenance System e Menu Navigation e The Main Menu e The Connection Screens e The Requester Screens e The Outbound Service Information Screens e The User Connection ACCOUNT Screens e The Inbound Service Information Screens e The Handler Configuration Screens e Dynamically Configuring TMA TCP for CICS e Administering the Gateways Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide 4 1 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 Table 4 1 Menu Groups Menu Type Use Connection To monitor and control confi
50. ay find it necessary to customize tables See the Oracle TMA TCP gateway User Guide for complete instructions Converting Numeric Data You can convert numeric data into different data types easily provided that you have enough range in the intermediate and destination types to handle the maximum value you need to represent For example you can convert an FML field of double into a packed decimal field on the remote target system by specifying an appropriate dec_t type VIEW element In addition you can convert numeric values into strings and the reverse For example while FML buffers do not directly support the dec_t type you can place decimal values in string fields and map these to dec t fields within VIEw definitions Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide CHAPTER 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 The following topics explain the how to set up security e Service Request Processing with Security Security Checking from UNIX to Mainframe Security Checking from Mainframe to UNIX e Setting Up Security for TMA TCP for CICS Securing User Connections Securing Inbound Services Securing Outbound Connections from CICS to UNIX Securing Outbound Connections from CICS to CICS Securin
51. ccount I1 Insert Inbound Service Information I2 Update Inbound Service Information I3 Inquire Inbound Service information I4 Delete Inbound Service Information I5 Browse Inbound Service Information H2 Update Handler Configuration H3 Inquire Handler Configuration You can use the maintenance system screens to view and alter a connection but not to insert create or delete a connection Connections are created and deleted by TMA TCP for CICS in its normal operation The maintenance system checks the two character selection code that you enter and displays the appropriate screen if the code is valid If the code you enter is not valid you receive an error message Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide 4 5 The Connection Screens 4 6 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 For the purposes of TMA TCP for CICS a remote endpoint is an TMA TCP gateway gateway executing within a remote Oracle Tuxedo domain PF Keys The following function keys are available on various connection screens Table 4 4 Function Keys Function Key Definitions ENTER Process the selection
52. ced as TMA TCP for CICS are sent back to the remote TMA TCP gateway and written to the ULOG on that system Message Description BI EA TMA TCP for CICS server The Handler process has been started process initiated Welcome to BEA TMA TCP for The connect process has completed successfully MVS CICS Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide A 1 Error and Informational Messages Message Goodbye Description 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 A client process has made a request to the TMA TCP for CICS gateway but has not yet established a login connection The connection request protocol was never sent BEA TMA TCP MVS CICS server is active This message is returned to the remote Tuxedo gateway when a PING request is sent to the TMA TCP for CICS gateway from the tmadmin administration tool 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 Sorry System Resource is protected by CICS The account code specified
53. cessing scenarios to consider e Requests that originate in a remote Oracle Tuxedo domain and request services offered by CICS e Requests that originate in a CICS region and request services offered by a remote Oracle Tuxedo domain Oracle TMA TCP Functionality The following functionality is available in the TMA TCP product Domains based Gateway Connectivity The TMA TCP product has a domains based architecture supporting bidirectional communications request response support and concurrent support for the CICS interface 1 2 Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide 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 This support allows you to change the IP address at the Domain Name Server to implement address changes without reconfiguring the TMA TCP gateway Dynamic Configuration The TMA TCP product supports dynamic configuration updates for some of the TMA TCP configuration parameters You can modify the configuration without shutting down and restarting the TMA TCP product For more information about dynamic c
54. curity Checking from Mainframe to UNIX 00 0 0 000 2 e eee 3 3 Setting Up Security for TMA TCP for CICS 0 00 0 ee eee 3 4 Securing User Connections 0 00 cee ee eee eee 3 4 Securing Inbound Services 0 00 eee cece eens 3 4 Securing Outbound Connections from CICS to UNIX 0005 3 5 iv OracleTuxedo Mainframe Adapter for TCP CICS User Guide Securing Outbound Connections from CICS to CICS 0005 3 5 Securing Outbound Connections from CICS toIMS 0 0000 3 5 Securing Outbound Services 0 00 3 6 Configuring and Administering Oracle TMA TCP for CICS Menu Navigations rss peger tute hb eae Reale Re ae Waele ee Sees 4 2 The Mam Mente sarees eea tan tobe dette s bead oie Riley Slane wh EE gehen 4 2 USa eres et Ae hts eh Sls eh ht ok OAR Soha ahha a a he RAR 4 3 The Connection Screens oe ge eee Rae Fe 4 6 PE KEYS ar e Ea hee hat ated cate bdo fot a ech deg a aes 4 6 Update Connection Screen C2 0 0 eee cee een eens 4 6 PIGlds sain etn tes ciliated E ERG Jara EN BESS ESSEN een ke bk 4 7 Inquire Connection Screen C3 0 cece cette een e eee 4 8 Fields coronis athe Gee e a a a el Bese OO Ree OLE 4 9 Browse Connection Screen C5 1 0 nunnan ennnen eere 4 10 The Requester Screens oii epatta pth sb ote eA A esa ee ae ko ets al 4 11 BE Keys 2p tinct a aone btn et ane oe eet mag elect es unger betas 4 12 Insert Requester
55. d only when the AUTO ENABLE option is set to E Codes Returned to a CICS Client Program The following codes are returned to a CICS client program on return from a LINK to TMA TCP For system level problems please notify your CICS administrator Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide A 7 Error and Informational Messages 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 BEA ERR SRC NOT FOUND Value 4 The service that was called cannot be found in the outbound service table BEA ERR READ UMT Value 5 Check the FCT entry for the CONNECTIONS dataset BEA ERR SERVER Value 6 There was a problem accessing the Requester Check that it is enabled BEA ERR POST Value 7 A CICS Post error occurred in TMA TCP BEA_ERR_CANCEL Value 8 A CICS Cancel error occurred in TMA TCP BEA ERR WAIT Value 9 A CICS Wait error occurred in TMA TCP BEA ERR LMID NOT FOUND Value 10 The service name provided specified a non existent LMID BEA ERR START TRANSID Value 11 A CICS START error occurred in TMA TCP BEA ERR_DISABLE_ACQUI
56. double PIC Packed Decimal dec t m n S9 m n 1 2 V9 n COMP 3 Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide 2 9 2 10 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 For example when a CICS application program expects 10 characters in an input record specify 10 for that field not 10 plus 1 Note Although TMA TCP gateway does not require strings to be NULL terminated it respects NULL termination Therefore when TMA TCP gateway detects a NULL zero character within a string it does not process any subsequent characters To pass full 8 bit data that contains embedded NULL values use a CARRAY type field or buffer The character set translations performed by TMA TCP gateway can be fully localized in accordance with the X Open XPG Portability Guides ASCII and EBCDIC translations are loadable from message files The TMA TCP gateway software contains default behaviors which should meet the requirements of most English language applications However you m
57. e of a TS Q that is used for communications between the Pre requester and the Requester AUTO ENABLE LMID E D Enter E to automatically enable a disabled Requester LMID for TMA TCP for CICS gateway Enter D to disable the automatic enabling of a disabled Requester LMID for TMA TCP for CICS gateway 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 MACHINE NAME field unprotected Enter the logical machine name and press ENTER The screen is re displayed with the data from the requested record and the LOGICAL MACHINE NAME field is unprotected Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide The Requester Screens BEAPREQ BEA TMA 10 0 TCP FOR CICS BEAM R3 INQUIRE REQUESTER LMID MULTIPLEX_CNT DNS HOST ADDRESS PORT NUMBER MIN TIME MILLISEC SECURITY Y N MAX TIME MILLISEC ACCOUNT ID DELTA TIME MILLISEC PASSWORD IDLE TIME SECONDS REQ IDLE TIME SECONDS MAX QUEUE SIZ LATENCY TIME SECONDS T MAX MSG SIZE MAX CONNS ER RETRY LIMIT LMID TYPE QUEUE NAME 1 START TRAN ID QUEUE NAME 2 CICS DATA AUTO ENABLE LMID E D _ ENTER PROCESS MENU PF5 BROWSE Fields Field Name Description LMID This name is the logical machine name or gate
58. edo side configuration Coordinate with the Oracle Tuxedo Administrator Required if there is an entry in the ACCOUNT ID field Example LETMEIN1 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 Enter the account ID and press ENTER The screen is then re displayed with the data from the requested record and the PASSWORD field is unprotected The following message is displayed RECORD READY FOR UPDATE 4 34 Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide The User Connection ACCOUNT Screens After the changes are validated and processed the screen is re displayed and the account field is unprotected EAPUSR BEA TMA 10 0 TCP FOR CICS BEAM U2 w 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 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 Example LETMEIN1 Inquire User Connection ACCOUN
59. eee eee 5 8 Programming Services with a Response 00 0 0c cece eee eee eee 5 9 Programming Services without a Response 0 0 0 c eee ee eee eee 5 9 OracleTuxedo Mainframe Adapter for TCP CICS User Guide vii Modifying the Length of the Return Message 0 00000 ee ee 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 0 0 cee cece eee A 1 Messages Written to the TMA TCP for CICS Log 0 0 0 0 2 2 eee eee A 3 Codes Returned to a CICS Client Program 0 0 cece eee eee A 7 Informational Process Messages 1 2 0 00 00 cece cece teen ene ae A 10 Data Field Error Messages 0 0 0 c eee eects A 10 System Error Messages arein ea eps sad we aden SHRM D EAN SEER Raed A 13 viii OracleTuxedo Mainframe Adapter for TCP CICS User Guide CHAPTER D 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 Tuxed
60. equester NUMBER SESSIONS The number of active sessions on this connection ACTIVE Inquire Connection Screen C3 Use this screen to inquire about a record from the Connection file When the screen is initially displayed the LOGICAL MACHINE NAME and TYPE fields are unprotected Enter a valid LOGICAL MACHINE NAMI E gateway ID and TYPE and press ENTER The screen is re displayed with the data from the record you specified and the LOGICAL MACHINE NAME and TYPE fields are unprotected Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide The Connection Screens BEAPCON BEA TMA 10 0 TCP FOR CICS BEAM C3 INQUIRE CONNECTION LOGICAL MACHINE NAME TYPE STATUS AX MSG SIZE REQUESTER TASK NUMBER UMBER REQUESTS UMBER SUCCESS REQS UMBER RECONNECTS UMBER OPEN SOCKETS UMBER SESSIONS ACTIVE ENTER PROCESS PF3 MENU PF5 BROWSE Fields Field Name Description LOGICAL MACHINE This name is the gateway ID Specify a unique name up to 16 NAME characters Example bankmach1 For Requesters this name is the LMID associated with the service that the Requester is requesting For a Handler this name is BEAH followed by the task number The task number of the Handler is given in the BEALOG TYPE The type of connection I represents incoming connections or O represents outgoing connections STATUS The status
61. er 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 Example LETMEIN1 MAX QUEUE SIZE Specifies the size of the local queue where requests are stored for servicing A typical setting is 200 MAX MSG SIZE The largest message allowed to be sent across this connection The maximum is 32000 Example 4096 RETRY LIMIT If the connection fails this number determines how many attempts the system makes to reestablish the connection before marking the connection disabled Example 5 LMID TYPE The type of gateway the remote system is running C for CICS I for IMS T for Tuxedo START TRANID The ID of the transaction to be started if the remote system type is CICS CICS DATA A string to be passed to the IBM TCP IP Listener for use with the TMA TCP for CICS gateway The default is ULTIPLEX CNT The number of concurrent requests for each connection IN TIME The minimum length of time in milliseconds for a socket read to wait for data to be processed AX TIME The maximum length of time in milliseconds for a socket read to wait for data to be processed DELTA TIME The time increase in milliseconds from MIN TIME to MAX TIME Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide 4 23 4 24
62. ess would be referred to as a call toa black box In a CICS application that uses TMA TCP for CICS a service name is passed in the data area in EC CICS LINK command and the results are returned in that same area The service screens use the terms service name and remote service name The service name such as CICO1XXYYZZ is what the service is known as to your CICS environment and the remote service name such as WITHDRAWL is what the service is known as to Oracle Tuxedo For simplicity you can make both names the same but if naming conventions differ you can use different names an EXI Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide 4 25 4 26 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 PFS 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 Insert Outbound Service Information Screen 1 Use this screen to insert a record into the service name file The screen is first displayed with all fields unprotected Enter the required data in the appropriate fields and press ENTER After the data is validated and proc
63. essed the screen is re displayed and all the fields are unprotected Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide The Outbound Service Information Screens BEAPSVC ENTER PROCESS Fields w EA TMA 10 0 TCP FOR CICS INSERT OUTBOUND SERVICE INFORMATION SERVICE NAME LOGICAL MACHINE NAME a EMOTE SERVICE NAME SERVICE TIMEOUT SEC SECURITY Y N PF3 MENU PF5 BROWSE F eld Name Description SI ERVICE NAME The service name as it is known to the CICS programmer LOGICAL MACHINE This name is a symbolic name as it was defined on the Requester NAME Insert screen It denotes the remote machine on which this service should be processed REMOTE SERVICE The name as it is known in the remote Oracle Tuxedo domain NAME SERVICE TIMEOUT The number of seconds to wait for timing out this service request SECURITY The status of request level security Y specifies that security is on and N denotes that security is off Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide BEAM S1 4 21 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 reques
64. essed the screen is re displayed and the REMOTE SERVICE NAME field is unprotected Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide 4 41 BEAPISN 4 42 R BEA TMA 10 0 TCP FOR CICS BEAM I2 UPDATE INBOUND SERVICE INFORMATION EMOTE SERVICE NAME LOCAL SERVICE NAME TRANSACTION NAME MAX MESSAGE SIZ n gt ECURITY Y N ENTER PROCESS PF3 MENU PF5 BROWSE Fields 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 Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide The Inbound Service Information Screens 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 Note Services sending requests using a tpacal1 with the TPNOREPLY flag set must have a unique TRANSACTION NAME associated with it Do not use the TRANSACTION NAME for the Application Handler program or an error message results MAX MESSAGE SIZE The largest message allowed to be sent across this connection The maximum is 3
65. ets 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 Listing 5 3 COBOL CICS Client Program Example IDENTIFICATION DIVISION PROGRAM ID ENVIRONMENT TESTCLN DIVISION CONFIGURATION SECTION SOURCE COMPUTER IBM 3090 OBJECT COMPUTER IBM 3090 DATA DIVISION WORKING STORAGE SECTION 01 FILLER PIC X 32 VALUE SAMPLE COBOL CICS CLIENT PROGRAM 01 MSG AREA 05 M DATA PIC X 42 VALUE SPACES 05 M RCDE PIC Z 05 VALUE ZEROS 01 WS COMMAREA 05 WC DATALEN PIC S9 9 COMP 4 05 WC SVCNAME PIC X 16 05 WC REQUESTCD PIC S9 9 COMP 4 05 WC RETURNCD PIC S9 9 COMP 4 05 WC REQRETURNCD PIC S9 9 COMP 4 05 WC REQDATA PIC X 14 LINKAGE SECTION 01 DFHCOMMAREA PIC X 14 PROCEDURE DIVISION A100 ENTRY OVE 14 TO WC DATALEN Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide 5 5 5 6 TOLOWER 5 THIS IS AT CICS OV OV EXEC a GI END EXEC IF RETURNCD 0 OVE SUCCESSF TO MSG DATA ELSE OVE TO OVE DELE PROCESS MSG DATA ti Z x lt LINK PROGRAM COMMAREA WS COM LENGTH LENGTH OF TO WC SVCNAME GI O WC REQUESTCD
66. 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 EAPUSR BEA TMA 10 0 TCP FOR CICS BEAM U4 w DELETE 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 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 Example LETMEIN1 The Browse User Connection ACCOUNT Screen U5 Use this screen to browse the records in the account 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 Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide 4 37 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 selec
67. for TCP CICS User Guide The Requester Screens Field Name IDLE TIME Description 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 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 QUEUE NAME 2 The unique name of a TS Q that is used for communications between the Pre requester and the Requester AUTO ENABLE LMID E D This field is used for auto enabling of LMID Enter E to automatically enable a disabled Requester LMID for TMA TCP for CICS gateway Enter D to disable the automatic enabling of a disabled Requester LMID for TMA TCP for CICS gateway Update Requester Screen R2 Use this screen to update a record from the Requester file The fields are the same as the ones on the Requester Insert screen but on this screen you can change the values When the screen is first displayed the LMID field is unprotected Enter a logical
68. g Outbound Connections from CICS to IMS Securing Outbound Services Service Request Processing with Security The following sections describe the process flow for security verification of a service request Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide 3 1 3 2 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 Application Handler BEA TMA TCP Gateway 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 When the client program issues a tpcall or tpacall Tuxedo verifies against the tpacl file the user is authorized to invoke the gateway service 3 When the gateway establishes the initial connection connection security information specified as RMTNAME and PASSWORD in the GWICONF1IG file is passed from the TMA TCP gateway to the remote gateway If the RMTNAME and PASSWORD values match the values configured on the remote gateway the connection is established With each request the TMA TCP gateway passes the user s Tuxedo identity to the remote TMA TCP for CICS gateway to the Handler Note To pass authority checking the user s Tuxedo identity must match the mainframe user I
69. gured and active connections Requester To configure and maintain remote endpoints Outbound Service To configure each remote service and specify which Information Requester to use for each service User Connection Account To create and maintain user accounts Inbound Service Information To configure services residing locally that are accessed remotely Handler Configuration To configure and maintain the local endpoint Each of these topics is discussed in more detail in the following sections The Main Menu The Main menu BEAM gives you access to all the maintenance screens 4 2 Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide The Main Menu BEAPMNU BEA TMA 10 0 TCP FOR CICS BEAM M1 SELECTION SCREEN TABLE OPERATION C CONNECTION 1 INSERT R REQUESTER 2 UPDATE S OUTBOUND SERVICE INFORMATION 3 INQUIRE U USER CONNECTION ACCOUNT 4 DELETE I INBOUND SERVICE INFORMATION 5 BROWSE H HANDLER CONFIGURATION SELECTION __ e g R3 ENTER PROCESS PF3 EXIT Usage Use the Main menu to access the screens that make up the maintenance system To move from the Main menu to a sub menu enter the appropriate two character code The first character in the code denotes the area in which you want to operate the second character denotes the operation you want to perform on that area The following table lists the codes for the areas of operation
70. he 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 Note Services sending requests using a tpacal1 with the TPNOREPLY flag set must have a unique TRANSACTION NAME associated with it Do not use the TRANSACTION NAME for the Application Handler program or an error message results MAX MESSAGE SIZE The largest message allowed to be sent across this connection The maximum is 32000 This is the size of the actual data TMA TCP manages additional message size through its internal headers SECURITY The status of security Y specifies that security is on and N denotes that security is off Delete Inbound Service Information Screen 14 Use this screen to delete a record in the inbound service name file The screen is first displayed with the REMOTE SERVICE NAME field unprotected Enter the remote service name and press ENTER The screen is re displayed with the data from the record requested and all fields protected The following message displays TO CONFIRM DELETE PRESS ENTER AGAIN After you press ENTER to confirm the deletion the screen is re displayed and the REMOTE SERVICE NAME field is unprotected Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide 4 45 BEAPISN 4 46 R BEA TMA 10 0 TCP FOR CICS BEAM I4 DE
71. he screen If you access this screen from the Connection Update screen or the Inquire screen the list starts with the key received from that screen To select a record for processing enter a valid selection code in the SEL CDE field 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 all others are ignored After the selection code is validated and processed the screen for that process is displayed and the record key appears in the LOGICAL MACHINE NAME field Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide The Requester Screens BEAPCON BEA TMA 10 0 TCP FOR CICS BEAM C5 BROWSE CONNECTION SEL LOGICAL MACHINE STA MAXMSG NUMBER NUMBER NUMBER SOCK SESS ACT CDE NAME TUS SIZE REQS SUCREQ RECONS ETS IONS IVE TYPE SELCDE 2 UPD 3 INQ ENTER PROCESS PF3 MENU PF7 PREV PF8 NEXT BEG END OF FILE The Requester Screens A Requester is responsible for collecting request information to be sent to the remote Oracle Tuxedo domain The Requester establishes network connectivity transmits data to Oracle Tuxedo and receives data from Oracle Tuxedo Each Requester is responsible for one and only one remote endpoint or one TCP IP address port combination You can configure multiple Requesters to point to the same endpoint but each Requester can have o
72. ield 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 Example LETMEIN2 MAX QU EUE SIZE Specifies the size of the local queue where requests are stored for servicing A typical setting is 200 MAX MSG SIZE The largest message allowed to be sent across this connection The maximum is 32000 Example 4096 RETRY LIMIT If the connection fails this number determines how many attempts the system makes to reestablish the connection before marking the connection disabled Example 5 LMID TYPE The type of gateway the remote system is running C for CICS I for IMS T for Tuxedo START TRANID The ID of the transaction to be started if the remote system type is CICS CICS DATA A string to be passed to the IBM TCP IP Listener for use with the TMA TCP for CICS gateway The default is ULTIPLEX CNT The number of concurrent requests for each connection IN TIME The minimum length of time in milliseconds for a socket read to wait for data to be processed AX TIME The maximum length of time in milliseconds for a socket read to wait for data to be processed DELTA TIME The time increase in milliseconds from MIN TIME to MAX TIME Oracle Tuxedo Mainframe Adapter
73. iplex count for the existing connection is not exceeded Also additional connections are opened as necessary until the configured maximum connection count is reached or all requests are accommodated Processing TMA TCP for CICS Originated Service Requests 1 The CICS client program your program issues an EXEC CICS LINK command to the TMA TCP for CICS Pre requester 2 The Pre requester verifies that the request is valid and then determines whether a Requester has been started for the specific endpoint for which this request is destined If a Requester is not already running the Pre requester starts one 3 The request is then handed over to the Requester 4 The Requester transmits the request information to the remote Oracle Tuxedo domain 5 If the request is a type that needs a response the Requester receives that response back from Oracle Tuxedo and hands the data over to the Pre requester 6 The Pre requester issues an EXEC CICS RETURN command to the client program your program The client receives its response in the COMMAREA Shutting Down the Requester There are two ways to shut down the Requester e Use the administrative tool described in Configuring and Administering Oracle TMA TCP for CICS to disable the Requester This method causes the selected Requester to clean up its tables and shut down gracefully It also prohibits any service requests invoking it When you are ready use the administrative too
74. is field name is the LMID associated with the service that the Requester is requesting For a Handler this field name is BEAH followed by the task number The task number of the Handler is given in the BEALOG TYPE The type of connection Specify I for incoming connections or O for outgoing connections STATUS The status of the connection Specify E to enable the connection Specify D for normal shutdown which allows initiated tasks to complete prior to disconnecting Specify A for immediate shutdown which aborts all initiated tasks and disconnects Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide BEAM C2 4 7 4 8 Field Name MAX MSG SIZI Cat Description The largest message allowed to be sent across this connection The maximum is 32000 Example 31000 REQUESTER TASK The task number of the Requester that is currently associated NUMBER 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 NUMBER REQUESTS The number of service requests made during this connection NUMBER SUCCESS The number of successful communications REQ NUMBER RECONNECTS The number of successful connections NUMBER OPEN The number of sockets that are currently opened by the SOCKETS R
75. l to enable the Requester Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide 2 5 e 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 Listing 2 2 Bown Command Line Syntax for Requesters BDWN ALL REQUESTER I REQUESTER BDWN 2 6 Shuts down all Handlers or all Requesters or both It also frees shared memory used by the Requesters associated with each logical machine ID LMID You can specify optional parameters with the BDWN transaction to shut down Handlers or Requesters immediately or after processing of all requests has completed The default is ALL ALL Shuts down all Handlers and Requesters gracefully allowing them to complete all processing of all requests that were received before the execution of the BDWN transaction Specifying ALL also frees any shared memory This is the default for BDWN REQUESTER I Shuts down all Requesters immediately and frees memory associated with each LMID This parameter does not shut down any Handlers REQUESTER Shuts dow
76. machine name and press ENTER The screen is re displayed showing the data from the requested record The HOST ADDRESS PORT NUMB ER ACCOUNT ID PASSWORD MAX MSG SIZE and CONNECT RI ETRY LIMIT fields are unprotected The following message is displayed RECORD READY FOR UPDATE After the changes you entered are validated and processed the screen is re displayed and the LMID field is unprotected Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide 4 15 BEAPREQ LMID DNS w EA TMA 10 0 TCP FOR CICS BEAM R2 UPDATE REQUESTER MULTIPLEX_CNT HOST ADDR PORT NUMBI Pa a SECURITY Y N ACCOUNT ID PASSWORD MAX QUEUE SIZ MAX MSG SI RETRY LIMI LMID TYPE CICS DATA ZE T START TRAN ID ENTER PROCESS MIN TIME MILLISEC MAX TIME MILLISEC DELTA TIME MILLISEC LE TIME SECONDS REQ IDLE TIME SECONDS LATENCY TIME SECONDS MAX CONNS H k UE QUEUE NAM QUEUE NAM AUTO ENABLE LMID E D _ E HE AE I 23 MENU PF5 BROWSE Fields Field Name Description LMID This name is the logical machine name or gateway ID Give it a unique name up to 16 characters Example bankmach1 DNS The host name that the Domain Name Service recognizes HOST ADDRE The TCP IP dot address Example 199 99 99 99
77. make an inquiry about a record from the SERVICE NAME file The screen is initially displayed with the SERVICE NAME field unprotected Enter the service name and press ENTER The screen is re displayed with the data from the requested record and the SERVICE NAME field is unprotected BEAPSVC BEA TMA 10 0 TCP FOR CICS BEAM S3 INQUIRE OUTBOUND SERVICE INFORMATION SERVICE NAME LOGICAL MACHINE NAME a EMOTE SERVICE NAME SERVICE TIMEOUT SEC SECURITY Y N ENTER PROCESS PF3 MENU PF5 BROWSE Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide 4 29 Fields Field Name Description SERVICE NAME The service name as it is known to the CICS programmer LOGICAL MACHINE This name is a symbolic name as it was defined on the Inquire NAME Outbound Service Information screen It denotes the remote machine on which this service should be processed REMOTE SERVICE The name as it is known in the remote Oracle Tuxedo domain NAME 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 Delete Outbound Service Information Screen 4 Use this screen to delete records from the service name file The screen is initially displayed with the SERVICE NAME field unprotected Type the service n
78. n Error Handling You may encounter the following three types of errors while using TMA TCP for CICS e Gateway errors Communications problems e MVS or CICS errors e Application errors The following subsections explain how TMA TCP handles these different kinds of errors Gateway Errors When local or remote gateway errors occur they are logged in the Oracle Tuxedo ULOG file on the remote Oracle Tuxedo node and in the BEALOG file a TD Queue defined during installation within the CICS region All associated service requests fail and if the TMA gateways are able to communicate with each other error messages are communicated between them MVS or CICS Errors For requests originating in the Oracle Tuxedo domain if the remote target system does not make it possible for TMA TCP for CICS to detect particular types of failure the TMA TCP gateway the Oracle Tuxedo domain blocking time out parameter can be tuned to provide timely Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide 5 7 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
79. n all Requesters gracefully allowing them to complete all processing off all requests that were received before the execution of the BDWN transaction It also frees memory associated with each LMID This parameter does not shut down any Handlers Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide Translating Data with TMA TCP gateway 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 It is through this mechanism that environmental differences such as naming conventions and data formats are concealed from programmers and programs Although all data is converted and translated automatically by the remote TMA TCP gateway gateway the rules implemented are outlined in the following subsections to assist the CICS programmer in understanding how the data is manipulated It is important for the CICS programmer to remember that this information is written from the point of view of the Oracle Tuxedo environment When a client program on the remote Oracle Tuxedo system sends data to or receives data from a service routine on a different model of computer TMA TCP gateway automatically translates data as required Translation involves changing the representation
80. nal Messages Message Invalid password Description 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 message header please check A message received is larger than the maximum allowable message length 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 Unable to start another session The Handler is already processing the maximum number of service requests configured as the multiplex count Unable to start transaction Error occurred in Application Handler A CICS error occurred attempting to start the transaction The Application Handler encountered a CICS error Security error occurred in Application Handler The Application Handler encountered a CICS security error DNS Lookup Failed for HOST host ERRNO errno The DN
81. name file Use the appropriate maintenance screens to accomplish the necessary task S1 to insert S2 to update or S4 to delete For field definitions refer to the The Outbound Service Information Screens section Modifying User Connection Accounts You can dynamically configure User Connection Accounts and enable accounts to connect to Handlers by inserting a new account into the user account file modifying an existing user account or deleting a user account Use the appropriate maintenance screens to accomplish the Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide 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 Using the Update Connection screen C2 you can enable disable or abort the connection for a given LMID Dynamically configuring the status of a connection has an immediate effect on the corresponding Requesters For field definitions refer to the The Connection Screens section Note Because the data in the Update Connection screen is transient setting the LMID status to disable does not persist after the CICS region is shut down and then restarted
82. nd Service Screen 15 Use this screen to browse the records in the inbound 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 If you enter more than one selection code the first one is used and the others are ignored After the selection code is validated and processed the screen for that process is displayed and the record key appears in the REMOTE SERVICE NAME field Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide 4 41 BEAPISN BEA TMA 10 0 TCP FOR CICS BEAM 15 BROWSE INBOUND SERVICE SEL REMOTE SERVICE LOCAL SERVICE TRAN MAX CDE NAME NAME NAME SIZE SEC SELCDE 1 INS 2 UPD 3 INQ 4 DEL ENTER PROCESS PF3 MENU PF7 PREV PF8 NEXT RECORD NOT FOUND The Handler Configuration Screens A Handler is responsible for receiving service requests from the remote Oracle Tuxedo domain The Handler Configuration screens allow for dynamic manipulation of the configuration used by all Handler programs in the system Note To apply changes that have been made to the Handler Configuration
83. nding Handler exceeded maximum idle time The TMA TCP Handler shuts down after the currently pending requests complete The TMA TCPHandler has exceeded the configured IDLE TIME BEA TMA TCP Handler is shutting down The TMA TCP Handler is shutting down Client disconnected The client has been disconnected from the TMA TCP Handler Read of file failed resp hexcode A CICS READ command failed Freemain did not work resp hexcode A CICS FREEMAIN command failed Getmain shared failed resp hexcode A CICS GETMAIN SHARED command failed Delete from file failed resp hexcode A CICS DELETE command failed Write to file failed resp hexcode A CICS WRITE command failed Rewrite of file failed resp hexcode Read update of file failed resp hexcode A CICS REWRITE command failed A CICS READ UPDATE command failed Unauthorized Client Rejected The client request are not allowed because the account and or password codes are not authorized deleteq ts did not work resp hexcode ACICS DELETEQ TS command failed A 6 Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide Codes Returned to a CICS Client Program Message Unable to start transaction Description A CICS error occurred attempting to start the transaction Security Violation Invalid user for this transaction The user ID
84. nection Account screen When sECU RITY y the requester program sends the ACCOUNT and PASSWORD to the remote CICS system on connection initiation When SECURITY N the gateway attempts to make a connection without any verification Securing Outbound Connections from CICS to IMS 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 ACCOUNT and PASSWORD values in the GATEWAY TYPE REMOTE Statement When SECU RITY y the requester program sends the ACCOUNT and PASSWORD to the remote IMS system on connection initiation When SECURITY N the gateway attempts to make a connection without any verification Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide 3 5 3 6 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 Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide CHAPTER QP Configuring and Administering Oracle TMA TCP for CICS It is the responsibility of the Oracle Tuxedo administr
85. nly one endpoint On the following maintenance screens each instance of the Requester is given a logical machine ID LM1D You can give a Requester any unique LMID that is meaningful to you Every service name is associated with one LMID This method allows the Requester to know which remote machine is responsible for a particular service Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide 4 11 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 Insert Requester Screen R1 Use this screen to configure a new Requester by inserting a new record into the Requester file When the screen is first displayed all the fields are unprotected Type the required data then press ENTER After the data is validated and processed the screen is re displayed and all the fields are unprotected 4 12 Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide The Requester Screens BEAPREQ LMID DNS w EA TMA 10 0 TCP FOR CICS BEAM R1 INSERT Zs EQUESTER MULTIPLEX_CNT HOST ADDR PORT NUMBI
86. o configuration The TMA TCP for CICS software is designed to provide transparent CICS program access from within an Oracle Tuxedo domain and Oracle Tuxedo access from within a CICS region The following information introduces the TMA TCP for CICS product e What You Need to Know e Oracle TMA TCP for CICS Architecture e Oracle TMA TCP Functionality e Oracle TMA TCP for CICS Components e Processing Scenarios e Getting Started with TMA TCP for CICS What You Need to Know This document is primarily for CICS system administrators who configure and administer TMA TCP In addition programmers can find useful pointers for developing client programs and service routines that send data through to the remote TMA TCP gateway Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide 1 1 Programmers who work with TMA TCP should be familiar with CICS applications development System administrators who work with TMA TCP should be familiar with the following concepts tools and procedures e TCP IP networking e IBM CICS Sockets Interface e Defining new resources to CICS e Standard CICS monitoring tools Oracle TMA TCP for CICS Architecture Oracle TMA TCP for CICS is composed of four CICS programs running within a CICS region e Handler e Application Handler e Pre requester e Requester It uses the Sockets Interface and Sockets for CICS Listener that is shipped with the IBM TCP IP for CICS TS Sockets Interface There are two different pro
87. of intrinsic data types by changing attributes such as word length and byte order The following subsections describe the basic rules that TMA TCP gateway follows when it translates data and provide detailed information about how TMA TCP gateway handles string and numeric data Oracle Tuxedo Terminology The following terms are some commonly used Oracle Tuxedo terms for buffer types Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide 2 1 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 A CARRAY is an exemplary buffer type for a graphics file VIEW A VIEW buffer is a collection of field definitions that can be treated as a single entity It is comparable to a record layout in COBOL or a structure in C FML FML Fielded Manipulation Language buffers are variable length dynamic self describing buffers Each field in the buffer has its own descriptive header In Oracle Tuxedo FML buffers can be tied closely to VIEW buffers so that conversion from one to the other is direct Data Translation Rule
88. of the connection E means the connection is enabled D means the connection is designated for a normal shutdown which allows initiated tasks to complete prior to disconnecting A means the connection shuts down immediately aborts all initiated tasks and disconnects Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide 4 9 4 10 Field Name Description MAX MSG SIZE The largest message allowed to be sent across this connection The maximum is 32000 Example 31000 REQUESTER TASK The task number of the Requester that is currently associated NUMBER 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 NUMBER REQUESTS The number of service requests made during this connection NUMBER SUCCESS REQS The number of successful communications NUMBER RECONNECTS The number of successful connections NUMBER OPEN SOCKETS The number of sockets that are currently opened by the Requester NUMBER SESSIONS The number of active sessions on this connection ACTIVE Browse Connection Screen C5 Use this screen to browse records in the Connection file and to select individual records for further processing If you access this screen from the Main menu the first record on file is displayed at the top of t
89. on keys available on various inbound service screens Table 4 7 Function Keys Function Key Function ENTER Process the data 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 Insert Inbound Service Information Screen 11 Use this screen to insert a record into the service name file The screen is first displayed with all fields unprotected Enter the required data in the following fields and press ENTER After the data is validated and processed the screen is re displayed and all the fields are unprotected Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide 4 39 BEAPISN 4 40 BEA TMA 10 0 TCP FOR CICS BEAM I1 INSERT INBOUND SERVICE INFORMATION REMOTE SERVICE NAME LOCAL SERVICE NAME TRANSACTION NAME MAX MESSAGE SIZ n gt ECURITY Y N ENTER PROCESS PF3 MENU PF5 BROWSE Fields 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 Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide The Inbound Service Information Screens Field Name TRANSACTION
90. onfiguration refer to the Dynamically Configuring TMA TCP for CICS section Load Balancing of a Requester The TMA TCP for CICS supports Requester load balancing TMA TCP for CICS provides configuration for multiple services with the same name and the ability to associate them with different unique LMIDs This configuration enables load balancing of the Requesters Automatic Enabling of LMID The TMA TCP for CICS supports automatic enabling of a given Requester which is already disabled The AUTO ENABLE LMID option is provided in the Requester configuration When the option is set to E Enable the Pre Requester automatically enables the LMID and starts the Requester and processes the request Oracle TMA TCP for CICS Components There are four programs used in processing remotely and locally initiated requests e Handler e Application Handler Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide 1 3 1 4 e Pre requester e Requester Two administrative tools are also available e An online CICS administrative tool for configuring and maintaining the TMA TCP for CICS gateway e 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 A Handler is started automatically within a CICS region when Oracle
91. oo full Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide A 9 Error and Informational Messages Informational Process Messages Message RECORD READY FOR UPDATE Description The record selected is ready to be updated Action 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 PFS TO CONFIRM DELETE PRESS ENTER AGAIN The record selected is ready to be deleted Press ENTER to delete the selected record of press PF3 or PF5 to abort the delete DELETE COMPLETED E The record selected for delete has been deleted Select another record to delete or press PF 3 or PFS INQUIRE COMPLETED The record selected for inquiry has been processed Select another record to inquiry or press PF 3 or PFS INSERT COMPLETED The record entered has been inserted into the file Enter another record or press PF3 or PF5 Data Field Error Messages Message INVALID FUNCTION KEY OPTIONS ENTER BE Sis Description this operation The PFKey pressed is not valid in Action Press a valid PFKey See OPTIONS INVALID FUNCTION KEY OPTIONS ENTER PF3 PEs The PFKey pressed is not valid in this operation Press a valid PFKey See
92. out of the structure in C that must be passed in the LINK call is shown in Listing 5 2 The following C structures are in the clienth h INCLUDE file Listing 5 2 C Structures typedef struct CLIENTHDR long DataLen THE LEN OF THE DATA FROM AND TO APPL char SvcName 16 THE SERVICE NAME long RequestCd THE REQUEST COMMAND FROM THE APPL long ReturnCd THE RETURN CODE TO THE APPL long ReqReturnCd THE RETURN CODE FROM THE PREQ AND REQ CLIENTHDR typedef struct CMAREA Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide Client Application Considerations CLIENTHDR CltHdr HEADER char Request data MAX DATA LENGTH REQUEST DATA CMAREA 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 In this case the request is sent over to Oracle Tuxedo for the service to be performed but no response data is sent back BEA_REQUEST_RESPONSE Value is 5 A Request Response Request A request is sent to Oracle Tuxedo and a response is expected back Table 5 1 Request Codes Code Value BEA REQUEST RESPO
93. ove the START TRAN CODE or change the LMID TYPE to CICS QUEUE NAME REQUIRED The QUEUE NAME has not been entered Enter a valid QUEUE NAME CICS DATA INVALID FOR LMID TYPE I IMS T TEP CICS DATA has been entered and the LMID TYPE is not CICS Remove the CICS DATA or change the LMID TYPE to CICS INVALID PORT NUMBER OPTIONS 1 gt 65 535 The PORT NUMBER entered is not valid Enter a valid PORT NUMBER i e 1234 Must not start with a space null or underscore and must be within the range 1 gt 65 535 ACCOUNT ID REQUIRED An ACCOUNT ID is required if you entered a PASSWORD Enter an ACCOUNT or erase the PASSWORD PASSWORD REQUIRED A PASSWORD is required if you entered an ACCOUNT ID Enter a PASWORD or erase the ACCOUNT ID Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide A 11 Error and Informational Messages Message INVALID MAX MSG SIZE OPTIONS 1 gt 32000 Description The MAX MSG SIZE entered is not valid Action Enter a valid MAX MSG SIZE e 4096 Must not start with a space null or underscore and must be within the range 1 gt 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 INVALID SELCDE OPTIONS 1 INS UPD 3
94. ovided in the message header from the remote Tuxedo gateway Unable to start another session The Handler is already processing the maximum number of service requests configured as the multiplex count Unable to start transaction A CICS error occurred attempting to start the transaction Error occurred in Application Handler The Application Handler encountered a CICS error Security error occurred in Application Handler The Application Handler encountered a CICS security error 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 configuring the CICS log refer to the Configuring and Administering Oracle TMA TCP for CICS section Message Goodbye Description 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 A client process has made a request to the TMA TCP for CICS gateway but has not yet established a login connection The connection request protocol was never sent Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide A 3 Error and Informatio
95. p services Follow the installation instructions for TMA TCP given in the Oracle TMA TCP Installation Guide Using the administration tool described in Configuring and Administering Oracle TMA TCP for CICS define the services and remote endpoints for use by TMA TCP The best way to approach this is to talk to the Oracle Tuxedo administrator and choose one service only Attempting to set up all the services at once would be a complex task but after you learn how to set up one service you should have no difficulty setting up the others e Add an EXEC LINK statement to one of your CICS programs and set up the data area as described in Understanding How Oracle TMA TCP for CICS Works Consult your Oracle Tuxedo administrator about service names what to call a service and what Oracle Tuxedo names it and the layout of data each service expects to ensure there are no consistency problems 1 10 Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide CHAPTER Q Understanding How Oracle IMA ICP 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 e Starting the Listener Program e 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 C
96. re modification and adaptation shall be subject to the restrictions and license terms set forth in the applicable Government contract and to the extent applicable by the terms of the Government contract the additional rights set forth in FAR 52 227 19 Commercial Computer Software License December 2007 Oracle USA Inc 500 Oracle Parkway Redwood City CA 94065 This software is developed for general use in a variety of information management applications It is not developed or intended for use in any inherently dangerous applications including applications which may create a risk of personal injury If you use this software in dangerous applications then you shall be responsible to take all appropriate fail safe backup redundancy and other measures to ensure the safe use of this software Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software in dangerous applications Oracle is a registered trademark of Oracle Corporation and or its affiliates Other names may be trademarks of their respective owners This software and documentation may provide access to or information on content products and services from third parties Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third party content products and services Oracle Corporation and its affiliates will not be responsible for any loss costs or damages inc
97. rocessing of all requests that were received before the execution of the BDWN transaction Specifying ALL also frees any shared memory This is the default for BDWN CLEANUP Frees any shared memory of Handlers that have abended CLEANUP does not shut down any Handlers or Requesters HANDLER I Shuts down all Handlers immediately and frees any shared memory of Handlers that have abended This parameter does not shut down any Requesters HANDLER Shuts down all Handlers gracefully allowing them to complete all processing off all requests that were received before the execution of the BDWN transaction This parameter also frees any shared memory of Handlers that have abended It does not shut down any Requesters 2 4 Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide Running Oracle TMA TCP for CICS 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 After a configured number of unsuccessful connection attempts the Requester marks itself disabled If the gateway receives additional service requests they are accommodated as long as the maximum mult
98. s The following table lists the data translation rules that TMA TCP gateway follows Table 2 2 Data Translation Rules Field Type Translation Rules CARRAY Passed untranslated as sequences of bytes STRING and CHAR Translated from ASCII to EBCDIC if needed SHORT Translated to S9 4 COMP 2 8 Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide Translating Data with TMA TCP gateway 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 Therefore a decimal field with a size of 8 5 corresponds to S9 10 V9 5 COMP 3 The following table summarizes the translation rules between C and IBM 370 data types Table 2 3 Translation Rules Between C and IBM 370 Data Types Remote Data Type Description View Field Type Length PIC X n Alpha numeric Characters string n PIC X Single Alpha numeric Character char PIC X n Raw Bytes carray n PIC X Single Numeric Byte carray 1 PIC S9 4 COMP 16 bit Integer short PIC S9 9 COMP 32 bit Integer long COMP 1 Single precision Floating Point float COMP 2 Double precision Floating Point
99. 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 A user from a terminal has attempted to start the transaction that initiates the Application Handler App Handler received corrupted header exiting The Application Handler is terminating on initialization because there is a problem with the header it received This would occur for example if the transaction for the Application Handler was given in the Inbound Service Information screen as the transaction to start a service with no reply opcode is not CONNECT on connection The Requester has received a reply that should be the acknowledgment of a connection request however the message does not contain the correct opcode Trying connection but already connected The Requester has received a reply containing an opcode indicating a response to a connection request however the connection already exists Read on sockets failed Connection closed by other side The Handler terminated because the socket status indicated that the client side had closed the connection LMID is disabled Auto enabling LMID LMID name gt The pre requester is dynamically enabling an LMID which is disabled This message will be displaye
100. ssages Message INVALID SERVICE TIMEOUT SEC Description The SERVICE TIMEOUT SEC entered is not valid Action 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 The AUTO ENABLE Enter a valid option E or D ENABLE D DISABLE LMID E D option entered is not valid or is empty NO CHANGE DONE STATUS The STATUS on the record is E Enter the appropriate STATUS w m ECORD TERED SAME AS ON BEA_REQ_HDR RI FOUND ECORD NOT and you entered an E The STATUS on the record is D and you entered a D The STATUS on the record is A and you entered a A An error occurred within the Connection CSA Contact your system administrator System Error Messages Message Description Action BEG END OF The end of file was detected None FILE during a browse DUPLICATE The record being inserted is Use a different record key RECORD already on the file FILE NOT The file is not available to Contact your system administrator Check the file OPENED CICS status via CEMT DSIDERR Refer to the CICS Application Contact your system administrator Reference Manual ILLOGIC Refer to the CICS Application
101. ted 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 UPDATI E EH After the changes are validated and processed the screen is re displayed and the SERVICE NAME field is unprotected BEAPSVC BEA TMA 10 0 TCP FOR CICS BEAM S2 UPDATE OUTBOUND SERVICE INFORMATION SERVICE NAME LOGICAL MACHINE NAME REMOTE SERVICE NAME SERVICE TIMEOUT SEC n ECURITY Y N ENTER PROCESS PF3 MENU PF5 BROWSE 4 28 Fields Field Name Description SERVICE NAME The service name as it is known to the CICS programmer LOGICAL MACHINE This name is a symbolic name as it was defined on the Update NAME Outbound Service Information screen It denotes the remote machine on which this service should be processed Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide The Qutbound Service Information Screens Field Name Description REMOTE SERVICE The name as it is known in the remote Oracle Tuxedo domain NAME 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
102. til there is a network problem that affects the socket connection The Handler processes service requests up to the configured multiplex count To process more service requests than the configured multiplex count TMA TCP gateway starts more than one Handler For limitations of the IBM Sockets for CICS Listener refer to the appropriate IBM product documentation Initializing the Handler The very first service request that is sent from the TMA TCP gateway gateway running on a remote Oracle Tuxedo node causes the following to occur 1 CICS Sockets Listener starts the TMA TCP for CICS Handler 2 Listener issues a givesocket function call 3 Handler issues a takesocket function call 4 Listener resumes listening for new connection requests 5 Handler communicates directly with the remote TMA TCP gateway gateway using TCP IP Processing Remote Service Requests 1 The TMA TCP Handler receives the request from the remote TMA TCP gateway gateway in the Oracle Tuxedo region over TCP IP If necessary the data is translated and or converted into the proper data format or layout Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide Running Oracle TMA TCP for CICS 2 Ifthe 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 c d The Handler issues a CICS LINK command to execute the program specified in the TM
103. tion code the first one is used and the others are ignored BEAPUSR BEA TMA 10 0 TCP FOR CICS BEAM U5 BROWSE USER CONNECTION ACCOUNTS SE CDE ACCOUNT SELCDE 1 INS 2 UPD 3 INQ 4 DEL BEG END OF FIL ENTER PROC SS PF3 MENU PF7 PREV PF8 NEXT The Inbound Service Information Screens 4 38 A service is a name associated with some component of work That component of work can be a banking transaction an airline flight reservation or an order for a dozen widgets In Oracle Tuxedo a client program that needs work done makes a service request A server performs the work described in the service request on behalf of the client then returns the results of its efforts back to the client In MVS this would be referred to as a call to a black box The service screens use the terms LOCAL SERVICE NAME and REMOTE SERVICE NAME The LOCAL SERVICE NAME such as CIC01XXYYZZ is what the service is known as to your CICS environment and the REMOTE SERVICE NAME such as WITHDRAWL is what the service is known Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide The Inbound Service Information Screens 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 functi
104. ts Products This document refers to the IBM TCP IP sockets interface product If you are using another supported TCP IP product consult that product s documentation for equivalent components IBM TCP IP Sockets for CICS Supplied Listener The IBM TCP IP Sockets for CICS Supplied Listener is responsible for capturing the initial connection request and passing that request along to the TMA TCP for CICS Handler It is a piece of the IBM TCP IP Sockets for CICS product which you must purchase directly from IBM The listener should be installed and configured as outlined in the manual shipped with the product IBM User Maintained Tables UMT The Connection file BEAVCON defaults to a user maintained table UMT If you choose to change this file to a VSAM file you must add the transaction BDWN to PLTSI for CICS This Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide 1 5 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 Requests from within an Oracle Tuxedo Domain Because of the way Oracle Tuxedo maps services to servers service requests from remote Oracle Tuxedo regions to TMA TCP are transparent to the user the Oracle Tuxedo developer and the CICS programmer
105. unning C for CICS I for IMS T for Tuxedo START TRANID The ID of the transaction to be started if the remote system type is CICS CICS DATA A string to be passed to the IBM TCP IP Listener for use with the TMA TCP for CICS gateway The default is ULTIPLEX CNT The number of concurrent requests for each connection IN TIME The minimum length of time in milliseconds for a socket read to wait for data to be processed AX TIME The maximun length of time in milliseconds for a socket read to wait for data to be processed DELTA TIME The time increase in milliseconds from MIN TIME to MAX TIME 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 Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide 4 17 4 18 Field Name REQ IDLE TIME Description 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 QUEUE NAME 2 The unique nam
106. urred due to your access to or use of third party content products or services Contents Introducing Tuxedo Mainframe Adapter for TCP CICS What You Need to KNOW Heinea e e ccc ene REN 1 1 Oracle TMA TCP for CICS Architecture 00 0 ee eee eee 1 2 Oracle TMA TCP Functionality 0 0 0 eee eee eee 1 2 Domains based Gateway Connectivity 0 00 0 cece eee eee eee 1 2 SOCUIILY a a ahaa et i tach eta Bui east aba ch at alte ela tae Ak 1 3 Domain Name Server Support 0 0 0 eee eee eee eee 1 3 Dynamic Configuration soe irota ere AARE AR E AERE A R AAE E R eens 1 3 Load Balancing of a Requester 0 2 0 0 0 eee eee eee 1 3 Automatic Enabling of LMID 0 0 00 eee eee 1 3 Oracle TMA TCP for CICS Components 0 00 eee eee eee 1 3 The TMA TCP for CICS Handler 0 0 0 2 eee eee eee 1 4 The TMA TCP for CICS Application Handler 000 1 4 The TMA TCP for CICS Pre requester 0 0 0 eee eee eee 1 5 The TMA TCP for CICS Requester 0 0 0 0 eee eee eee 1 5 IBM TCP IP Sockets Interface 2 0 0 eee B R 1 5 Using Other Supported TCP IP Sockets Products 000 1 5 IBM TCP IP Sockets for CICS Supplied Listener 00 0 1 5 IBM User Maintained Tables UMT 00 cc ccc eens 1 5 Processing Scenarios 2 0 eee ee ee eee eee eee ene eect eres 1 6 Requests from within an Oracle Tuxedo Domain
107. way ID This name is a unique name up to 16 characters Example bankmach1 DNS The host name that the domain Name Service recognizes HOST ADDRESS The TCP IP dot address Example 199 99 99 99 PORT NUMBER The TCP IP port Check with the TCP IP administrator for available ports Example 1234 SECURITY The status of security Y specifies that security is on and N denotes that security is off Note For additional security information refer to the Configuring the TMA TCP Security section Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide 4 19 4 20 Field Name ACCOUNT ID Description 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 Example LETMEIN1 MAX QUEUE SIZE Specifies the size of the local queue where requests are stored for servicing A typical setting is 200 MAX MSG SIZE The largest message allowed to be sent across this connection The maximum is 32000 Example 4096 RETRY LIMIT If the connection fails this number determines how many
108. xedo Figure 1 2 shows the configuration of the Oracle TMA client gateway A client program your CICS program issues an EX EC CICS LINK command to the Pre requester The Pre requester verifies that the service name is valid and identifies the Requester to which it should it should pass the request The Pre requester starts a different Requester for each configured remote endpoint The Requester then sends the request to the remote Oracle Tuxedo domain and waits for a response Once the resp onse is returned the Requester notifies the Pre requester and hands the response to the Pre requester which then returns the response to the client program Oracle Tuxedo Mainframe Adapter for TCP CICS User Guide 1 9 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 e Ensure that MVS TCP IP is installed and configured e Ensure that the Sockets for CICS interface and supplied listener are installed and configured The listener product comes with the Sockets for CICS interface From the MVS TCP IP administrator find out at which port and address your supplied listener should listen Give this information to the Oracle Tuxedo administrator so that the remote TMA TCP gateway component knows where to find the CICS TCP IP listener Find out on which ports TMA TCP gateway is listening This information is necessary when you begin setting u

Oracle Audio Technologies 12.2 Server User Manual

Contents

Download Pdf Manuals

Related Search

Related Contents