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
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
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.
*
******************************************************************