Data Transformation Engine Services Guide

Chapter 19 – Advanced Topics for Mercator Command Server Adapters
113
Cleanup Calls
An application used as a map source or target can be implemented to provide rollback
capability, as specified with the OnFailure adapter setting. It is the responsibility of the
adapter developer to add the processing necessary to implement the rollback. However,
the EXITPARAM structure has been designed to provide the information for passing to
and/or from the application the data necessary to perform this cleanup.
EXITPARAM includes a Boolean, bRollback, for the first time the function executes,
indicating whether or not the user has specified Rollback OnFailure setting for the card
using the application adapter. It is up to the application to recognize the setting of this
flag and do whatever initial processing is necessary.
If the function should be called in a cleanup mode after the map has completed, the
Boolean, bCleanup, should be set to TRUE (1) by the application. Furthermore, lpv may
be set by the adapter to contain any information that needs to be input to the function at
cleanup time.
On the subsequent call to the function after the map, burst or card completes (depending
on the AdapterScope setting), the value of bCleanup will be set, serving as an indicator to
the adapter function that it should operate in clean-up mode. When the function is called
for cleanup mode, lpv contains the data set by the initial call to the function, bCleanup
will be set and nReturn will be used as an input to specify the outcome of the mapping.
Cleanup calls to Get or Put are made at the adapter’s request at a time corresponding to
the transactional scope. Within the Get or Put function, if the adapter wishes to be called
back to complete the transaction or perform some other cleanup, then it should set the
bCleanup flag in EXITPARAM. At the appropriate time, as determined by the
following table, the Get or Put function will be called again, with the bCleanup flag set
to indicate that it is the cleanup call.
Scope Cleanup
Card
Called when the card completes. An adapter may chose to do its
cleanup in the card’s get or put and therefore not set the cleanup call,
and not require any cleanup.
Burst The cleanup is called after the last output card of the burst has been
called.
Map The cleanup is called after the last output card of the map has been
called. If operating in burst mode, the cleanup is called only after all
bursts have completed.
Within the cleanup call, the adapter will typically look at the return status (nReturn) if
OnFailure was specified as ‘Rollback’ and determine whether to perform a ‘commit’ or
‘rollback’ option. If OnFailure was specified as ‘Commit’, then the value of nReturn is
immaterial.
Burst Mode
Burst mode operation allows a map to operate in an iterative manner; to get data from
sources in a piecemeal fashion, or write data out ‘in bursts’. Implementation requires a