dtspump.h

sql2000 DEVTOOLS INCLUDE

	//
	DTSBindMode_Byref_ClientOwned				= 0x00000003,

	// By itself, ProviderOwned is seldom used by itself except for BSTR, which does not always
	// support Byref.  It is primarily for DBTYPE_((W)STR|BYTES) with Byref, to reduce allocations
	// and/or copies, as described below.  It may not be supported by providers for other datatypes.
	//
	DTSBindMode_ProviderOwned					= 0x00000004,

	// This flag causes source columns to be bound to return a pointer into the provider's memory
	// space for DBTYPE_((W)STR|BYTES).  This pointer is read-only and must not be freed.
	//
	// For Blob columns, the Source Provider may not support (Byref_)ProviderOwned Blobs; this
	// would require that the entire Blob be buffered contiguously.  Therefore, unless you have
	// specific knowledge of the provider, this flag is discouraged.
	//
	// For DBTYPE_BSTR, the BYREF specification may not be supported, and may require DBMEMOWNER_PROVIDEROWNED
	// (without BYREF).  The client must not free the data.
	//
	// For other types, including DBTYPE_VARIANT, OLEDB raises an error for this specification
	// when creating an accessor.
	//
	// For the destination, specifying ProviderOwned requires that the data be shallow-copied into
	// the destination binding to avoid memory leaks (this is automatically done by IDTSDataConvert::
	// ConvertToBinding).
	//
	DTSBindMode_Byref_ProviderOwned				= 0x00000005,

	// This indicates whether the Pump should buffer Source Blob Storage Objects.  For most cases,
	// this should be left _BufferDefault; for performance reasons, the DataPump will only buffer
	// where it is necessary to avoid data loss.  This is in the following cases:
	//	DTSBindMode_Blob_BufferAlways
	//	DTSBindMode_Blob_BufferDefault, provider doesn't allow multiple SO's, and any of following:
	//		The column is referenced in a subsequent transform.
	//		The column is not the rightmost column of all transforms up to and including it.
	//
	// The DataPump can buffer from a source provider's ISequentialStream or ILockBytes, and
	// exposes both these interfaces on its own object.  Because it is a buffer, the object's data
	// can be edited via Write(At) to reduce memory requirements in the TransformServer (allowing the
	// source object to be placed in the destination row, if the destination supports Storage Objects).
	//
	// DTSBindMode_Blob_* is ignored for in-memory binding, which is an implicit buffering.
	DTSBindMode_Blob_BufferDefault				= 0x00000010,
	DTSBindMode_Blob_BufferAlways				= 0x00000020,
	DTSBindMode_Blob_BufferNever				= 0x00000040,

	// This indicates whether to use a Structured Storage object for binding a BLOB column.  The Transform
	// Server should indicate which interface it wants in DTSBindInfo::fStorageObject, on return from
	// ValidateSchema().  The DataPump supports the following behaviour:
	//    Custom Transformations:
	//       For Source, if the DataPump does not buffer, only the provider-supported Storage Object interfaces
	//			are available.  Generally this will always include ISequentialStream.  See comments regarding
	//			DTSBindMode_Blob_Buffer*; if the DataPump buffers the Blob data, it supports only ISequentialStream
	//			and ILockBytes.
	//          If the source does not support storage objects, then the Transform Server must not request a
	//			Storage Object, and must bind the source data as in-memory, specifying DTSBindInfo::cbInMemoryBlobSize.
	//       For Destination, the Transform Server supplies the Storage object placed into the row, and must
	//			specify one interface from fProviderStorageObjects for the DataPump to bind the destination.
	//          If the destination does not support storage objects, then the TransformServer must not request
	//			a Storage Object, and must bind the destination data as in-memory, ClientOwned or ProviderOwned,
	//			specifying DTSBindInfo::cbInMemoryBlobSize.
	//    Default (DataPump-supplied) TransformCopy:
	//       If either Source or Destination do not support ISequentialStream, then the DataPump will bind both
	//          as ClientOwned in-memory, using the source column's DTSBindInfo::cbInMemoryBlobSize.
	//			Otherwise, the DataPump will bind to the providers as ISequentialStream, with default buffering.
	//			See also comments regarding DTSBindMode_Blob_Buffer*; this can be specified to override the
	//			Pump's default handling even in the TransformCopy case.
	//
	// DTSBindMode_Blob_StorageObject cannot be specified with non-DTSBindMode_Blob_* flags.
	DTSBindMode_Blob_StorageObject				= 0x00000100,

	// Allow a Byref or StorageObject binding to be downgraded to an inline binding by a subsequent transform.
	// If not set and a subsequent transform tries to change the binding, it will fail.
	DTSBindMode_AllowInlineOverride				= 0x00001000,

	// Column has already been bound by a prior transform.  Current transform should avoid re-specifying
	// bind info, or may attempt legal rebinding (AllowInlineOverride).
	DTSBindMode_BoundInPriorTransform			= 0x00002000,
} DP_ENUM_END(DTSBindMode);

// Indicates which of the DataPump defaults are to be overridden on a single AddTransform().
typedef DP_ENUM_BEGIN(DTSSpecifyBlobDefaults, "Specify overrides of DataPump Blob-handling defaults") {
	DTSBlobDefault_DataPumpDefaults		= 0x0000,	// None (initialization)
	DTSBlobDefault_BufferSource			= 0x0001,	// Override DTSBindMode_Blob_BufferDefault for source Blob Storage Objects
	DTSBlobDefault_InMemorySize			= 0x0002,	// Override DTS_DEFAULT_INMEMORY_BLOB_SIZE.
	DTSBlobDefault_ForceInMemory 		= 0x0004,	// Force Blobs to be InMemory (no Storage Objects) for this Transform.
													// Forces DTSTransformColumnInfo.fProviderStorageObjects
													// sent to the Transformer to be 0.
	DTSBlobDefault_ForceMultipleStorageObjects	= 0x0008,	// Forces DTSTransformColumnInfo.dtsProviderFlags sent to the
													// Transformer to include DTSProviderFlag_Blob_MultipleStorageObjects.
													// This could be an optimization if the Source provider supports multiple
													// storage objects and the destination is known to support them only
													// multiple blobs for insert, since the OLEDB spec does not distinguish
													// between multiple-StorageObject support for GetData vs. SetData/Insert.
} DP_ENUM_END(DTSSpecifyBlobDefaults);

// Flags indicating known Provider Blob capabilities; their absence indicates
// corresponding Provider restrictions or requirements.
typedef DP_ENUM_BEGIN(DTSProviderFlags, "Provider behaviour characteristics") {
	DTSProviderFlag_None					= 0x00000000,	// None

	DTSProviderFlag_ProviderOwned			= 0x00000001,	// Provider supports Byref binding (some may not).

	DTSProviderFlag_Blob_InsertNoLength		= 0x00000100,	// Blob Inserts do not require length to be prespecified
	DTSProviderFlag_Blob_Revisitable		= 0x00000200,	// Provider guarantees that Blob data is not skipped when succeeding columns fetched
	DTSProviderFlag_Blob_Rewindable			= 0x00000400,	// Provider guarantees Blob data supports random access
	DTSProviderFlag_Blob_ProviderOwned		= 0x00000800,	// Provider allows the PROVIDEROWNED flag for use with Blobs
	DTSProviderFlag_Blob_MultipleStorageObjects = 0x00001000,		// Provider supports multiple storage objects per row.
	DTSProviderFlag_Blob_NonBlockingStorageObjects = 0x00002000,	// Provider supports multiple nonblocking storage objects per row.
} DP_ENUM_END(DTSProviderFlags);

// Extended options on DataPump operation.
typedef DP_ENUM_BEGIN(DTSDataPumpOptions, "Extended options on DataPump operation") {
	DTSDataPumpOpt_Default						= 0x00000000,	// Default operation

	// Always commit final batch even on DataPump abort (to support restartability).
	DTSDataPumpOpt_AlwaysCommitFinalBatch		= 0x00000001,

} DP_ENUM_END(DTSDataPumpOptions);
typedef DTSDataPumpOptions *LPDTSDataPumpOptions;

// The actual structure passed to AddTransform to specify overriding Blob defaults.
// This is most useful for the default TransformCopy case, but can also be used by
// a client who predetermines (e.g. via a query) the maximum Blob size in the coming
// result set, for the most efficient memory allocations.
#ifndef DP_NO_AUTOCTOR
	struct DTSTransformBlobDefaults {
#else   // DP_NO_AUTOCTOR
	typedef struct {
#endif  // DP_NO_AUTOCTOR
		DTSSpecifyBlobDefaults dtsSpecifyMask;		// Which of the following items to override.
		BOOL bBufferSource;							// If dtsSpecifyMask & DTSBlobDefault_BufferSource;
													// TRUE or FALSE forces Pump to buffer source Blobs or not.
		ULONG cbInMemorySize;						// If dtsSpecifyMask & DTSBlobDefault_InMemorySize;
													// overrides DTS_DEFAULT_INMEMORY_BLOB_SIZE.  Size in bytes.
#ifndef DP_NO_AUTOCTOR
		DTSTransformBlobDefaults()
				: dtsSpecifyMask(DTSBlobDefault_DataPumpDefaults)
			{	}
	};
#else   // DP_NO_AUTOCTOR
	} DTSTransformBlobDefaults;
#endif  // DP_NO_AUTOCTOR
typedef DTSTransformBlobDefaults *LPDTSTransformBlobDefaults;
typedef const DTSTransformBlobDefaults *LPCDTSTransformBlobDefaults;

// Specifies an individual column passed to AddTransform.  The column may be specified by
// name, or if the name is NULL, by an ordinal (this makes unnamed columns easier for the
// consumer to specify).
typedef struct {
	LPOLESTR pwzColumnName;						// Name of column
	ULONG ulColumnOrdinal;						// Ordinal of column if name is NULL; 1-based for OLEDB consistency.
} DTSTransformColumnSpecification, *LPDTSTransformColumnSpecification;
typedef const DTSTransformColumnSpecification *LPCDTSTransformColumnSpecification;

// Specifies a list of columns passed to AddTransform.
#ifndef DP_NO_AUTOCTOR
	struct DTSTransformColumnsSpecification {
#else   // DP_NO_AUTOCTOR
	typedef struct {
#endif  // DP_NO_AUTOCTOR

		ULONG cSourceColumns;						// Specify source columns
		LPCDTSTransformColumnSpecification pSourceColumns;
		ULONG cDestinationColumns;					// Specify destination columns
		LPCDTSTransformColumnSpecification pDestinationColumns;
		DTSTransformBlobDefaults BlobDefaults;		// Blob default overrides if specified

#ifndef DP_NO_AUTOCTOR
		DTSTransformColumnsSpecification() 
				: cSourceColumns(0)
				, pSourceColumns(NULL)
				, cDestinationColumns(0)
				, pDestinationColumns(NULL)
			{	}
	};
#else   // DP_NO_AUTOCTOR
	} DTSTransformColumnsSpecification;
#endif   // DP_NO_AUTOCTOR
typedef DTSTransformColumnsSpecification *LPDTSTransformColumnsSpecification;
typedef const DTSTransformColumnsSpecification *LPCDTSTransformColumnsSpecification;

// Specifies a query and list of columns for IDTSDataDrivenQuery.
#ifndef DP_NO_AUTOCTOR
	struct DTSTransformQuerySpecification {
#else   // DP_NO_AUTOCTOR
	typedef struct {
#endif  // DP_NO_AUTOCTOR

		LPCOLESTR wzQuery;								// The Parameterized Query
		ULONG cColumns;									// Specify count of columns
		LPCDTSTransformColumnSpecification pColumns;	// Specify column mapping to parameters, in order found in query.

#ifndef DP_NO_AUTOCTOR
		DTSTransformQuerySpecification() 
				: wzQuery(NULL)
				, cColumns(0)
				, pColumns(NULL)
			{	}
	};
#else   // DP_NO_AUTOCTOR
	} DTSTransformQuerySpecification;
#endif   // DP_NO_AUTOCTOR
typedef DTSTransformQuerySpecification *LPDTSTransformQuerySpecification;
typedef const DTSTransformQuerySpecification *LPCDTSTransformQuerySpecification;

// Transform-server specifiable binding information.  An array of these structures is passed to
// ValidateSchema() with default values (possibly derived from DTSTransformBlobDefaults overrides),
// and the Transform Server can set the values.  Because source columns can appear multiple times
// in the same or different transactions, the last specification wins; therefore, a TransformServer's
// Execute() method should gracefully handle a source binding different from what it specified in
// ValidateSchema().
typedef struct {
	DTSBindMode eBindMode;						// Per above.  For Blobs, specifying a Buffering mode overrides
												// the DataPump and any DTSTransformBlobDefaults default.
	DWORD fStorageObject;						// For DTSBindMode_Blob_StorageObject; one of DBPROPVAL_SS_*.  If
												// specified, eBindMode must be DTSBindMode_Blob_StorageObject.
	ULONG cbInMemoryBlobSize;					// For DTSBindMode of inmemory Blobs.  Setting this value overrides
												// the DataPump and any DTSTransformBlobDefaults default.  Size in bytes.
} DTSBindInfo;

// This is a single column definition, binding, and data item for DTSTransformColumnInfo.
typedef struct {
	const DBCOLUMNINFO *pDBColumnInfo;			// Pointer to source or destination DBCOLUMNINFO for this column.
	const DBBINDING *pDBBinding;				// Pointer to source or destination DBBINDING for this column.
												// wType == DBTYPE_EMPTY if this column is not referenced in any transform.
	DTSBindInfo *pDTSBindInfo;					// Pointer to source or destination DTSBindInfo for this column.
	LPBYTE pvData;								// Data space for this column, indexed by pDBBinding offsets.
												// NULL if this column was not referenced in any Transform.
} DTSColumnData;

// The DBCOLUMNFLAGS and pwszName are in DBCOLUMNINFO and not DBBINDING;
// therefore pass both structures to transform code.  The COM Transform server uses the
// binding info to access the pvRowData.  This structure is passed to ITransformExecute::
// Execute to expose the source and destination columns specified by the Transform.
typedef struct {
	DWORD fProviderStorageObjects;				// DBPROPVAL_SS_*; Blob Storage Object interfaces supported
												// by source or destination provider.  Will be 0 if none supported,
												// or if DTSTransformBlobDefaults::bForceBlobsInMemory is specified.
	DTSProviderFlags dtsProviderFlags;			// Provider characterstics, e.g Blob Flags.
	ULONG cColumns;								// Count of columns in rgColumns
	DTSColumnData *rgColumnData;				// Column schema and binding information
	ULONG cPriorBlobStorageObjects;				// Number of Blobs bound as Storage Objects in prior transforms.
												// Can be used with DTSProviderFlag_Blob_MultipleStorageObjects
												// to determine if the current Transform can use a storage object.
} DTSTransformColumnInfo, *LPDTSTransformColumnInfo;
typedef const DTSTransformColumnInfo *LPCDTSTransformColumnInfo;

typedef enum {
	DTSGuid_Variant,
	DTSGuid_Guid,
	DTSGuid_OleStr
} DTSGuidType;

typedef struct {
	DTSGuidType eType;							// Indexes union.
	union {
		GUID Guid;								// GUID form
		VARIANT Variant;						// BSTR == progid or clsid (differentiated by looking for