11 External CICS Interface (EXCI)

This chapter contains the following topics:

• Overview
  
• EXCI in Oracle Tuxedo Application Runtime
  

11.1 Overview

The external CICS interface is an application programming interface which enables a non-CICS program running in MVS to:

• Allocate and open sessions to a CICS system, and issue DPL requests on these sessions.
• Call a server program running in a CICS environment, pass and receive data by means of a communications area.

The external CICS interface provides two forms of programming interface:

• The EXCI CALL interface, which consists of six commands that allow you to:
  • Allocate and open sessions to a CICS system from non-CICS programs running under the MVS.
  • Issue DPL requests on these sessions from the non-CICS programs.
  • Close and release the sessions on completion of the DPL requests.
• The EXCI EXEC CICS interface, which provides a single composite command that performs all six commands of the EXCI CALL interface in one invocation.

11.2 EXCI in Oracle Tuxedo Application Runtime

Figure 11-1 EXCI in ART

Each EXCI ART CICS program must be defined as a DPL service in the resource/program.desc file. The seventh column must contain the CICS SYSID, and the service is advertised with the name: <SYSID>_<PROGRAM>.

If a mirror transaction is defined in transaction.desc using DFHMIRS, DPL advertises a service with name <APPLID>_MIRROR_<TRANSID> or MIRROR_<TRANSID>.

If all DPL requests are done with SYNCONRETURN and not under the RRMS control, no Resource Manager is required in the Tuxedo Client. The initialization is done during the first EXCI request process and the Tuxedo session is terminated at the end of the client process.

If RRMS is used or one DPL request is done without SYNCONRETURN, the Tuxedo Client process must be built with one Resource Manager. At the initialization, the Resource Manager is opened and the transaction is begun at the beginning of the Client process. If one of these steps is not successful, the Client process aborts. At the normal end of the client process, the transaction is committed if it was not explicitly done by the client program (RSSCMIT). At the abnormal end of the client process, the transaction is rolled back. In each of these cases the Resource Manager is closed and the Tuxedo session is terminated.

• Supported EXCI Interface
  
• Precompiler Controls
  
• Access Authorization
  
• ART CICS Implementation
  

11.2.1 Supported EXCI Interface

The EXCI precompiler option must be used for CICS client batch program.

The COBOL precompiler supports EXCI CALL or only one CICS command, EXEC CICS LINK with the next described options. The C precompiler only supports EXCI EXEC CICS LINK.

ART CICS supports DFHXCIS API for making EXCI requests (DFHXCIS is a procedure API that client programs make EXCI CALL).

In case of EXEC CICS LINK, the RETCODE command option is mandatory with EXCI but forbidden with NOEXCI, and the APPLID option is EXCI specific. Without EXCI the SYSID option can be used.

With the EXCI precompiler option neither DFHEIBLK nor DFHCOMMAREA is generated as PROCEDURE DIVISION USING parameter.

The EXCI precompiler option is set by inserting a COBOL comment line containing from the seventh column:

*KIX--OPTION EXCI

before IDENTIFICATION DIVISION line.

The EXCI C precompiler option is set by "-B".

ART CICS supports the following EXCI EXEC CICS LINK commands: PROGRAM (name), APPLID (name), and TRANSID (name). DATALENGTH (data-value) is recognized.

11.2.2 Precompiler Controls

• PROGRAM() and RETCODE() are required for the LINK command in EXCI.
• SYSID is not recognized in EXCI.
• COMMAREA must be present if LENTGH or DATALENGTH is present.
• EXCI CICS LINK is the only supported command in EXCI.

11.2.3 Access Authorization

The Tuxedo configuration SECURITY level drives the access authorization.

The MT_EXCIAPPPROFILE environment variable provides the application profile file name generated by the genappprofile ARTKIX tool. The default file name is $HOME/.tuxAppProfile.

In DPL program which is issued by EXCI client, the EXEC CICS ASSIGN USERID() command returns:

The value of $USER environment variable when there is no security level set inside the Tuxedo ubbconfig The value of USERID input in genappprofile tool when enabling security level inside the Tuxedo ubbconfig, the value of USERID is got from .tuxAppProfile and passed by DPL request.

See Oracle Tuxedo Application Runtime for Batch documentation for more details.

In DPL program which is issued by EXCI client, the EXEC CICS ASSIGN USERNAME() command returns:

The value of $USERNAME environment variable no matter whether there is any security level set inside the Tuxedo ubbconfig or not.

11.2.4 ART CICS Implementation

The programs linked via the EXCI interface are advertised by the ARTDPL server. They are named as <program>_<sysid>, where <program> is the linked program name (option PROGRAM(<program>) of EXCI EXEC interface), and <sysid> is the CICS system ID.

The EXCI interface uses the <applid> CICS application ID to address the appropriate CICS region. The relationship between <applid> and <sysid> is made via a specific DPL server service named <applid>_info.

The -a user parameter value of the DPL server command line (CLOPT) is used as <applid> value for the _info service.

If the <applid> is omitted by the client (without APPLID(<applid>) EXCI EXEC interface option), the default_info service is called. This service is advertised by the first DPL booted server.

The _info service returns the <sysid> associated to the server by the -s user parameter of the server command line.

Since ART CICS 12c rolling patch 015, four services are advertised by the ARTDPL server:

• <applid>_CSMI, where <applid> is the CICS application ID to address the appropriate CICS region. This service is called if <transid> is not specified but <applid> is specified in EXCI interface by the client.
• CSMI. This service is called if both <applid> and <transid> are not specified in EXCI interface by the client.
• <applid>_MIRROR_<transid>, where <applid> is the CICS application ID to address the appropriate CICS region, and <transid> is the transaction ID. This service is called if both <applid> and <transid> are specified in EXCI interface by the client.
• MIRROR_<transid>, where <transid> is the transaction ID. This service is called if <applid> is not specified but <transid> is specified in EXCI interface by the client.

• ART Restrictions
  
• SRRCMIT/SRRBACK Functions
  
• Configuration Files Declaration for EXCI EXEC CICS LINK
  

11.2.4.1 ART Restrictions

This section has the following topics:

• Common EXCI Interfaces ART Restrictions
  
• EXCI CALL Interface ART Restrictions
  
• EXCI EXEC Interface ART Restrictions
  

11.2.4.1.1 Common EXCI Interfaces ART Restrictions

• The TRANSID has no meaning. There is no control on it. It is only passed to the DPL service in the EIBTRNID field in DFHEIBLK structure.
• The COMMAREA length is limited to 32763 bytes.

11.2.4.1.2 EXCI CALL Interface ART Restrictions

• Only VERSION-1 is supported.
• The initial user USER-NAME is only used to generate a user-token without any control.
• The DPL UOWID is kept for compatibility only, and is not set and tested.
• The PIPE-TYPE has no meaning. The recognized values for PIPE-TYPE are only X'00' and (X'C3' or X'D8) (X'C3' and X'D8' are the possible ASCII values for X'80' EBCDIC depending code-page). On other value the response code is set to 12 and the reason code to 498.
• The recognized values for SYNC-TYPE are only X'00' and (X'C3' or X'D8') (X'C3' and X'D8' are the possible ASCII values for X'80' EBCDIC depending code-page). On other value the response code is set to 12 and the reason code to 499.

11.2.4.1.3 EXCI EXEC Interface ART Restrictions

The DFHXCRM replaceable-module is not treated.

11.2.4.2 SRRCMIT/SRRBACK Functions

The SRRCMIT and SRRBACK functions are available. ATRCMIT and ATRBACK functions are not supported.

SRRCMI and SRRBACK fuctions must be coded as:

01 SRR-RETCODE PIC 9(8) COMP-5.

CALL "SRRCMIT" USING SRR-RETCODE

CALL "SRRBACK" USING SRR-RETCODE

11.2.4.3 Configuration Files Declaration for EXCI EXEC CICS LINK

To use EXCI EXEC CICS Link command, the system.desc, transactions.desc, and program.desc configuration files should be configured.

Following are configuration examples.

Listing 11‑1 system.desc

[SYSID]
APPLID={applid}

Listing 11‑2 transactions.desc

#TRANSNAME;GROUPNAME; DESCRIPTION; PROGRAM,hardcode with DFHMIRS
ECCI;SIMPDPL;pg for simpapp;DFHMIRS

Listingn 11‑3 program.desc

#PROGRAM;GROUP;DESCRIPTION;LANGUAGE;EXECKEY;STATUS
TOUPSVR;SIMPDPL;pg for simpapp;COBOL; ;ENABLED;KIXD