Data Transformation Engine Services Guide

Chapter 17 – Calling Interface for Functions
105
The adapter can pass its data back to the Mercator Command Server either in a
memory buffer or in a file. If a memory buffer is used, the adapter is responsible for
allocating the memory for the data. Note that the adapter must not free the memory
allocated for the data; the server frees this memory. The adapter specifies that the source
data is in a memory buffer by assigning the address of the memory buffer to
lpDataFromApp and its length to dwFromLen and by not assigning a value to szFile.
The adapter specifies that the source data is in a file by assigning that file’s name
(including path, if necessary) to szFile. In this case, the Mercator Command Server
ignores lpDataFromApp and dwFromLen.
When the adapter completes, it should assign a return code value to nReturn and an error
description to szErrMsg that will be reported in the Execution Log. The ability to call the
function after the mapping has completed or in cleanup mode is also implemented. To
enable this cleanup, when the library function is called initially, bCleanup should be set
to TRUE (1).
The adapter should allocate the memory pointed to by lpDataFromApp using malloc.
This memory is freed by the Mercator Command Server when it has finished with
referencing it.
See the section entitled ‘Cleanup Calls’ for more information on the cleanup mechanism.
Put Command
This function is called by the Resource Manager to put data to the resource.
The function has the prototype:
void Put ( EXITPARAM *lpep );
DwSize The size of EXITPARAM to assure correct compatibility.
DwToLen Used on input, the size of the data passed to the adapter. Note: this is also provided in the cleanup call.
DwMapInstance Used as input, a unique identifier based on an instance of a particular map.
Lpv Used as input, contains the value that was set up in the connect call (if applicable). Whatever value is set by
the adapter, will be returned to the adapter on the cleanup call.
LpszCmdLine Used as input, the command line for the card (if using a 1.4 style command line). Mutually exclusive with
lpCmdStruct.
LpDataToApp Used as input, the data passed to the adapter. Note: this is also provided in the cleanup call.
UretryCount Used as input, a retry count specified by the user.
UretryInterval Used as input, a retry interval (in seconds) specified by the user.
Brollback Used as input, whether or not the user specified rollback.
Bcleanup Used as input and output – if set on calling the adapter is being called to cleanup. Otherwise, the adapter can
set the cleanup flag to indicate that it expects to be called back for a cleanup.
Nreturn Used as output, contains the return code representing whether the put succeeded or not.
SzErrMsg Used as output, contains the string message based on nReturn.
LpCmdStruct Used as input, the command structure for the card (if using 2.0 style commands). Mututally exclusive with
lpszCmdLine. [Not supported for 2.0]
LpAdaptParms Used as input, contains the adapter specific parameter block
LpContext Used as input, contains the adapter specific context structure containing handles etc for the open connection
LpszMapDirectory Used as input, the full path to the directory of the MMC file
WCardNum Used as input, the card number (offset from 0?)
WCleanupAction Used as input, the action to be taken on cleanup
WScope Used as input, the scope of the transaction
BBurst Used as input, TRUE if the card mode is burst.
BFromRule Used as input, set to FALSE if an output card, or TRUE if a PUT function
BSource Used as input, set to FALSE
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
DwRecords Used as output, the number of records (the meaning of which is adapter specific) processed by the adapter