dtspump.h

sql2000 DEVTOOLS INCLUDE

// OLEDB Error Records via the IDTSErrorRecords interface passed to 
// IDTSDataPumpTransform::AddVariable).  A FAILED HRESULT returned from
// DTSDataPumpTransform::Execute indicates an unrecoverable error and aborts
// the DataPump.
typedef DP_ENUM_BEGIN(DTSTransformStatus, "Return value (int or long) from ActiveX Scripting Transform") {
	// Default; conversions (if any) succeeded; write the row to destination if
	// specified, without calling any error handlers.  Default is to do Insert;
	// this may be overridden for data-driven queries by other flags to do Insert,
	// Update, Delete, or UserQuery for a user-defined ad-hoc query.
	DTSTransformStat_OK							= 0x00000001,

	// Success with additional info, which the app may want to process further
	// by reading its pvTransformUserData (if it shares that knowledge with the
	// transform server) or thru OLEDB Error Records; therefore, the Pump will 
	// call the ErrorSink if one was specified, but does not increment the error
	// row count.  The DTSTransformStatus result of the operation is passed to
	// the ErrorSink, so the app can switch on this bit.
	DTSTransformStat_Info						= 0x00001000,

	// Write row if destination specified; also call ErrorSink with Info.
	DTSTransformStat_OKInfo						= 0x00001001,

	// Abort further processing of this row, for non-error reasons.
	DTSTransformStat_SkipRow					= 0x00000002,

	// Abort further processing of this row, and calls ErrorSink with Info.
	DTSTransformStat_SkipRowInfo				= 0x00001002,

	// Do not fetch the next row; re-execute all transforms against the current
	// source and destination rows.  No initialization is done to the destination
	// row, so this could be used to generate multiple output rows from a single
	// input row.  Subsequent transforms are still executed unless a SkipRow* flag
	// is also present.
	DTSTransformStat_SkipFetch					= 0x00000004,

	// Do not write the current row to destination.  Usually used to fetch the next
	// source row to generate a simple aggregate.  Subsequent transforms are still
	// executed unless a SkipRow* flag is also present.  DTSTransformStat_SkipInsert
	// forces DTSTransformFlag_PreserveDestRows behaviour for the row for which it
	// is specified.
	DTSTransformStat_SkipInsert					= 0x00000008,

	// The following 4 flags are not compatible together.  They execute the
	// similarly-named statement passed to SetRowsetAndQueries on the Destination,
	// with values from the currently transformed Destination Row.
	DTSTransformStat_InsertQuery				= 0x00000010,
	DTSTransformStat_UpdateQuery				= 0x00000020,
	DTSTransformStat_DeleteQuery				= 0x00000040,
	DTSTransformStat_UserQuery					= 0x00000080,

	// This flag is set by transforms which do not require setting data into the
	// destination (for example, WriteFile).  If all Transforms set this flag, no
	// Insert (or DataDrivenQuery) is done.  Implies DTSTransformStat_OK, which can
	// also be OR'd in.
	// This is similar to SkipInsert, except that SkipInsert will always skip;
	// DestDataNotSet will only skip the insert if all transforms return it.
	// Therefore, it is always cleared from the transform status referenced by
	// the pointer passed to the TransformServer.
	DTSTransformStat_DestDataNotSet				= 0x00000200,

	// May be bit-OR'd into the following error returns.
	DTSTransformStat_Error						= 0x00002000,

	// Abort further processing of this row due to error and call the error sink,
	// but do not write to exception file.  Should be handled by the ErrorSink.
	DTSTransformStat_ErrorSkipRow				= 0x00002002,

	// Abort further processing of this row as an exception and call the error sink,
	// and write this row to exception file.  Should be handled by the ErrorSink.
	// Note this bit does not map to any non-error bits.
	DTSTransformStat_ExceptionRow				= 0x00002100,

	// Or抎 with prior bits to abort processing any further rows and return
	// DTSTransformExec_AbortPump from IDTSDataPump::Execute().  
	// This does not include the Error bit so &'ing with it will only return
	// TRUE for this bit.
	DTSTransformStat_AbortPump					= 0x00004000,

	// Transform determined that this row is the last one to be operated on,
	// so allows the pump to be aborted "normally" (without signifying an error).
	// May be or'd with other bits to skip the current row; otherwise it will go
	// to the next transforms and then write it to destination (in accordance with
	// how the following transforms specify).
	DTSTransformStat_NoMoreRows					= 0x00008000,

} DP_ENUM_END(DTSTransformStatus);

// Status returned from an IDataPump::Execute operation.
typedef DP_ENUM_BEGIN(DTSExecuteStatus, "Return value (int or long) from DataPump Execution") {
	// All rows copied (or skipped) without error.
	DTSTransformExec_OK							= 0x00000000,

	// Bit-OR抎 into the following error returns.
	DTSTransformExec_Error						= 0x00001000,	// Bit-or抎 into following

	// Pump continued to completion but errors were encountered
	DTSTransformExec_OKErrors					= 0x00001001,

	// Pump aborted because too many rows had errors.
	DTSTransformExec_ErrorCountExceeded			= 0x00001002,

	// Pump aborted due to Transform request or ErrorSink return.
	DTSTransformExec_AbortPump					= 0x00001004,
} DP_ENUM_END(DTSExecuteStatus);

#endif	// DTSDataPump_CONSTANTS_

////////////////////////////////////////////
// CPP-only definitions
////////////////////////////////////////////

#ifndef DTSDataPump_ODL_

// Define parameter usage.
#define DP_IN
#define DP_OUT
#define DP_INOUT

#ifdef NONAMELESSUNION
#define DP_UNION_NAME(u)	u
#else
#define DP_UNION_NAME(u)
#endif

// For safety, struct initialization values are set in ctors for C++ clients.
#if !defined(__cplusplus) && !defined(DP_NO_AUTOCTOR)
#define DP_NO_AUTOCTOR
#endif

// These are the conversion flags indicating what may happen during an individual column
// Convert() call, and accounts for the column lengths, nullability, sign, etc.
// See DTSTransformFlags for a more detailed discussion of the similarly-named TransformFlag
// which will allow conversion to proceed when these conditions are present.
//	Keys:
//		<T> - TransformFlag is available to explicitly allow this.
//		<E>	- Error may be encountered during Convert()
//		<F> - Fatal; Convert() will error as unsupported or with overflow.
//
typedef DP_ENUM_BEGIN(DTSConvertFlags, "DTSConvertFlags") {
	// The conversion is between columns of identical type, length or precision/scale,
	// and nullability, or is between text and another type, with the text being of
	// sufficient length for a representation of that datatype.  Errors should not be
	// encountered during Convert() unless a text conversion contains invalid data.
	DTSConvertFlag_ExactType					= 0x00000000,

	// The conversion will promote the range of data from source to destination
	// (e.g. I4 -> I2, [var]char -> longer [var]char, numeric(x, y) -> numeric(x+1, y+1)).
	// <T>
	DTSConvertFlag_Promotion					= 0x00000001,
	
	// Conversion will demote (e.g. I4 -> I2); overflow error possible.
	// <T, E> 
	DTSConvertFlag_Demotion						= 0x00000002,
	
	// Conversion may do string or byte truncation; truncation error possible if
	// this flag is not specified on Convert().
	// <T, E>
	DTSConvertFlag_StringTruncation				= 0x00000004,
	
	// Conversion may do integral rounding from float or numeric, or move a larger
	// scale into a smaller scale (both cases resulting in truncation of digits to
	// the right of the decimal point).  This is also flagged when moving from integral
	// or numeric to float/double when source precision is greater than FLT/DBL_DIG.
	// <T> 
	DTSConvertFlag_NumericTruncation			= 0x00000008,
	
	// Conversion may try to put NULL source data into a NonNULL destination column,
	// which will error, or vice-versa, which will be safe.
	// <T, E>
	DTSConvertFlag_NullChange					= 0x00000010,
	
	// Conversion may try to put a signed value int/float into an unsigned destination, 
	// or vice-versa.  This may error if the source value is negative and destination
	// is unsigned, or if the source is unsigned and its value is larger than the
	// signed destination's maximum signed value (overflow).
	// <T, E>
	DTSConvertFlag_SignChange					= 0x00000020,
	
	// Destination column size is too short for a meaningful conversion from source
	// column type.
	// <F>
	DTSConvertFlag_DestTooShort					= 0x00000040,
	
	// Source column size is too short for a meaningful conversion to destination
	// column type.
	// <F>
	DTSConvertFlag_SourceTooShort				= 0x00000080,
	
	// Source and destination datatypes are not really compatible, but conversion can be forced.
	// <T>
	DTSConvertFlag_ForceConvert					= 0x00000100,
	
	// Conversion fails because of bad or incompatible column types.
	// <F>
	DTSConvertFlag_Unsupported					= 0x00001000,

} DP_ENUM_END(DTSConvertFlags);

// Binding modes for column data; returned from IDTSDataPumpTransform::ValidateSchema
// via DTSTransformColumnInfo.  Normally the DataPump default handling does not need to
// be changed, but for Blob ((DBCOLUMNFLAGS_ISLONG) columns, custom Transforms are able
// to adjust bindings to maximize performance.
//
typedef DP_ENUM_BEGIN(DTSBindMode, "DTSBindMode") {
	// Indicates data should be bound "in-memory, out of line".  Currently this is only supported
	// by the OLEDB specification for variable-length types: DBTYPE_((W)STR|BYTES); therefore,
	// the DataPump will error if it is specified for other types.  DTSBindMode_(Client|Provider)Owned
	// must be specified with DTSBindMode_Byref.
	// 
	// For source, the returned data will be a direct pointer to the provider's data if
	// DTSBindMode_ProviderOwned is specified (in which case it must not be free'd or written to),
	// or a CoTaskMemAlloc()'d pointer if DTSBindMode_ClientOwned is specified (in which case it
	// is the client's property and must be freed).
	//
	// For destination, the transformation server must place the data pointer in
	// pDestColumnInfo->pvRowData.  If DTSBindMode_ClientOwned is specified, then the data
	// is assumed to require freeing after the InsertRow operation completes.  The DataPump
	// will never perform a non-Byref, in-memory destination binding for a Blob, so this flag
	// must be specified unless a Storage Object is used.
	//
	DTSBindMode_Byref							= 0x00000001,

	// Default "in-memory, inline" binding mode; space for the source and destination data, including
	// the full length of a DBTYPE_((W)STR|BYTES) column, is allocated in rgColumnData[ii].pvData and
	// passed to IDTSDataPumpTransform::Execute.
	//
	// For a BLOB (DBCOLUMNFLAGS_ISLONG) column, IDTSDataPumpTransform::ValidateSchema returns
	// the length to use for this binding in ppDTSColBinding[ii].cbInMemoryBlobSize.  This will
	// result in a separate allocation for that Blob column (i.e. multiple Blobs are not
	// allocated within a single contiguous row).
	//
	// On fetch from Source, the DBSTATUS in the binding will indicate whether the data was
	// truncated; it is up to the Transform server how (or if) this is handled.
	//
	// For performance reasons, this flag should not be specified for non-Blob (W)STR|BYTES
	// source columns; DTSBindMode_Byref_ProviderOwned is the default, to use a pointer to the
	// provider's data cache and avoid an unnecessary copy.
	//
	// For DBTYPE_BSTR and DBTYPE_VARIANT, this specifies that the binding is DBMEMOWNER_CLIENTOWNED
	// (without BYREF), and the client is responsible for freeing it (e.g. IDTSDataConvert::ClearBindingData).
	//
	DTSBindMode_ClientOwned						= 0x00000002,

	// For Source DBTYPE_((W)STR|BYTES), this flag causes the OLEDB binding to be done as DBTYPE_BYREF
	// with DBMEMOWNER_CLIENTOWNED, resulting in a CoTaskMemAlloc which the client is
	// responsible for freeing (e.g. via IDTSDataConvert::ClearBindingData).  For a BLOB
	// column, the length to use for this binding is returned from ValidateSchema() in 
	// ppDTSColBinding[ii].cbInMemoryBlobSize.  On fetch from Source, the DBSTATUS in the binding
	// will indicate whether the data was truncated; it is up to the Transform server how (or if)
	// this is handled.
	//
	// This flag causes each row to have a separate CoTaskMemAlloc for the source column.  This is
	// somewhat less efficient than the other in-memory options, and thus should only be used by
	// a Transform which wants to assume ownership of that allocation.  The Transform is responsible
	// for tracking and freeing the allocation (and for ensuring that OnRowComplete does not free
	// it if it is to be used in subsequent Transforms).
	//
	// For destination columns, this is the "safest" way to pass an in-memory pointer, as some providers
	// may not allow ProviderOwned on a destination (such as with Blob columns).  The Transform must
	// ensure that it does not double-free a pointer.