The AddTransform method adds a transformation to the data pump.
HRESULT AddTransform (
LPBYTE pvUserData,
LPCDTSTransformColumnsSpecification pColumns,
DTSGuid ServerClsid,
VARIANT ServerParameters,
DTSTransformFlags dwFlags,
IStorage *pIStorage );
| Argument | Description |
|---|---|
| pvUserData [in] | Data that is passed to the event sink if an event occurs during a transformation |
| pColumns [in] | Source and destination columns |
| ServerClsid [in] | COM server ProgID, CLSID, or IUnknown |
| ServerParameters [in] | Server parameters for the current transformation |
| dwFlags [in] | Transformation column-validation flags |
| *pIStorage [in] | Pointer to persistent storage of transformation properties |
The data pump calls the CoCreateInstance function on the object specified by ServerClsid. The COM object specified must support the IDTSDataPumpTransform interface and is responsible for verifying that the source and destination column values can be converted as specified.
The variant ServerParameters may be of type VT_UNKNOWN. If ServerParameters has the type VT_UNKNOWN, then the VT_UNKNOWN pointer is used to access the IDTSDataPumpTransform interface using the OLE DB QueryInterface method. This allows the data pump to use custom COM objects that have not been previously registered on the system, making it easier to distribute custom transformations. This is also used when providing a transformation server whose properties must be set programmatically by the data pump consumer prior to adding the transformation. In this case, the consumer creates an instance of the object, calls IUnknown::QueryInterface, and sets the properties.
If an IUnknown pointer is passed to the data pump, the data pump determines whether the pointer has previously been passed, and if so, appropriately handles calling OnNextRow only one time, regardless of how many times that pointer has been passed as a transformation server. In this case, ServerParameters specifies the shared object to handle. This is useful for objects that need to perform specific row-by-row aggregations without potentially conflicting with named variables added by AddTransform.
The transformation validation is controlled by the DTSTransformFlags constants specified in the parameter list. If different validations are required for different columns of the row, then a separate transformation must be added.
ServerClsid allows specification of the transformation server’s CLSID as a CLSID, ProgID, or as an existing IUnknown object implementing the IDTSDataPumpTransform interface.
pIStorage is used to set the transformation server’s properties, after an instance of the transformation is created, if necessary.
pvUserData allows information about a specific transformation to be passed to an event sink. This pointer is not passed to the transformation server; ServerParameters performs that task.
Transformations are always invoked in the order they are added.