IDTSDataPumpTransform Interface
All Data Transformation Services (DTS) custom transformations must implement the IDTSDataPumpTransform interface. Custom transformations that implement IDTSDataPumpTransform but do not implement IDTSDataPumpTransform2 can only be used with Microsoft® SQL Server™ version 7.0. Such transformations only support a single phase of execution.
The IDTSDataPumpTransform interface has the following elements.
| Element | Description |
|---|---|
| Initialize method | Initializes the transformation for the current transform operation. |
| AddVariable method | Adds a variable to the transformations execution context. |
| ValidateSchema method | Validates the schemas that are to be transformed. |
| Execute method | Executes the transformation for a single row. |
| OnRowComplete method | Performs any processing that is necessary after each row has been transformed. |
| OnTransformComplete method | Performs any processing that is necessary after all rows have been transformed. |
As required by COM, all these methods must be present, but they can be placeholders returning NOERROR.
Initialize Method
Initialize can be used to allocate local storage for the transform operation. The output parameter of Initialize is passed to all the other methods so that it can store the state of the particular transform operation. This allows a single instance of the custom transformation to process multiple operations. This is only done when the task that creates the custom transformation passes a reference to a single instance in multiple IDTSDataPump::AddTransform calls.
AddVariable Method
AddVariable is always called at least once to add the DTSErrorRecords collection so that subsequent methods can report errors. It is also called to add the collections used in Microsoft ActiveX® scripts, such as DTSGlobalVariables and DTSLookups.
ValidateSchema Method
ValidateSchema is called after the data pump has opened the source and destination rowsets but before any source rows are fetched. It verifies that the meta data of the columns to be transformed is consistent with the needs of the transformation. Data structures defining the source and destination columns are passed to the method. For more information, see Column Information Structures in DTS Transformations.
ValidateSchema verifies that the number and types of the source and destination columns are appropriate. It also determines whether the transformations being performed are consistent with the specified transform flags. For example, if a column for which NULLs are allowed is being copied to a column defined as NOT NULL, ValidateSchema indicates an error unless the DTSTransformFlag_AllowNullChange is specified. Likewise, it indicates an error if, for example, an int column is being copied to a smallint column, unless DTSTransformFlag_AllowDemotion is specified.
Execute Method
Execute is called to perform the transformation once for each source row. The method returns a code other than NOERROR from the function only in the event of a fatal error, which terminates the data pump. Execute indicates row data errors or specifies the data driven query by returning an appropriate value from DTSTransformStatus. After a successful return from Execute, the data pump attempts to insert the row data into, or perform the indicated data driven query on, the destination rowset.
OnRowComplete Method
OnRowComplete is called after the row data is applied to the destination rowset in an insert operation or a data driven query. It is called even when the insert fails or is not attempted because Execute specified the data not be inserted, or when Execute itself failed. The primary function of OnRowComplete is to release allocations made by Execute that need to be retained until after the row data is applied to the destination.
OnTransformComplete Method
OnTransformComplete is called after all the source rows have been processed. It gives the transformation an opportunity to release allocations and perform any other post-processing that might be necessary. It is not called if IDTSDataPumpTransform2 is implemented and the transformation supports DTSTransformPhase_OnPumpComplete phase, which is called instead. For more information, see IDTSDataPumpTransform2 Interface.
See Also
IDTSDataPumpTransform::AddVariable
IDTSDataPumpTransform::Execute
IDTSDataPumpTransform::Initialize
IDTSDataPumpTransform::OnRowComplete