Monday, January 9, 2012

Call a CICS program from a batch program

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.