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.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 RecordThe layout 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 StructuresThe length of the data in the Request_data field.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
Note: For a complete description of these codes, refer to the “Codes Returned to a CICS Client Program” section in Appendix A.
Table 5‑2 Return Codes This code is the return code from the Oracle Tuxedo Domain. See the Oracle Tuxedo documentation for a complete list of Tuxedo error codes.Listing 5‑3 COBOL CICS Client Program ExampleListing 5‑4 C CICS Client Program Example
Note: C Programmers, do not include the NULL terminator on any strings. In the previous example, the memxxx calls were used instead of the strxxx calls. This example is typical when using C and CICS together. For more information see your C for CICS documentation.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.Problems with requests that originate in the CICS region are also logged to the BEALOG file. Additionally, time-out periods for these requests can be tuned using the TMA TCP for CICS administration tool.For more information about the blocking time-out parameter, refer to the Oracle TMA TCP gateway User Guide.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.CICS service programs that are called from Oracle Tuxedo clients must be careful if they give up control, as when performing an EXEC CICS 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.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.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.You can manage 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.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.To modify the return message length on a per request basis, specify the message length in the RTN-MSG-SIZE field in a TWA_CONNECT record layout in the copybook TWACOPY.