The external CICS interface (EXCI) is an application programming interface that enables a non-CICS program (a client program) running in MVS to call a program (a server program) running in a CICS region and to pass and receive data by means of a communications area. The CICS application program is invoked as if linked-to by another CICS application program.
This programming interface allows a user to allocate and open sessions, or pipes (a one-way communication path between a sending process and a receiving process) to a CICS region, and to pass distributed program link (DPL) requests over them. The multiregion operation (MRO) facility of CICS interregion communication (IRC) facility supports these requests, and each pipe maps onto one MRO session, where the client program represents the sending process and the CICS server region represents the receiving process.
To do this, we need to define a connection and session as shown below. The session is defined with “RECEIVE count=4” which means four different batch jobs can use EXCI connection simultaneously.
CEDC View CONnection( RXCI )
CONnection : RXCI
Group : TSTEXCI
DEScription : RXCI SPECIFIC CONNECTION
CONNECTION IDENTIFIERS
Netname : TSTNETNM
INDsys :
REMOTE ATTRIBUTES
REMOTESYSTem :
REMOTEName :
REMOTESYSNet :
CONNECTION PROPERTIES
ACcessmethod : IRc Vtam | IRc | INdirect | Xm
PRotocol : Exci Appc | Lu61 | Exci
COnntype : Specific Generic | Specific
SInglesess : No No | Yes
DAtastream : User User | 3270 | SCs | STrfield | Lms
+ RECordformat : U U | Vb
CEDC View Sessions( RXCI )
Sessions : RXCI
Group : TSTEXCI
DEScription : RXCI SPECIFIC SESSIONS DEFINITION
SESSION IDENTIFIERS
COnnection : RXCI
SESSName :
NETnameq :
MOdename :
SESSION PROPERTIES
Protocol : Exci Appc | Lu61 | Exci
MAximum : 000 , 000 0-999
RECEIVEPfx : PX
RECEIVECount : 004 1-999
SENDPfx :
SENDCount : 1-999
SENDSize : 04096 1-30720
+ RECEIVESize : 04096 1-30720
We need to invoke the target CICS program thru a mirror transaction. So, the below transaction is defined to invoke the IBM supplied mirror transaction program DFHMIRS. The EXCI call will invoke this transaction which in turn performs LINK to the target application program.
I TRAN(TXCI)
STATUS: RESULTS - OVERTYPE TO MODIFY
Tra(KXCI) Pri( 001 ) Pro(DFHMIRS ) Tcl( TSTEXCI ) Ena Sta
Pur Prf(DFHCICSA) Uda Any Iso Bac Wai
The EXCI CALL interface consists of five commands that allow us to:
- Allocate and open sessions to a CICS system from non-CICS programs running
under MVS
- Issue distributed program link (DPL) requests on these sessions from the
non-CICS programs
- Close and deallocate sessions on completion of DPL requests.
The five EXCI commands are:
- Initialize_User – It initializes the user environment. This includes obtaining authority to use IRC.facilities.
- Allocate Pipe – It logs on to the target CICS region
- Open_Pipe and DPL_Request – It inokes the mirror transaction which in turn LINKs to the target application program
- Close_Pipe – It disconnects the session from the CICS region
- Deallocate_Pipe – It destroy the CICS session
The below sample COBOL program calls a CICS program using EXCI call interface.
WORKING STORAGE section code
01 PROGRAM-FIELDS.
05 EXCI-UNPACKED PIC Z(08).
05 TARGET-PROGRAM PIC X(08) VALUE 'MYTSTPGM'.
05 TARGET-TRANSID PIC X(04) VALUE 'TXCI'.
05 TARGET-SYSTEM PIC X(08).
05 TARGET-USERID PIC X(08).
05 NET-NAME PIC X(08) VALUE 'TSTNETNM '.
05 USER-TOKEN PIC S9(08) COMP VALUE ZERO.
05 PIPE-TOKEN PIC S9(08) COMP VALUE ZERO.
05 COMM-LENGTH PIC S9(08) COMP VALUE 1340.
05 DATA-LENGTH PIC S9(08) COMP VALUE 1340.
05 VERSION-1 PIC 9(8) COMP VALUE 1.
05 VERSION-2 PIC 9(8) COMP VALUE 2.
05 INIT-USER PIC 9(8) COMP VALUE 1.
05 ALLOCATE-PIPE PIC 9(8) COMP VALUE 2.
05 OPEN-PIPE PIC 9(8) COMP VALUE 3.
05 CLOSE-PIPE PIC 9(8) COMP VALUE 4.
05 DEALLOCATE-PIPE PIC 9(8) COMP VALUE 5.
05 DPL-REQUEST PIC 9(8) COMP VALUE 6.
05 SPECIFIC-PIPE PIC X(01) VALUE X'00'.
05 GENERIC-PIPE PIC X(01) VALUE X'80'.
05 NOSYNCONRETURN PIC X(01) VALUE X'00'.
05 SYNCONRETURN PIC X(01) VALUE X'80'.
01 WS-COMM-AREA PIC X(1340).
*****************************************************************
*
* EXCI_RETURN_CODE : STRUCTURE OF THE RETURN_AREA REQUIRED FOR
* ALL CALL API REQUESTS OF THE EXTERNAL CICS
* INTERFACE.
*****************************************************************
01 EXCI-RETURN-CODE.
05 EXCI-RESPONSE PIC 9(8) COMP.
05 EXCI-REASON PIC 9(8) COMP.
05 EXCI-SUB-REASON1 PIC 9(8) COMP.
05 EXCI-SUB-REASON2 PIC 9(8) COMP.
05 EXCI-MSG-PTR POINTER.
*****************************************************************
*
* EXCI_DPL_RETAREA : STRUCTURE OF THE DPL_RETAREA REQUIRED ON A
* DPL REQUEST USING THE CALL API OF THE
* EXTERNAL CICS INTERFACE.
*
*****************************************************************
01 EXCI-DPL-RETAREA.
05 EXCI-DPL-RESP PIC 9(8) COMP.
05 EXCI-DPL-RESP2 PIC 9(8) COMP.
05 EXCI-DPL-ABCODE PIC X(4).
PROCEDURE DIVISION code
MOVE ‘CICSTEST’ TO TARGET-SYSTEM.
/* Supply the netname defnined in the connection */
MOVE ‘TSTNETNM’ TO NET-NAME.
/* Supply the TSO user id */
MOVE ‘TSUXXAX’ TO TARGET-USERID.
CALL 'DFHXCIS' USING VERSION-1 EXCI-RETURN-CODE USER-TOKEN
INIT-USER NET-NAME
IF EXCI-RESPONSE IS NOT = 0
DISPLAY 'INITIALIZE FAILED'
MOVE EXCI-REASON TO EXCI-UNPACKED
DISPLAY 'REASON CODE=' EXCI-UNPACKED
CALL ABORT program
END-IF
DISPLAY 'INIT SUCCESSFUL'.
CALL 'DFHXCIS' USING VERSION-1 EXCI-RETURN-CODE USER-TOKEN
ALLOCATE-PIPE PIPE-TOKEN TARGET-SYSTEM
SPECIFIC-PIPE
IF EXCI-RESPONSE IS NOT = 0
DISPLAY 'ALLOCATION FAILED'
MOVE EXCI-REASON TO EXCI-UNPACKED
DISPLAY 'REASON CODE=' EXCI-UNPACKED
CALL ABORT program
END-IF
DISPLAY 'PIPE ALLOCATED'.
CALL 'DFHXCIS' USING VERSION-1 EXCI-RETURN-CODE USER-TOKEN
OPEN-PIPE PIPE-TOKEN
IF EXCI-RESPONSE IS NOT = 0
DISPLAY 'OPEN PIPE FAILED'
MOVE EXCI-REASON TO EXCI-UNPACKED
DISPLAY 'REASON CODE=' EXCI-UNPACKED
CALL ABORT program
END-IF
DISPLAY 'PIPE OPENED'.
SET ADDRESS OF NULL-PTR TO NULLS.
CALL 'DFHXCIS' USING
VERSION-1 EXCI-RETURN-CODE USER-TOKEN
DPL-REQUEST PIPE-TOKEN TARGET-PROGRAM
WS-COMM-AREA
COMM-LENGTH DATA-LENGTH TARGET-TRANSID
NULL-PTR TARGET-USERID EXCI-DPL-RETAREA
SYNCONRETURN
IF EXCI-RESPONSE NOT = 0
DISPLAY 'LINK FAILED'
MOVE EXCI-REASON TO EXCI-UNPACKED
DISPLAY 'REASON CODE=' EXCI-UNPACKED
DISPLAY 'ABEND CODE=' EXCI-DPL-ABCODE
CALL ABORT program
END-IF
CALL 'DFHXCIS' USING VERSION-1 EXCI-RETURN-CODE USER-TOKEN
CLOSE-PIPE PIPE-TOKEN.
DISPLAY 'PIPE CLOSED'.
CALL 'DFHXCIS' USING VERSION-1 EXCI-RETURN-CODE USER-TOKEN
DEALLOCATE-PIPE PIPE-TOKEN.
DISPLAY 'PIPE DEALLOCATED'.
No comments:
Post a Comment
Note: Only a member of this blog may post a comment.