Writing a custom EP adapter

A custom EP adapter is a CICS® program associated with an event binding that formats and then emits events produced by the event binding.

About this task

If the CICS-supplied EP adapters do not meet your requirements for processing events, you can write your own custom EP adapter to process the event data yourself.

CICS invokes the EP adapter for each event that is emitted. The input to a custom EP adapter is the current channel, which contains the CICS event object as a collection of containers. The containers are: DFHEP.CONTEXT, DFHEP.DESCRIPTOR, DFHEP.ADAPTER, DFHEP.ADAPTPARM, and DFHEP.DATA.nnnnn. Copybooks are provided for the DFHEP.CONTEXT, DFHEP.DESCRIPTOR, and DFHEP.ADAPTPARM containers. These copybooks can change with different releases of CICS; therefore, custom EP adapters cannot run on new releases of CICS without recompiling.

In addition to the emitted event, the custom EP adapter must produce an indication of success or failure.

Procedure

  1. Include the event context data copybook for your programming language.
    This copybook describes the DFHEP.CONTEXT container of context data for the event your EP adapter is processing.
    • DFHEPCXD for Assembler language
    • DFHEPCXO for COBOL
    • DFHEPCXL for PL/I
    • DFHEPCXH for C
  2. Include the event descriptor copybook for your programming language.
    This copybook describes the DFHEP.DESCRIPTOR container that describes the captured business data for the event your EP adapter is processing.
    • DFHEPDED for Assembler language
    • DFHEPDEO for COBOL
    • DFHEPDEL for PL/I
    • DFHEPDEH for C
  3. Include the EP adapter parameters copybook for your programming language.
    This copybook describes the DFHEP.ADAPTPARM container.
    • DFHEPAPD for Assembler language
    • DFHEPAPO for COBOL
    • DFHEPAPL for PL/I
    • DFHEPAPH for C
  4. Get the context information from the DFHEP.CONTEXT container using the event context data copybook.
  5. Get the EP adapter custom data. The DFHEP.ADAPTER container contains the data that is specified in the field Data passed to the Custom Adapter that is in the Adapter tab of the CICS event binding editor for your event binding.
    Note: Start of changeThe data in this container is restricted to EBCDIC characters. End of change
  6. Get the EP adapter parameters from the DFHEP.ADAPTPARM container using the EP adapter parameters configuration copy book.
    An important item of information in the DFHEP.ADAPTPARM container is the emission recoverability indicator, EPAP-RECOVER. This container also includes the adapter name, EPAP-ADAPTER-NAME.
  7. The custom adapter must verify the EPAP-RECOVER setting in the DFHEP.ADAPTPARM container in the custom EP adapter.
    EP adapters must emit the events by using a transport in a recoverable or unrecoverable way. If the setting is not EPAP-ANY-RECOVERABLE, you must honor the EPAP-RECOVER setting. To support synchronous emission, EP adapters must be sensitive to the transport recoverability requirement that is indicated by the EPAP-RECOVER setting in the context container:
    • If the field is set to EPAP-RECOVERABLE, the EP adapter must write to the transport in a recoverable way.
    • If the field is set to EPAP-NON-RECOVERABLE, the EP adapter must not write to the transport in a recoverable way.
    You must terminate the adapter if you cannot honor the recoverability setting; otherwise, the transactional requirement for the event is not implemented correctly.

    The field is set to EPAP-ANY-RECOVERABLE for asynchronous emission.

  8. Get the event descriptor from the DFHEP.DESCRIPTOR container using the event descriptor copybook.
    The event descriptor consists of a prefix describing the number of data items in the descriptor and a descriptor for each data item. The data item descriptor includes the name of the business data item and its type. The data items themselves are in containers with a name of format DFHEP.DATA.nnnnn, where nnnnn is a 5-digit sequence number that indicates the ordering of the captured data starting at 00001.
  9. Get data items from the DFHEP.DATA.nnnnn containers.
    Process the items of captured data. For example, you might want to write each item to a CICS transient data queue.
    Note: If a data item was not available for data capture, the corresponding data item container is not present in the CICS event object. This situation can happen, for example, when CAPTURESPEC specifies a capture data item associated with an optional parameter that was not present on the API command that caused the event.
  10. Format the data and emit the event.

    Each item in the DESCRIPTOR array defines the type of the source data captured and the required length and type of that data when and if it is formatted.

    Data is captured up to the length specified in the capture data item spec. The captured data is exactly as found in the source data areas. If the capture data is not available then the corresponding DFHEP.DATA container is not created.

    A format length of Automatic (0) is supported for all data types. When a format length of Automatic is used, the equivalent EPDE field is set to epde_formatLen_auto.

    A format precision of Automatic, resulting in the length that is required for the specified data type and precision being used, is supported for all numeric data types. When a format precision of Automatic is used, the equivalent EPDE field is set to epde_formatPrec_auto.

  11. Complete processing by issuing an EXEC CICS RETURN or EXEC CICS ABEND command.

    In addition to the emitted event, the custom EP adapter must produce an indication of success or failure. A custom EP adapter that cannot emit the event must end with an abend code so that CICS can start any required recovery actions and increment the appropriate statistics.

An example code fragment in the COBOL language

This code fragment shows the sequence of steps described in this procedure. It does not include any processing of the EP adapter information or the data items.

******************************************************************
 Linkage section.                                                 
******************************************************************
 01 EPContext.                                                    
    copy dfhepcxo.                                                
 01 EPDescriptor.                                                 
    copy dfhepdeo.                                                
 01 EPAdapter          pic x(16).                                 
 01 EPAdaptparm                                                   
    copy dfhepapo.                                                
 01 EPData             pic x(32000).                              
******************************************************************
 Main-program section.                                            
******************************************************************
*                                                                 
     perform Initial-processing.                                  
*                                                                 
*    Process the data items                                       
     perform Process-data-item                                    
             varying ItemNum from 1 by 1                          
             until ItemNum > epde-itemcount.                      
*                                                                 
******************************************************************
* Any final EVENT PROCESSING code to go here                      
******************************************************************
*                                                                 
*    Return to caller                                             
     EXEC CICS RETURN END-EXEC.                                   
*                                                                 
 Main-program-exit.                                               
     exit.                                                        
*                                                                 
******************************************************************
 Initial-processing section.                                      
******************************************************************
*                                                                 
*    Obtain the DFHEP.CONTEXT container                           
     EXEC CICS GET CONTAINER('DFHEP.CONTEXT')                     
                   SET(address of EPContext)                      
                   FLENGTH(EPContextLength)                       
     END-EXEC.                                                    
*                                                                 
*    Obtain the DFHEP.DESCRIPTOR container                        
     EXEC CICS GET CONTAINER('DFHEP.DESCRIPTOR')                  
                   SET(address of EPDescriptor)                   
                   FLENGTH(EPDescriptorLength)                    
     END-EXEC.                                                    
*                                                                 
*    Obtain the DFHEP.ADAPTER container                           
     EXEC CICS GET CONTAINER('DFHEP.ADAPTER')                     
                   SET(address of EPAdapter)                      
                   FLENGTH(EPAdapterLength)                       
     END-EXEC.                                                    
*                                                                 
*    Obtain the DFHEP.ADAPTPARM container                           
     EXEC CICS GET CONTAINER('DFHEP.ADAPTPARM')                     
                   SET(address of EPAdaptparm)                      
                   FLENGTH(EPAdaptparmLength)                       
     END-EXEC.                                                    
*                                                                 

*    Check the recoverability of the transport is right for the event
     if not epap-any-recoverable                                  
       perform Check-recoverability.                                

*                                                                 
 Initial-processing-exit.                                         
     exit.                                                        
*                                                                 
******************************************************************
 Process-data-item section.                                       
******************************************************************
*                                                                 
*    Process a data descriptor item                               
*                                                                 
*    Build the data container name: DFHEP.DATA.nnnnn              
     string 'DFHEP.DATA.' delimited by size                       
            ItemNum         delimited by size                     
            into ContainerName                                    
     end-string.                                                  
*                                                                 
*    Obtain the DFHEP.DATA.nnnnn container - if present           
     EXEC CICS GET CONTAINER(ContainerName)                       
                   SET(address of EPData)                         
                   FLENGTH(EPDataLength)                          
                   RESP(Resp) RESP2(Resp2)                        
     END-EXEC.                                                    
******************************************************************
* Any final code to process DATA ITEM to go here                  
******************************************************************
*                                                                 
*    Convert the data according to epde-datatype                  
     perform Convert-data.                                        
*                                                                 
*    Calculate the target field length                            
     move epde-formatlen of epde-item(ItemNum) to TSQFieldLength  
     if TSQFieldLength = 0 and Resp = dfhresp(normal)             
       move TSQItemLength to TSQFieldLength                       
     end-if                                                       
     if 32001 - TSQFieldIndex < TSQFieldLength                    
       compute TSQFieldLength = 32001 - TSQFieldIndex             
     end-if.                                                      
*                                                                 
*    Format the data according to epde-formattype                 
     perform Format-data.                                         
*                                                                 
*    Move over the data item ready for the next one               
     add TSQFieldLength to TSQFieldIndex.                         
*                                                                 
 Process-data-item-exit.                                          
     exit.                                                        
*                                                                 
******************************************************************