[Top] [Previous] [Next] [End of Book]

# Chapter 6 . Programming BEA Connect TCP for CICS

## Programming Considerations

The following subsections identify issues that CICS programmers should be aware of when they develop or modify application programs that interoperate with Connect TCP for CICS.

### Introduction

A CICS application program that processes requests originating from a remote BEA 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 BEA TUXEDO requests are the ones that perform a certain operation and return information to the caller. The CICS services requested by a BEA TUXEDO client program must entail a single request/response scenario.

CICS service programs that are called from BEA 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 BEA Connect TCP for CICS Handler by the final program in the chain.

To make requests to remote BEA 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 BEA TUXEDO should be agreed upon by the CICS applications programmer, the BEA TUXEDO applications developer, and the BEA 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 BEA TUXEDO domain, make an EXEC CICS LINK call to the Pre-requester. The service you want to access must be configured by the BEA Connect Administrator, but from a programming point of view the LINK call is all you need.

> Listing 6-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 as follows:

> Listing 6-2 C Structure

>     struct callstruct {
>      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 to the appl */
>      char Request_data[DATALEN]; /*This length should be the max length
>     				 between the request data and the
>     				 respond data*/ } CALLSTRUCT

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_ONLY - Value is 7. A No Reply Service Request. In this case the request will be sent over to BEA TUXEDO for the service to be performed, but no response data will be sent back.

  BEA_REQUEST_RESPONSE - Value is 5. A Request/Response Request. A request is sent to BEA TUXEDO and a response is expected back.

`ReturnCd`
  This is the return code from the BEA TUXEDO domain.

`ReqReturnCd`
  This is the return code from the CICS Requester.

  For both return codes, a 0 signifies a successful service call return. All other return and request codes are listed in the following tables. Some apply to one of the return code fields and some to the other. Notify the administrator if any of the return codes indicate a processing or network problem.

  > Table 6-1 Request Codes

  Code | Value
  --- | ---
  BEA-REQUEST-RESPONSE | +5.
  BEA-REQUEST-NORESPONSE | +7.

  > Table 6-2 Response 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.

`Request_data`
  This 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 for. Check with the administrator for each service. The maximum value is 32000.

#### Examples

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

> Listing 6-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 6-4 C CICS Client Program Example

>     long resp, resp2;
>     unsigned short int lmsg;
>     struct CALLSTRUCT carea;

>     carea.DataLen = strlen(sendbuf);
>     memcpy(carea.SvcName, "ECHO", 4);
>     carea.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.ReturnCd || carea.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 is typical when using C and CICS together. For more information see your C for CICS documentation.

### Error Handling

There are three types of errors you may encounter while using BEA Connect TCP for CICS:

- Gateway errors (communications problems)

- MVS or CICS errors

- Application errors

The following subsections explain how Connect TCP handles these different kinds of errors.

#### Gateway Errors

When local or remote gateway errors occur they are logged in the BEA TUXEDO ULOG file on the remote BEA 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 Connect gateways are able to communicate with each other, error messages are communicated between them.

#### MVS or CICS Errors

For requests originating in the BEA TUXEDO domain, if the remote target system does not make it possible for Connect TCP for CICS to detect particular types of failure, the Connect TPS (the BEA TUXEDO domain) blocking time-out parameter can be tuned to provide timely detection of problems. This configuration parameter is set in the remote Connect TPS system; discuss any changes you wish 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 BEA Connect TCP for CICS administration tool.

See the BEA Connect TPS User Guide for more information about the blocking time-out parameter.

#### Application Errors

If an error occurs that makes the Handler unable to execute a certain program (i.e., the program does not exist or is disabled) the Handler sends a message back to the Connect TPS 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, BEA TUXEDO will return information about specific problems, if possible. If there are network problems that prohibit the transmission of data, the request will receive a time-out error.

## Application Server Considerations

If you want to manage the actual size of the message sent back over the gateway, you must address the TWA using the delivered copybook in the "YOURHLQ".BEATCPC.INCLUDE JCL file. You can modify the TWA and specify the size for the return message. The COBOL copybook member is `TWACOPY` and the C copybook member is `TWAINCL.`

[Top] [Previous] [Next] [End of Book]