Data Transformation Engine Services Guide

Chapter 17 – Calling Interface for Functions
106
The adapter should not attempt to free the memory passed in lpDataToApp. It will be
freed by the Mercator Command Server after the cleanup call.
The Mercator Command Server assigns the address of the mapped data to
lpDataToApp and its length to dwToLen. Then calls the adapter “put” function.
When the library function is completed, it should assign a return code value to nReturn
and an error description to szErrMsg, which will be reported in the Execution Log. Note
that the Mercator Command Server allocates and frees the data at location
lpDataToApp. The ability to call the function after the mapping has completed or in
cleanup mode is also implemented. To enable this cleanup, when the function is called
initially, bCleanup should be set to TRUE (1).
See the section entitled ‘Cleanup Calls’ for more information on the cleanup mechanism.
Disconnect Command
This function is called by the Resource Manager to close the connection to the resource
The function has the prototype:
void Disconnect ( EXITPARAM *lpep );
where:
DwSize The size of EXITPARAM to assure correct compatibility.
Lpv Used as input, the value that was set by the adapter (either in a connect, get or put call) is returned to the
adapter.
Nreturn Used as output, contains the return code representing whether the disonnection was successful or not.
SzErrMsg Used as output, contains the string message based on nReturn.
lpAdaptParms Used as input, contains the adapter specific parameter block of the “parsed” command.
lpContext Used as input, contains the adapter specific context structure containing handles etc for the open connection
bBurst Used as input, TRUE if the card mode is burst.
lpfnMS Used as input, a callback function to the map status function
lpMS Used as input, a pointer to the map status procedure used to communicate to the map status function
The lpContext structure contains fields which contain the handles or connection contexts
that are required to be closed. As well as disconnecting from the resource, the adapter
should also free the memory used by the lpContext structure in this call.
Compare Connections Command
This function is called by the Resource Manager component of the Mercator Command
Server to see whether an existing connection can be reused. The Resource Manager has
a list of open connections, and for each has an adapter parms structure. When it is
determining whether a new connection has to be made, it obtains the adapter parms for
the new command line by calling the ‘Validate Command ’ structure and then compares
this to each adapter parms structure in its list of connections. If CompareConnections
returns a match, then the connection can be reused. Otherwise, a new connection will be
made.
If an adapter does not permit connection reuse then it need not provide this function.