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):

•	Client Application Considerations

•	Server Application Considerations

Client Application Considerations

The following sections identify issues that CICS 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.

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 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 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
{
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-RESPONSE	+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.

 

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-OVERFLOW	+21.

ReqReturnCd

This code is the return code from the Oracle Tuxedo Domain. See the Tuxedo documentation for a complete list of Tuxedo error codes

Request_data

This area is the area where request data gets placed and in which your returned data arrives. The length depends on how long this particular service is configured. Check with the administrator for each service. The maximum value is 32000.

Examples

The following sample is an example of a COBOL CICS client program.

Listing 5‑3 COBOL CICS Client Program Example

IDENTIFICATION DIVISION.

PROGRAM-ID. TESTCLN.
ENVIRONMENT 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.
MOVE +14 TO WC-DATALEN.
MOVE 'TOLOWER' TO WC-SVCNAME.
MOVE +5 TO WC-REQUESTCD.
MOVE 'THIS IS A TEST' TO WC-REQDATA.
EXEC CICS LINK PROGRAM('BEAPRERQ')
COMMAREA(WS-COMMAREA)
LENGTH(LENGTH OF WS-COMMAREA)
END-EXEC.
IF RETURNCD = 0
MOVE 'SUCCESSFUL CALL, RETURN DATA IS IN WC-DATA'
TO MSG-DATA
ELSE
MOVE 'PROCESS ERROR OCCURRED, RETURN CODE EQUAL '
TO MSG-DATA
MOVE RETURNCD TO M-RCDE
END-IF.
EXEC CICS SEND TEXT FROM(MSG-AREA) LENGTH(47)
ERASE TERMINAL FREEKB CURSOR(0)
END-EXEC.
A200-EXIT.
EXEC CICS RETURN END-EXEC.

 

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 lmsg;
struct CMAREA carea;

carea.CltHdr.DataLen = strlen(sendbuf);
memcpy(carea.CltHdr.SvcName, “ECHO”, 4);
carea.CltHdr.RequestCd = BEA_REQUEST_RESPONSE;
memcpy(carea.Request_data, “This is a test”, 14);
lmsg=sizeof(carea);
/* Use the name defined during installation */
EXEC CICS LINK PROGRAM("PREREQ")
COMMAREA(&carea)
LENGTH(lmsg) RESP(resp) RESP2(resp2);

if(carea.CltHdr.ReturnCd || carea.CltHdr.ReqReturnCd)
process error;
else
successful call, returned data is in Request_data;

 

Note:

C Programmers, do not include the NULL terminator on any strings. In the previous example, the memxxx calls were used instead of the strxxx calls. This example is typical when using C and CICS together. For more information see your C for CICS documentation.

Error Handling

You may encounter the following three types of errors while using TMA TCP for CICS:

•	Gateway errors (communications problems)

•	MVS or CICS errors

•	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 detection of problems. This configuration parameter is set in the remote TMA TCP gateway system; discuss any changes you want to make with the administrator of that system.

Problems with requests that originate in the CICS region are also logged to the BEALOG file. Additionally, time-out periods for these requests can be tuned using the TMA TCP for CICS administration tool.

For more information about the blocking time-out parameter, refer to the Oracle TMA TCP gateway User Guide.

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

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

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 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 RTN-MSG-SIZE field in a TWA_CONNECT record layout in the copybook TWACOPY.