dtspump.h

sql2000 DEVTOOLS INCLUDE

//
// DTSPump.h
//	Header file for the OLEDB DTSDataPump Service Provider.
//	Copyright 1997 Microsoft Corporation
//
#ifndef DTSDataPump_H_
#define DTSDataPump_H_

#ifndef DTSDataPumpVersion_Major
	#define DTSDataPumpVersion_Major 2
	#define DTSDataPumpVersion_Minor 0
#endif // DTSDataPumpVersion_Major

#ifndef DTSDataPump_VersionOnly

// The default Blob size used in this version of the DataPump.
// May be overridden on a per-Transform or per-column basis.
#define DTS_DEFAULT_INMEMORY_BLOB_SIZE (1024 * 1024)

// Default number of successful InsertRows which will be Committed if supported by provider.
// Currently set to 0 which means not to do a commit until all rows have been transferred.
#define DTS_DEFAULT_InsertCommitSize	0

///////////////////////////////////////////////////////////////////////////////////////
// CPP and OleAut Enumerations and constants.
///////////////////////////////////////////////////////////////////////////////////////
#ifndef DTSDataPump_CONSTANTS_
#define DTSDataPump_CONSTANTS_

// To avoid the need to cast on bitwise operations (which defeats typesafety anyway),
// define the datatype as DWORD for C/CPP.  OleAut languages don't do typechecking
// and organize by the enum name.
#ifdef DTSDataPump_ODL_
	#define DP_ENUM_BEGIN(tdef, hstring)	[helpcontext(H_##tdef), helpstring(hstring)] enum tdef
		// item = value, ...
	#define DP_ENUM_END(tdef)				tdef, *LP##tdef
#else
	#define DP_ENUM_BEGIN(tdef, hstring)	DWORD tdef, *LP##tdef; enum tag##tdef
		// item = value, ...
	#define DP_ENUM_END(tdef)				
#endif

typedef DP_ENUM_BEGIN(DTSDataPumpError, "Error ranges for DTSDataPump execution") {
	DTSDataPump_E_NotImplemented				= 0x2000,
	DTSDataPump_E_RowsetsAlreadySet				= 0x2001,
	DTSDataPump_E_TransformsAlreadySet			= 0x2002,
	DTSDataPump_E_DestRowsetNotSupplied			= 0x2003,
	DTSDataPump_E_RowsetsNotSupplied			= 0x2004,
	DTSDataPump_E_SourceColumnsRequired			= 0x2005,
	DTSDataPump_E_ColCountButNoCols				= 0x2006,
	DTSDataPump_E_MismatchColOrdAndName			= 0x2007,
	DTSDataPump_E_ColumnNameNotFound			= 0x2008,
	DTSDataPump_E_ColumnOutOfRange				= 0x2009,
	DTSDataPump_E_DestColumnAlreadySpecified	= 0x200a,
	DTSDataPump_E_IDataConvertRequired			= 0x200b,
	DTSDataPump_E_NullVariantIUnknown			= 0x200c,
	DTSDataPump_E_NotReentrant					= 0x200d,
	DTSDataPump_E_RowsetChangeMustInsert		= 0x200e,
	DTSDataPump_E_DataPumpNotReentrant			= 0x200f,
	DTSDataPump_E_DestColumnReadOnly			= 0x2010,
	DTSDataPump_E_MustSpecifyDestOrTransform	= 0x2011,
	DTSDataPump_E_BadTransformFlag				= 0x2012,
	DTSDataPump_E_BadTransformStatusReturned	= 0x2013,
	DTSDataPump_E_TransformServerException		= 0x2014,
	DTSDataPump_E_CannotRebindColumn			= 0x2015,
	DTSDataPump_E_InvalidFetchBufferSize		= 0x2016,
	DTSDataPump_E_InvalidDTSBindMode			= 0x2017,
	DTSDataPump_E_SourceBlobBinding				= 0x2018,
	DTSDataPump_E_NonBlobStorageBind			= 0x2019,
	DTSDataPump_E_LookupDupName					= 0x201a,
	DTSDataPump_E_CannotTransformChapterColumns	= 0x201b,

	DTSDataPump_E_DestinationBlobBinding		= 0x2020,

	DTSDataPump_E_Copy_NeedSrcAndDestColumns	= 0x2024,
	DTSDataPump_E_Copy_ValidateSchemaError		= 0x2025,

	DTSDataPump_E_Convert_DestNotNull			= 0x2026,
	DTSDataPump_E_Convert_BadBindInfo			= 0x2027,
	DTSDataPump_E_Convert_DestOverflow			= 0x2028,
	DTSDataPump_E_Convert_SourceInvalidVariant	= 0x2029,
	DTSDataPump_E_Convert_SourceInvalidLength	= 0x202a,
	DTSDataPump_E_Convert_ConversionInvalid		= 0x202b,
	DTSDataPump_E_Convert_ConversionFailed		= 0x202c,
	DTSDataPump_E_Convert_ProviderOwnedTypeMismatch	= 0x202d,
	DTSDataPump_E_Convert_BlobStorageNoInterface	= 0x202e,

	DTSDataPump_E_AxScript_RequiredParams		= 0x2040,
	DTSDataPump_E_AxScript_ValidateSchemaError	= 0x2041,
	DTSDataPump_E_AxScript_ParseError			= 0x2042,
	DTSDataPump_E_AxScript_BadTransformFunction	= 0x2043,
	DTSDataPump_E_AxScript_CantChangeSrcCols	= 0x2044,
	DTSDataPump_E_AxScript_CantResetAfterInitialize	= 0x2045,
	DTSDataPump_E_AxScript_CantInitializeEngine	= 0x2046,
	DTSDataPump_E_AxScript_RunTimeError			= 0x2047,

	DTSDataPump_E_AutoBufferInterfaceNotSupported	= 0x2051,
	DTSDataPump_E_InvalidSpecifyBlobDefaults	= 0x2051,
	DTSDataPump_E_LineageVariableNotFound		= 0x2052,
	DTSDataPump_E_LastRowCantBeLessThanFirst	= 0x2053,

	DTSDataPump_E_DDQ_NeedTransformStatus		= 0x2060,
	DTSDataPump_E_DDQ_NeedInsertQuery			= 0x2061,
	DTSDataPump_E_DDQ_NeedUpdateQuery			= 0x2062,
	DTSDataPump_E_DDQ_NeedDeleteQuery			= 0x2063,
	DTSDataPump_E_DDQ_NeedUserQuery				= 0x2064,
	DTSDataPump_E_DDQ_InformationNotSet			= 0x2065,
	DTSDataPump_E_DDQ_BadTransformStatusContext	= 0x2065,
	DTSDataPump_E_DDQ_DestColumnNotTransformed	= 0x2066,
	DTSDataPump_E_DDQ_DestColumnNeedsLength		= 0x2067,
	DTSDataPump_E_DDQ_DestDoesNotSupportSQL		= 0x2068,
	DTSDataPump_E_DDQ_TransformStatusForced		= 0x2069,
	DTSDataPump_E_RowFailuresExceedLimit		= 0x206a,

	DTSDataPump_E_TransformString_NeedSrcAndDestColumns		= 0x2080,
	DTSDataPump_E_TransformString_ColumnCount				= 0x2081,
	DTSDataPump_E_TransformReadFile_NeedSrcAndDestColumns	= 0x2082,
	DTSDataPump_E_TransformString_ValidateSchemaError		= 0x2083,
	DTSDataPump_E_TransformString_DestStringTrunc			= 0x2084,

	DTSDataPump_E_TransformDateTimeString_NeedSrcAndDestColumns		= 0x2090,
	DTSDataPump_E_TransformDateTimeString_IndexOutOfRange			= 0x2091,
	DTSDataPump_E_TransformDateTimeString_InvalidNameOrFormat		= 0x2092,
	DTSDataPump_E_TransformDateTimeString_InvalidY2KCutoff			= 0x2093,
	DTSDataPump_E_TransformDateTimeString_ErrorParsingInputFormat	= 0x2094,
	DTSDataPump_E_TransformDateTimeString_ErrorParsingOutputFormat	= 0x2095,
	DTSDataPump_E_TransformDateTimeString_ErrorParsingInputData		= 0x2096,
	DTSDataPump_E_TransformDateTimeString_InvalidFormatString		= 0x2097,

	DTSDataPump_E_TransformWriteFile_NeedSrcAndDestColumns		= 0x2100,
	DTSDataPump_E_TransformWriteFile_FileAlreadyExists			= 0x2101,
	DTSDataPump_E_TransformWriteFile_FileColumnNameNotFound		= 0x2102,
	DTSDataPump_E_TransformWriteFile_InvalidSourceSchema		= 0x2103,
	DTSDataPump_E_TransformWriteFile_InvalidDestSchema			= 0x2104,
	DTSDataPump_E_TransformWriteFile_InvalidFileColumnName		= 0x2105,
	DTSDataPump_E_TransformWriteFile_FetchedNullFileName		= 0x2106,

	DTSDataPump_E_TransformReadFile_FileNotFound				= 0x2120,
	DTSDataPump_E_TransformReadFile_InvalidSourceSchema			= 0x2121,
	DTSDataPump_E_TransformReadFile_InvalidDestSchema			= 0x2122,
	DTSDataPump_E_TransformReadFile_DestStringTrunc				= 0x2123,

	DTSDataPump_E_BadTransformPhase								= 0x2130,
	DTSDataPump_E_InvalidStatusForPhase							= 0x2131,
	DTSDataPump_E_UnsupportedPhase								= 0x2132,
	DTSDataPump_E_InvalidDataPumpOption							= 0x2133,
	DTSDataPump_E_AxScript_InvalidPhaseColumnAccess				= 0x2134,

	DTSDataPump_E_AxScript_AbortPumpReturned					= 0x2136,
	DTSDataPump_E_AxScript_NoPhaseFunc							= 0x2137,

} DP_ENUM_END(DTSDataPumpError);

// These allow definition of how the transform will proceed.
typedef DP_ENUM_BEGIN(DTSTransformFlags, "Flags (int or long) controlling Transform") {
	// No flags are specified; essentially, the conversion must be between exact types.
	// Note that this allows string <--> nonstring conversions, because every nonstring datatype
	// has a meaningful string representation.  This may be overridden by RequireExactType,
	// which is even stricter.
	DTSTransformFlag_Strict						= 0x00000000,

	// This flag means that IDTSDataPumpTransform::ValidateSchema should allow the transfer to proceed 
	// even if there are potential overflows, under the assumption that the consumer is aware of this but
	// knows the source values are all (or mostly) within the destination column抯 range.  Any overflows during
	// transformation will cause the row to be exceptioned.  This flag is generally of interest only to 
	// the IID_IDTSDataPumpTransformCopy implementation, as this is a direct copy, whereas other
	// implementations would probably convert the values or determine validity on a specific case-by-case basis.
	// This value is also used for date/time conversions which result in loss, such as DATE -> DBTIME,
	// where a subset of the source value is still meaningful.
	DTSTransformFlag_AllowDemotion 				= 0x00000001,

	// This flag means that IDTSDataPumpTransform::ValidateSchema should allow the transfer to proceed 
	// when there is promotion in the data range when moving from the source to the destination types,
	// such as I2->I4 or I4->float/double.  Note that in some cases, such as I4->R4, the data range
	// increases but at the loss of some digits of precision.
	// If AllowLossless is specified, this is allowed by the Transform.
	DTSTransformFlag_AllowPromotion 			= 0x00000002,

	// This flag allows column (w)char or byte data to be truncated silently, such as when moving data
	// from a char(60) to a char(40) column.  AllowDemotion is implied but overflow will be
	// silently truncated instead of causing an error.
	DTSTransformFlag_AllowStringTruncation 		= 0x00000004,

	// This flag means that IDTSDataPumpTransform::ValidateSchema should allow the transfer to proceed 
	// even in the event that the source is a floating-point or numeric/decimal type and the destination
	// is an integral type.  This is a numeric flavour of AllowDemotion and will not cause an error 
	// (integer overflow will still be an error; i.e. left-of-decimal digits are significant).
	DTSTransformFlag_AllowNumericTruncation		= 0x00000008,

	// This flag means that IDTSDataPumpTransform::ValidateSchema should allow the transfer to proceed 
	// even if the source column allows NULL values and the destination column does not.  As with
	// AllowDemotion, errors may be encountered during a transform.
	// If AllowLossless is specified, this is allowed by the Transform if going from nonNULLable to NULLable.
	DTSTransformFlag_AllowNullChange			= 0x00000010,

	// This flag means that IDTSDataPumpTransform::ValidateSchema should allow the transfer to proceed 
	// even in the event that the source and destination have a signed vs. unsigned mismatch.  As with
	// AllowDemotion, errors may be encountered during a transform.
	// If AllowLossless is specified, this is allowed by the Transform when going from unsigned to signed
	// with promotion (e.g. UI2 -> I4).
	DTSTransformFlag_AllowSignChange			= 0x00000020,

	// Require that the destination column's datatype be exactly the same as the source column's
	// (including length or precision/scale, fixed vs. variable length, sign, and nullability).
	// This overrides any other flags specified for column conversion validation.
	// Cannot be specified with ForceConvert.
	DTSTransformFlag_RequireExactType			= 0x00000040,

	// Allow the conversion to proceed at all times, even when the source and destination types are
	// fundamentally different.  Currently this applies to:
	//		<nonchar> <--> bytes:		Does a bitwise copy; caveats apply for endian, machine representations.
	//		int/real <--> date:			DATE is a double so this just converts between int and double.
	//		real <--> date:				DATE is a double so this just copies.
	// Cannot be specified with RequireExactType.
	DTSTransformFlag_ForceConvert				= 0x00000080,

	// Causes the TransformServer to not ClearBindingData() the destination-row storage
	// for the columns in this Transform during OnRowComplete().  This allows the
	// destination row's values to be reused by the next transform.
	DTSTransformFlag_PreserveDestRows			= 0x00000100,

	// Causes the TransformServer to allow all conversions for which a lossless conversion is
	// possible - e.g. Promotion, nonNULLable -> NULLable, unsigned -> promoted signed.
	DTSTransformFlag_AllowLosslessConversion	= 0x00000200,

	// No flags are specified; essentially, the conversion must be between exact types.
	// Note that this allows string <--> nonstring conversions, because every nonstring datatype
	// has a meaningful string representation.  This may be overridden by RequireExactType.
	DTSTransformFlag_Default					= (DTSTransformFlag_AllowDemotion | DTSTransformFlag_AllowPromotion | DTSTransformFlag_AllowStringTruncation | DTSTransformFlag_AllowNumericTruncation | DTSTransformFlag_AllowNullChange | DTSTransformFlag_AllowSignChange)

} DP_ENUM_END(DTSTransformFlags);

// These allow definition of how the transform will proceed.
typedef DP_ENUM_BEGIN(DTSTransformPhaseEnum, "Bitmask (int or long) indicating supported or requested Transform Phases.") {
	DTSTransformPhase_None						= 0x00000000,

	// Identify which phase(s) the transform is to be called in.
	// These must be passed to DataPump::AddTransform2 or the transform will not
	// be called for that phase.
	DTSTransformPhase_PreSourceData				= 0x00000001,
	DTSTransformPhase_PostSourceData			= 0x00000002,
	DTSTransformPhase_Transform					= 0x00000004,
	DTSTransformPhase_OnTransformFailure		= 0x00000008,
	DTSTransformPhase_OnInsertSuccess			= 0x00000010,
	DTSTransformPhase_OnInsertFailure			= 0x00000020,
	DTSTransformPhase_OnBatchComplete			= 0x00000040,

	// This may also be passed to DataPump::AddTransform2, but if not, the DataPump will
	// query IDTSTransformServer2::GetTransformServerInfo to see if it supports this phase,
	// and will call it in place of OnTransformComplete if so.
	DTSTransformPhase_OnPumpComplete			= 0x00000080,

	// Bitmask of all valid phases.
	DTSTransformPhase_All						= 0x000000FF,

} DP_ENUM_END(DTSTransformPhaseEnum);

// Status returned from a Transform operation.
// All "normal" errors from DTSDataPumpTransform::Execute should be returned as
// one of these flags, with a SUCCEEDED HRESULT (possibly with the addition of