DTS Scripting Reference

This section documents the objects and collections, and their properties and methods, that are provided by the Data Transformation Services (DTS) data pump for the scripts of Microsoft® ActiveX® Script transformations. They can also be referenced in custom transformations implemented in Microsoft Visual C++® and the C language. The data pump is the engine for the Transform Data task, the Data Driven Query task, and the Parallel Data Pump task.

These objects and collections can generally not be used in the scripts associated with the ActiveX Script task or with DTS package steps. Moreover, the name you use within an ActiveX Script transformation is generally different from the object name. This table specifies the names to be used within scripts, the types of scripts in which they are valid, and a reference to the underlying object.

Scripting Name	Validity	Reference
DTSErrorRecords	ActiveX Script transformations	DTSErrorRecords Collection
DTSGlobalVariables	All DTS ActiveX scripts	GlobalVariables Collection
DTSLookups	ActiveX Script transformations	DTSDataPumpLookups Collection
DTSPackageLog	ActiveX Script tasks	PackageLog Object
DTSSource DTSDestination	ActiveX Script transformations	DTSDataPumpColumns Collection
DTSTransformPhaseInfo	ActiveX Script transformations	DTSTransformPhaseInfo Object
To reference any other object in the DTS object model hierarchy from an ActiveX script, use DTSGlobalVariables.Parent to return a reference to the Package2 object, from which you can reference any other object in the hierarchy. For example, to cause a step named DTSStep_DTSBulkInsertTask_1 to execute again after it has already completed execution, set:

DTSGlobalVariables.Parent.Steps("DTSStep_DTSBulkInsertTask_1").ExecutionStatus = _

DTSStepExecStat_Waiting

See Also

Package2 Object


Scripting Objects

This section documents the Data Transformation Services (DTS) objects exposed by the DTS data pump for the scripts of Microsoft® ActiveX® Script transformations. They can also be referenced in custom transformations implemented in Microsoft Visual C++® and the C language.

Topic	Description
DTSDataPumpColumn Object	Provides access to a column for a transformation or ActiveX script.
DTSDataPumpColumn2 Object	Extends the functionality of the DTSDataPumpColumn object.
DTSDataPumpLookup Object	Specifies a named, parameterized query string for a transformation or ActiveX script.
DTSTransformPhaseInfo Object	Makes status information available to a transformation or ActiveX script.


DTSDataPumpColumn Object

The DTSDataPumpColumn object provides access to a column value and its meta data to a Microsoft® ActiveX® script.

Properties

ActualSize Property	OriginalValue Property
Attributes Property	Precision Property
DefinedSize Property	Type Property
Name Property	UnderlyingValue Property
NumericScale Property	Value Property
Methods

AppendChunk Method	GetChunk Method
Remarks

The DTSDataPumpColumn object belongs to the DTSSource and DTSDestination collections. The DTSDataPumpColumn object is identical to the ADO.Field interface.

The DTSDataPumpColumn object is compatible with Microsoft® SQL Server™ version 7.0. For more information about an extended version of this object, see DTSDataPumpColumn2 Object.

Reference the DTSDataPumpColumn object from within ActiveX script transformations by referencing an element of the DTSSource or DTSDestination collections. If you must remain compatible with SQL Server 7.0, use only the properties specified above.

See Also

Column Object

DTSDataPumpColumns Collection


DTSDataPumpColumn2 Object

The DTSDataPumpColumn2 object provides access to a column value and its meta data to a Microsoft® ActiveX® script.

Extended Properties

Status Property

Remarks

The DTSDataPumpColumn2 object extends the functionality of the DTSDataPumpColumn object and inherits the properties and methods of that object. In addition, the Status property indicates whether the data value is to be used as the value of the column and whether the data pump was able to get or set the value.

For more information about when to use the DTSDataPumpColumn object instead of the DTSDataPumpColumn2 object, see Extended DTS Objects.

Reference the DTSDataPumpColumn2 object from within ActiveX script transformations by referencing an element of the DTSSource or DTSDestination collections.

See Also

Column Object

DTSDataPumpColumn Object

DTSDataPumpColumns Collection


DTSDataPumpLookup Object

The DTSDataPumpLookup object provides information about columns in a Data Transformation Services (DTS) lookup query to a Microsoft® ActiveX® script. The DTSDataPumpLookup object belongs to the DTSDataPumpLookups collection.

Properties

LastRowCount Property	Name Property
Methods

AddToCache Method	RemoveFromCache Method
Execute Method
Remarks

DTSDataPumpLookup returns a variant or an array of variants (if multivalued) corresponding to the sequence of columns in the single output row resulting from the execution of a query. If multiple rows are returned, only the value of the first row is returned in the output variant. An application can call LastRowCount to assert that only one row was returned.

See Also

DTSDataPumpLookups Collection

Lookup Object


DTSTransformPhaseInfo Object

The DTSTransformPhaseInfo object makes status information available to Data Transformation Services (DTS) transformations and Microsoft® ActiveX® Script transformations.

Properties

CurrentPhase Property	ErrorCode Property
CurrentSourceRow Property	ErrorRows Property
DestinationRowsComplete Property	TransformStatus Property
Remarks

The following information is available from the DTSTransformPhaseInfo object:

•	Current source row being processed; first row is row 1.

•	Destination rows inserted or Data driven queries executed.

•	Total number of error rows encountered.

•	Error code of operation preceding current phase.

•	Transform status of most recently completed transformation.

•	Current transformation phase.

The DTSTransformPhaseInfo object is available within ActiveX Script transformations using the same name, DTSTransformPhaseInfo.

See Also

Adding DTS Transformations


Scripting Collections

Microsoft® SQL Server™ 2000 Data Transformation Services (DTS) scripting collections contain groups of related data pump scripting objects. They can be used from custom transformations or Microsoft ActiveX® script transformations.

Topic	Description
DTSDataPumpColumns Collection	Contains descriptions of source and destination columns for ActiveX script transformations.
DTSDataPumpLookups Collection	Specifies named, parameterized query strings for a transformation or ActiveX script.
DTSErrorRecords Collection	Details errors that a custom transformation or ActiveX script transformation has added to data pump error stack.


DTSDataPumpColumns Collection

The DTSDataPumpColumns collection contains groups of columns that provide source and destination column information to a Microsoft® ActiveX® Script transformation or a custom transformation.

Properties

Count Property

Methods

Item Method

Remarks

Reference the DTSDataPumpColumns collection from within transformation ActiveX scripts by referencing the DTSSource or DTSDestination collections.

See Also

Columns Collection

DTSDataPumpColumn Object


DTSDataPumpLookups Collection

The DTSDataPumpLookups collection contains DTSDataPumpLookup objects that provide Data Transformation Services (DTS) lookup column information to a Microsoft® ActiveX® script.

Properties

Count Property

Methods

Item Method

Remarks

Reference the DTSDataPumpLookups collection from within ActiveX script transformations by referencing the DTSLookups collection.

See Also

Lookups Collection

DTSDataPumpLookup Object


DTSErrorRecords Collection

The DTSErrorRecords collection allows an application to append error records to the OLE DB IErrorInfo interface of the current thread. This information can be provided by a Microsoft® ActiveX® script.

Methods

Add Method	Clear Method
See Also

Handling DTS Events and Errors

IDTSDataPumpErrorSink


Scripting Properties

This section defines the properties of the Microsoft® SQL Server™ 2000 Data Transformation Services (DTS) scripting objects and collections. With these properties, you can retrieve and set the attributes of objects within Microsoft ActiveX® scripts.


ActualSize Property

The ActualSize property returns the actual size of a column value for the current row.

Applies To

DTSDataPumpColumn Object	DTSDataPumpColumn2 Object
Syntax

object.ActualSize

Part	Description
Object	Expression that evaluates to an object in the Applies To list
Data Type

Long

Modifiable

Read-only

Prototype (C/C++)

HRESULT get_ActualSize(long *pl);

Remarks

The ActualSize property may be less than the DefinedSize of the column.

See Also

DefinedSize Property

Type Property


Attributes Property

The Attributes property returns one or more characteristics of a column.

Applies To

DTSDataPumpColumn Object	DTSDataPumpColumn2 Object
Syntax

object.Attributes

Part	Description
object	Expression that evaluates to an object in the Applies To list
Data Type

Long

Modifiable

Read-only

Prototype (C/C++)

HRESULT get_Attributes(long *pl);

Remarks

For more information about the valid values for the Attributes property, search for DBCOLUMNFLAGS_ in include file OLEDB.h. This default location for this file is c:\Program Files\Microsoft SQL Server\80\Tools\DevTools\include\ if, during a Custom installation of Microsoft SQL Server, Development Tools/Headers and Libraries was selected from the Select Components dialog box.

See Also

Flags Property

Type Property


Count Property

The Count property specifies the number of items in a scripting collection.

Applies To

DTSDataPumpColumns Collection	DTSDataPumpLookups Collection
Syntax

object.Count

Part	Description
object	Expression that evaluates to an object in the Applies To list
Data Type

Long

Modifiable

Read-only

Prototype (C/C++)

HRESULT GetCount(long *pRetVal);

See Also

Item Method


CurrentPhase Property

The CurrentPhase property specifies the current transformation phase.

Applies To

DTSTransformPhaseInfo Object

Syntax

object.CurrentPhase

Part	Description
object	Expression that evaluates to a DTSTransformPhaseInfo object
Data Type

DTSTransformPhaseEnum

Modifiable

Read-only

Prototype (C/C++)

HRESULT get_CurrrentPhase(LPDTSTransformPhaseEnum *pRetVal);

Remarks

The DTSTransformPhaseInfo object is referenced within a transformation script or custom transformation.

See Also

Adding DTS Transformations

DTSTransformScriptProperties2 Object

Transformation2 Object


CurrentSourceRow Property

The CurrentSourceRow property specifies the current source row being processed by a Transform Data task, Data Driven Query task, or Parallel Data Pump task.

Applies To

DTSTransformPhaseInfo Object

Syntax

object.CurrentSourceRow

Part	Description
object	Expression that evaluates to a DTSTransformPhaseInfo object
Data Type

Variant/vt_decimal

Modifiable

Read-only

Prototype (C/C++)

HRESULT get_CurrentSourceRow(VARIANT *pRetVal);

Remarks

The DTSTransformPhaseInfo object is referenced within a transformation script or custom transformation.

Some scripting languages, for example Microsoft® Visual Basic® Scripting Edition (VBScript), do not support the vt_decimal data type of the CurrentSourceRow property. In VBScript, convert CurrentSourceRow to Long before using it. For example, use the following code to assign CurrentSourceRow to a global variable:

DTSGlobalVariables("GV1") = CLng(DTSTransformPhaseInfo.CurrentSourceRow)

See Also

Data Driven Query Task

DestinationRowsComplete Property

DTSTransformScriptProperties2 Object

ErrorRows Property

ParallelDataPumpTask Object

Transform Data Task


DefinedSize Property

The DefinedSize property specifies the maximum size of a column.

Applies To

DTSDataPumpColumn Object	DTSDataPumpColumn2 Object
Syntax

object.DefinedSize

Part	Description
object	Expression that evaluates to an object in the Applies To list
Data Type

Long

Modifiable

Read-only

Prototype (C/C++)

HRESULT get_DefinedSize(long *pl);

Remarks

The ActualSize property specifies the size of the data in the current row of the column.

See Also

ActualSize Property

Type Property


DestinationRowsComplete Property

The DestinationRowsComplete property specifies the number of destination rows inserted or data-driven queries executed so far for the current rowset by a Transform Data task, Data Driven Query task, or Parallel Data Pump task.

Applies To

DTSTransformPhaseInfo Object

Syntax

object.DestinationRowsComplete

Part	Description
object	Expression that evaluates to a DTSTransformPhaseInfo object
Data Type

Variant/vt_decimal

Modifiable

Read-only

Prototype (C/C++)

HRESULT get_DestinationRowsComplete(VARIANT *pRetVal);

Remarks

The DTSTransformPhaseInfo object is referenced within a transformation script or custom transformation.

Some scripting languages, for example Microsoft® Visual Basic® Scripting Edition (VBScript), do not support the vt_decimal data type of the DestinationRowsComplete property. In VBScript, you must convert DestinationRowsComplete to Long before using it. For example, use the following code to compare DestinationRowsComplete to a global variable in VBScript:

If DTSGlobalVariables("GV1") <> CLng(DTSTransformPhaseInfo.DestinationRowsComplete) Then ...

DestinationRowsComplete is incremented after the Transform and OnTransformFailure phases, but prior to the OnInsertSuccess phase. It is not incremented for this row if the OnInsertFailure phase occurs.

See Also

CurrentSourceRow Property

Data Driven Query Task

DTSTransformScriptProperties2 Object

ErrorRows Property

ParallelDataPumpTask Object

Transform Data Task


ErrorRows Property

The ErrorRows property specifies the number of error rows encountered for the current rowset by a transformation in a Transform Data task, Data Driven Query task, or Parallel Data Pump task.

Applies To

DTSTransformPhaseInfo Object

Syntax

object.ErrorRows

Part	Description
object	Expression that evaluates to a DTSTransformPhaseInfo object
Data Type

Variant/vt_decimal

Modifiable

Read-only

Prototype (C/C++)

HRESULT get_ErrorRows(VARIANT *pRetVal);

Remarks

The DTSTransformPhaseInfo object is referenced within a Microsoft® ActiveX® Script transformation or custom transformation.

Some scripting languages, for example Microsoft Visual Basic® Scripting Edition (VBScript), do not support the vt_decimal data type of the ErrorRows property. In VBScript, you should convert ErrorRows to Long before using it. For example, use the following code to compare ErrorRows to a global variable in VBScript:

If DTSGlobalVariables("GV1") > CLng(DTSTransformPhaseInfo.ErrorRows) Then ...

ErrorRows includes the current row if in the OnTransformFailure or OnInsertFailure phases.

See Also

CurrentSourceRow Property

Data Driven Query Task

DestinationRowsComplete Property

DTSTransformScriptProperties2 Object

ParallelDataPumpTask Object

Transform Data Task


LastRowCount Property

The LastRowCount property returns the number of rows returned during the last operation of this lookup.

Applies To

DTSDataPumpLookup Object

Syntax

object.LastRowCount

Part	Description
object	Expression that evaluates to a DTSDataPumpLookup object
Data Type

Long

Modifiable

Read-only

Prototype (C/C++)

HRESULT get_LastRowCount(LONG *pRetVal);

Remarks

If multiple rows are retrieved by the lookup, only the fields of the first row are returned by the Execute method. Use LastRowCount to determine whether one or more rows were retrieved.

See Also

Execute Method


Name Property

The Name property specifies the name of a scripting object.

Applies To

DTSDataPumpColumn Object	DTSDataPumpLookup Object
DTSDataPumpColumn2 Object
Syntax

object.Name

Part	Description
object	Expression that evaluates to an object in the Applies To list
Data Type

String

Modifiable

Read-only

Prototype (C/C++)

HRESULT get_Name(*pbstr);


NumericScale Property

The NumericScale property specifies the scale for numeric values in a column.

Applies To

DTSDataPumpColumn Object	DTSDataPumpColumn2 Object
Syntax

object.NumericScale [= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
Data Type

Byte

Modifiable

Read-only

Prototype (C/C++)

HRESULT get_NumericScale(*pbNumericScale);

See Also

Precision Property

Type Property


OriginalValue Property

The OriginalValue property specifies the value of a column before it was modified.

Applies To

DTSDataPumpColumn Object	DTSDataPumpColumn2 Object
Syntax

object.OriginalValue

Part	Description
object	Expression that evaluates to an object in the Applies To list
Data Type

Variant

Modifiable

Read-only

Prototype (C/C++)

HRESULT get_OriginalValue(*pvar);

Remarks

For source columns, this property is the same as the current value because the source values cannot be modified. For destination columns, this is always empty because the original value of a destination column (prior to transformation) is not set.

See Also

UnderlyingValue Property

Value Property


Precision Property

The Precision property specifies the precision of numeric values in a column.

Applies To

DTSDataPumpColumn Object	DTSDataPumpColumn2 Object
Syntax

object.Precision

Part	Description
object	Expression that evaluates to an object in the Applies To list
Data Type

Byte

Modifiable

Read-only

Prototype (C/C++)

HRESULT get_Precision( BYTE *pbPrecision);

See Also

NumericScale Property

Type Property


Status Property

The Status property indicates whether the data value or some other value, such as NULL, is to be used as the value of the column. It may also indicate whether the data pump was able to get or set the value.

Applies To

DTSDataPumpColumn2 Object

Syntax

dpcolumn.Precision

Part	Description
dpcolumn	Expression that evaluates to a DTSDataPumpColumn2 object
Data Type

Long

Modifiable

Read-only

Prototype (C/C++)

HRESULT get_Status( long *pl );

Remarks

The values for the Status property are from the OLE DB DBSTATUS enumeration. See the definition for DBSTATUSENUM in include file OLEDB.h. This file is installed by default in C:\Program Files\Microsoft SQL Server\80\Tools\DevTools\Include\ during a custom installation of Microsoft® SQL Server™ if Development Tools/Headers and Libraries was selected from the Select Components dialog box.

See Also

Attributes Property

Type Property


TransformStatus Property

The TransformStatus property specifies the status of the most recently completed transformation for the current row in a Transform Data task, Data Driven Query task, or Parallel Data Pump task.

Applies To

DTSTransformPhaseInfo Object

Syntax

object.TransformStatus

Part	Description
object	Expression that evaluates to a DTSTransformPhaseInfo object
Data Type

DTSTransformStatus

Modifiable

Read-only

Prototype (C/C++)

HRESULT get_TransformStatus(DTSTransformStatus *pRetVal);

Remarks

The DTSTransformPhaseInfo object is referenced within a Microsoft® ActiveX® Script transformation or custom transformation.

When there are multiple transformations scheduled to run during a particular transform phase, they are executed sequentially in the order in which the Transformation2 objects were added to the Transformations collection. The TransformStatus property allows a transformation to pass on the status code from previous transformation or to generate one of its own. In Microsoft Visual Basic® Scripting Edition (VBScript), this would look like:

Function Transform_Next( )

Transform_Next = DTSTransformPhaseInfo.TransformStatus

{logic which may or may not assign a function return value}

End Function

TransformStatus is not updated after the execution of the insert or data-driven queries on the destination rowset.

See Also

Data Driven Query Task

ParallelDataPumpTask Object

Transform Data Task

Transformation2 Object

Transformations Collection


Type Property

The Type property specifies the data type of a column.

Applies To

DTSDataPumpColumn Object	DTSDataPumpColumn2 Object
Syntax

object.Type

Part	Description
object	Expression that evaluates to an object in the Applies To list
Data Type

Long

Modifiable

Read-only

Prototype (C/C++)

HRESULT get_Type(Long *pDataType);

Remarks

For more information about the valid values for the Type property, search the include file oledb.h for DBTYPEENUM. Oledb.h is installed to c:\Program Files\Microsoft SQL Server\80\Tools\DevTools\include\ by default during a custom installation of Microsoft® SQL Server™ if Development Tools/Headers and Libraries was selected from the Select Components dialog box.

See Also

ActualSize Property

Attributes Property

DefinedSize Property

Status Property


UnderlyingValue Property

The UnderlyingValue property specifies the committed value of a column.

Applies To

DTSDataPumpColumn Object	DTSDataPumpColumn2 Object
Syntax

object.UnderlyingValue

Part	Description
object	Expression that evaluates to an object in the Applies To list
Data Type

Variant

Modifiable

Read-only

Prototype (C/C++)

HRESULT get_UnderlyingValue(*pvar);

Remarks

In Microsoft® SQL Server™ 2000, the UnderlyingValue property is the same as the OriginalValue property.

See Also

OriginalValue Property

Value Property


Value Property

The Value property specifies the current value of a column.

Applies To

DTSDataPumpColumn Object	DTSDataPumpColumn2 Object
Syntax

object.Value [= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	Current value of a column
Data Type

Variant

Modifiable

Read/write

Prototype (C/C++)

HRESULT get_Value(*pRetVal);

HRESULT put_Value(NewValue);

See Also

OriginalValue Property

UnderlyingValue Property


Scripting Methods

This section defines the data pump scripting methods of Microsoft® SQL Server™ 2000 Data Transformation Services (DTS). The methods control the operation of Microsoft ActiveX® scripts in DTS objects.


Add Method

The Add method adds an error record to the errors collection for a transformation.

Applies To

DTSErrorRecords Collection

Syntax

object.Add(
Number,
NativeError,
Description,
Source,
Helpfile,
Helpid)

Part	Description
object	Expression that evaluates to a DTSErrorRecords collection
Number	Error number
NativeError	Native error code
Description	Description of the error
Source	Source of the error
Helpfile	Name of the help file
Helpid	Help context ID within the help file
Prototype (C/C++)

HRESULT Add(
long Number,
long NativeError,
BSTR Description,
BSTR Source,
BSTR Helpfile,
long Helpid);

See Also

Clear Method


AddToCache Method

The AddToCache method adds a key and value mapping to the lookup object cache.

Applies To

DTSDataPumpLookup Object

Syntax

object.AddToCache(
DataValues,
ParamArray KeyValues())

Part	Description
object	Expression that evaluates to a DTSDataPumpLookup object
DataValues	Data values
KeyValues	Key values
Prototype (C/C++)

HRESULT AddToCache(
VARIANT DataValues,
SAFEARRAY * KeyValues);

Remarks

Either the key or value parameters may be a variant array.

See Also

Execute Method

RemoveFromCache Method


AppendChunk Method

The AppendChunk method adds a segment to a binary large object (BLOB) column value.

Applies To

DTSDataPumpColumn Object	DTSDataPumpColumn2 Object
Syntax

object.AppendChunk( Data )

Part	Description
object	Expression that evaluates to an object in the Applies To list
Data	The segment to be added to the BLOB column
Prototype (C/C++)

HRESULT AppendChunk(
VARIANT Data);

Remarks

If the column value is not a BLOB type, AppendChunk sets the value of the column.

See Also

GetChunk Method


Clear Method

The Clear method clears the error records collection for the current transformation.

Applies To

DTSErrorRecords Collection

Syntax

object.Clear()

Part	Description
object	Expression that evaluates to a DTSErrorRecords collection
Prototype (C/C++)

HRESULT Clear();

See Also

Add Method


Execute Method

The Execute method returns a value or row of values from the lookup based on the lookup keys provided.

Applies To

DTSDataPumpLookup Object

Syntax

DTSDataPumpLookup.Execute(
ParamArray KeyValues())

Part	Description
object	Expression that evaluates to a DTSDataPumpLookup object
KeyValues	An array of key values associated with a lookup operation
Prototype (C/C++)

HRESULT Execute(
SAFEARRAY * KeyValues,
VARIANT *pRetVal);

See Also

AddToCache Method

RemoveFromCache Method


GetChunk Method

The GetChunk method retrieves the next segment of a binary large object (BLOB) column value.

Applies To

DTSDataPumpColumn Object	DTSDataPumpColumn2 Object
Syntax

object.GetChunk(Length)

Part	Description
object	Expression that evaluates to an object in the Applies To list
Length	Length of the BLOB segment
Prototype (C/C++)

HRESULT GetChunk(
long Length,
VARIANT *pvar);

Remarks

If the column value is not a BLOB type, GetChunk gets the value of the column.

See Also

AppendChunk Method


Item Method

The Item method retrieves an object from a scripting collection.

Applies To

DTSDataPumpColumns Collection	DTSDataPumpLookups Collection
Syntax

object.Item(Index)

Part	Description
object	Expression that evaluates to an object in the Applies To list
Index	Item name or number
Prototype (C/C++)

HRESULT Item(
VARIANT Index,
interface **pRetVal);

interface is IDTSDataPumpColumn or IDTSDataPumpLookup.

Remarks

Index is the object name or ordinal.

See Also

Count Property

DTSDataPumpColumn2 Object

DTSDataPumpLookup Object


RemoveFromCache Method

The RemoveFromCache method removes a key and value mapping to the lookup object cache.

Applies To

DTSDataPumpLookup Object

Syntax

DTSDataPumpLookup.RemoveFromCache(
ParamArray KeyValues())

Part	Description
object	Expression that evaluates to a DTSDataPumpLookup object
KeyValues	Key to value mapping to remove from the cache
Prototype (C/C++)

HRESULT RemoveFromCache(SAFEARRAY * KeyValues);

Remarks

The KeyValues array should have the same number of elements as are used for Execute.

See Also

AddToCache Method

Execute Method


Scripting Constants

These are the Microsoft® SQL Server™ 2000 Data Transformation Services (DTS) constants that are frequently used in Microsoft ActiveX® scripts.

Constants	Description
DTSStepExecResult	Specifies the result from the execution of a step
DTSStepExecStatus	Specifies the current status of a step
DTSStepPrecedenceBasis	Specifies whether execution status or result is used to specify precedence basis
DTSStepScriptResult	Specifies the disposition of the task associated with a step script
DTSTaskExecResult	Specifies the result from the execution of a task
DTSTransformFlags	Specifies the exception handling options for transformations
DTSTransformPhaseEnum	Specifies the available phases for transformations
DTSTransformStatus	Specifies the Insert operation or data driven query to be taken by data pump after a transformation completes


DTS Programming Reference

This section documents the objects and collections, as well as their associated properties, methods, events, and constants, of the Microsoft® SQL Server™ 2000 Data Transformation Services (DTS) object model. For more information about the object model and a graphical representation, see DTS Object Model Diagram.

For more information about the system requirements and configuration instructions for developing DTS applications in a particular programming environment, see Creating DTS Packages in Visual Basic.


 Task Objects

The following table describes the Data Transformation Services (DTS) task classes supplied with Microsoft® SQL Server™ 2000.

DTS Task	Description
ActiveScriptTask Object	Runs a Microsoft ActiveX® script in the context of a DTS task.
BulkInsertTask Object	Performs the function of Transact-SQL BULK INSERT statements.
CreateProcessTask Object	Runs a Microsoft Win32® executable or batch file.
CreateProcessTask2 Object	Extends the CreateProcessTask object.
DataDrivenQueryTask Object	Transforms source data and writes it to the destination through user-specified queries.
DataDrivenQueryTask2 Object	Extends the DataDrivenQueryTask object.
DataPumpTask Object	Transforms source data and copies it to the destination.
DataPumpTask2 Object	Extends the DataPumpTask object.
DynamicPropertiesTask Object	Changes the values of the properties of DTS objects at runtime.
ExecutePackageTask Object	Runs another DTS package.
ExecuteSQLTask Object	Runs a sequence of SQL statements.
ExecuteSQLTask2 Object	Runs a sequence of SQL statements. Extended ExecuteSQLTask object.
DTSFTPTask Object	Transfers files using File Transfer Protocol (FTP).
DTSMessageQueueTask Object	Sends and receives Message Queuing messages.
ParallelDataPumpTask Object	Transforms hierarchical source rowsets and writes to destination.
SendMailTask Object	Sends e-mail in the context of a DTS task.
TransferObjectsTask Object	Transfers SQL Server objects between source and destination.
TransferObjectsTask2 Object	Transfers SQL Server objects between source and destination. Extended TransferObjectsTask object.


ActiveScriptTask Object

The ActiveScriptTask object defines a task that is a Microsoft® ActiveX® script. ActiveX Script tasks do not use the data pump and therefore do not have access to the Connections collection or Data Transformation Services (DTS) source and destination collections. However, ActiveScriptTask objects have full access to the GlobalVariables collection, which provides a way to share information across tasks.

Collections

Properties Collection

Properties

ActiveXScript Property	FunctionName Property
AddGlobalVariables Property	Name Property
Description Property
Methods

CheckSyntax Method	Execute Method
Remarks

Script languages available on a particular system can be determined by enumerating the ScriptingLanguageInfos collection of the Application object. For more information about the scripting language appropriate for use with DTS, see ScriptingLanguageInfo Object.

Example

The following Microsoft Visual Basic® code creates ActiveScriptTask and Step objects. The ActiveX script returns DTSTaskExecResult_Success or DTSTaskExecResult_Failure, depending on the value of a global variable. The success or failure return can be used to direct the workflow of subsequent steps in the package.

Dim objPackage      As DTS.Package2

Dim objStep         As DTS.Step

Dim objTask         As DTS.Task

Dim objScripTask    As DTS.ActiveScriptTask

. . .

'create step and task, specify script, func name and language

Set objStep = objPackage.Steps.New

Set objTask = objPackage.Tasks.New("DTSActiveScriptTask")

Set objScripTask = objTask.CustomTask

With objScripTask

    .Name = "AXScr_Task"

    .ActiveXScript = _

        "Function Main()" & vbCrLf & _

        "If DTSGlobalVariables( ""GlobalOne"" ) > 0 Then" & vbCrLf & _

        vbTab & "Main = DTSTaskExecResult_Success" & vbCrLf & _

        "Else" & vbCrLf & _

        vbTab & "Main = DTSTaskExecResult_Failure" & vbCrLf & _

        "End If" & vbCrLf & _

        "End Function"

        .FunctionName = "Main"

        .ScriptLanguage = "VBScript"

End With

'link step to task to package

objStep.TaskName = objScripTask.Name

objStep.Name = "AXScr_Step"

With objPackage

    .Steps.Add objStep

    .Tasks.Add objTask

    .FailOnError = False

End With

Note   If an ActiveX script returns DTSTaskExecResult_Failure and the FailOnError property of the Package2 object is TRUE, the entire package will fail.

See Also

Application Object

ScriptingLanguageInfos Collection


BulkInsertTask Object

The BulkInsertTask object, based on the Transact-SQL BULK INSERT statement, provides the fastest method for copying large amounts of data from a text file to Microsoft® SQL Server™. Use BulkInsertTask for copying operations, and in situations where performance is the most important consideration. It is not used in conjunction with transformations during data import operations.

Collections

Properties Collection

Properties

BatchSize Property	FormatFile Property
CheckConstraints Property	KeepIdentity Property
Codepage Property	KeepNulls Property
ConnectionID Property	LastRow Property
DataFile Property	MaximumErrors Property
DataFileType Property	Name Property
Description Property	RowTerminator Property
DestinationTableName Property	SortedData Property
FieldTerminator Property	TableLock Property
FirstRow Property
Methods

Execute Method

Remarks

A Connection2 object must be used to access the database into which data is inserted. You can specify the format of the input data file directly using the FieldTerminator and RowTerminator properties, or indirectly through a bcp format file.

Example

The following Microsoft Visual Basic® code uses the BulkInsertTask object to insert data from file D:\DTS_UE\BCPData\Payroll.txt into table Payroll of database DTS_UE.

Public Sub Main()

'initialize Payroll table in DTS_UE db with bulk data

Dim objPackage      As DTS.Package2

Dim objConnect      As DTS.Connection2

Dim objStep         As DTS.Step

Dim objTask         As DTS.Task

Dim objBulkCopy     As DTS.BulkInsertTask

Set objPackage = New DTS.Package

'create database connection

Set objConnect = objPackage.Connections.New("SQLOLEDB.1")

With objConnect

    .ID = 1

    .DataSource = "(local)"

    .UseTrustedConnection = True

End With

objPackage.Connections.Add objConnect

'create step and task, specify data file and format

Set objStep = objPackage.Steps.New

Set objTask = objPackage.Tasks.New("DTSBulkInsertTask")

Set objBulkCopy = objTask.CustomTask

With objBulkCopy

    .Name = "BulkInsTask"

    .DataFile = "D:\DTS_UE\BCPData\Payroll.txt"

    .ConnectionID = 1

    .DestinationTableName = "DTS_UE..Payroll"

    .FieldTerminator = "|"

    .RowTerminator = "\r\n"

End With

'link step to task to package, run package

objStep.TaskName = objBulkCopy.Name

objStep.Name = "BulkInsStep"

With objPackage

    .Steps.Add objStep

    .Tasks.Add objTask

    .FailOnError = True

    .Execute

End With

End Sub


CreateProcessTask Object

The CreateProcessTask object runs a Microsoft® Win32® executable or batch file in the context of the Data Transformation Services (DTS) package.

Use the ProcessCommandLine property to specify the file to be executed and command line parameters. You can set a Timeout for the executed process. You can specify TerminateProcessAfterTimeout, or also FailPackageOnTimeout.

Collections

Properties Collection

Properties

Description Property	SuccessReturnCode Property
FailPackageOnTimeout Property	TerminateProcessAfterTimeout Property
Name Property	Timeout Property
ProcessCommandLine Property
Methods

Execute Method

Remarks

The CreateProcessTask object is compatible with Microsoft SQL Server™ version 7.0. For information about an extended version of this object, see CreateProcessTask2 Object.


CreateProcessTask2 Object

The CreateProcessTask2 object runs a Microsoft® Win32® executable or batch file in the context of the Data Transformation Services (DTS) package. It is called the Execute Process Task in DTS Designer.

Extended Methods

GetExpandedProcessCommandLine Method

Remarks

The CreateProcessTask2 object extends the functionality of the CreateProcessTask Object and inherits the properties and methods of that object. In addition, the GetExpandedProcessCommandLine method returns the process command line parameter string with environment variables expanded.

For more information about when to use the CreateProcessTask object instead of the CreateProcessTask2 object, see Extended DTS Objects.


DataDrivenQueryTask Object

The DataDrivenQueryTask object reads data through a source Connection object and transforms it using one or more Transformation objects. One of the transformations, a DataPumpTransformScript object, returns an indicator that determines which of four parameterized queries is executed on the destination Connection object. For more information, see Adding DTS Transformations and Adding DTS Column Objects.

The queries are called the Insert query, Update query, Delete query and User query, although they do not actually need to be used for these purposes. Any sequence of SQL action statements and stored procedure calls can be used for any of the queries. The query parameters are columns from the destination connection. For more information, see Adding DTS Query Strings.

Collections

Lookups Collection	Transformations Collection
Properties Collection
Properties

DeleteQuery Property	InsertQueryColumns Property
DeleteQueryColumns Property	LastRow Property
Description Property	MaximumErrorCount Property
DestinationColumnDefinitions Property	Name Property
DestinationCommandProperties Property	ProgressRowCount Property
DestinationConnectionID Property	SourceCommandProperties Property
DestinationObjectName Property	SourceConnectionID Property
DestinationSQLStatement Property	SourceObjectName Property
ExceptionFileColumnDelimiter Property	SourceSQLStatement Property
ExceptionFileName Property	UpdateQuery Property
ExceptionFileRowDelimiter Property	UpdateQueryColumns Property
FetchBufferSize Property	UserQuery Property
FirstRow Property	UserQueryColumns Property
InsertQuery Property
Methods

Execute Method

Remarks

The query selection indicator must be from the DTSTransformStatus constants. Do not use a sum or logical OR of these values. If more than one DataPumpTransformScript object returns an indicator, all but the last will be overwritten and lost.

The DataDrivenQueryTask object is compatible with Microsoft® SQL Server™ version 7.0. For information about an extended version of this object, see DataDrivenQueryTask2 Object.

For more information about how to create a DataDrivenQueryTask object and assign query strings and parameters, see DTS Query Strings in Visual Basic.

See Also

DTSTransformStatus


DataDrivenQueryTask2 Object

The DataDrivenQueryTask2 object transforms data from a source connection and invokes user-defined queries to write data to a destination connection.

Extended Properties

ExceptionFileOptions Property	RowsComplete Property
ExceptionFileTextQualifier Property	RowsInError Property
InputGlobalVariableNames Property
Remarks

The DataDrivenQueryTask2 object extends the functionality of the DataDrivenQueryTask object and inherits the properties and methods of that object. In addition, Microsoft® SQL Server™ 2000 provides the following properties:

•	The ExceptionFileOptions property specifies how errors and exception rows are to be written to the appropriate files. The ExceptionFileTextQualifier property specifies the text qualifier for the data in the exception file.

•	The SourceSQLStatement property specifies parameters that can now be coded in the query. The InputGlobalVariableNames property specifies a list of package global variable names whose values are to be substituted for the query parameters.

•	The RowsComplete property returns the count of transformed rows and the RowsInError property returns the number of transformation error rows.

For more information about when to use the DataDrivenQueryTask object instead of the DataDrivenQueryTask2 object, see Extended DTS Objects.

See Also

DataDrivenQueryTask Object

SourceSQLStatement Property


DataPumpTask Object

The Data Transformation Services (DTS) data pump is an OLE DB service provider that provides the means to import, export, and transform data between heterogeneous data sources.

The DataPumpTask object makes the features of the data pump available as a DTS task.

Collections

Lookups Collection	Transformations Collection
Properties Collection
Properties

AllowIdentityInserts Property	FirstRow Property
Description Property	InsertCommitSize Property
DestinationColumnDefinitions Property	LastRow Property
DestinationCommandProperties Property	MaximumErrorCount Property
DestinationConnectionID Property	Name Property
DestinationObjectName Property	ProgressRowCount Property
DestinationSQLStatement Property	SourceCommandProperties Property
ExceptionFileColumnDelimiter Property	SourceConnectionID Property
ExceptionFileName Property	SourceObjectName Property
ExceptionFileRowDelimiter Property	SourceSQLStatement Property
FastLoadOptions Property	UseFastLoad Property
FetchBufferSize Property
Methods

Execute Method


DataPumpTask2 Object

The DataPumpTask2 object imports, exports, and transforms data between heterogeneous data sources.

Extended Properties

DataPumpOptions Property	InputGlobalVariableNames Property
ExceptionFileOptions Property	RowsComplete Property
ExceptionFileTextQualifier Property
Remarks

The DataPumpTask2 object extends the functionality of the DataPumpTask object and inherits the properties and methods of that object. In addition, Microsoft® SQL Server™ 2000 provides the following properties:

•	The ExceptionFileOptions property specifies how errors and exception rows are to be written to the appropriate files. The ExceptionFileTextQualifier property specifies the text qualifier for the data in the exception file.

•	The SourceSQLStatement property specifies parameters that can now be coded in the query. The InputGlobalVariableNames property specifies a list of package global variable names whose values are to be substituted for the query parameters.

•	The RowsComplete property returns the count of transformed rows and the RowsInError property returns the number of transformation error rows.

For more information about when to use the DataPumpTask object instead of the DataPumpTask2 object, see Extended DTS Objects.

See Also

DataPumpTask Object

SourceSQLStatement Property


DynamicPropertiesTask Object

The DynamicPropertiesTask object changes the values of package objects properties at runtime. Any property of any object in the package can be modified. This is useful for packages created with Data Transformation Services (DTS) Designer and the DTS Import/Export Wizard because many package object properties are fixed after the design process is complete.

The Dynamic Properties Task object provides several different sources for the new value of a property:

•	A constant

•	The contents of a data file

•	An environment variable

•	A DTS global variable

•	A field in an .ini file

•	An SQL query

In an application that creates and manipulates DTS objects, it is often easier to modify the values of properties directly in code rather than use a Dynamic Properties Task object. However, if part of a DTS package is contained within a module that cannot be modified easily, the Dynamic Properties Task object may be useful.

Collections

DynamicPropertiesTaskAssignments Collection	Properties Collection
Properties

Assignments Property	Name Property
Description Property
Methods

Execute Method

Remarks

To use the Dynamic Properties Task object, for each package object property that is to be modified, a DynamicPropertiesTaskAssignment object is created. The properties of this object are set to specify the package object property to be changed and the source of the new value. The DynamicPropertiesTaskAssignment object is added to the DynamicPropertiesTaskAssignments collection.

The New method of the Tasks collection of the Package object returns a reference to a Task object. The CustomTask property of the Task object returns a reference to the appropriate custom task object. For more information, see Creating DTS Package Workflow and Tasks.

See Also

DynamicPropertiesTaskAssignment Object


ExecutePackageTask Object

The ExecutePackageTask object runs another Data Transformation Services (DTS) package. The package can be located in Microsoft® SQL Server™ 2000 Meta Data Services, in SQL Server, or in a file. The package can be specified by name or by package or version globally unique identifier (GUID).

DTS global variables can be passed to the target package. For each such global variable, a GlobalVariable object, which defines the name of the variable and value, is added to the GlobalVariables collection of the ExecutePackageTask object. These global variables are distinct from the members of the GlobalVariables collection of the Package2 object that contains the ExecutePackageTask object. Use the InputGlobalVariableNames property to specify members of the parent package GlobalVariables collection that are to be created or set in the child package.

Steps in child packages can join the transactions of parent packages, if Microsoft Distributed Transaction Coordinator (MS DTC) is running.

Collections

GlobalVariables Collection	Properties Collection
Properties

Description Property	RepositoryDatabaseName Property
FileName Property	ServerName Property
InputGlobalVariableNames Property	ServerPassword Property
Name Property	ServerUserName Property
PackageID Property	UseRepository Property
PackageName Property	UseTrustedConnection Property
PackagePassword Property
Methods

Execute Method

Remarks

The New method of the Tasks collection of the Package object returns a reference to a Task object. The CustomTask property of the Task object returns a reference to the appropriate custom task object.

Example

The following Microsoft Visual Basic® code uses the Execute Package Task object to run a package located in the file VarPubsFields.dts, which is encrypted and requires the password "user" to access.

Public Sub Main()
'Run package stored in file C:\DTS_UE\TestPkg\VarPubsFields.dts.
    Dim oPackage    As DTS.Package
    Dim oStep       As DTS.Step
    Dim oTask       As DTS.Task
    Dim oCustTask   As DTS.ExecutePackageTask

    Set oPackage = New DTS.Package

    'Create step and task, link step to task.
    Set oStep = oPackage.Steps.New
    oStep.Name = "ExecPkgStep"
    Set oTask = oPackage.Tasks.New("DTSExecutePackageTask")
    Set oCustTask = oTask.CustomTask
    oCustTask.Name = "ExecPkgTask"
    oStep.TaskName = oCustTask.Name
    oPackage.Steps.Add oStep
    Set oStep = Nothing

    'Specify package to be run.
    oCustTask.PackagePassword = "user"
    oCustTask.FileName = "C:\DTS_UE\TestPkg\VarPubsFields.dts"

    'Link task to package, run package.
    oPackage.Tasks.Add oTask
    Set oCustTask = Nothing
    Set oTask = Nothing
    oPackage.Execute
    Set oPackage = Nothing
End Sub


ExecuteSQLTask Object

The ExecuteSQLTask object allows you to execute a sequence of one or more SQL statements on a connection. Use the ConnectionID property to specify the connection and the SQLStatement property to specify the sequence of SQL statements.

Collections

Properties Collection

Properties

CommandProperties Property	Description Property
CommandTimeout Property	Name Property
ConnectionID Property
Methods

Execute Method


ExecuteSQLTask2 Object

The ExecuteSQLTask2 object allows you to execute a sequence of one or more SQL statements on a connection.

Extended Properties

InputGlobalVariableNames Property	OutputGlobalVariableNames Property
OutputAsRecordset Property
Remarks

The ExecuteSQLTask2 object extends the functionality of the ExecuteSQLTask object and inherits the properties and methods of that object. In addition, the ExecuteSQLTask2 adds the InputGlobalVariableNames, OutputAsRecordset and OutputGlobalVariableNames properties.

The InputGlobalVariableNames property specifies a list of Data Transformation Services (DTS) global variable names that are used as parameters for the sequence of SQL statements specified by the SQLStatement property. The OutputGlobalVariableNames property specifies a list of global variable names that receive fields from the first row of the first rowset produced by the SQLStatement query. If the OutputAsRecordset property is set, the entire rowset is written to the first global variable specified by OutputGlobalVariableNames as a disconnected Microsoft® ActiveX® Data Objects (ADO) recordset.

For more information about when to use the ExecuteSQLTask object instead of the ExecuteSQLTask2 object, see Extended DTS Objects.

See Also

ExecuteSQLTask Object

SQLStatement Property


DTSFTPTask Object

The DTSFTPTask object transfers one or more files from a specified Internet FTP site or network directory to a destination directory.

Collections

Properties Collection

Properties

Description Property	SourceFilename Property
DestSite Property	SourceLocation Property
Name Property	SourcePassword (DTSFTPTask) Property
NonOverwritable Property	SourceSite Property
NumRetriesOnSource Property
Methods

Execute Method

Remarks

The New method of the Tasks collection of the Package object returns a reference to a Task object. The CustomTask property of the Task object returns a reference to the appropriate custom task object.

Example

The following Microsoft® Visual Basic® code uses the DTSFTPTask object to copy the files File3.dat and NWProdWiz.xls from the directory I:\DTS\TestData to D:\DTS_UE\Dest.

Public Sub Main()

'Copy files from I:\DTS\TestData to D:\DTS_UE\Dest.

    Dim oPackage    As DTS.Package

    Dim oStep       As DTS.Step

    Dim oTask       As DTS.Task

    Dim oCustTask   As DTSCustTasks.DTSFTPTask

    Set oPackage = New DTS.Package

    oPackage.FailOnError = True

    'Create step and task, link step to task.

    Set oStep = oPackage.Steps.New

    oStep.Name = "FTPSrcDirStep"

    Set oTask = oPackage.Tasks.New("DTSFTPTask")

    Set oCustTask = oTask.CustomTask

    oCustTask.Name = "FTPSrcDirTask"

    oStep.TaskName = oCustTask.Name

    oPackage.Steps.Add oStep

    Set oStep = Nothing

    'Specify files, source and destination directories.

    oCustTask.SourceLocation = DTSFTPSourceLocation_Directory

    oCustTask.SourceSite = "I:\DTS\TestData"

    oCustTask.SourceFilename = _

            "'File3.dat';'';'123';'NWProdWiz.XLS';'';'458240';"

    oCustTask.DestSite = "D:\DTS_UE\Dest"

    'Link task to package, run package.

    oPackage.Tasks.Add oTask

    Set oCustTask = Nothing

    Set oTask = Nothing

    oPackage.Execute

    Set oPackage = Nothing

End Sub


DTSMessageQueueTask Object

The DTSMessageQueueTask object sends and receives messages to or from a queue of Message Queuing. It allows participation in distributed transactions when Microsoft® Distributed Transaction Coordinator (MS DTC) is running.

A single instance of the DTSMessageQueueTask either sends one or more messages to a specified queue or receives a single message from a specified queue, waiting, if necessary, for the message to arrive.

Three types of messages can be sent:

•	A string message, which is supplied as the value of a property.

•	A data file message, which is generated from the contents of a specified data file.

•	A global variables message, which is generated from the names and values of one or more Data Transformation Services (DTS) global variables.

Two types of messages can be received:

•	A string message. Various comparisons can be specified to determine whether the task returns success or failure.

•	A global variables message. The values of one or more global variables (specified by the message) in the local package can be updated. If any of the global variables do not exist in the local package, they are created.

Collections

DTSMQMessages Collection	Properties Collection
Properties

DataFileNonOverwritable Property	ReceiveMessageTimeout Property
Description Property	ReceiveMessageType Property
DTSMessageLineageID Property	RemoveFromQueue Property
DTSMessagePackageID Property	SaveDataFileName Property
DTSMessageVersionID Property	StringCompareType Property
ErrorIfReceiveMessageTimeout Property	StringCompareValue Property
Name Property (DTS)	TaskType Property
QueuePath Property
Methods

Execute Method	Messages Method
Remarks

The New method of the Tasks collection of the Package object returns a reference to a Task object. The CustomTask property of the Task object returns a reference to the appropriate custom task object.


ParallelDataPumpTask Object

The ParallelDataPumpTask object copies and transforms data from source to destination rowsets. It performs the same functions as the DataPumpTask2 and DataDrivenQueryTask2, except that it will also copy and transform hierarchical rowsets. The FastLoad option of the DataPumpTask2 is not supported, however.

In the ParallelDataPumpTask object, a TransformationSets collection is populated with one or more TransformationSet objects, each of which includes a Transformations collection and contains all the information necessary to transform a component rowset of the source hierarchical rowset to the corresponding component rowset in the destination.

The component rowsets are scanned and matched source to destination through recursive descent. The columns of the parent rowset are in column-ordinal order. When a child rowset column is encountered, it is scanned before the remaining columns of the parent. Child rowsets are similarly processed; their own children are scanned when encountered, before their remaining rows, with greater column ordinal.

Using Transformation Modes

The ParallelDataPumpTask operates in one of the following modes:

•	In flattened mode, the component rowsets are copied without regard to the chapter values. All the rows of each child rowset are copied, including those not referenced by any chapters.

•	In hierarchical mode, rowsets are copied a row at a time. The rows of a child rowset referenced by the chapter in the parent rowset row are copied. Thus, child rowset rows can be copied multiple times, or not at all.

•	In data driven query mode, rowsets are processed in the same way as in flattened mode, except that one of four queries, typically an INSERT, UPDATE or DELETE SQL statement, or stored procedure, can be executed based on the return code of a script transform.

The mode is specified with the TransformationSetOptions property of the TransformationSet object.

Collections

Properties Collection	TransformationSets Collection
Properties

Description Property	Name Property
DestinationCommandProperties Property	SourceCommandProperties Property
DestinationConnectionID Property	SourceConnectionID Property
DestinationObjectName Property	SourceObjectName Property
DestinationSQLStatement Property	SourceSQLStatement Property
InputGlobalVariableNames Property
Methods

Execute Method

Remarks

A failure of any TransformationSet (including failure due to the maximum number of error rows being exceeded for that TransformationSet, regardless of the error counts in other TransformationSets) results in the failure of the ParallelDataPumpTask.

In Microsoft® SQL Server™ 2000, the ParallelDataPumpTask is available only through the Data Transformation Services (DTS) object model. It cannot be accessed through DTS Designer or the DTS Import/Export Wizard.

Examples

Parallel Data Driven Query Example	Parallel Data Pump Example
See Also

Hierarchical Rowsets

TransformationSet Object


Hierarchical Rowsets

A rowset is an OLE DB object that consists of data organized as a grid of rows and named, typed columns. Typically, a rowset contains a result set from a database query, but the data can come from any source.

In a hierarchical rowset, one or more columns are themselves rowsets. The individual column values are references to subsets, called chapters, of the column rowset. A chapter can include none, some, or all of its rows. The column rowsets can themselves have one or more columns that are rowsets, nested to an arbitrary level.

Using the Data Shaping Service for OLE DB

Hierarchical rowsets are often generated with the Microsoft® Data Shaping Service for OLE DB. This provider supports the Shape language, which allows rowset hierarchies to be constructed from rowsets obtained from an OLE DB data provider. The Shape Append command appends one or more child rowsets as columns to a parent rowset, and assigns a reference to a chapter to each row value in each appended column. For example:

SHAPE {SELECT au_id, au_lname, au_fname FROM authors}
APPEND ({SELECT au_id, title FROM titleauthor TA, titles TS
WHERE TA.title_id = TS.title_id}
AS title_chap RELATE au_id TO au_id)

This command creates a parent rowset from table authors and appends a child rowset in a column named title_chap. Each row value in title_chap is a reference to the subset of the child rowset that has the same value in its au_id column as in the au_id column of the parent rowset for that row. The tables referenced by this command are in the pubs database that is supplied with Microsoft SQL Server™ 2000.

Writing sGetTitleAuthors Code

This is the Microsoft Visual Basic® source code for the sGetTitleAuthors function:

Private Function sGetTitleAuthors() As String

Dim rstParent   As ADODB.Recordset

Dim rstChild    As ADODB.Recordset

Dim sBuf        As String

Const CONNECT_PUBS = "PROVIDER=MSDataShape;DATA PROVIDER=SQLOLEDB;" & _

    "SERVER=;DATABASE=pubs;UID=sa;PWD=;"

Const SHAPE_TITLEAUTHORS = _

    "SHAPE {SELECT au_id, au_lname, au_fname FROM authors} " & _

    "APPEND ({SELECT au_id, title FROM titleauthor TA, titles TS " & _

             "WHERE TA.title_id = TS.title_id} " & _

            "AS title_chap RELATE au_id TO au_id)"

    '----- create rowsets

    Set rstParent = New ADODB.Recordset

    rstParent.Open SHAPE_TITLEAUTHORS, CONNECT_PUBS

    '----- process parent rowset

    Do While Not rstParent.EOF

        sBuf = sBuf & rstParent("au_id") & vbTab & _

            rstParent("au_lname") & ", " & rstParent("au_fname") & vbCrLf

        '----- process chapter of child rowset

        Set rstChild = rstParent("title_chap").Value

        Do While Not rstChild.EOF

            sBuf = sBuf & vbTab & vbTab & rstChild("title") & vbCrLf

            rstChild.MoveNext

        Loop

        rstParent.MoveNext

    Loop

    sGetTitleAuthors = sBuf

End Function

Running sGetTitleAuthors

This Microsoft Visual Basic function creates and processes the hierarchical rowset described earlier. It returns a string consisting of each author name, followed by the titles associated with that author in the pubs database.

This example can be run on a computer on which Visual Basic 6.0 and SQL Server 2000 have been installed.

The steps for running this example are as follows:

1.	Create a new Standard EXE project in the Visual Basic development environment.

2.	In the Project/References dialog box, select Microsoft ActiveX Data Objects 2.5 Library.

3.	Place a command button and a textbox on the form Form1. Set the ScrollBars property of the textbox to 3 – Both and the MultiLine property to TRUE.

4.	Copy the following code for function sGetTitleAuthors to the code window for Form1.

5.	In the _Click sub for the command button, call sGetTitleAuthors, and assign the string it returns to the Text property of the text box.

6.	Run the project and click the command button.


Parallel Data Pump Example

This sample Microsoft® Visual Basic® function sCopyCustOrderProd creates and runs a package that transforms parts of the Customers, Orders, Order Details, and Products tables from the Northwind database that ships with Microsoft SQL Server™ 2000. The function generates a hierarchical rowset consisting of the customers located in the U.K., their orders, the order details, and the products.

Creating the sCopyCustOrderProd Rowset

This function copies the data to tables in a database called DTSTest that have the following structure:

CREATE TABLE dbo.customers (
customer_key NCHAR (5) NOT NULL ,
company_name NVARCHAR (40) NOT NULL )

CREATE TABLE dbo.orders (
customer_key NCHAR (5) NULL ,
order_key INT NOT NULL )

CREATE TABLE dbo.products (
product_key INT NOT NULL ,
product_name NVARCHAR (40) NOT NULL )

CREATE TABLE dbo.order_details (
order_key INT NOT NULL ,
product_key INT NOT NULL ,
discount REAL NOT NULL )

The number of rows copied depends on whether Flattened or Hierarchical mode is used. In Flattened mode, the entire Orders, Order Details, and Products tables are copied. In Hierarchical mode, only the rows referenced by the U.K. customers are copied, although there are many duplicates of these rows in the products table in the destination database.

The Visual Basic Function for sCopyCustOrderProd

This is the Visual Basic source code for the sCopyCustOrderProd code:

Private Function sCopyCustOrderProd( _

    ByVal TranSetOpt As DTS.DTSTransformationSetOptions) As String

Dim oPackage            As New DTS.Package

Dim oConnection         As DTS.Connection

Dim oTask               As DTS.Task

Dim oStep               As DTS.Step

Dim oTransform          As DTS.Transformation

Dim oTransformationSet  As DTS.TransformationSet

Dim oParallelPumpTask   As DTS.ParallelDataPumpTask

Const SHAPE_NW_CUST_ORDER_PROD = _

    "SHAPE {SELECT CustomerID, CompanyName " & _

           "FROM Customers WHERE Country = 'UK'} " & _

    "APPEND ((SHAPE {SELECT OrderID, CustomerID FROM Orders} " & _

            "APPEND ((SHAPE {SELECT OrderID, ProductID, Discount " & _

                            "FROM [Order Details]} " & _

                    "APPEND ({SELECT ProductID, ProductName " & _

                             "FROM Products} " & _

                            "AS ProductChap " & _

                            "RELATE ProductID TO ProductID)) " & _

                    "AS DetailChap RELATE OrderID TO OrderID)) " & _

            "AS OrderChap RELATE CustomerID TO CustomerID)"

Const SHAPE_UE_CUST_ORDER_PROD = _

    "SHAPE {SELECT * FROM customers} " & _

    "APPEND ((SHAPE {SELECT * FROM orders} " & _

            "APPEND ((SHAPE {SELECT * FROM order_details} " & _

                    "APPEND ({SELECT * FROM products} " & _

                            "AS product_chap " & _

                            "RELATE product_key TO product_key)) " & _

                    "AS detail_chap RELATE order_key TO order_key)) " & _

            "AS order_chap RELATE customer_key TO customer_key)"

    '----- define source connection - Northwind

    Set oConnection = oPackage.Connections.New("MSDataShape")

    With oConnection

        .ConnectionProperties("Data Provider") = "SQLOLEDB"

        .ID = 1

        .Catalog = "Northwind"

        .UserID = "sa"

    End With

    oPackage.Connections.Add oConnection

    '----- define destination connection - (local) DTSTest

    Set oConnection = oPackage.Connections.New("MSDataShape")

    With oConnection

        .ConnectionProperties("Data Provider") = "SQLOLEDB"

        .ID = 2

        .DataSource = "(local)"

        .Catalog = "DTSTest"

        .UseTrustedConnection = True

    End With

    oPackage.Connections.Add oConnection

    '----- set hierarchical/flattened, set connections and commands

    Set oTask = oPackage.Tasks.New("DTSParallelDataPumpTask")

    Set oParallelPumpTask = oTask.CustomTask

    With oParallelPumpTask

        .TransformationSetOptions = TranSetOpt

        .SourceConnectionID = 1

        .SourceSQLStatement = SHAPE_NW_CUST_ORDER_PROD

        .DestinationConnectionID = 2

        .DestinationSQLStatement = SHAPE_UE_CUST_ORDER_PROD

    End With

    '----- create TransformationSet for customers

    Set oTransformationSet = oParallelPumpTask. _

        TransformationSets.New("TransformSet_Customers")

    oParallelPumpTask.TransformationSets.Add oTransformationSet

    Set oTransform = oTransformationSet. _

        Transformations.New("DTS.DataPumpTransformCopy")

    With oTransform

        .SourceColumns.AddColumn "CustomerID", 1

        .SourceColumns.AddColumn "CompanyName", 2

        .DestinationColumns.AddColumn "customer_key", 1

        .DestinationColumns.AddColumn "company_name", 2

        .Name = "Transform"

    End With

    oTransformationSet.Transformations.Add oTransform

    '----- create TransaformationSet for orders

    Set oTransformationSet = oParallelPumpTask. _

        TransformationSets.New("TransformSet_Orders")

    oParallelPumpTask.TransformationSets.Add oTransformationSet

    Set oTransform = oTransformationSet. _

        Transformations.New("DTS.DataPumpTransformCopy")

    With oTransform

        .SourceColumns.AddColumn "OrderID", 1

        .SourceColumns.AddColumn "CustomerID", 2

        .DestinationColumns.AddColumn "order_key", 1

        .DestinationColumns.AddColumn "customer_key", 2

        .Name = "Transform"

    End With

    oTransformationSet.Transformations.Add oTransform

    '----- create TransformationSet for order details

    Set oTransformationSet = oParallelPumpTask. _

        TransformationSets.New("TransformSet_Details")

    oParallelPumpTask.TransformationSets.Add oTransformationSet

    Set oTransform = oTransformationSet. _

        Transformations.New("DTS.DataPumpTransformCopy")

    With oTransform

        .SourceColumns.AddColumn "OrderID", 1

        .SourceColumns.AddColumn "ProductID", 2

        .SourceColumns.AddColumn "Discount", 3

        .DestinationColumns.AddColumn "order_key", 1

        .DestinationColumns.AddColumn "product_key", 2

        .DestinationColumns.AddColumn "discount", 3

        .Name = "Transform"

    End With

    oTransformationSet.Transformations.Add oTransform

    '----- create TransaformationSet for products

    Set oTransformationSet = oParallelPumpTask. _

        TransformationSets.New("TransformSet_Products")

    oParallelPumpTask.TransformationSets.Add oTransformationSet

    Set oTransform = oTransformationSet. _

        Transformations.New("DTS.DataPumpTransformCopy")

    With oTransform

        .SourceColumns.AddColumn "ProductID", 1

        .SourceColumns.AddColumn "ProductName", 2

        .DestinationColumns.AddColumn "product_key", 1

        .DestinationColumns.AddColumn "product_name", 2

        .Name = "Transform"

    End With

    oTransformationSet.Transformations.Add oTransform

    '----- add task, step to package

    oTask.Name = "ParallelDPTask"

    With oPackage

        Set oStep = oPackage.Steps.New

        oStep.Name = "ParallelDPStep"

        oStep.TaskName = oTask.Name

        .Tasks.Add oTask

        .Steps.Add oStep

        .Name = "ParallelDataPumpTask Package"

        .FailOnError = True

        .Execute            'run the package

   End With

End Function

Running sCopyCustOrderProd

This example can be run on a computer on which Microsoft Visual Basic 6.0 and SQL Server 2000 have been installed.

The basic steps for running sCopyCustOrderProd are as follows:

1.	Create a database named DTSTest using SQL Server Enterprise Manager, and then create the tables defined above in DTSTest. If you use another database, change the line in the example that sets the database name for the destination connection.

2.	Create a new Standard EXE project in the Visual Basic development environment. In the Project/References dialog box, select Microsoft DTSPackage Object Library.

3.	Copy the following code for function sCopyCustOrderProd to the code window for Form1.

4.	Place a command button and another control, such as a check box, on the form Form1. In the _Click sub for the command button, call sCopyCustOrderProd, and use the other control to provide values for the parameter TranSetOpt.

5.	You can add completion notification, such as a message box, and an error handler. For more information about returning meaningful error information, see Handling DTS Errors in Visual Basic.

6.	If you are using a database other than DTSTest, change the setting of the Catalog property of connection 2.

7.	Run the project, providing the value DTSTranSetOpt_Flattened for the TranSetOpt parameter. View, truncate the destination tables, and then run the sample again with TranSetOpt set to DTSTranSetOpt_Hierarchical.

See Also

Hierarchical Rowsets


Parallel Data Driven Query Example

This sample Microsoft® Visual Basic® function, sDDQTitleAuthors, creates and runs a package that transforms parts of the authors, titleauthor, and titles tables from the pubs database that ships with Microsoft SQL Server™ 2000. The function generates a hierarchical rowset consisting of the authors from the pubs database and the titles with which they are associated.

Creating sDDQTitleAuthors Rowset

This function copies the data to tables in a database called DTSTest that have the following structure:

CREATE TABLE dbo.AuthNames (
AuthID VARCHAR (11) NOT NULL ,
LastName VARCHAR (40) NOT NULL ,
FirstName VARCHAR (20) NOT NULL )

CREATE TABLE dbo.TitleNames (
AuthID VARCHAR (11) NOT NULL ,
TitleName VARCHAR (80) NOT NULL )

As in flattened mode, the component rowsets are copied without regard to the chapters.

Running sDDQTitleAuthors

This example can be run on a computer on which Visual Basic 6.0 and SQL Server 2000 have been installed.

The steps for running sDDQTitleAuthors are as follows:

1.	Create a database named DTSTest using SQL Server Enterprise Manager, and then create the tables defined earlier in DTSTest. If you use another database, change the line in the example that sets the database name for the destination connection.

2.	Create a new Standard EXE project in the Visual Basic development environment. In the Project/References dialog box, check Microsoft DTSPackage Object Library and Microsoft DTSDataPump Scripting Object Library.

3.	Copy the following code for function sDDQTitleAuthors to the code window for Form1.

4.	Place a command button on the form Form1. In the _Click sub for the command button, call sDDQTitleAuthors.

5.	You can add completion notification, such as a message box, and an error handler. For more information about returning meaningful error information, see Handling DTS Errors in Visual Basic.

6.	If you are using a database other than DTSTest, change the setting of the Catalog property of connection 2.

7.	Run the project, click the command button, and then view the destination tables.

Writing sDDQTitleAuthors Code

This is the Visual Basic source code for the sDDQTitleAuthors function:

Private Function sDDQTitleAuthors() As String

    Dim oPackage            As New DTS.Package

    Dim oConnection         As DTS.Connection

    Dim oTask               As DTS.Task

    Dim oStep               As DTS.Step

    Dim oTransform          As DTS.Transformation

    Dim oScriptTransform    As DTSPump.DataPumpTransformScript

    Dim oTransformationSet  As DTS.TransformationSet

    Dim oParallelPumpTask   As DTS.ParallelDataPumpTask

    Dim sScript(1 To 3)     As String

    Dim sScriptLanguage     As String

    Dim sScriptFunction     As String

Const SHAPE_PUBS_TITLEAUTHORS = _

    "SHAPE {SELECT au_id, au_lname, au_fname FROM authors} " & _

    "APPEND ({SELECT au_id, title FROM titleauthor TA, titles TS " & _

             "WHERE TA.title_id = TS.title_id} " & _

            "AS title_chap RELATE au_id TO au_id)"

Const SHAPE_DTSUE_TITLEAUTHORS = _

    "SHAPE {SELECT * FROM AuthNames} " & _

    "APPEND ({SELECT * FROM TitleNames} " & _

            "AS TitleChap RELATE AuthID TO AuthID)"

    '----- generate scripts, one needs 2 col, other needs 3

    sScriptLanguage = "VBScript"

    sScriptFunction = "Transform"

    sScript(1) = "Function Transform()" & vbCrLf & _

                 "DTSDestination(1) = DTSSource(1)" & vbCrLf & _

                 "DTSDestination(2) = DTSSource(2)" & vbCrLf

    sScript(2) = "DTSDestination(3) = DTSSource(3)" & vbCrLf

    sScript(3) = "Transform = DTSTransformStat_InsertQuery" & _

                 vbCrLf & "End Function"

    '----- define source connection - pubs

    Set oConnection = oPackage.Connections.New("MSDataShape")

    With oConnection

        .ConnectionProperties("Data Provider") = "SQLOLEDB"

        .ID = 1

        .Catalog = "pubs"

        .UserID = "sa"

    End With

    oPackage.Connections.Add oConnection

    '----- define destination connection - (local) DTSTest

    Set oConnection = oPackage.Connections.New("MSDataShape")

    With oConnection

        .ConnectionProperties("Data Provider") = "SQLOLEDB"

        .ID = 2

        .DataSource = "(local)"

        .Catalog = "DTSTest"

        .UseTrustedConnection = True

    End With

    oPackage.Connections.Add oConnection

    '----- Create ParallelDPTask set DDQ, connections and commands

    Set oTask = oPackage.Tasks.New("DTSParallelDataPumpTask")

    Set oParallelPumpTask = oTask.CustomTask

    With oParallelPumpTask

        .TransformationSetOptions = DTSTranSetOpt_DataDrivenQueries

        .SourceConnectionID = 1

        .SourceSQLStatement = SHAPE_PUBS_TITLEAUTHORS

        .DestinationConnectionID = 2

        .DestinationSQLStatement = SHAPE_DTSUE_TITLEAUTHORS

    End With

    '----- create TransformationSet for parent rowset

    Set oTransformationSet = oParallelPumpTask. _

        TransformationSets.New("TransformSet_author")

    oParallelPumpTask.TransformationSets.Add oTransformationSet

    Set oTransform = oTransformationSet. _

        Transformations.New("DTS.DataPumpTransformScript")

    Set oScriptTransform = oTransform.TransformServer

    With oScriptTransform

        .Language = sScriptLanguage

        .FunctionEntry = sScriptFunction

        .Text = sScript(1) & sScript(2) & sScript(3)

    End With

    '----- define source/dest columns for parent

    With oTransform

        .SourceColumns.AddColumn "au_id", 1

        .SourceColumns.AddColumn "au_lname", 2

        .SourceColumns.AddColumn "au_fname", 3

        .DestinationColumns.AddColumn "AuthID", 1

        .DestinationColumns.AddColumn "LastName", 2

        .DestinationColumns.AddColumn "FirstName", 3

        .Name = "Transform"

    End With

    '----- define INSERT query, params for parent

    With oTransformationSet

        .InsertQuery = "INSERT AuthNames VALUES (?, ?, ?)"

        .InsertQueryColumns.AddColumn "AuthID", 1

        .InsertQueryColumns.AddColumn "LastName", 2

        .InsertQueryColumns.AddColumn "FirstName", 3

        .Transformations.Add oTransform

    End With

    '----- create TransaformationSet for child rowset

    Set oTransformationSet = oParallelPumpTask. _

        TransformationSets.New("TransformSet_title")

    oParallelPumpTask.TransformationSets.Add oTransformationSet

    Set oTransform = oTransformationSet. _

        Transformations.New("DTS.DataPumpTransformScript")

    Set oScriptTransform = oTransform.TransformServer

    With oScriptTransform

        .Language = sScriptLanguage

        .FunctionEntry = sScriptFunction

        .Text = sScript(1) & sScript(3)

    End With

    '----- define source/dest columns for child

    With oTransform

        .SourceColumns.AddColumn "au_id", 1

        .SourceColumns.AddColumn "title", 2

        .DestinationColumns.AddColumn "AuthID", 1

        .DestinationColumns.AddColumn "TitleName", 2

        .Name = "Transform"

    End With

    '----- define INSERT query, params for child

    With oTransformationSet

        .InsertQuery = "INSERT TitleNames VALUES (?, ?)"

        .InsertQueryColumns.AddColumn "AuthID", 1

        .InsertQueryColumns.AddColumn "TitleName", 2

        .Transformations.Add oTransform

    End With

    '----- add task, step to package

    oTask.Name = "ParallelDDQTask"

    With oPackage

        Set oStep = .Steps.New

        oStep.Name = "ParallelDPStep"

        oStep.TaskName = oTask.Name

        .Tasks.Add oTask

        .Steps.Add oStep

        .Name = "ParallelDDQTask Package"

        .FailOnError = True

        .Execute            'run the package

    End With

End Function

See Also

Hierarchical Rowsets


SendMailTask Object

The SendMailTask object lets you send an e-mail as a task. For example, if you want to notify a database administrator about the success or failure of a particular task (such as a backup), you can link a SendMailTask object with a precedence constraint to the previous task. To use a SendMailTask, the computer must have the Microsoft® messaging API installed with a valid user profile.

A SendMailTask can include attached data files. You can point to a location for an attached file and send a dynamically updated file, rather than a static copy of the file fixed when you create the task. This feature is useful for sending attachments, such as log and exception files, which contain information that changes constantly, and for which the file may not exist when the package is created (at design time).

Note   If you enter an attachment file name and path that does not exist when the package is run, with some versions of the messaging API you receive the message: "Error sending mail: Internal MAPI error: the address book has no directories that contain names." This message indicates the file does not exist at the specified location, or that access permissions are not granted for the file. To fix the error, make sure that the file is available at the specified location when the package is run, or that access is granted.

Collections

Properties Collection

Properties

CCLine Property	Password Property
Description Property	Profile Property
FileAttachments Property	SaveMailInSentItemsFolder Property
IsNTService Property	Subject Property
MessageText Property	ToLine Property
Name Property
Methods

Execute Method	Logon Method
GetDefaultProfileName Method	ResolveName Method
InitializeMAPI Method	ShowAddressBook Method
Logoff Method
Example

The Microsoft Visual Basic® Sub SendMailMsg creates a Data Transformation Services (DTS) step and a SendMailTask object. It configures the task to send an e-mail message with attachment to a recipient named "IT Managers" and CC to "Data Center Operations":

Private Sub SendMailMsg(ByVal objPackage As DTS.Package2)

Dim objStep         As DTS.Step

Dim objTask         As DTS.Task

Dim objSendMail     As DTS.SendMailTask

'create step and task

Set objStep = objPackage.Steps.New

Set objTask = objPackage.Tasks.New("DTSSendMailTask")

Set objSendMail = objTask.CustomTask

'configure send mail task

With objSendMail

    .Name = "ErrorMailTask"

    .Profile = "Microsoft Outlook"

    .ToLine = "IT Managers"

    .CCLine = "Data Center Operations"

    .Subject = "Error in DTS Nightly Job"

    .MessageText = "An error occurred loading data " & _

                "warehouse.  See attachment for details."

    .FileAttachments = "D:\DTS_UE\Messages\DTSError.txt"

    .IsNTService = True

    .SaveMailInSentItemsFolder = True

End With

'link step to task

objStep.TaskName = objSendMail.Name

objStep.Name = "ErrorMailStep"

objPackage.Steps.Add objStep

objPackage.Tasks.Add objTask

End Sub


TransferObjectsTask Object

The TransferObjectsTask object allows you transfer one or more Microsoft® SQL Server™ objects between source and destination databases. An object can represent:

•	A table, or table data.

•	A view.

•	A referential integrity constraint.

•	A stored procedure.

•	An index.

•	A default or a rule.

•	A user-defined data type.

In addition, you can transfer all users or all logins (roles) for the source database. You can also transfer all objects dependent on the requested objects.

Note   The source and destination must both be Microsoft SQL Server version 7.0 or later databases.

Collections

Properties Collection

Properties

CopyAllObjects Property	IncludeLogins Property
CopyData Property	IncludeUsers Property
CopySchema Property	Name Property
Description Property	ScriptFileDirectory Property
DestinationDatabase Property	ScriptOption Property
DestinationLogin Property	ScriptOptionEx Property
DestinationPassword Property	SourceDatabase Property
DestinationServer Property	SourceLogin Property
DestinationUseTrustedConnection Property	SourcePassword Property
DropDestinationObjectsFirst Property	SourceServer Property
IncludeDependencies Property
Methods

AddObjectForTransfer Method	GetObjectForTransfer Method
CancelExecution Method	OnError Event
Execute Method
Remarks

Certain errors can occur that are documented in an error message written to a log file named server.database.LOG, in the directory specified by the ScriptFileDirectory property. In some cases, these errors may not raise the OnError event, and may not be recorded in the Data Transformation Services (DTS) error file or the SQL Server log.

The TransferObjectsTask object is compatible with SQL Server 7.0. For information about an updated version of this object, see TransferObjectsTask2 Object.

Example

The Microsoft Visual Basic® Sub RunTransfer creates a DTS step and a TransferObjectsTask object. It configures the task to copy the tables authors and employee, the view titleview, and the stored procedure byroyalty, and all objects dependent on these, from the pubs database supplied with SQL Server 2000 to a database named SomeOfPubs.

Private Sub RunTransfer(ByVal objPackage As DTS.Package2)

Dim objStep         As DTS.Step

Dim objTask         As DTS.Task

Dim objXferObj      As DTS.TransferObjectsTask

'create step and task

Set objStep = objPackage.Steps.New

Set objTask = objPackage.Tasks.New("DTSTransferObjectsTask")

Set objXferObj = objTask.CustomTask

'configure transfer objects task

With objXferObj

    .Name = "XferObjTask"

    .SourceServer = "(local)"

    .SourceUseTrustedConnection = True

    .SourceDatabase = "pubs"

    .DestinationServer = "(local)"

    .DestinationUseTrustedConnection = True

    .DestinationDatabase = "SomeOfPubs"

    .ScriptFileDirectory = "D:\DTS_UE\Scripts"

    .CopyAllObjects = False

    .IncludeDependencies = True

    .IncludeLogins = False

    .IncludeUsers = False

    .DropDestinationObjectsFirst = True

    .CopySchema = True

    .CopyData = DTSTransfer_AppendData

    .AddObjectForTransfer "authors", "dbo", DTSSQLObj_UserTable

    .AddObjectForTransfer "employee", "dbo", DTSSQLObj_UserTable

    .AddObjectForTransfer "titleview", "dbo", DTSSQLObj_View

    .AddObjectForTransfer "byroyalty", "dbo", DTSSQLObj_StoredProcedure

End With

'link step to task

objStep.TaskName = objXferObj.Name

objStep.Name = "XferObjStep"

objPackage.Steps.Add objStep

objPackage.Tasks.Add objTask

End Sub


TransferObjectsTask2 Object

The TransferObjectsTask2 object transfers objects between instances of Microsoft® SQL Server™.

Extended Properties

DestTranslateChar Property	SourceTranslateChar Property
DestUseTransaction Property
Remarks

The TransferObjectsTask2 object extends the functionality of the existing TransferObjectsTask object and inherits the properties and methods of that object.

The SourceTranslateChar and DestTranslateChar properties turn character translation on or off at the source and destination, respectively. However, the SourceTranslateChar and DestTranslateChar properties are now largely unused as they only support translation of non-Unicode characters.

The transfer of SQL Server objects is done within a transaction on the destination server if the DestUseTransaction property is set.

If the UseCollation property is set, column-level collation settings on the source table are used when transferring data between computers running instances of SQL Server 2000.

For more information about when to use the TransferObjectsTask object instead of the TransferObjectsTask2 object, see Extended DTS Objects.

See Also

TransferObjectsTask Object


Transformation Objects

This section describes the Data Transformation Services (DTS) transformation classes supplied with Microsoft® SQL Server™ 2000.

Topic	Description
DataPumpTransformCopy Object	Copies multiple source columns to destination columns.
DataPumpTransformDateTimeString Object	Converts datetime string formats.
DataPumpTransformLowerString Object	Converts multiple source columns to lowercase characters and copies them to destination columns.
DataPumpTransformMidString Object	Extracts substrings from a source column; optionally trims white space and changes case.
DataPumpTransformReadFile Object	Copies data read from files into destination columns.
DataPumpTransformScript Object	Transforms data with user-supplied Microsoft ActiveX® scripts.
DataPumpTransformTrimString Object	Removes white-space characters from data and optionally changes case.
DataPumpTransformUpperString Object	Converts multiple source columns to uppercase characters and copies them to destination columns.
DataPumpTransformWriteFile Object	Writes data from a source column into files.
DTSTransformScriptProperties2 Object	Supports multiphase transformations with an extended DataPumpTransformScript object.


DataPumpTransformCopy Object

The DataPumpTransformCopy object converts a source column to the destination column data type and moves the data to the destination column. DataPumpTransformCopy supports multiple source and destination columns. Destination truncation is possible by setting DTSTransformFlag_AllowStringTruncation in the TransformFlags property of the Transformation2 object. There are no transformation properties.

For more information, see DataPumpTransformLowerString Object. The DataPumpTransformCopy object is used the same way as the DataPumpTransformLowerString object in the example in that section, except that it is created as follows:

    Set oTransform = oCustTask.Transformations. _

            New("DTSPump.DataPumpTransformCopy")

See Also

Adding DTS Column Objects

Adding DTS Transformations

Transformation2 Object

TransformFlags Property


DataPumpTransformDateTimeString Object

The DataPumpTransformDateTimeString object converts a datetime string in one format to another datetime format. It requires one source and one destination column, both of data types compatible with the OLE DB data type DBTIMESTAMP. The transformation properties InputFormat and OutputFormat specify the formats of the source and destination columns, respectively.

Properties

AMSymbol Property	Month??ShortName Property
Day?LongName Property	OutputFormat Property
Day?ShortName Property	PMSymbol Property
InputFormat Property	ShortYear2000Cutoff Property
Month??LongName Property
Methods

GetDayLongName Method	SetDayLongName Method
GetDayShortName Method	SetDayShortName Method
GetMonthLongName Method	SetMonthLongName Method
GetMonthShortName Method
Remarks

The New method of the Transformations collection of the DataPumpTask2, DataDrivenQueryTask2, and TransformationSet objects returns a reference to a Transformation2 object. The TransformServer property of the Transformation2 object returns a reference to the DataPumpTransformDateTimeString object.

Example

This example Microsoft® Visual Basic® program transforms a date column in the employee table of the pubs database, where dates are in a short date format, to column HireDate in table Employee in a Microsoft Access database D:\DTS_UE\Data\jetPubs.mdb. For example, 5/1/94 is converted to May 01, 1994 (Sunday):

Public Sub Main()

'Copy/reformat pubs..employee.hire_date to Access DB.

    Dim oPackage    As DTS.Package

    Dim oConnect    As DTS.Connection

    Dim oStep       As DTS.Step

    Dim oTask       As DTS.Task

    Dim oCustTask   As DTS.DataPumpTask

    Dim oTransform  As DTS.Transformation

    Dim oColumn     As DTS.Column

    Dim oDateTime   As DTSPump.DataPumpTransformDateTimeString

    Set oPackage = New DTS.Package

    oPackage.FailOnError = True

    'Establish connection to SQL Server DB.

    Set oConnect = oPackage.Connections.New("SQLOLEDB.1")

    With oConnect

        .ID = 1

        .DataSource = "(local)"

        .UseTrustedConnection = True

    End With

    oPackage.Connections.Add oConnect

    'Establish connection to Access database.

    Set oConnect = oPackage.Connections.New( _

                                "Microsoft.Jet.OLEDB.4.0")

    oConnect.ID = 2

    oConnect.DataSource = "D:\DTS_UE\Data\JetPubs.mdb"

    oPackage.Connections.Add oConnect

    'Create step and task, link step to task.

    Set oStep = oPackage.Steps.New

    oStep.Name = "DateTimeStep"

    Set oTask = oPackage.Tasks.New("DTSDataPumpTask")

    Set oCustTask = oTask.CustomTask

    oCustTask.Name = "DateTimeTask"

    oStep.TaskName = oCustTask.Name

    oPackage.Steps.Add oStep

    'Link task to connections.

    With oCustTask

        .SourceConnectionID = 1

        .SourceObjectName = "[pubs].[dbo].[employee]"

        .DestinationConnectionID = 2

        .DestinationObjectName = "Employee"

    End With

    'Create custom transform, link to source and dest columns.

    Set oTransform = oCustTask.Transformations. _

            New("DTSPump.DataPumpTransformDateTimeString")

    oTransform.Name = "DateTimeTransform"

    Set oColumn = oTransform.SourceColumns.New("hire_date", 1)

    oTransform.SourceColumns.Add oColumn

    Set oColumn = oTransform.DestinationColumns. _

            New("HireDate", 1)

    oTransform.DestinationColumns.Add oColumn

    'Define source and destination date formats.

    Set oDateTime = oTransform.TransformServer

    oDateTime.InputFormat = "M/d/yy"

    oDateTime.OutputFormat = "MMMM dd, yyyy (dddd)"

    'Link transform to task, task to package, and then run package.

    oCustTask.Transformations.Add oTransform

    oPackage.Tasks.Add oTask

    oPackage.Execute

End Sub

See Also

Adding DTS Column Objects

Adding DTS Transformations

DataDrivenQueryTask2 Object

DataPumpTask2 Object

New (ID) Method

Transformation2 Object

Transformations Collection

TransformationSet Object

TransformServer Property


DataPumpTransformLowerString Object

The DataPumpTransformLowerString object converts a source column to lowercase characters and, if necessary, to the destination column data type. It requires source and destination columns to be of string data types (char, varchar, text, nchar, nvarchar, ntext, and flat file strings). Like the DataPumpTransformCopy object, this transformation object supports multiple source and destination columns. Destination truncation is possible by setting DTSTransformFlag_AllowStringTruncation in the TransformFlags property of the Transformation2 object. There are no custom transformation properties.

Remarks

Conversion to lowercase characters is also a feature of the DataPumpTransformTrimString and DataPumpTransformMidString objects.

Example

This example Microsoft® Visual Basic® program converts two columns from the authors table in the pubs database to lowercase characters while copying them to a table named AuthNames in a database named DTS_UE.

Public Sub Main()

'copy pubs..authors names to DTS_UE..AuthNames, making lower case

    Dim oPackage    As DTS.Package

    Dim oConnect    As DTS.Connection

    Dim oStep       As DTS.Step

    Dim oTask       As DTS.Task

    Dim oCustTask   As DTS.DataPumpTask

    Dim oTransform  As DTS.Transformation

    Dim oColumn     As DTS.Column

    Set oPackage = New DTS.Package

    oPackage.FailOnError = True

    'establish connection to source server

    Set oConnect = oPackage.Connections.New("SQLOLEDB.1")

    With oConnect

        .ID = 1

        .DataSource = "(local)"

        .UseTrustedConnection = True

    End With

    oPackage.Connections.Add oConnect

    'establish connection to destination server

    Set oConnect = oPackage.Connections.New("SQLOLEDB.1")

    With oConnect

        .ID = 2

        .DataSource = "(local)"

        .UseTrustedConnection = True

    End With

    oPackage.Connections.Add oConnect

    'create step and task, link step to task

    Set oStep = oPackage.Steps.New

    oStep.Name = "LowerCaseStep"

    Set oTask = oPackage.Tasks.New("DTSDataPumpTask")

    Set oCustTask = oTask.CustomTask

    oCustTask.Name = "LowerCaseTask"

    oStep.TaskName = oCustTask.Name

    oPackage.Steps.Add oStep

    'link task to connections

    With oCustTask

        .SourceConnectionID = 1

        .SourceObjectName = "pubs..authors"

        .DestinationConnectionID = 2

        .DestinationObjectName = "[DTS_UE].[dbo].[AuthNames]"

    End With

    'create custom transform, link to source and dest columns

    Set oTransform = oCustTask.Transformations. _

            New("DTSPump.DataPumpTransformLowerString")

    With oTransform

        .Name = "LowerCaseTransform"

        .SourceColumns.AddColumn "au_fname", 1

        .SourceColumns.AddColumn "au_lname", 2

        .DestinationColumns.AddColumn "FirstName", 1

        .DestinationColumns.AddColumn "LastName", 2

    End With

    'link transform to task, task to package, run package

    oCustTask.Transformations.Add oTransform

    oPackage.Tasks.Add oTask

    oPackage.Execute

End Sub

See Also

Adding DTS Column Objects

Adding DTS Transformations

DataPumpTransformCopy Object

DataPumpTransformMidString Object

DataPumpTransformTrimString Object

DataPumpTransformUpperString Object

Transformation2 Object

TransformFlags Property


DataPumpTransformMidString Object

The DataPumpTransformMidString object extracts a substring from the source column and converts it, if necessary, to the destination column data type. This object requires one source column and one destination column, both of a string data type (char, varchar, text, nchar, nvarchar, ntext, and flat file strings). The properties CharacterStart and CharacterCount specify the position of the substring.

Optionally, the transformation converts the extracted substring to uppercase or lowercase characters, as specified by the UpperCaseString and LowerCaseString properties. It also optionally trims white-space characters, as specified by the TrimLeadingWhiteSpace, TrimTrailingWhiteSpace, and TrimEmbeddedWhiteSpace properties. Substring extraction occurs before the trimming of white space characters.

Destination truncation is possible by setting DTSTransformFlag_AllowStringTruncation in the TransformFlags property of the Transformation2 object.

Properties

CharacterCount Property	TrimLeadingWhiteSpace Property
CharacterStart Property	TrimTrailingWhiteSpace Property
LowerCaseString Property	UpperCaseString Property
TrimEmbeddedWhiteSpace Property
Remarks

If only case conversion is required, the DataPumpTransformLowerString or DataPumpTransformUpperString objects can be used. These transformations accept multiple source and destination columns. If only case conversion and trimming of white space is required, the DataPumpTransformTrimString object can be used.

The New method of the Transformations collection of the DataPumpTask, DataDrivenQueryTask, and TransformationSet objects returns a reference to a Transformation object. The TransformServer property of the Transformation object returns a reference to the appropriate custom transformation object.

Example

This example Microsoft® Visual Basic® program splits the phone column from the authors table in the pubs database into two columns named AreaCode and LocalPhone while copying it to a Microsoft Excel worksheet named Phones in PubsAuthors.xls. The worksheet had been previously created by the Microsoft OLE DB Provider for Jet from:

CREATE TABLE `Phones` (
`AreaCode` VarChar (255) ,
`LocalPhone` VarChar (255) )

The basic steps for manually creating a worksheet are as follows:

1.	Open a new workbook in Excel and rename one of the blank sheets Phones.

2.	Enter AreaCode in cell A1 and LocalNumber in cell B1.

3.	Save the workbook as PubsAuthors.xls, and then close Excel.

Public Sub Main()

'Copy pubs..authors.phone to Excel. Split out area code and local number.

    Dim oPackage    As DTS.Package

    Dim oConnect    As DTS.Connection

    Dim oStep       As DTS.Step

    Dim oTask       As DTS.Task

    Dim oCustTask   As DTS.DataPumpTask

    Dim oTransform  As DTS.Transformation

    Dim oColumn     As DTS.Column

    Dim oMidString  As DTSPump.DataPumpTransformMidString

    Set oPackage = New DTS.Package

    oPackage.FailOnError = True

    'Establish a connection to the source server.

    Set oConnect = oPackage.Connections.New("SQLOLEDB.1")

    With oConnect

        .ID = 1

        .DataSource = "(local)"

        .UseTrustedConnection = True

    End With

    oPackage.Connections.Add oConnect

    Set oConnect = Nothing

    'Establish a connection to an Excel worksheet.

    Set oConnect = oPackage.Connections.New("Microsoft.Jet.OLEDB.4.0")

    With oConnect

        .ID = 2

        .DataSource = "D:\DTS_UE\Data\PubsAuthors.xls"

        .ConnectionProperties("Extended Properties").Value = _

                                            "Excel 8.0;HDR=YES;"

    End With

    oPackage.Connections.Add oConnect

    Set oConnect = Nothing

    'Create a step and task, and then link the step to the task.

    Set oStep = oPackage.Steps.New

    oStep.Name = "MidStringStep"

    Set oTask = oPackage.Tasks.New("DTSDataPumpTask")

    Set oCustTask = oTask.CustomTask

    oCustTask.Name = "MidStringTask"

    oStep.TaskName = oCustTask.Name

    oPackage.Steps.Add oStep

    'Link the task to the connections.

    With oCustTask

        .SourceConnectionID = 1

        .SourceObjectName = "[pubs].[dbo].[authors]"

        .DestinationConnectionID = 2

        .DestinationObjectName = "Phones$"

    End With

    'Create an area code transform, and link it to source and destination columns.

    Set oTransform = oCustTask.Transformations. _

            New("DTSPump.DataPumpTransformMidString")

    With oTransform

        .Name = "AreaCodeTransform"

        .SourceColumns.AddColumn "phone", 1

        .DestinationColumns.AddColumn "AreaCode", 1

    End With

    'Define start and width for area code, and then link transform to task.

    Set oMidString = oTransform.TransformServer

    oMidString.CharacterStart = 1

    oMidString.CharacterCount = 3

    oCustTask.Transformations.Add oTransform

    'Create local numeric transform, and then link to source and destination columns.

    Set oTransform = oCustTask.Transformations. _

            New("DTSPump.DataPumpTransformMidString")

    With oTransform

        .Name = "LocalNumTransform"

        .SourceColumns.AddColumn "phone", 1

        .DestinationColumns.AddColumn "LocalNumber", 1

    End With

    'Define start and width for local number.

    Set oMidString = oTransform.TransformServer

    oMidString.CharacterStart = 5

    oMidString.CharacterCount = 8

    'Link transform to task and task to package. Then run the package.

    oCustTask.Transformations.Add oTransform

    oPackage.Tasks.Add oTask

    oPackage.Execute

End Sub

See Also

Adding DTS Column Objects

Adding DTS Transformations

DataDrivenQueryTask2 Object

DataPumpTask2 Object

DataPumpTransformLowerString Object

DataPumpTransformTrimString Object

DataPumpTransformUpperString Object

New (ID) Method

Transformation2 Object

Transformations Collection

TransformationSet Object

TransformFlags Property

TransformServer Property


DataPumpTransformReadFile Object

The DataPumpTransformReadFile object copies the contents of a file, the name of which is specified by a source column, to a destination column.

Data conversion is controlled by the OEMFile and UnicodeFile properties. If the file named by the source column contains the Unicode prefix bytes (hex FFFE), the file is assumed to be Unicode regardless of the value of UnicodeFile, and the prefix bytes are skipped.

Properties

ErrorIfFileNotFound Property	OEMFile Property
FilePath Property
Remarks

If the file name column contains a path, it can use either a drive letter or a universal naming convention (UNC) file specification. If no path is present, the FilePath property can be used to supply the path. However, FilePath is always used when it is nonempty, even when the file name column contains a path.

The New method of the Transformations collection of the DataPumpTask, DataDrivenQueryTask, and TransformationSet objects returns a reference to a Transformation2 object. The TransformServer property of the Transformation2 object returns a reference to the appropriate custom transformation object.

Example

This example Microsoft® Visual Basic® program transforms a column in a Microsoft Excel sheet to a database column using the Read File custom transformation. Column file_name (row 1 of the column contains the label "file_name") of worksheet FileSpecTwo in D:\DTS_UE\Source\FileSpecs.xls contains the file names. The transformation writes the file data to column file_data in table FileDataOut in database DTS_UE on the local server:

Public Sub Main()

'Read file names from Excel worksheet. Write file data to database column.

    Dim oPackage    As DTS.Package

    Dim oConnect    As DTS.Connection

    Dim oStep       As DTS.Step

    Dim oTask       As DTS.Task

    Dim oCustTask   As DTS.DataPumpTask

    Dim oTransform  As DTS.Transformation

    Dim oColumn     As DTS.Column

    Dim oReadFile   As DTSPump.DataPumpTransformReadFile

    Set oPackage = New DTS.Package

    oPackage.FailOnError = True

    'Establish connection to source Excel worksheet.

    Set oConnect = oPackage.Connections.New("Microsoft.Jet.OLEDB.4.0")

    With oConnect

        .ID = 1

        .DataSource = "D:\DTS_UE\Source\FileSpecs.xls"

        .ConnectionProperties("Extended Properties") = _

                                "Excel 8.0;HDR=YES;"

    End With

    oPackage.Connections.Add oConnect

    'Establish connection to the destination server.

    Set oConnect = oPackage.Connections.New("SQLOLEDB.1")

    With oConnect

        .ID = 2

        .DataSource = "(local)"

        .UseTrustedConnection = True

    End With

    oPackage.Connections.Add oConnect

    'Create the step and task, and link the step to the task

    Set oStep = oPackage.Steps.New

    oStep.Name = "ReadFileStep"

    Set oTask = oPackage.Tasks.New("DTSDataPumpTask")

    Set oCustTask = oTask.CustomTask

    oCustTask.Name = "ReadFileTask"

    oStep.TaskName = oCustTask.Name

    oPackage.Steps.Add oStep

    'Link the task to the connections, and specify worksheet, database and table.

    With oCustTask

        .SourceConnectionID = 1

        .SourceObjectName = "FileSpecTwo$"

        .DestinationConnectionID = 2

        .DestinationObjectName = "DTS_UE..FileDataOut"

    End With

    'Create transform, and link it to the source and destination columns.

    Set oTransform = oCustTask.Transformations. _

            New("DTSPump.DataPumpTransformReadFile")

    oTransform.Name = "ReadFileTransform"

    Set oColumn = oTransform.SourceColumns.New("file_name", 1)

    oTransform.SourceColumns.Add oColumn

    Set oColumn = oTransform.DestinationColumns. _

            New("file_data", 1)

    oTransform.DestinationColumns.Add oColumn

    'Define error action and path prefix.

    Set oReadFile = oTransform.TransformServer

    oReadFile.ErrorIfFileNotFound = False

    oReadFile.FilePath = "D:\DTS_UE"

    'Link transform to task and task to package. Then run the package.

    oCustTask.Transformations.Add oTransform

    oPackage.Tasks.Add oTask

    oPackage.Execute

End Sub

See Also

Adding DTS Column Objects

Adding DTS Transformations

DataDrivenQueryTask2 Object

DataPumpTask2 Object

New (ID) Method

Transformation2 Object

Transformations Collection

TransformationSet Object

TransformServer Property


DataPumpTransformScript Object

The DataPumpTransformScript object transforms source columns and moves data to the destination columns using a Microsoft® ActiveX® script. Columns can be transformed in any way supported by the scripting language. The driver for the specific ActiveX scripting language must be installed.

The DataPumpTransformScript object supports properties that are used to specify the script text, scripting language, and entry point name.

Properties

FunctionEntry Property	Text Property
Language Property
Remarks

Valid script languages available on a particular system can be determined by enumerating the ScriptingLanguageInfos collection of the Application object. For more information about the scripting language appropriate for use with Data Transformation Services (DTS), see ScriptingLanguageInfo Object.

The DataPumpTransformScript object is compatible with Microsoft SQL Server™ version 7.0. For more information about an extended version of this object, see DTSTransformScriptProperties2 Object.

See Also

Adding DTS ActiveX Scripts

Adding DTS Column Objects

Adding DTS Transformations

Application Object

DTS Scripting Reference

ScriptingLanguageInfos Collection


DataPumpTransformTrimString Object

The DataPumpTransformTrimString object converts the source column to uppercase or lowercase characters, as specified by the UpperCaseString and LowerCaseString properties. It trims white-space characters, as specified by the TrimLeadingWhiteSpace, TrimTrailingWhiteSpace and TrimEmbeddedWhiteSpace properties. It converts, if necessary, to the destination column data type. It requires one source column and one destination column, both of a string data type (char, varchar, text, nchar, nvarchar, ntext, and flat file strings).

Destination truncation is possible by setting DTSTransformFlag_AllowStringTruncation in the TransformFlags property of the Transformation object.

Properties

LowerCaseString Property	TrimTrailingWhiteSpace Property
TrimEmbeddedWhiteSpace Property	UpperCaseString Property
TrimLeadingWhiteSpace Property
Remarks

The DataPumpTransformMidString object also performs case changing and white space removal functions. If only case conversion is required, the DataPumpTransformLowerString or DataPumpTransformUpperString objects can be used. These transformations accept multiple source and destination columns.

The New method of the Transformations collection of the DataPumpTask, DataDrivenQueryTask, and TransformationSet objects returns a reference to a Transformation2 object. The TransformServer property of the Transformation2 object returns a reference to the appropriate custom transformation object.

See Also

Adding DTS Column Objects

Adding DTS Transformations

DataDrivenQueryTask2 Object

DataPumpTask2 Object

DataPumpTransformLowerString Object

DataPumpTransformMidString Object

DataPumpTransformUpperString Object

New (ID) Method

Transformation2 Object

Transformations Collection

TransformationSet Object

TransformFlags Property

TransformServer Property


DataPumpTransformUpperString Object

The DataPumpTransformUpperString object converts a source column to uppercase characters and, if necessary, to the destination column data type. It requires source and destination columns to be of string data types (char, varchar, text, nchar, nvarchar, ntext, and flat file strings). Like the DataPumpTransformCopy object, this transformation object supports multiple source and destination columns. Destination truncation is possible by setting DTSTransformFlag_AllowStringTruncation in the TransformFlags property of the Transformation2 object. There are no custom transformation properties.

Remarks

Conversion to uppercase characters is also a feature of the DataPumpTransformTrimString and DataPumpTransformMidString objects.

For more information, see DataPumpTransformLowerString Object. The DataPumpTransformUpperString object is used the same way as the DataPumpTransformLowerString object in the example in that section, except that it is created as follows:

    Set oTransform = oCustTask.Transformations. _

            New("DTSPump.DataPumpTransformUpperString")

See Also

Adding DTS Column Objects

Adding DTS Transformations

DataPumpTransformCopy Object

DataPumpTransformMidString Object

DataPumpTransformTrimString Object

Transformation2 Object

TransformFlags Property


DataPumpTransformWriteFile Object

The DataPumpTransformWriteFile object converts a field from one source column into a file, the path of which is specified by another source column. Columns in the destination connection of the task are not written, although the connection must exist.

Data conversion is controlled by the OEMFile and UnicodeFile properties. If UnicodeFile is set to TRUE, the Unicode file header (hex FFFE) is prepended to the file, if it is not already there. The default behavior is to overwrite the destination file if it exists already.

Properties

AppendIfFileExists Property	FilePath Property
ErrorIfFileExists Property	OEMFile Property
FileColumnName Property
Remarks

The data column must be a string or binary data type. If it is NULL, no file is written. If AppendIfFileExists is set to FALSE and the file exists, it is deleted. If the file is empty, a zero-length file is created. The file name column cannot be NULL or empty. If the file name column contains a path, it can use either a drive letter or a universal naming convention (UNC) file specification.

If no path is present, the FilePath property can be used to supply the path. However, FilePath is always used when it is nonempty, even when the file name column contains a path.

This transformation object does not write destination columns, but a destination connection must still be provided. If no other transformations write columns, no rows are written.

You must explicitly add the source columns to the SourceColumns collection, even if the source connection has only two columns. If you do not add the columns, the transformation assumes you are including all the source and destination columns. This causes an error because the transformation cannot reference destination columns.

The New method of the Transformations collection of the DataPumpTask, DataDrivenQueryTask and TransformationSet objects returns a reference to a Transformation2 object. The TransformServer property of the Transformation2 object returns a reference to the appropriate custom transformation object.

Example

This example Microsoft® Visual Basic® program transforms a database column to written flat files with a Write File custom transformation. In table WriteFileData in database DTS_UE, column file_spec provides the file names, and file_data provides the data.

Public Sub Main()

'Write the data in DTS_UE. WriteFileData to specified files.

    Dim oPackage    As DTS.Package

    Dim oConnect    As DTS.Connection

    Dim oStep       As DTS.Step

    Dim oTask       As DTS.Task

    Dim oCustTask   As DTS.DataPumpTask

    Dim oTransform  As DTS.Transformation

    Dim oColumn     As DTS.Column

    Dim oWriteFile  As DTSPump.DataPumpTransformWriteFile

    Set oPackage = New DTS.Package

    oPackage.FailOnError = True

    'Establish a connection to the source server.

    Set oConnect = oPackage.Connections.New("SQLOLEDB.1")

    With oConnect

        .ID = 1

        .DataSource = "(local)"

        .UseTrustedConnection = True

    End With

    oPackage.Connections.Add oConnect

    'Establish connection to the (dummy) destination server.

    Set oConnect = oPackage.Connections.New("SQLOLEDB.1")

    With oConnect

        .ID = 2

        .DataSource = "(local)"

        .UseTrustedConnection = True

    End With

    oPackage.Connections.Add oConnect

    'Create a step and task, and then link the step to the task.

    Set oStep = oPackage.Steps.New

    oStep.Name = "WriteFileStep"

    Set oTask = oPackage.Tasks.New("DTSDataPumpTask")

    Set oCustTask = oTask.CustomTask

    oCustTask.Name = "WriteFileTask"

    oStep.TaskName = oCustTask.Name

    oPackage.Steps.Add oStep

    'Link the task to the connections, and specify tables.

    With oCustTask

        .SourceConnectionID = 1

        .SourceObjectName = "DTS_UE.dbo.WriteFileData"

        .DestinationConnectionID = 2

        .DestinationObjectName = "DTS_UE.dbo.WriteFileData"

    End With

    'Create transform, and link it to source columns.

    Set oTransform = oCustTask.Transformations. _

            New("DTSPump.DataPumpTransformWriteFile")

    With oTransform

        .Name = "WriteFileTransform"

        .SourceColumns.AddColumn "file_spec", 1

        .SourceColumns.AddColumn "file_data", 2

    End With

    'Define error action and path prefix.

    Set oWriteFile = oTransform.TransformServer

    With oWriteFile

        .ErrorIfFileExists = False

        .FileColumnName = "file_spec"

        .AppendIfFileExists = True

        .FilePath = "D:\DTS_UE"

    End With

    'Link transform to the task, the task to the package, and run the package.

    oCustTask.Transformations.Add oTransform

    oPackage.Tasks.Add oTask

    oPackage.Execute

End Sub

See Also

Adding DTS Column Objects

Adding DTS Transformations

DataDrivenQueryTask2 Object

DataPumpTask2 Object

New (ID) Method

Transformation2 Object

Transformations Collection

TransformationSet Object

TransformServer Property


DTSTransformScriptProperties2 Object

The DTSTransformScriptProperties2 object transforms source columns and moves data to the destination columns using a Microsoft® ActiveX® script. Columns can be transformed in any way supported by the scripting language being used.

Extended Properties

BatchCompleteFunctionEntry Property	PreSourceDataFunctionEntry Property
InsertFailureFunctionEntry Property	PumpCompleteFunctionEntry Property
InsertSuccessFunctionEntry Property	TransformFailureFunctionEntry Property
PostSourceDataFunctionEntry Property
Remarks

The DTSTransformScriptProperties2 object extends the functionality of the DataPumpTransformScript and inherits the properties and methods of that object. In addition, the extended object supports multiple transformation phases and adds properties to specify the script function entry point for each supported phase.

The following table specifies the transformation phases and the property that specifies the entry point for the phase. For a phase to be supported by a DTSTransformScriptProperties2 object, the function entry point must be specified, and the phase must be specified using the TransformPhases property of the Transformation2 object.

Phase	Description	Entry Point Property
PreSourceData	Occurs before first row is fetched from source connection.	PreSourceDataFunctionEntry
Transform	Occurs after each source row is fetched and before the destination row is written.	FunctionEntry
OnTransformFailure	Occurs after a failure in the Transform phase, indicated by the return of DTSTransformStat_Error or DTSTransformStat_ExceptionRow. Typically this failure is caused by conversion errors.	TransformFailureFunctionEntry
OnInsertSuccess	Occurs after each data row is written successfully to the destination connection.	InsertSuccessFunctionEntry
OnInsertFailure	Occurs after each attempt to write a data row to the destination connection fails (for example, by attempting to write a duplicate value to a primary key field, or a NULL to a NOT NULL field).	InsertFailureFunctionEntry
OnBatchComplete	Occurs in DataPumpTask2 when using the FastLoad option after each batch is written, successfully or unsuccessfully.	BatchCompleteFunctionEntry
PostSourceData	Occurs after the last row is written to the destination connection.	PostSourceDataFunctionEntry
OnPumpComplete	Occurs at the end of the execution of the task.	PumpCompleteFunctionEntry
To create the DTSTransformScriptProperties2 object, declare an object variable or pointer of type DTSTransformScriptProperties2, but use the ProgID of the DataPumpTransformScript object as the parameter for the New method of the Transformations collection. The following Microsoft Visual Basic® code illustrates this:

    Dim objCustTask     As DTS.DataPumpTask2

    Dim objTransform    As DTS.Transformation2

    Dim objTranScript   As DTSPump.DTSTransformScriptProperties2

. . .

    Set objTransform = _

        objCustTask.Transformations.New("DTSPump.DataPumpTransformScript")

    Set objTranScript = objTransform.TransformServer

For more information about when to use the DataPumpTransformScript object instead of the DTSTransformScriptProperties2 object, see Extended DTS Objects.

Example

The following Visual Basic program uses multiphased transformations to insert data into a table and correct certain errors.

The data source is a table named Transactions in a database named DailyRuns. The following is the definition of Transactions:

CREATE TABLE dbo.Transactions (

CustID INT PRIMARY KEY ,

CustName VARCHAR (50) NULL ,

CustAddr VARCHAR (100) NULL ,

TransAmount VARCHAR (50) NOT NULL )

The data destination is two tables named Transactions and ErrorAmounts in a database named DataPerm. The following are the definitions of these tables:

CREATE TABLE dbo.Transactions (

CustID INT PRIMARY KEY ,

CustName VARCHAR (50) NOT NULL ,

CustAddr VARCHAR (50) NOT NULL ,

TransAmount MONEY NOT NULL ,

ErrorCount INT NOT NULL )

CREATE TABLE dbo.ErrorAmounts (

CustID INT NOT NULL ,

TransAmount VARCHAR (50) NOT NULL )

The example program inserts the data from DailyRuns..Transactions into DataPerm..Transactions and handles these error conditions:

•	If the CustName or CustAddr columns in the source contain Null values, they cannot be inserted into the corresponding columns in the destination, which are specified NOT NULL.

•	An error occurs if the TransAmount column in the source, which is varchar, cannot be converted to money.

•	An error occurs if the destination already contains a row that has the same value for the primary key CustID as the source row.

One or more of these errors can occur in a single source row.

The example uses a DataPumpTransformCopy transformation that supports the Transform phase. The transformation inserts rows from DailyRuns..Transactions into DataPerm..Transactions. A SourceSQLStatement provides an initial value for the ErrorCount column and correctly maps the data source to the destination table.

The example also uses a DTSTransformScriptProperties2 transformation that supports the OnTransformFailure, OnInsertFailure and PreSourceData phases. The transformation processes the errors described above. It contains these ActiveX script functions to support the transformation phases.

Script Function	Transformation Phase
TransformFailed	OnTransformFailure
InsertFailed	OnInsertFailure
InitializeGV	PreSourceData
The TransformFailed function determines if a conversion error to the money data type occurred. If it did, the function opens a Microsoft ActiveX Data Objects (ADO) recordset on the ErrorAmounts table and writes a record containing the CustID and TransAmount columns from the data source. It sets the destination columns TransAmount to 0.0 and ErrorCount to 1. It saves the current source row number in a global variable so the InsertFailed function can determine if TransformFailed found an error converting to money for the current row. If either of the source columns CustName or CustAddr are NULL, it sets the corresponding destination column to "<unknown>".

The InsertFailed function executes when a duplicate primary key error occurs. It opens an ADO recordset and queries for the existing record in the DataPerm..Transactions table. It updates the CustName and CustAddr columns only if the original values in the source row were not NULL. If the TransformFailed function found that an error converting to money occurred, InsertFailed increments the ErrorCount column. Otherwise it adds the TransAmount column from the source row to the TransAmount column of the existing record.

The InitializeGV function initializes the global variable that is used to determine if both a transform failure and an insert failure occurred on the same row.

For more information about these script functions and a view of them separated from their text string, see Phased Transformation Samples.

Note   Database operations using ADO from ActiveX scripts cannot be made to join the package transaction that DTS manages.

Building the Multiphased Example

This is the Visual Basic code for the multi-phased transformation example:

Public Sub Main()

'Copy DailyRuns..Transactions to DataPerm..Transactions.

    Dim objPackage      As DTS.Package2

    Dim objConnect      As DTS.Connection2

    Dim objStep         As DTS.Step2

    Dim objTask         As DTS.Task

    Dim objCustTask     As DTS.DataPumpTask2

    Dim objTransform    As DTS.Transformation2

    Dim objTranScript   As DTSPump.DTSTransformScriptProperties2

    Dim strVBS          As String       'Assemble VBScript text.

    Set objPackage = New DTS.Package

    objPackage.FailOnError = True

    'Establish connection to source server.

    Set objConnect = objPackage.Connections.New("SQLOLEDB")

    With objConnect

        .ID = 1

        .DataSource = "(local)"

        .UseTrustedConnection = True

    End With

    objPackage.Connections.Add objConnect

    'Establish connection to destination server.

    Set objConnect = objPackage.Connections.New("SQLOLEDB")

    With objConnect

        .ID = 2

        .DataSource = "(local)"

        .UseTrustedConnection = True

    End With

    objPackage.Connections.Add objConnect

    'Create step and task, and link step to task.

    Set objStep = objPackage.Steps.New

    objStep.Name = "CopyNValidateStep"

    Set objTask = objPackage.Tasks.New("DTSDataPumpTask")

    Set objCustTask = objTask.CustomTask

    objCustTask.Name = "CopyNValidateTask"

    objStep.TaskName = objCustTask.Name

    objPackage.Steps.Add objStep

    'Link task to connections.

    With objCustTask

        .SourceConnectionID = 1

        .SourceSQLStatement = _

            "SELECT CustID, CustName, CustAddr, TransAmount, 0 AS ErrorCount " & _

            "FROM DailyRuns..Transactions"

        .DestinationConnectionID = 2

        .DestinationObjectName = "[DataPerm].[dbo].[Transactions]"

        .UseFastLoad = False

        .MaximumErrorCount = 4

    End With

    'Create transform to copy source to destination data.

    Set objTransform = objCustTask.Transformations. _

            New("DTSPump.DataPumpTransformCopy")

    With objTransform

        .Name = "CopyData"

        .TransformPhases = DTSTransformPhase_Transform

        .TransformFlags = DTSTransformFlag_Default

    End With

    objCustTask.Transformations.Add objTransform

    'Create transform to handle error conditions.

    Set objTransform = objCustTask.Transformations. _

            New("DTSPump.DataPumpTransformScript")

    With objTransform

        .Name = "InsertFailure"

        .TransformPhases = DTSTransformPhase_OnInsertFailure + _

            DTSTransformPhase_OnTransformFailure + DTSTransformPhase_PreSourceData

        Set objTranScript = .TransformServer

    End With

    'Define the ActiveX script functions.

    With objTranScript

        .InsertFailureFunctionEntry = "InsertFailed"

        .TransformFailureFunctionEntry = "TransformFailed"

        .PreSourceDataFunctionEntry = "InitializeGV"

        .Language = "VBScript"

        strVBS = "Option Explicit" & vbCrLf

        strVBS = strVBS & "Function InsertFailed()" & vbCrLf

        strVBS = strVBS & "   Dim rstCustomers " & vbCrLf & "   Dim strConnect" & vbCrLf & "   Dim strQuery" & vbCrLf

        strVBS = strVBS & "   strConnect = ""Provider=SQLOLEDB;Data Source=(local);" & _

                         "Initial Catalog=DataPerm;User Id=sa;Password=; """ & vbCrLf

        strVBS = strVBS & "   strQuery = ""SELECT CustID, CustName, CustAddr, TransAmount, ErrorCount " & _

                         "FROM Transactions WHERE CustID = '""" & vbCrLf

        strVBS = strVBS & "   'open recordset" & vbCrLf

        strVBS = strVBS & "   Set rstCustomers = CreateObject(""ADODB.Recordset"")" & vbCrLf

        strVBS = strVBS & "   rstCustomers.LockType = 3                         'adLockOptimistic" & vbCrLf

        strVBS = strVBS & "   strQuery = strQuery & DTSSource(""CustID"").Value & ""'""" & vbCrLf

        strVBS = strVBS & "   rstCustomers.Open strQuery, strConnect, , , 1             'adCmdText" & vbCrLf

        strVBS = strVBS & "   If rstCustomers.EOF Then" & vbCrLf

        strVBS = strVBS & "      rstCustomers.AddNew" & vbCrLf

        strVBS = strVBS & "      rstCustomers(""CustID"") = DTSSource(""CustID"")" & vbCrLf

        strVBS = strVBS & "   End If" & vbCrLf

        strVBS = strVBS & "   If DTSSource(""CustName"") <> ""<unknown>"" Then" & vbCrLf

        strVBS = strVBS & "      rstCustomers(""CustName"") = DTSSource(""CustName"")" & vbCrLf

        strVBS = strVBS & "   End If" & vbCrLf

        strVBS = strVBS & "   If DTSSource(""CustAddr"") <> ""<unknown>"" Then" & vbCrLf

        strVBS = strVBS & "      rstCustomers(""CustAddr"") = DTSSource(""CustAddr"")" & vbCrLf

        strVBS = strVBS & "   End If" & vbCrLf

        strVBS = strVBS & "   If  CLng(DTSTransformPhaseInfo.CurrentSourceRow) <> (DTSGlobalVariables(""LastErrorRow"")) Then" & vbCrLf

        strVBS = strVBS & "      rstCustomers(""TransAmount"") = rstCustomers(""TransAmount"") + DTSSource(""TransAmount"")" & vbCrLf

        strVBS = strVBS & "   Else" & vbCrLf

        strVBS = strVBS & "      rstCustomers(""ErrorCount"") = rstCustomers(""ErrorCount"") + 1" & vbCrLf

        strVBS = strVBS & "   End If" & vbCrLf

        strVBS = strVBS & "   rstCustomers.Update" & vbCrLf

        strVBS = strVBS & "   rstCustomers.Close" & vbCrLf

        strVBS = strVBS & "   InsertFailed = DTSTransformStat_OK" & vbCrLf

        strVBS = strVBS & "End Function" & vbCrLf

        strVBS = strVBS & "Function TransformFailed()" & vbCrLf

        strVBS = strVBS & "   Dim rstErrors " & vbCrLf & "   Dim strConnect" & vbCrLf

        strVBS = strVBS & "   DTSDestination(""CustID"") = DTSSource(""CustID"")" & vbCrLf

        strVBS = strVBS & "   DTSDestination(""ErrorCount"") = 0 " & vbCrLf

        strVBS = strVBS & "   On Error Resume Next" & vbCrLf

        strVBS = strVBS & "   DTSDestination(""TransAmount"") = CCur(DTSSource(""TransAmount""))" & vbCrLf

        strVBS = strVBS & "   If Err.Number <> 0 Then " & vbCrLf

        strVBS = strVBS & "      On Error GoTo 0 " & vbCrLf

        strVBS = strVBS & "      strConnect = ""Provider=SQLOLEDB;Data Source=(local);" & _

                                "Initial Catalog=DataPerm;User Id=sa;Password=; """ & vbCrLf

        strVBS = strVBS & "      Set rstErrors = CreateObject(""ADODB.Recordset"")" & vbCrLf

        strVBS = strVBS & "      rstErrors.LockType = 3                         'adLockOptimistic" & vbCrLf

        strVBS = strVBS & "      rstErrors.Open ""ErrorAmounts"", strConnect, , , 2             'adCmdTable" & vbCrLf

        strVBS = strVBS & "      rstErrors.AddNew" & vbCrLf

        strVBS = strVBS & "      rstErrors(""CustID"") = DTSSource(""CustID"")" & vbCrLf

        strVBS = strVBS & "      rstErrors(""TransAmount"") = DTSSource(""TransAmount"")" & vbCrLf

        strVBS = strVBS & "      rstErrors.Update" & vbCrLf

        strVBS = strVBS & "      rstErrors.Close" & vbCrLf

        strVBS = strVBS & "      DTSDestination(""TransAmount"") = 0.0" & vbCrLf

        strVBS = strVBS & "      DTSDestination(""ErrorCount"") = 1" & vbCrLf

        strVBS = strVBS & "      DTSGlobalVariables(""LastErrorRow"") = CLng(DTSTransformPhaseInfo.CurrentSourceRow)" & vbCrLf

        strVBS = strVBS & "   End If" & vbCrLf

        strVBS = strVBS & "   On Error GoTo 0 " & vbCrLf

        strVBS = strVBS & "   If IsNull(DTSSource(""CustName"").Value) Then" & vbCrLf

        strVBS = strVBS & "      DTSDestination(""CustName"") = ""<unknown>""" & vbCrLf

        strVBS = strVBS & "   Else" & vbCrLf

        strVBS = strVBS & "      DTSDestination(""CustName"") = DTSSource(""CustName"")" & vbCrLf

        strVBS = strVBS & "   End If" & vbCrLf

        strVBS = strVBS & "   If IsNull(DTSSource(""CustAddr"")) Then" & vbCrLf

        strVBS = strVBS & "      DTSDestination(""CustAddr"") = ""<unknown>""" & vbCrLf

        strVBS = strVBS & "   Else" & vbCrLf

        strVBS = strVBS & "      DTSDestination(""CustAddr"") = DTSSource(""CustAddr"")" & vbCrLf

        strVBS = strVBS & "   End If" & vbCrLf

        strVBS = strVBS & "   TransformFailed = DTSTransformStat_OK" & vbCrLf

        strVBS = strVBS & "End Function" & vbCrLf

        strVBS = strVBS & "Function InitializeGV()" & vbCrLf

        strVBS = strVBS & "   DTSGlobalVariables(""LastErrorRow"") = CLng(DTSTransformPhaseInfo.CurrentSourceRow)" & vbCrLf

        strVBS = strVBS & "   InitializeGV = DTSTransformStat_OK" & vbCrLf

        strVBS = strVBS & "End Function" & vbCrLf

        .Text = strVBS

    End With

    objCustTask.Transformations.Add objTransform

    'Link task to package, run package.

    objPackage.Tasks.Add objTask

    objPackage.Execute

    Exit Sub

End Sub

See Also

Adding DTS ActiveX Scripts

Adding DTS Column Objects

Adding DTS Transformations

DTS Scripting Reference

New (ID) Method

SourceSQLStatement Property

Transformation2 Object

Transformations Collection

TransformPhases Property


Phased Transformation Samples

These Microsoft® Visual Basic® Scripting Edition (VBScript) functions support a Data Transformation Services (DTS) package program that uses multiphase transformations. For more information, see DTSTransformScriptProperties2 Object.

TransformFailed Function

If an error occurred converting to money, TransformFailed opens a Microsoft ActiveX® Data Objects (ADO) recordset on an error records table. Then it writes a record containing the primary key from the data source and the invalid money field. It sets destination columns to indicate the error occurred. It saves the current source row number in a global variable to indicate the conversion error occurred for the current row. If source columns are Null, it sets the corresponding destination column to "<unknown>".

Example

The following is the VBScript for the TransformFailed function:

Function TransformFailed()

'Called on transform failure, usually conversion error or Null -> NOT NULL error.

   Dim rstErrors

   Dim strConnect

   DTSDestination("CustID") = DTSSource("CustID")

   DTSDestination("ErrorCount") = 0

   'See if transaction amount conversion error occurred.

   On Error Resume Next

   DTSDestination("TransAmount") = CCur(DTSSource("TransAmount"))

   'Conversion error occurred. Write bad transaction amount to error table.

   If Err.Number <> 0 Then

      On Error GoTo 0

      strConnect = "Provider=SQLOLEDB;Data Source=(local);Initial Catalog=DataPerm;User Id=sa;Password=; "

      Set rstErrors = CreateObject("ADODB.Recordset")

      rstErrors.LockType = 3                         	'adLockOptimistic

      rstErrors.Open "ErrorAmounts", strConnect, , , 2  'adCmdTable

      rstErrors.AddNew

      rstErrors("CustID") = DTSSource("CustID")

      rstErrors("TransAmount") = DTSSource("TransAmount")

      rstErrors.Update

      rstErrors.Close

      'Indicate error in destination table, and flag that that transform error occurred in this row.

      DTSDestination("TransAmount") = 0.0

      DTSDestination("ErrorCount") = 1

      DTSGlobalVariables("LastErrorRow") = _

         CLng(DTSTransformPhaseInfo.CurrentSourceRow)

   End If

   On Error GoTo 0

   'If NULL is in Name or Address, write <unknown>. Otherwise update field.

   If IsNull(DTSSource("CustName").Value) Then

      DTSDestination("CustName") = "<unknown>"

   Else

      DTSDestination("CustName") = DTSSource("CustName")

   End If

   If IsNull(DTSSource("CustAddr")) Then

      DTSDestination("CustAddr") = "<unknown>"

   Else

      DTSDestination("CustAddr") = DTSSource("CustAddr")

   End If

   TransformFailed = DTSTransformStat_OK

End Function

InsertFailedFunction

InsertFailed executes when a duplicate primary key error occurs. It opens an ADO recordset and queries for the existing record in the destination table. It updates columns only if the original values in the source row had not been NULL. If an error converting to money had occurred, it increments an error column. Otherwise, the function adds the TransactionAmounts column from the source row to the corresponding column of the existing record.

Example

he following is the VBScript for the InsertFailed function:

Function InsertFailed()

'Called when insert fails, usually because the primary key is already present in destination.

   Dim rstCustomers

   Dim strConnect

   Dim strQuery

   'Open recordset on row already present in destination table.

   strConnect = "Provider=SQLOLEDB;Data Source=(local);Initial Catalog=DataPerm;User Id=sa;Password=; "

   strQuery = "SELECT CustID, CustName, CustAddr, TransAmount, ErrorCount FROM Transactions WHERE CustID = '"

   Set rstCustomers = CreateObject("ADODB.Recordset")

   strQuery = strQuery & DTSSource("CustID").Value & "'"

   rstCustomers.LockType = 3                         	'adLockOptimistic

   rstCustomers.Open strQuery, strConnect, , , 1        'adCmdText

   'Add new row if source primary key is not already present.

   If rstCustomers.EOF Then

      rstCustomers.AddNew

      rstCustomers("CustID") = DTSSource("CustID")

   End If

   'If name or address not NULL in source, update destination.

   If DTSSource("CustName") <> "<unknown>" Then

      rstCustomers("CustName") = DTSSource("CustName")

   End If

   If DTSSource("CustAddr") <> "<unknown>" Then

      rstCustomers("CustAddr") = DTSSource("CustAddr")

   End If

   'If no transform failure occurred, add to transaction amount.

   If  CLng(DTSTransformPhaseInfo.CurrentSourceRow) <> (DTSGlobalVariables("LastErrorRow")) Then

      rstCustomers("TransAmount") = rstCustomers("TransAmount") + DTSSource("TransAmount")

   'If transform failed in this row, increment error count.

   Else

      rstCustomers("ErrorCount") = rstCustomers("ErrorCount") + 1

   End If

   'Update and close recordset.

   rstCustomers.Update

   rstCustomers.Close

   InsertFailed = DTSTransformStat_OK

End Function

InitializeGV Function

InitializeGV initializes a global variable.

Example

The following is the VBScript for the InitializeGV function:

Function InitializeGV()

   'Write row 0 into transform error row indicator.

   DTSGlobalVariables("LastErrorRow") = _

      CLng(DTSTransformPhaseInfo.CurrentSourceRow)

   InitializeGV = DTSTransformStat_OK

End Function


Other Objects

This section describes the objects of the Microsoft® SQL Server™ 2000 Data Transformation Services (DTS) object model.

For more information about the task objects and transformation objects supplied with SQL Server 2000, see Task Objects and Transformation Objects.

Topic	Description
Application Object	Provides access to system properties and information about system components.
Column Object	Contains information about a source or destination column, or a data-driven query parameter.
Connection Object	Contains information about connections to OLE DB data sources.
Connection2 Object	Extends the functionality of the Connection object.
CustomTask Object	Allows developers to implement DTS custom tasks.
CustomTaskUI Object	Allows developers to implement a user interface for a custom task.
DTSMQMessage Object	Holds the definition of a DTSMessageQueueTask message to be sent.
DynamicPropertiesTaskAssignment Object	Holds the definition of a DTS object property for a DynamicPropertiesTask object.
GlobalVariable Object	Defines a DTS global variable.
GlobalVariable2 Object	Extends the functionality of the GlobalVariable object.
IDTSStdObject	Serves as the base object from which all other DTS objects are derived.
Lookup Object	Specifies named, parameterized query string.
OLEDBProperty Object	Specifies property to be set in an OLE DB service provider at run time.
OLEDBProperty2 Object	Extends the functionality of the OLEDBProperty object.
OLEDBProviderInfo Object	Supplies information about an OLE DB provider.
Package Object	Heads the hierarchy of objects.
Package2 Object	Extends the functionality of the Package object.
PackageInfo Object	Provides information about a DTS package in persistent storage.
PackageLineage Object	Provides the contents of a SQL Server 2000 Meta Data Services package lineage record.
PackageLog Object	Allows a custom task or task script to write task log records.
PackageLogRecord Object	Provides the contents of a package log record.
PackageRepository Object	Provides access to the DTS components on Meta Data Services.
PackageSQLServer Object	Provides access to the components on an instance of SQL Server.
PersistPropertyBag Object	Defines a persistent property storage interface for a custom task
PrecedenceConstraint Object	Limits when a DTS step can begin execution.
PropertiesProvider Object	Defines an object supplying a DTS Properties collection.
Property Object	Exposes the attributes of an object property.
PropertyBag Object	Defines a name-indexed container for property values.
SavedPackageInfo Object	Contains information about a package saved in a COM-structured storage file.
ScriptingLanguageInfo Object	Provides information about a Microsoft ActiveX® scripting language registered on the system.
Step Object	Controls the execution of a task in the package.
Step2 Object	Extends the functionality of the Step object.
StepLineage Object	Provides the contents of a step lineage record from Meta Data Services.
StepLogRecord Object	Provides the contents of a step log record from an instance of SQL Server.
Task Object	Defines a unit of work to be performed as part of a package.
TaskInfo Object	Provides information about a task class registered on the computer system.
TaskLogRecord Object	Provides the contents of a task log record from an instance of SQL Server.
Transformation Object	Contains information about the transformation class and the source and destination columns.
Transformation2 Object	Extends the functionality of the Transformation object.
TransformationInfo Object	Provides information about a registered DTS transformation class.
TransformationSet Object	Defines the transformations to be performed on a component of a hierarchical rowset.
See Also

Creating a DTS Package

Programming DTS Applications


Application Object

The Application object provides access to system properties and information about system components. It returns connections to Microsoft® SQL Server™ storage or to SQL Server 2000 Meta Data Services instances that contain Data Transformation Services (DTS) packages.

Collections

OLEDBProviderInfos Collection	TaskInfos Collection
Properties Collection	TransformationInfos Collection
ScriptingLanguageInfos Collection
Properties

DesignerSettings Property	Parent Property
JITDebug Property
Methods

GetPackageRepository Method	GetPackageSQLServer Method
Remarks

The Application object is not derived from another DTS component. Instead, it is created. For example, do this with the New operator in Microsoft Visual Basic®:

    Dim objDTSAppl      As DTS.Application

    . . .

    Set objDTSAppl = New DTS.Application

The system properties accessible through the Application object are:

•	Whether Phased Transformation features are visible in DTS Designer.

•	Whether script run-time errors cause the scripting debugger to be entered.

The system components about which information is accessible through the Application object are:

•	The set of OLE DB providers available on the system.

•	The scripting languages that can be used in ActiveX® Script tasks, ActiveX Script transformations, and step scripts.

•	The DTS tasks available on the system, including the tasks provided with SQL Server 2000 and custom tasks implemented by users and other vendors.

•	The DTS transformations available on the system, including the transformations provided with SQL Server 2000 and custom transformations implemented by users and other vendors.

Examples

For more information about the Application object and examples of its use, see Retrieving DTS System, Package and Log Data.


Column Object

The Column object contains information about a source or destination column, or a data driven query parameter. If no source or destination columns are specified for a transformation, then all columns are implied by default.

Collections

Properties Collection

Properties

ColumnID Property	NumericScale Property
DataType Property	Ordinal Property
Flags Property	Parent Property
Name Property	Precision Property
Nullable Property
See Also

Adding DTS Column Objects

Columns Collection

DeleteQueryColumns Property

DestinationColumnDefinitions Property

DestinationColumns Property

InsertQueryColumns Property

SourceColumns Property

UpdateQueryColumns Property

UserQueryColumns Property


Connection Object

The Connection object contains information about connections to data sources through OLE DB service providers. Connection objects allow connection pooling and reuse for connections within a package so that only one connection must be established for multiple steps or tasks.

Properties

Catalog Property	InUse Property
Connected Property	LastOwnerTaskName Property
ConnectImmediate Property	Name Property
ConnectionProperties Property	Parent Property
ConnectionTimeout Property	Password Property
DataSource Property	ProviderID Property
Description Property	Reusable Property
ID Property	UserID Property
InTransaction Property
Methods

AcquireConnection Method	ReleaseConnection Method
Remarks

The Connection object is compatible with Microsoft® SQL Server™ version 7.0. For more information about an extended version of this object, see Connection2 Object

See Also

Connections Collection

Creating DTS Package Objects and Connections


Connection2 Object

The Connection2 object contains information about connections to data sources through OLE DB service providers.

Extended Properties

UDLPath Property

Remarks

The Connection2 object extends the functionality of the Connection Object and inherits the properties and methods of that object. In addition, the UDLPath property is read/write, while it is read-only in the Connection object.

For more information about when to use the Connection object instead of the Connection2 object, see Extended DTS Objects.

See Also

Connection Object

Creating DTS Package Objects and Connections


CustomTask Object

The CustomTask object is an interface that all Data Transformation Services (DTS) tasks must implement. This allows programmers to create their own custom tasks, which can be controlled by the DTS package.

Collections

Properties Collection

Properties

Description Property	Name Property
Methods

Execute Method

Remarks

After inheriting from the CustomTask object, a DTS custom task must implement the following:

•	Description property

•	Execute method

•	Name property

•	Properties collection

To inherit from the CustomTask interface in Microsoft® Visual Basic®, the program references the interface with the Implements statement:

Implements  DTS.CustomTask

Then prototypes for the elements the custom task must implement can be selected from the Procedures/Events box in the code window in the Visual Basic integrated development environment (IDE), after selecting CustomTask from the Object Box.

DTS implements a default properties provider for the Properties collection if the user-supplied Property Get CustomTask_Properties(.) function returns Nothing.

To implement a user interface in a custom task, the program must also inherit from the CustomTaskUI interface.

See Also

CustomTaskUI Object


CustomTaskUI Object

The CustomTaskUI object is an interface that allows you to optionally specify a custom dialog box for a Data Transformation Services (DTS) custom task that can be used in DTS Designer. The CustomTaskUI interface is only used in conjunction with custom tasks. If the CustomTaskUI is not implemented, DTS Designer displays a default user interface for task properties in a simple grid format.

Methods

CreateCustomToolTip Method	Help Method
Delete Method	Initialize Method
Edit Method	New Method
GetUIInfo Method
Remarks

After inheriting from the CustomTaskUI interface, a custom task must implement the following:

•	CreateCustomToolTip method

•	Delete method

•	Edit method

•	GetUIInfo method

•	Help method

•	Initialize method

•	New method

Some of these methods can be placeholders that do nothing.

To inherit from the CustomTaskUI interface in Microsoft® Visual Basic®, the program references the interface with the Implements statement:

Implements  DTS.CustomTaskUI

Then prototypes for the elements the custom task must implement can be selected from the Procedures/Events Box in the code window in the Visual Basic integrated development environment (IDE), after selecting CustomTaskUI from the Object Box.

All DTS tasks must implement the CustomTask interface.

See Also

CustomTask Object


DTSMQMessage Object

The DTSMQMessage object holds the definition of a single message to be sent by a DTSMessageQueueTask object.

Collections

Properties Collection

Properties

MessageDataFile Property	MessageType Property
MessageGlobalVariables Property	UseTransaction Property
MessageString Property
Methods

Reset Method

Remarks

DTSMQMessage objects are used only to define the messages to be sent by a DTSMessageQueueTask object. The single message to be received by a receiving task is defined by the task properties.

See Also

DTSMQMessages Collection

DTSMessageQueueTask Object


DynamicPropertiesTaskAssignment Object

The DynamicPropertiesTaskAssignment object holds the definition of a single package object property to be modified by a Dynamic Properties Task object, and the source of the new property value.

Collections

Properties Collection

Properties

DestinationPropertyID Property	SourceIniFileKey Property
SourceConstantValue Property	SourceIniFileSection Property
SourceDataFileFileName Property	SourceQueryConnectionID Property
SourceEnvironmentVariable Property	SourceQuerySQL Property
SourceGlobalVariable Property	SourceType Property
SourceIniFileFileName Property
Methods

Reset Method

Remarks

One of the following sources for the new property value can be specified:

•	A constant

•	The contents of a data file

•	An environment variable

•	A Data Transformation Services (DTS) global variable

•	A field in an .ini file

•	An SQL query

See Also

DynamicPropertiesTask

DynamicPropertiesTaskAssignments Collection


GlobalVariable Object

The GlobalVariable object defines a variable that allows data to be shared across steps and Microsoft® ActiveX® scripts.

Collections

Properties Collection

Properties

Name Property	Value Property
Parent Property
Remarks

Global variables can be shared between Data Transformation Services (DTS) packages by using the ExecutePackageTask or DTSMessageQueueTask objects.

The GlobalVariable object is compatible with Microsoft® SQL Server™ version 7.0. For more information about an extended version of this object, see GlobalVariable2 Object.

See Also

Adding DTS Lookups and Global Variables

DTSMessageQueueTask Object

ExecutePackageTask Object

GlobalVariables Collection


GlobalVariable2 Object

The GlobalVariable2 object defines a variable that allows data to be shared across steps and Microsoft® ActiveX® scripts.

Extended Methods

Lock Method	Unlock Method
Remarks

The GlobalVariable2 object extends the functionality of the GlobalVariable Object and inherits the properties and methods of that object. In addition, the Lock and Unlock methods allow a task to acquire a GlobalVariable2 object for exclusive use and to later release it.

For more information about when to use the GlobalVariable object instead of the GlobalVariable2 object, see Extended DTS Objects.

See Also

Adding DTS Lookups and Global Variables

GlobalVariable Object

GlobalVariables Collection


IDTSStdObject

The IDTSStdObject is the base object from which all other Data Transformation Services (DTS) package objects are derived. It has no properties, methods, or events.

See Also

Parent Property


Lookup Object

The Lookup object allows a data pump consumer, for example a DataDrivenQueryTask2, DataPumpTask2 or ParallelDataPumpTask object, to specify one or more named, parameterized query strings that allow a transformation to retrieve data from locations other than the row being transformed. For example, a Lookup object might reference data in a Microsoft® Excel worksheet.

Collections

Properties Collection

Properties

ConnectionID Property	Parent Property
MaxCacheRows Property	Query Property
Name Property
See Also

Adding DTS Lookups and Global Variables

DataDrivenQueryTask2 Object

DataPumpTask2 Object

Lookups Collection

ParallelDataPumpTask Object


OLEDBProperty Object

OLEDBProperty objects are used by the Connection object to specify properties of sessions and rowsets to be set in the OLE DB service provider at run time. These properties are set automatically by the Data Transformation Services (DTS) package at run time. Connection properties of each OLE DB service provider can also be set this way.

Collections

Properties Collection

Properties

Name Property	PropertySet Property
Parent Property	Value Property
PropertyID Property
Remarks

The OLEDBProperty object is compatible with Microsoft® SQL Server™ version 7.0. For more information about an extended version of this object, see OLEDBProperty2 Object.

See Also

CommandProperties Property

ConnectionProperties Property

Creating DTS Package Objects and Connections

DestinationCommandProperties Property

OLEDBProperties Collection

SourceCommandProperties Property


OLEDBProperty2 Object

OLEDBProperty2 objects are used by the Connection object to specify properties of sessions and rowsets to be set in the OLE DB service provider at run-time.

Extended Properties

IsDefaultValue Property

Remarks

The OLEDBProperty2 object extends the functionality of the OLEDBProperty object and inherits the properties and methods of that object. In addition, the IsDefaultValue property indicates whether the value of the OLEDBProperty2 object has been explicitly set to a value other than the code for "restore default value".

For more information about when to use the OLEDBProperty object instead of the OLEDBProperty2 object, see Extended DTS Objects.

See Also

CommandProperties Property

ConnectionProperties Property

Creating DTS Package Objects and Connections

DestinationCommandProperties Property

OLEDBProperty Object

OLEDBProperties Collection

SourceCommandProperties Property


OLEDBProviderInfo Object

The OLEDBProviderInfo object provides information about an OLE DB provider that is registered on the computer system.

Properties

ClassID Property	Name Property
Description Property	Parent Property
ImplementationFileName Property	ParseName Property
ImplementationFileVersionString Property
Remarks

Access the OLEDBProviderInfo objects by creating the Data Transformation Services (DTS) Application object and iterating through the OLEDBProviderInfos collection.

See Also

Application Object

OLEDBProviderInfos Collection

Retrieving DTS System, Package and Log Data


Package Object

The Package object is the main transformation-defining object from which all other objects stem.

Collections

Connections Collection	Steps Collection
GlobalVariables Collection	Tasks Collection
Properties Collection
Properties

AutoCommitTransaction Property	PackageID Property
CreationDate Property	PackagePriorityClass Property
CreatorComputerName Property	Parent Property
CreatorName Property	RepositoryMetadataOptions Property
Description Property	TransactionIsolationLevel Property
FailOnError Property	UseOLEDBServiceComponents Property
LineageOptions Property	UseTransaction Property
LogFileName Property	VersionID Property
MaxConcurrentSteps Property	WriteCompletionStatusToNTEventLog Property
Name Property
Methods

Execute Method	RemoveFromRepository Method
GetDTSVersionInfo Method	RemoveFromSQLServer Method
GetLastExecutionLineage Method	SaveAs Method
GetSavedPackageInfos Method	SaveToRepository Method
LoadFromRepository Method	SaveToSQLServer Method
LoadFromSQLServer Method	SaveToStorageFile Method
LoadFromStorageFile Method
Events

OnError Event	OnQueryCancel Event
OnFinish Event	OnStart Event
OnProgress Event
Remarks

The Package object is compatible with Microsoft® SQL Server™ version 7.0. For more information about an extended version of this object, see Package2 Object.

See Also

Creating DTS Package Objects and Connections


Package2 Object

The Package2 object is the parent object of a Data Transformation Services (DTS) package. Most of the new properties support logging to the msdb database of a specified instance of Microsoft® SQL Server™.

Extended Properties

ExplicitGlobalVariables Property	LogServerUserName Property
FailPackageOnLogFailure Property	LogToSQLServer Property
LogServerFlags Property	NestedExecutionLevel Property
LogServerName Property	PackageType Property
LogServerPassword Property
Extended Methods

SaveToRepositoryAs Method	SaveToStorageFileAs Method
SaveToSQLServerAs Method
Remarks

The Package2 object extends the functionality of the existing Package object and inherits the properties and methods of that object. In addition, several extended methods and properties have been added.

The ExplicitGlobalVariables property inhibits automatic creation of global variables on first reference. The NestedExecutionLevel property helps detect uncontrolled recursive package execution through the ExecutePackageTask object. The PackageType property provides information about the package creator.

The LogToSQLServer, LogServerFlags, LogServerName, LogServerPassword, LogServerUserName, and FailPackageOnLogFailure properties enable logging to an instance of SQL Server, identify the server, and provide authentication information.

The SaveToRepositoryAs, SaveToSQLServerAs, and SaveToStorageFileAs methods assign a new name and package ID to a Package2 object, and then save it to the specified persistent storage.

Note   In SQL Server 2000, if a Package2 object variable is declared, WithEvents, event handlers should be provided for all of the Package events, and the ExecuteInMainThread property should be set to TRUE for all steps.

From within ActiveX® scripts, use DTSGlobalVariables.Parent to reference the Package2 object. From the Package2 object, you can reference any other object in the hierarchy.

For more information about when to use the Package object instead of the Package2 object, see Extended DTS Objects.

See Also

Creating DTS Package Objects and Connections

Package Object


PackageInfo Object

The PackageInfo object provides information about a package stored in Microsoft® SQL Server™ 2000 Meta Data Services or SQL Server storage.

Properties

CreationDate Property	PackageID Property
Description Property	PackageType Property
IsOwner Property	Parent Property
Name Property	Properties Collection
Owner Property	VersionID Property
PackageDataSize Property
Remarks

Access the PackageInfo objects by using the EnumPackageInfos method of the PackageRepository or PackageSQLServer objects and iterating through the PackageInfos collection the method returns.

See Also

EnumPackageInfos Method

PackageInfos Collection

PackageRepository Object

PackageSQLServer Object

Retrieving DTS System, Package and Log Data


PackageLineage Object

The PackageLineage object provides the contents of a package lineage record from Microsoft® SQL Server™ 2000 Meta Data Services. The record contains information about a Data Transformation Services (DTS) package execution hosted by Meta Data Services.

Properties

Computer Property	Operator Property
ExecutionDate Property	PackageID Property
LineageFullID Property	Parent Property
LineageShortID Property	Properties Collection
Name Property
Remarks

A package lineage record is written each time a package stored in Meta Data Services is executed, if the package LineageOptions property specifies this be done.

Access the PackageLineage objects by using the EnumPackageLineages method of the PackageRepository object and iterating through the PackageLineages collection the method returns.

See Also

EnumPackageLineages Method

LineageOptions Property

PackageLineages Collection

PackageRepository Object

Retrieving DTS System, Package and Log Data


PackageLog Object

The PackageLog object allows a Data Transformation Services (DTS) custom task or ActiveScriptTask object to write task log records in the database or write log messages to the log file.

Methods

WriteStringToLog Method	WriteTaskRecord Method
Remarks

The reference to the PackageLog object is a parameter of the task Execute method, which you implement in a custom task, and thus have access. It is also available in task Microsoft® ActiveX® scripts, through the DTSPackageLog object.

See Also

EnumTaskLogRecords Method

Execute Method

PackageLogRecords Collection

Retrieving DTS System, Package and Log Data


PackageLogRecord Object

The PackageLogRecord object provides the contents of a package log record from an instance of Microsoft® SQL Server™. The log record contains information about a package execution.

Properties

Computer Property	LogDate Property
Description Property	Name Property
ErrorCode Property	Operator Property
ErrorDescription Property	PackageID Property
ExecutionTime Property	Parent Property
FinishTime Property	Properties Collection
LineageFullID Property	StartTime Property
LineageShortID Property
Remarks

A package log record is written to the msdb database on the server specified by the package LogServerName property each time a Data Transformation Services (DTS) package is executed, if the package LogToSQLServer property has been set.

Access the PackageLogRecord objects by using the EnumPackageLogRecords method of the PackageSQLServer object and iterating through the PackageLogRecords collection the method returns.

See Also

EnumPackageLogRecords Method

LogServerName Property

LogToSQLServer Property

PackageLogRecords Collection

PackageSQLServer Object

Retrieving DTS System, Package and Log Data


PackageRepository Object

The PackageRepository object provides access to the Data Transformation Services (DTS) components hosted by an instance of Microsoft® SQL Server™ 2000 Meta Data Services. Through methods of this object, you can obtain information about the DTS packages stored in Meta Data Services and access the contents of the package and step lineage data for these packages.

Properties

Name Property	Properties Collection
Parent Property
Methods

EnumPackageInfos Method	EnumStepLineages Method
EnumPackageLineages Method
Remarks

A package lineage record is written each time a package stored in Meta Data Services is executed, if the package LineageOptions property specifies this to be done.

Access the PackageRepository object by using the GetPackageRepository method of the Application object. Provide the necessary login information to access the instance of SQL Server that hosts the desired Meta Data Services instance.

See Also

Application Object

GetPackageRepository Method

Retrieving DTS System, Package and Log Data


PackageSQLServer Object

The PackageSQLServer object provides access to the Data Transformation Services (DTS) components hosted by an instance of Microsoft® SQL Server™. Through methods of this object, you can obtain information about the DTS packages stored in SQL Server storage and access the contents of the package, step, and task log records stored on that server.

Properties

Name Property	Properties Collection
Parent Property
Methods

EnumPackageInfos Method	RemoveAllLogRecords Method
EnumPackageLogRecords Method	RemovePackageLogRecords Method
EnumStepLogRecords Method	RemoveStepLogRecords Method
EnumTaskLogRecords Method
Remarks

Access the PackageSQLServer object by using the GetPackageSQLServer method of the Application object. Provide the necessary login information to access the instance of SQL Server you want.

See Also

Application Object

GetPackageSQLServer Method

Retrieving DTS System, Package and Log Data


PersistPropertyBag Object

The PersistPropertyBag object defines a persistent property storage interface for an object implementing a Data Transformation Services (DTS) custom task. The PropertyBag object is a name-indexed container object for object properties. When implemented, the PropertyBag and PersistPropertyBag objects allow simple object property handling.

Methods

Load Method	Save Method
Remarks

DTS provides these options for custom task object property storage. You can:

•	Do nothing. DTS will save and load properties when Package object store and retrieve methods are called. The object can, optionally, implement a PropertiesProvider object to expose its properties as a DTS Properties collection.

•	Implement a PersistPropertyBag object.

•	If using Microsoft® Visual C++®, implement the IPersistStorage interface on the custom task object.

If implemented, DTS will call the PersistPropertyBag object Load method when a Package retrieving method is called. The Save method is called when a Package method storing a package is called.

See Also

PropertyBag Object


PrecedenceConstraint Object

The PrecedenceConstraint object contains information about a condition that must occur before a Data Transformation Services (DTS) step can be released for execution. The PrecedenceConstraint objects of all the package steps control the order in which steps are executed.

Collections

Properties Collection

Properties

Parent Property	StepName Property
PrecedenceBasis Property
See Also

Creating DTS Package Workflow and Tasks

PrecedenceConstraints Collection


PropertiesProvider Object

The PropertiesProvider object defines an object supplying a Data Transformation Services (DTS) Properties collection. When exposed, DTS will retrieve the Properties collection as required.

Methods

GetPropertiesForObject Method

See Also

CustomTask Object

Properties Collection


Property Object

The Property object exposes the attributes of a Data Transformation Services (DTS) object property.

Most DTS objects have Properties collections, which contain a Property object for each property the object has. By referencing the Properties collection, a user of the object can determine whether the object supports a particular property without causing a program error if it does not.

Collections

Properties Collection

Properties

Get Property	Set Property
Name Property	Type Property
Parent Property
Remarks

Development environments, such as Microsoft® Visual Basic®, typically provide syntax completion and other development aids. Because it exposes the attributes of object properties, the Property object supports such automated developer assistance.

Note   The Property object is implemented for automation controllers. Microsoft Visual C++® DTS applications have no direct access to the Property object.

See Also

TransformServerProperties Property


PropertyBag Object

The PropertyBag object defines a name-indexed container for property values for an object implementing a Data Transformation Services (DTS) custom task. Use the PropertyBag object as part of custom task object implementation when the custom task maintains storage for task properties.

DTS can read and write values of simple data types, such as String, in a PropertyBag object. DTS cannot support objects and other more complex data types as values in a PropertyBag container.

Methods

Read Method	Write Method
See Also

PersistPropertyBag Object


SavedPackageInfo Object

The SavedPackageInfo object contains information about packages that are saved in COM-structured storage files. This information is returned by the GetSavedPackageInfos method.

Properties

Description Property	PackageName Property
IsVersionEncrypted Property	VersionID Property
PackageCreationDate Property	VersionSaveDate Property
PackageID Property
See Also

GetSavedPackageInfos Method

Retrieving DTS System, Package and Log Data

SavedPackageInfos Collection


ScriptingLanguageInfo Object

The ScriptingLanguageInfo object provides information about a Microsoft® ActiveX® scripting language that is registered on the computer system.

Properties

ClassID Property	Name Property
Description Property	Parent Property
ImplementationFileName Property	Properties Collection
ImplementationFileVersionString Property
Remarks

Access the ScriptingLanguageInfo objects by creating the Data Transformation Services (DTS) Application object and iterating through the ScriptingLanguageInfos collection.

Typically, the available scripting languages will include the following.

Scripting Language	Name	Description
Microsoft JScript®	JScript	JScript Language
PerlScript	PerlScript	PerlScript Language
Microsoft Visual Basic® Scripting Edition (VBScript)	VBScript	VBScript Language
Extensible Markup Language	XML	XML Script Engine
The values in the Name and Description columns are the values that are returned by the Name and Description properties of the ScriptingLanguageInfo object. Use a value from the Name property to set the Language or ScriptLanguage property of scripting objects.

Note   Encoding versions of scripting languages, which may be installed on a computer system to support scripts embedded in Web pages, are not appropriate for use with DTS.

See Also

Application Object

Retrieving DTS System, Package and Log Data

ScriptingLanguageInfos Collection

ScriptLanguage PropertyLanguage Property


Step Object

The Step object controls the flow and execution of tasks within the Data Transformation Services (DTS) package. Each step is associated with a single task, although association with no task is possible. Step execution sequence is determined by the precedence constraints. A step cannot start execution until all its precedence constraints are satisfied.

Collections

PrecedenceConstraints Collection	Properties Collection
Properties

ActiveXScript Property	FunctionName Property
AddGlobalVariables Property	IsPackageDSORowset Property
CloseConnection Property	JoinTransactionIfPresent Property
CommitSuccess Property	Name Property
Description Property	Parent Property
DisableStep Property	RelativePriority Property
ExecuteInMainThread Property	RollbackFailure Property
ExecutionResult Property	ScriptLanguage Property
ExecutionStatus Property	StartTime Property
ExecutionTime Property	TaskName Property
FinishTime Property
Methods

Execute (Package) Method	GetExecutionErrorInfo Method
Remarks

The Step object is compatible with Microsoft® SQL Server™ version 7.0. For more information about an extended version of this object, see Step2 Object.

See Also

Creating DTS Package Workflow and Tasks

Steps Collection


Step2 Object

The Step2 object controls the flow and execution of tasks within the Data Transformation Services (DTS) package. Each step is associated with a single task, although association with no task is possible. Step execution sequence is determined by the precedence constraints. A step cannot start execution until all its precedence constraints are satisfied.

Extended Properties

FailPackageOnError Property

Remarks

The Step2 object extends the functionality of the Step Object and inherits the properties and methods of that object. In addition, the FailPackageOnError property causes the package to fail if the step fails.

For more information about when to use the Step object instead of the Step2 object, see Extended DTS Objects.

See Also

Creating DTS Package Workflow and Tasks

FailOnError Property

Step Object


StepLineage Object

The StepLineage object provides the contents of a step lineage record from Microsoft® SQL Server™ 2000 Meta Data Services. The record contains information about the execution of a step in a Data Transformation Services (DTS) package hosted by Meta Data Services.

Properties

ErrorCode Property	Name Property
ErrorDescription Property	Parent Property
ErrorHelpContext Property	Properties Collection
ErrorHelpFile Property	StartTime Property
ErrorSource Property	StepExecutionResult Property
ExecutionTime Property	StepExecutionStatus Property
FinishTime Property
Remarks

A step lineage record is written each time a step of a package stored in Meta Data Services is executed, if the package LineageOptions property specifies this to be done.

Access the StepLineage objects by using the EnumStepLineages method of the PackageRepository object and iterating through the StepLineages collection the method returns.

See Also

EnumStepLineages Method

LineageOptions Property

PackageRepository Object

Retrieving DTS System, Package and Log Data

StepLineages Collection


StepLogRecord Object

The StepLogRecord object provides the contents of a step log record from an instance of Microsoft® SQL Server™. The log record contains information about the execution of a step in a Data Transformation Services (DTS) package.

Properties

ErrorCode Property	Parent Property
ErrorDescription Property	ProgressCount Property
ExecutionTime Property	Properties Collection
FinishTime Property	StartTime Property
LineageFullID Property	StepExecutionID Property
Name Property	StepExecutionResult Property
Remarks

A step log record is written to the msdb database on the server specified by the package LogServerName property each time a step in a package is executed, if the package LogToSQLServer property has been set.

Access the StepLogRecord objects by using the EnumStepLogRecords method of the PackageSQLServer object and iterating through the StepLogRecords collection the method returns.

See Also

EnumStepLogRecords Method

LogServerName Property

LogToSQLServer Property

PackageSQLServer Object

Retrieving DTS System, Package and Log Data

StepLogRecords Collection


Task Object

The Task object defines a unit of work to be performed as part of a Data Transformation Services (DTS) package. A Task object is created in a package when the Tasks.New method is invoked with the program ID or class ID of the desired task class, followed by Tasks.Add.

Collections

Properties Collection

Properties

CustomTask Property	Name Property
CustomTaskID Property	Parent Property
Description Property
Methods

Execute Method

See Also

Creating DTS Package Workflow and Tasks

Tasks Collection


TaskInfo Object

The TaskInfo object provides information about a Data Transformation Services (DTS) task class that is registered on the computer system.

Properties

ClassID Property	ImplementationFileVersionString Property
Description Property	Name Property
IconFile Property	Parent Property
IconIndex Property	Properties Collection
ImplementationFileName Property
Remarks

The registered task classes include those provided with Microsoft® SQL Server™ 2000 and custom tasks provided by other vendors and implemented by users.

Access the TaskInfo objects by creating the DTS Application object and iterating through the TaskInfos collection.

See Also

Application Object

Retrieving DTS System, Package and Log Data

TaskInfos Collection


TaskLogRecord Object

The TaskLogRecord object provides the contents of a task log record from an instance of Microsoft® SQL Server™. The log record contains information about the execution of a task in a Data Transformation Services (DTS) package that has been implemented to write task log records.

Properties

ErrorCode Property	Properties Collection
ErrorDescription Property	SequenceID Property
Parent Property
Remarks

Task log records are not automatically written by the task classes supplied with SQL Server 2000, but the PackageLog interface is available so that a custom task or the script of an ActiveScriptTask object can write them. They are written to the msdb database on the server specified by the package LogServerName property each time a task in a package that has been implemented to write them is executed, if the package LogToSQLServer property has been set.

Access the TaskLogRecord objects by using the EnumTaskLogRecords method of the PackageSQLServer object and iterating through the TaskLogRecords collection the method returns.

See Also

ActiveScriptTask Object

EnumTaskLogRecords Method

LogServerName Property

LogToSQLServer Property

PackageSQLServer Object

Retrieving DTS System, Package and Log Data

TaskLogRecords Collection


Transformation Object

The generic Transformation object contains information about the class-specific transformation object and the source and destination columns it manipulates.

Collections

Properties Collection

Properties

DestinationColumns Property	SourceColumns Property
ForceBlobsInMemory Property	TransformFlags Property
ForceSourceBlobsBuffered Property	TransformServer Property
InMemoryBlobSize Property	TransformServerID Property
Name Property	TransformServerParameter Property
Parent Property
Remarks

The Transformation object is compatible with Microsoft® SQL Server™ version 7.0. For more information about an extended version of this object, see Transformation2 Object.

See Also

Adding DTS Transformations

Transformations Collection


Transformation2 Object

The generic Transformation2 object contains information about the class-specific transformation object and the source and destination columns it manipulates.

Extended Properties

TransformPhases Property

Remarks

The Transformation2 object extends the functionality of the Transformation object and inherits the properties and methods of that object. In addition, the TransformPhases property specifies which transform phases this transformation supports.

The Transformation2 object supports multiple transform phases, as shown in this table.

Phase	Description
PreSourceData	Occurs before first row is fetched from source connection.
Transform	Occurs after each source row is fetched, before the destination row is written.
OnTransformFailure	Occurs after a failure in the Transform phase, indicated by return of DTSTransformStat_Error or DTSTransformStat_ExceptionRow. Typically caused by conversion errors.
OnInsertSuccess	Occurs after each data row is written successfully to the destination connection.
OnInsertFailure	Occurs after each attempt to write a data row to the destination connection failed (for example, by attempting to write a duplicate value to a primary key field, or a NULL to a NOT NULL field).
OnBatchComplete	Occurs in DataPumpTask2 when using the FastLoad option after each batch is written, successfully or unsuccessfully.
PostSourceData	Occurs after the last row is written to the destination connection.
OnPumpComplete	Occurs at the end of the task's execution.
The Transformation object only supports the Transform phase.

Only the DTSTransformScriptProperties2 object and custom transformations can support phases other than the Transform phase.

For more information about when to use the Transformation object instead of the Transformation2 object, see Extended DTS Objects.

See Also

Adding DTS Transformations

DTSTransformScriptProperties2 Object

Transformation Object

Transformations Collection


TransformationInfo Object

The TransformationInfo object provides information about a Data Transformation Services (DTS) transformation class that is registered on the computer system.

Properties

ClassID Property	Name Property
Description Property	Parent Property
ImplementationFileName Property	Properties Collection
ImplementationFileVersionString Property
Remarks

The registered transformation classes include those provided with Microsoft® SQL Server™ 2000 and custom transformations provided by other vendors and implemented by users.

Access the TransformationInfo objects by creating the DTS Application object and iterating through the TransformationInfos collection.

See Also

Application Object

Retrieving DTS System, Package and Log Data

TransformationInfos Collection


TransformationSet Object

The TransformationSet object defines the transformations to be performed on the columns of a component rowset in a hierarchical rowset by the Parallel Data Pump Task object.

Collections

Lookups Collection	Transformations Collection
Properties Collection
Properties

DeleteQuery Property	InsertQueryColumns Property
DeleteQueryColumns Property	LastRow Property
Description Property	MaximumErrorCount Property
DestinationColumnDefinitions Property	Name Property
ExceptionFileColumnDelimiter Property	Parent Property
ExceptionFileName Property	ProgressRowCount Property
ExceptionFileOptions Property	RowsComplete Property
ExceptionFileRowDelimiter Property	RowsInError Property
ExceptionFileTextQualifier Property	UpdateQuery Property
FetchBufferSize Property	UpdateQueryColumns Property
FirstRow Property	UserQuery Property
InsertQuery Property
Remarks

The TransformationSet object includes a Transformations collection and contains all the information necessary to copy and transform a component rowset, such as data driven queries and their parameter collections, row and error counts, and exception file information.

The ordinal position of the TransformationSet object in the TransformationSets collection determines the component rowset to which the object is mapped. For more information about the mapping process, see TransformationSets Collection.

See Also

ParallelDataPumpTask Object


Collections

This section describes the collections of the Microsoft® SQL Server™ 2000 Data Transformation Services (DTS) object model. Collections contain groups of related DTS objects.

Topic	Description
Columns Collection	Contains descriptions of meta data for columns in a data source.
Connections Collection	Contains information about connections to OLE DB service providers.
DTSMQMessages Collection	Defines the messages to be sent by a DTSMessageQueueTask object.
DynamicPropertiesTaskAssignments Collection	Defines the properties to be changed by a DynamicPropertiesTask object.
GlobalVariables Collection	Contains information about data to be shared across DTS steps.
Lookups Collection	Defines query strings that allow data retrieval from other than the row being transformed.
OLEDBProperties Collection	Contains properties for an OLE DB service provider.
OLEDBProviderInfos Collection	Provides information about available OLE DB service providers.
PackageInfos Collection	Provides information about packages stored in SQL Server 2000 Meta Data Services or SQL Server storage.
PackageLineages Collection	Provides the contents of package lineage records from Meta Data Services.
PackageLogRecords Collection	Provides the contents of package log records from an instance of SQL Server.
PrecedenceConstraints Collection	Contains conditions that must occur before a step can execute.
Properties Collection	Contains a collection of properties for an object.
SavedPackageInfos Collection	Contains information about packages saved in files.
ScriptingLanguageInfos Collection	Provides information about Microsoft ActiveX® scripting languages available on the system.
StepLineages Collection	Provides the contents of step lineage records from Meta Data Services.
StepLogRecords Collection	Provides the contents of step log records from an instance of SQL Server.
Steps Collection	Contains information about the flow and execution of DTS tasks.
TaskInfos Collection	Provides information about the tasks available on the system.
TaskLogRecords Collection	Provides the contents of task log records from an instance of SQL Server.
Tasks Collection	Contains information about the tasks in a DTS package.
TransformationInfos Collection	Provides information about the DTS transformations available on the system.
Transformations Collection	Defines the transformations used by a task.
TransformationSets Collection	Defines the sets of transformations used to process components of a hierarchical rowset.


Columns Collection

A Columns collection is a group of Column objects containing a description of all available meta data about a column in a data source. This includes name, description, data type, precision, scale, nullability, and numeric base.

Properties

Count Property	Parent Property
Methods

Add Method	Item Method
AddColumn Method	New (Columns) Method
Insert Method
Remarks

Columns collections are referenced by the properties of the objects indicated in the table.

Property	Object
DestinationColumns Property SourceColumns Property	Transformation2
DeleteQueryColumns Property InsertQueryColumns Property UpdateQueryColumns Property UserQueryColumns Property	DataDrivenQueryTask2 TransformationSet
DestinationColumnDefinitions Property	DataDrivenQueryTask2 DataPumpTask2 TransformationSet
See Also

Adding DTS Column Objects

Column Object

DataDrivenQueryTask2 Object

DataPumpTask2 Object

Transformation2 Object

TransformationSet Object


Connections Collection

The Connections collection is a group of Connection objects containing information about connections to OLE DB service providers. This collection allows connection pooling and reuse across steps and tasks in a DTS package.

Applies To

Package Object	Package2 Object
Properties

Count Property	Parent Property
Methods

Add Method	Item Method
BeginAcquireMultipleConnections Method	New (ID) Method
EndAcquireMultipleConnections Method	NewDataLink Method
Insert Method
Remarks

When implementing a custom task that must acquire more than one connection, do the following to avoid deadlocks:

1.	Call BeginAcquireMultipleConnections.

2.	For each connection to be acquired:

•	Verify that connection.InUse is FALSE.

•	Call connection.AcquireConnection.

3.	Call EndAcquireMultipleConnections.

Prototype (C/C++)

HRESULT GetConnections(IDTSConnections **pRetVal);

See Also

Connection Object

Creating DTS Package Objects and Connections


DTSMQMessages Collection

The DTSMQMessages collection contains the DTSMQMessage objects that define the messages to be sent by a DTSMessageQueueTask object.

Applies To

DTSMessageQueueTask Object

Properties

Count Property

Methods

Add Method	New Method
Item Method
Remarks

The Messages method of a DTSMessageQueueTask object is used to get a reference to the DTSMQMessages collection.

See Also

DTSMQMessage Object

Messages Method


DynamicPropertiesTaskAssignments Collection

The DynamicPropertiesTaskAssignments collection contains the DynamicPropertiesTaskAssignment objects that define the source of the new value and the properties to be changed by a DynamicPropertiesTask object.

Applies To

DynamicPropertiesTask Object

Properties

Count Property

Methods

Add Method	New Method
Item Method
Remarks

The Assignments property of a DynamicPropertiesTask object is used to get a reference to the DynamicPropertiesTaskAssignments collection.

See Also

Assignments Property

DynamicPropertiesTaskAssignment Object


GlobalVariables Collection

The GlobalVariables collection is a group of GlobalVariable objects containing information about variants that allow data to be shared across steps and Microsoft® ActiveX® scripts.

Applies To

ExecutePackageTask Object	Package2 Object
Package Object
Properties

Count Property	Parent Property
Methods

Add Method	Item Method
AddGlobalVariable Method	New (Name) Method
Insert Method
Remarks

The GlobalVariables collection is dynamic; values may be added to the collection as the package executes. If the package ExplicitGlobalVariables property is not set, a global variable is created on first reference by an ActiveX script, if it does not already exist.

The GlobalVariables collection of the ExecutePackageTask object is exported to the target package, but it is not part of the parent package's GlobalVariables collection. To export global variables from the parent package to the target package, use the InputGlobalVariableNames property of the ExecutePackageTask object.

Reference the GlobalVariables collection from within ActiveX scripts with the name DTSGlobalVariables.

Prototype (C/C++)

HRESULT GetGlobalVariables(IDTSGlobalVariables **pRetVal);

See Also

Adding DTS Lookups and Global Variables

ExplicitGlobalVariables Property

GlobalVariable Object

InputGlobalVariableNames Property

Package2 Object


Lookups Collection

The Lookups collection is a group of Lookup object definitions. A Lookup object defines a named, parameterized query string that allows a transformation to retrieve data from a location other than the row being transformed.

Applies To

DataDrivenQueryTask Object	DataPumpTask2 Object
DataDrivenQueryTask2 Object	TransformationSet Object
DataPumpTask Object
Properties

Count Property	Parent Property
Methods

Add Method	Item Method
AddLookup Method	New (Name) Method
Insert Method
Remarks

In a Microsoft® ActiveX® script, the lookup should be referenced with the Execute method of an element of the DTSLookups collection. If the lookup rowset has more than one column, the Execute method returns a Variant array. The script may need to iterate through the array to use multiple values.

Prototype (C/C++)

HRESULT GetLookups(IDTSLookups **pRetVal);

See Also

Adding DTS Lookups and Global Variables

DTSDataPumpLookups Collection

Execute Method (Script)

Lookup Object


OLEDBProperties Collection

The OLEDBProperties collection is a group of OLEDBProperty objects containing information about an OLE DB service provider.

Properties

Count Property	Parent Property
Methods

Item Method

See Also

CommandProperties Property

ConnectionProperties Property

Creating DTS Package Objects and Connections

DestinationCommandProperties Property

OLEDBProperty Object

SourceCommandProperties Property


OLEDBProviderInfos Collection

The OLEDBProviderInfos collection contains OLEDBProviderInfo objects that provide information about each OLE DB provider available on the computer system.

Applies To

Application Object

Properties

Count Property	UseCache Property
Parent Property
Methods

Item Method	Refresh Method
Remarks

Obtain a reference to the OLEDBProviderInfos collection from the Application object.

You can iterate through the objects of the OLEDBProviderInfos collection using the Item method and Count property. However, it is faster to use For Each ... Next in Microsoft® Visual Basic®.

DTS maintains a cache, in the operating system registry, which holds the OLE DB provider information. If the UseCache property is TRUE, the cache is scanned, rather than all registered classes, when iterating through the OLEDBProviderInfos collection. Use the Refresh method to update the cache from the registered classes section of the system registry.

See Also

Application Object

Item Method

OLEDBProviderInfo Object

Refresh Method

Retrieving DTS System, Package and Log Data

UseCache Property


PackageInfos Collection

The PackageInfos collection contains PackageInfo objects that provide information about a DTS package stored in Microsoft® SQL Server™ 2000 Meta Data Services or SQL Server storage.

Properties

EOF Property

Methods

Next Method

Remarks

Use the EnumPackageInfos method of the PackageRepository or PackageSQLServer objects to return the PackageInfos collection.

Iterate through the objects of the PackageInfos collection by checking the EOF property after calling the Next method. If EOF is TRUE, Next will have returned Nothing and all the elements will have been fetched. You can also use For Each … Next in Microsoft Visual Basic®.

See Also

EnumPackageInfos Method

PackageInfo Object

PackageRepository Object

PackageSQLServer Object

Retrieving DTS System, Package and Log Data


PackageLineages Collection

The PackageLineages collection contains PackageLineage objects that provide the contents of package lineage records from Microsoft® SQL Server™ 2000 Meta Data Services. The records contain information about a DTS package execution hosted by Meta Data Services.

Properties

EOF Property

Methods

Next Method

Remarks

A package lineage record is written each time a package stored in Meta Data Services is executed, if the package LineageOptions property specifies this to be done.

Use the EnumPackageLineages method of the PackageRepository object to return the PackageLineages collection.

Iterate through the objects of the PackageLineages collection by checking the EOF property after calling the Next method. If EOF is TRUE, Next will have returned Nothing and all the elements will have been fetched. You can also use For Each … Next in Microsoft Visual Basic®.

See Also

EnumPackageLineages Method

LineageOptions Property

PackageLineage Object

PackageRepository Object

Retrieving DTS System, Package and Log Data


PackageLogRecords Collection

The PackageLogRecords collection contains PackageLogRecord objects that provide the contents of package log records from an instance of Microsoft® SQL Server™. The log records contain information about a DTS package execution.

Properties

EOF Property

Methods

Next Method

Remarks

A package log record is written to the msdb database on the server specified by the package LogServerName property each time a package is executed, if the package LogToSQLServer property has been set.

Use the EnumPackageLogRecords method of the PackageSQLServer object to return the PackageLogRecords collection.

Iterate through the objects of the PackageLogRecords collection by checking the EOF property after calling the Next method. If EOF is TRUE, Next will have returned Nothing and all the elements will have been fetched. You can also use For Each … Next in Microsoft Visual Basic®.

See Also

EnumPackageLogRecords Method

LogServerName Property

LogToSQLServer Property

PackageLogRecord Object

PackageSQLServer Object

Retrieving DTS System, Package and Log Data


PrecedenceConstraints Collection

The PrecedenceConstraints collection is a group of PrecedenceConstraint objects containing information about conditions that must occur before a DTS step can be released for execution.

Applies To

Step Object	Step2 Object
Properties

Count Property	Parent Property
Methods

Add Method	Item Method
AddConstraint Method	New (Name) Method
Insert Method
See Also

Creating DTS Package Workflow and Tasks

PrecedenceConstraint Object


Properties Collection

The Properties collection contains Property objects exposing the attributes of a DTS object property.

Properties

Count Property	Parent Property
Methods

Item Method

Remarks

Development environments, such as Microsoft® Visual Basic®, typically provide syntax completion and other development aids. Because the Property object exposes the attributes of object properties, it supports such automated developer assistance.

When using the Item method, the Properties collection supports member identification using either name or ordinal reference syntax. For example:

Set oProperty = oCustomTask.Properties("Name")

-or-

Set oProperty = oCustomTask.Properties(1)

Note   The Properties collection is implemented for automation controllers. DTS applications written in Microsoft Visual C++® and C have no direct access to the Property object.

See Also

Property Object

TransformServerProperties Property


SavedPackageInfos Collection

The SavedPackageInfos collection is a group of SavedPackageInfo objects containing information about DTS packages saved in files.

Properties

Count Property

Method

Item Method

See Also

Retrieving DTS System, Package and Log Data

SavedPackageInfo Object


ScriptingLanguageInfos Collection

The ScriptingLanguageInfos collection contains ScriptingLanguageInfo objects that provide information about each Microsoft® ActiveX® scripting language that is available on the system. You can use these scripting languages in ActiveX Script tasks, ActiveX Script transformations, and step scripts.

Properties

Count Property	UseCache Property
Parent Property
Methods

Item Method	Refresh Method
Remarks

Obtain a reference to the ScriptingLanguageInfos collection from the Application object.

You can iterate through the objects of the ScriptingLanguageInfos collection using the Item method and Count property. However, it is faster to use For Each ... Next in Microsoft Visual Basic®.

DTS maintains a cache, in the operating system registry, which holds the scripting language information. If the UseCache property is TRUE the cache is scanned, rather than all registered classes, when iterating through the ScriptingLanguageInfos collection. Use the Refresh method to update the cache from the registered classes section of the system registry.

See Also

Application Object

Item Method

Refresh Method

Retrieving DTS System, Package and Log Data

ScriptingLanguageInfo Object

UseCache Property


StepLineages Collection

The StepLineages collection contains StepLineage objects that provide the contents of step lineage records from Microsoft® SQL Server™ 2000 Meta Data Services. These records contain information about the execution of a step in a DTS package hosted by Meta Data Services.

Properties

EOF Property

Methods

Next Method

Remarks

A step lineage record is written each time a step of a package stored in Meta Data Services is executed, if the package LineageOptions property specifies this to be done.

Use the EnumStepLineages method of the PackageRepository object to return the StepLineages collection.

Iterate through the objects of the StepLineages collection by checking the EOF property after calling the Next method. If EOF is TRUE, Next will have returned Nothing and all the elements will have been fetched. You can also use For Each … Next in Microsoft Visual Basic®.

See Also

EnumStepLineages Method

LineageOptions Property

PackageRepository Object

Retrieving DTS System, Package and Log Data

StepLineage Object


StepLogRecords Collection

The StepLogRecords collection contains StepLogRecord objects that provide the contents of step log records from an instance of Microsoft® SQL Server™. The log records contain information about the execution of a step in a DTS package.

Properties

EOF Property

Methods

Next Method

Remarks

A step log record is written to the msdb database on the server specified by the package LogServerName property each time a step in a package is executed, if the package LogToSQLServer property has been set.

Use the EnumStepLogRecords method of the PackageSQLServer object to return the StepLogRecords collection.

Iterate through the objects of the StepLogRecords collection by checking the EOF property after calling the Next method. If EOF is TRUE, Next will have returned Nothing and all the elements will have been fetched. You can also use For Each … Next in Microsoft Visual Basic®.

See Also

EnumStepLogRecords Method

LogServerName Property

LogToSQLServer Property

PackageSQLServer Object

Retrieving DTS System, Package and Log Data

StepLogRecord Object


Steps Collection

The Steps collection is a group of Step2 objects that contain information about the flow and execution of tasks within a DTS package.

Applies To

Package Object	Package2 Object
Properties

Count Property	Parent Property
Methods

Add Method	New Method
Insert Method	Remove Method
Item Method
Remarks

The Step objects control the flow and execution of tasks within the package. Step execution sequence is determined by their precedence constraints.

Prototype (C/C++)

HRESULT GetSteps(IDTSSteps **pRetVal);

See Also

Creating DTS Package Workflow and Tasks

PrecedenceConstraint Object

Step2 Object


TaskInfos Collection

The TaskInfos collection contains TaskInfo objects that provide information about each DTS task available on the system. These include the tasks supplied by Microsoft® SQL Server™ 2000 and custom tasks implemented by users or other vendors.

Properties

Count Property	UseCache Property
Parent Property
Methods

Item Method	Refresh Method
Remarks

Obtain a reference to the TaskInfos collection from the Application object. For more information about the tasks supplied with SQL Server 2000, see Task Objects.

You can iterate through the objects of the TaskInfos collection using the Item method and Count property. However, it is faster to use For Each ... Next in Microsoft Visual Basic®.

DTS maintains a cache, in the operating system registry, that holds the task information. If the UseCache property is TRUE, the cache, rather than all registered classes, is scanned when iterating through the XXXXs collection. Use the Refresh method to update the cache from the registered classes section of the system registry.

See Also

Application Object

Item Method

Refresh Method

Retrieving DTS System, Package and Log Data

TaskInfo Object

UseCache Property


TaskLogRecords Collection

The TaskLogRecords collection contains TaskLogRecord objects that provide the contents of task log records from an instance of Microsoft® SQL Server™. The log record contains information about the execution of a task that has been implemented in a Data Transformation Services (DTS) package to write task log records.

Properties

EOF Property

Methods

Next Method

Remarks

Task log records are not automatically written by the task classes supplied with SQL Server 2000, but the PackageLog interface is available so that a custom task or the script of an ActiveScriptTask object can write them. They are written to the msdb database on the server specified by the package LogServerName property each time a task in a package that has been implemented to write them is executed, if the package LogToSQLServer property has been set.

Use the EnumTaskLogRecords method of the PackageSQLServer object to return the TaskLogRecords collection.

Iterate through the objects of the TaskLogRecords collection by checking the EOF property after calling the Next method. If EOF is TRUE, Next will have returned Nothing and all the elements will have been fetched. You can also use For Each … Next in Microsoft Visual Basic®.

See Also

ActiveScriptTask Object

EnumTaskLogRecords Method

LogServerName Property

LogToSQLServer Property

PackageSQLServer Object

Retrieving DTS System, Package and Log Data

TaskLogRecord Object


Tasks Collection

The Tasks collection is a group of Task objects that contain information about units of work to be performed as part of the transformation process. The Tasks collection contains all of the defined tasks in a DTS package.

Applies To

Package Object	Package2 Object
Properties

Count Property	Parent Property
Methods

Add Method	New (ID) Method
Insert Method	Remove Method
Item Method
Remarks

Tasks specifies a Tasks collection.

Prototype (C/C++)

HRESULT GetTasks(IDTSTasks **pRetVal);

See Also

Creating DTS Package Workflow and Tasks

Task Object


TransformationInfos Collection

The TransformationInfos collection contains TransformationInfo objects that provide information about each DTS transformation available on the system. These include the transformations supplied by Microsoft® SQL Server™ 2000 and custom transformations implemented by users or other vendors.

Properties

Count Property	UseCache Property
Parent Property
Methods

Item Method	Refresh Method
Remarks

Obtain a reference to the TransformationInfos collection from the Application object. For more information about the transformations supplied with SQL Server 2000, see Transformation Objects.

You can iterate through the objects of the TransformationInfos collection using the Item method and Count property. However, it is faster to use For Each ... Next in Microsoft Visual Basic®.

DTS maintains a cache, in the operating system registry, that holds the transformation information. If the UseCache property is TRUE the cache is scanned, rather than all registered classes, when iterating through the TransformationInfos collection. Use the Refresh method to update the cache from the registered classes section of the system registry.

See Also

Application Object

Item Method

Refresh Method

Retrieving DTS System, Package and Log Data

TransformationInfo Object

UseCache Property


Transformations Collection

The Transformations collection is a group of Transformation2 objects that contain information about the transformation, and about source and destination columns.

Applies To

DataDrivenQueryTask Object	DataPumpTask2 Object
DataDrivenQueryTask2 Object	TransformationSet Object
DataPumpTask Object
Properties

Count Property	Parent Property
Methods

Add Method	New (ID) Method
Insert Method	Remove Method
Item Method
Remarks

Transformations specifies the collection of transformations that transfer data from the data source to the data destination.

Prototype (C/C++)

HRESULT GetTransformations(IDTSTransformations **pRetVal);

See Also

Adding DTS Transformations

Transformation2 Object


TransformationSets Collection

The TransformationSets collection contains the TransformationSet objects that define the transformations to be performed on the columns of a component rowset in a hierarchical rowset by the Parallel Data Pump Task object.

Applies To

ParallelDataPumpTask Object

Properties

Count Property	Parent Property
Methods

Add Method	New (Name) Method
Insert Method	Remove Method
Item Method
Remarks

The New method creates a new TransformationSet object. The Add method adds a TransformationSet object to the collection at the last ordinal position. The Insert method adds a TransformationSet object to the collection at a specified ordinal position, or just ahead of a referenced object in the collection.

The ordinal position of the TransformationSet objects in the collection determines the order in which they are mapped to the component rowsets of the source and destination hierarchical rowsets.

Hierarchical rowsets are scanned in column-ordinal order. When a child rowset is encountered, it is mapped to the next TransformationSet object, and its columns are scanned before the remaining columns of the parent rowset are scanned. This process is continued recursively until the entire hierarchical rowset is scanned.

See Also

TransformationSet Object


Properties

This section defines the properties of the Microsoft® SQL Server™ 2000 Data Transformation Services (DTS) objects and collections. Use these properties to retrieve and set the attributes of the DTS components.


ActiveXScript Property

The ActiveXScript property specifies a Microsoft® ActiveX® script text string for an object to execute.

Applies To

ActiveScriptTask Object	Step2 Object
Step Object
Syntax

object.ActiveXScript [= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	ActiveX script for an object to execute
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetActiveXScript(BSTR *pRetVal);

HRESULT SetActiveXScript(BSTR NewValue);

Remarks

ActiveX scripts also are used by the DTSTransformScriptProperties2 and DataPumpTransformScript objects.

See Also

FunctionName Property

ScriptLanguage Property


AddGlobalVariables Property

The AddGlobalVariables property specifies whether global variables can be referenced from the current Microsoft® ActiveX® script.

Applies To

ActiveScriptTask Object	Step2 Object
Step Object
Syntax

object.AddGlobalVariables [= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	Boolean that specifies whether global variables can be referenced from the current ActiveX script
Data Type

Boolean

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetAddGlobalVariables(VARIANT_BOOL *pRetVal);

HRESULT SetAddGlobalVariables(VARIANT_BOOL NewValue);

Remarks

The default is TRUE. You access the GlobalVariables collection from within ActiveX scripts using the name DTSGlobalVariables.

See Also

GlobalVariables Collection


AllowIdentityInserts Property

The AllowIdentityInserts property specifies whether the SET IDENTITY_INSERT Transact-SQL statement is set to ON before and OFF after the data pump execution.

Applies To

DataPumpTask Object	DataPumpTask2 Object

Syntax

object.AllowIdentityInserts[= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	Boolean that specifies whether SET IDENTITY_INSERT is set to ON during data pump execution
Data Type

Boolean

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetAllowIdentityInserts(VARIANT_BOOL *pRetVal);

HRESULT SetAllowIdentityInserts(VARIANT_BOOL NewValue);

Remarks

AllowIdentityInserts only applies to Microsoft® SQL Server™.

See Also

KeepIdentity Property


AMSymbol Property

The AMSymbol property specifies or returns the string indicating the time format before 12:00 noon (for example, A.M.) when a 12-hour time format is specified.

Applies To

DataPumpTransformDateTimeString Object

Syntax

object.AMSymbol [= string]

Part	Description
object	Expression that evaluates to a DataPumpTransformDateTimeString object
string	Suffix string that indicates a time format before 12:00 noon for a 12-hour time format
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT AMSymbol(BSTR* pRetVal);

HRESULT AMSymbol(BSTR pRetVal);

Remarks

The default value is the English "AM".

The property also can be referenced through the TransformServerProperties collection with the following code:

Set transprops = transform.TransformServerProperties
transprops("AMSymbol") [= string]

See Also

InputFormat Property

OutputFormat Property

PMSymbol Property


AppendIfFileExists Property

The AppendIfFileExists property specifies or returns a value indicating whether data written to a destination file is appended to or is written over data that was present when the file was opened.

Applies To

DataPumpTransformWriteFile Object

Syntax

object.AppendIfFileExists [= boolean]

Part	Description
object	Expression that evaluates to a DataPumpTransformWriteFile object.
boolean	If TRUE, data is appended to data that already exists in the file. If FALSE, existing data is overwritten.
Data Type

Boolean

Modifiable

Read/write

Prototype (C/C++)

HRESULT AppendIfFileExists(VARIANT_BOOL* pRetVal);

HRESULT AppendIfFileExists(VARIANT_BOOL pRetVal);

Remarks

The property also can be referenced through the TransformServerProperties collection with the following code:

Set transprops = transform.TransformServerProperties
transprops"AppendIfFileExists") [= boolean]

See Also

ErrorIfFileExists Property

ErrorIfFileNotFound Property


Assignments Property

The Assignments property returns a reference to the DynamicPropertiesTaskAssignments collection.

Applies To

DynamicPropertiesTask

Syntax

[Set collection =] object.Assignments

Part	Description
object	Expression that evaluates to a DynamicPropertiesTask object
collection	An object variable compatible with type DTSCustTasks.DynamicPropertiesTaskAssignments
Data Type

DynamicPropertiesTaskAssignments Collection

Modifiable

Read-only

Prototype (C/C++)

HRESULT Assignments(DynamicPropertiesTaskAssignments** pVal);

See Also

DynamicPropertiesTaskAssignment Object


AutoCommitTransaction Property

The AutoCommitTransaction property specifies whether an active transaction is committed or rolled back on completion of Package.Execute.

Applies To

Package Object	Package2 Object
Syntax

object.AutoCommitTransaction[= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	Whether an active transaction is committed or rolled back
Data Type

Boolean

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetAutoCommitTransaction(VARIANT_BOOL *pRetVal);

HRESULT SetAutoCommitTransaction(VARIANT_BOOL NewValue);

See Also

TransactionIsolationLevel Property

UseTransaction Property


BatchCompleteFunctionEntry Property

The BatchCompleteFunctionEntry property specifies or returns the name of the script function that is to be called for the OnBatchComplete transformation phase.

Applies To

DTSTransformScriptProperties2 Object

Syntax

object.BatchCompleteFunctionEntry [= name]

Part	Description
object	Expression that evaluates to a DTSTransformScriptProperties2 object
name	Name of the script function that supports the OnBatchComplete phase
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT BatchCompleteFunctionEntry(BSTR* pRetVal);

HRESULT BatchCompleteFunctionEntry(BSTR pRetVal);

Remarks

The OnBatchComplete phase is available only in the DataPumpTask2 object, not in the DataDrivenQueryTask2 or ParallelDataPumpTask objects. The transform is called on success or failure of the batch.

The OnBatchComplete script function has no access to the columns of the DTSSource and DTSDestination collections. The only valid return values are DTSTransformStat_OK and DTSTransformStat_AbortPump.

The property also can be referenced through the TransformServerProperties collection with the following code:

Set transprops = transform.TransformServerProperties
transprops("BatchCompleteFunctionEntry") [= string]

See Also

DataDrivenQueryTask2 Object

DataPumpTask2 Object

DTSTransformStatus

FunctionEntry Property

InsertFailureFunctionEntry Property

InsertSuccessFunctionEntry Property

ParallelDataPumpTask Object

PostSourceDataFunctionEntry Property

PreSourceDataFunctionEntry Property

PumpCompleteFunctionEntry Property

TransformFailureFunctionEntry Property


BatchSize Property

The BatchSize property specifies the number of rows to load in a batch.

Applies To

BulkInsertTask Object

Syntax

object.BatchSize [= value]

Part	Description
object	Expression that evaluates to a BulkInsertTask object
value	Number of rows to load
Data Type

Long

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetBatchSize(LONG *pRetVal);

HRESULT SetBatchSize(LONG NewValue);

Remarks

The default is 0, which specifies that all rows are to be loaded as a single transaction.


Catalog Property

The Catalog property specifies the name of the catalog in which the connection is initially established.

Applies To

Connection Object	Connection2 Object
Syntax

object.Catalog [= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list.
value	Name of a catalog (for example, a database).
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetCatalog(BSTR *pRetVal);

HRESULT SetCatalog(BSTR NewValue);

Remarks

When the connection uses the Microsoft® OLE DB Provider for SQL Server, the Catalog property is a database name.

See Also

DataSource Property

UDLPath Property


CCLine Property

The CCLine property specifies e-mail addresses to include on the CC: line.

Applies To

SendMailTask Object

Syntax

object.CCLine[= value]

Part	Description
object	Expression that evaluates to a SendMailTask object
value	E-mail addresses to include on the CC: line
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetCCLine(BSTR *pRetVal);

HRESULT SetCCLine(BSTR NewValue);

Remarks

E-mail addresses must be separated by semicolons.

See Also

FileAttachments Property

MessageText Property

Subject Property

ToLine Property


CharacterCount Property

The CharacterCount property specifies or returns the number of characters in the substring of the source column to be copied by custom transformations.

Applies To

DataPumpTransformMidString Object

Syntax

object.CharacterCount [= value]

Part	Description
object	Expression that evaluates to a DataPumpTransformMidString object
value	Number of characters in the substring to be copied
Data Type

Long

Modifiable

Read/write

Prototype (C/C++)

HRESULT CharacterCount(long* pRetVal);

HRESULT CharacterCount(long pRetVal);

Remarks

If a value less than 1 is provided for CharacterCount, a zero-length string is copied. If a value greater than the number of characters available to be copied is provided, the entire source string from the specified CharacterStart to the end of the string is copied.

The property also can be referenced through the TransformServerProperties collection with the following code:

Set transprops = transform.TransformServerProperties
transprops("CharacterCount") [= value]

See Also

CharacterStart Property


CharacterStart Property

The CharacterStart property specifies or returns the starting position of the substring of the source column to be copied by custom transformations.

Applies To

DataPumpTransformMidString Object

Syntax

object.CharacterStart [= value]

Part	Description
object	Expression that evaluates to a DataPumpTransformMidString object
value	Position of the starting character of the substring to be copied
Data Type

Long

Modifiable

Read/write

Prototype (C/C++)

HRESULT CharacterStart(long* pRetVal);

HRESULT CharacterStart(long pRetVal);

Remarks

If the substring starts at the first character of the source column, the property has the value of 1. If a value less than 1 is provided, 1 is used. If a value greater than the number of characters in the source string is provided, a zero-length string is copied.

The property also can be referenced through the TransformServerProperties collection with the following code:

Set transprops = transform.TransformServerProperties
transprops("CharacterStart") [= value]

See Also

CharacterCount Property


CheckConstraints Property

The CheckConstraints property specifies whether any constraints must be checked while data is loaded.

Applies To

BulkInsertTask Object

Syntax

object.CheckConstraints [= value]

Part	Description
object	Expression that evaluates to a BulkInsertTask object
value	Boolean that specifies whether any constraints are checked
Data Type

Boolean

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetCheckConstraints(VARIANT_BOOL *pRetVal);

HRESULT SetCheckConstraints(VARIANT_BOOL NewValue);

Remarks

The default is FALSE.


ClassID Property

The ClassID property returns the class ID and a globally unique identifier (GUID), under which a class of a component used by Data Transformation Services (DTS) is registered in the operating system registry.

Applies To

OLEDBProviderInfo Object	TaskInfo Object
ScriptingLanguageInfo Object	TransformationInfo Object
Syntax

object.ClassID

Part	Description
object	Expression that evaluates to an object in the Applies To list
Data Type

String

Modifiable

Read-only

Prototype (C/C++)

HRESULT GetClassID(BSTR* pRetVal);

Remarks

The syntax of GUIDs is:

{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}

where X represents hexadecimal digits. The groupings are 8, 4, 4, 4, and 12 digits.

See Also

ImplementationFileName Property

ImplementationFileVersionString Property

UseCache Property


CloseConnection Property

The CloseConnection property specifies whether to close a connection on completion of a step.

Applies To

Step Object	Step2 Object
Syntax

object.CloseConnection [= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	Whether to close the connection on completion
Data Type

Boolean

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetCloseConnection(VARIANT_BOOL *pRetVal);

HRESULT SetCloseConnection(VARIANT_BOOL NewValue);

Remarks

The default is FALSE.

See Also

Connection2 Object


Codepage Property

The Codepage property specifies the code page to use while loading data.

Applies To

BulkInsertTask Object

Syntax

object.Codepage [= value]

Part	Description
object	Expression that evaluates to a BulkInsertTask object
value	Code page to use
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetCodepage(BSTR *pRetVal);

HRESULT SetCodepage(BSTR NewValue);

Remarks

Use one of these values:

•	ACP

•	OEM (default)

•	RAW

•	A code page number (for example, 850)


ColumnID Property

The ColumnID property specifies the column ID of a source or destination column.

Applies To

Column Object

Syntax

object.ColumnID [= value]

Part	Description
object	Expression that evaluates to a Column object
value	Column identifier
Data Type

Variant

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetColumnID(VARIANT *pRetVal);

HRESULT SetColumnID(VARIANT NewValue);

Remarks

The ColumnID property is typically the same as the column Name. The column Ordinal is a number that determines the position of the column in the column order.

See Also

Name Property

Ordinal Property


CommandProperties Property

The CommandProperties property returns a reference to an OLEDBProperties collection, which contains an OLEDBProperty object for each OLE DB command property for the connection.

Applies To

ExecuteSQLTask Object	ExecuteSQLTask2 Object
Syntax

object.CommandProperties

Part	Description
object	Expression that evaluates to an object in the Applies To list
Data Type

OLEDBProperties Collection

Modifiable

Read-only

Prototype (C/C++)

HRESULT GetCommandProperties(IDTSOleDBProperties **pRetVal);

See Also

Connection2 Object

OLEDBProperty Object


CommandTimeout Property

The CommandTimeout property specifies the amount of time, in seconds, before the command is presumed to have failed.

Applies To

ExecuteSQLTask Object	ExecuteSQLTask2 Object
Syntax

object.CommandTimeout [= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	Time, in seconds, before the command is presumed to have failed
Data Type

Long

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetCommandTimeout(LONG *pRetVal);

HRESULT SetCommandTimeout(LONG NewValue);

Remarks

A value of 0 (default) indicates no time-out period.


CommitSuccess Property

The CommitSuccess property specifies whether to commit a step if it completes successfully.

Applies To

Step Object	Step2 Object
Syntax

object.CommitSuccess [= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	A value indicating whether to commit the step
Data Type

Boolean

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetCommitSuccess(VARIANT_BOOL *pRetVal);

HRESULT SetCommitSuccess(VARIANT_BOOL NewValue);

See Also

JoinTransactionIfPresent Property

RollbackFailure Property


Computer Property

The Computer property specifies the network node name of the computer on which a Data Transformation Services (DTS) package was executed. This property applies only to packages for which a lineage or log record was written

Applies To

PackageLineage Object	PackageLogRecord Object
Syntax

object.Computer

Part	Description
object	Expression that evaluates to an object in the Applies To list
Data Type

String

Modifiable

Read-only

Prototype (C/C++)

HRESULT GetComputer(BSTR *pRetVal);

See Also

Operator Property


Connected Property

The Connected property indicates whether a connection is currently active.

Applies To

Connection Object	Connection2 Object
Syntax

object.Connected

Part	Description
object	Expression that evaluates to an object in the Applies To list
Data Type

Boolean

Modifiable

Read-only

Prototype (C/C++)

HRESULT GetConnected(VARIANT_BOOL *pRetVal);

See Also

AcquireConnection Method

ConnectImmediate Property

ReleaseConnection Method


ConnectImmediate Property

The ConnectImmediate property specifies whether to make an immediate connection, either when a Data Transformation Services (DTS) package starts running or at the time a step that references a task using this connection executes.

Applies To

Connection Object	Connection2 Object
Syntax

object.ConnectImmediate [= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	Value indicating whether to make an immediate connection
Data Type

Boolean

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetConnectImmediate(VARIANT_BOOL *pRetVal);

HRESULT SetConnectImmediate(VARIANT_BOOL NewValue);

Remarks

The default is FALSE.

See Also

Connected Property


ConnectionID Property

The ConnectionID property specifies the ID of a Connection object you use when connecting to a database or another data source.

Applies To

BulkInsertTask Object	ExecuteSQLTask2 Object
ExecuteSQLTask Object	Lookup Object
Syntax

object.ConnectionID [= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	ID of the Connection object you want to use
Data Type

Long

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetConnectionID(LONG *pRetVal);

HRESULT SetConnectionID(LONG NewValue);

See Also

Connection2 Object


ConnectionProperties Property

The ConnectionProperties property returns a reference to an OLEDBProperties collection used to establish the characteristics of a connection.

Applies To

Connection Object	Connection2 Object
Syntax

object.ConnectionProperties

Part	Description
object	Expression that evaluates to an object in the Applies To list
Data Type

OLEDBProperties Collection

Modifiable

Read-only

Prototype (C/C++)

HRESULT GetConnectionProperties(IDTSOleDBProperties **pRetVal);

Remarks

These properties are specific to the OLE DB provider used by the connection.

See Also

OLEDBProperty2 Object


ConnectionTimeout Property

The ConnectionTimeout property returns or sets the number of seconds to wait while establishing a connection. After that, an error is generated.

Applies To

Connection Object	Connection2 Object
Syntax

object.ConnectionTimeout [= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	Number of seconds to wait while establishing a connection
Data Type

Long

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetConnectionTimeout(LONG *pRetVal);

HRESULT SetConnectionTimeout(LONG NewValue);

Remarks

The default is 60 seconds.

See Also

AcquireConnection Method

ConnectImmediate Property


CopyAllObjects Property

The CopyAllObjects property specifies whether to transfer all objects from an instance of Microsoft® SQL Server™.

Applies To

TransferObjectsTask Object	TransferObjectsTask2 Object
Syntax

object.CopyAllObjects[= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	A value indicating whether to transfer all objects
Data Type

Boolean

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetCopyAllObjects(VARIANT_BOOL *pRetVal);

HRESULT SetCopyAllObjects(VARIANT_BOOL NewValue);

Remarks

The default is TRUE.

See Also

CopyData Property

CopySchema Property

DropDestinationObjectsFirst Property

IncludeDependencies Property

IncludeLogins Property

IncludeUsers Property


CopyData Property

The CopyData property specifies whether data is copied and whether existing data is replaced or appended to.

Applies To

TransferObjectsTask Object	TransferObjectsTask2 Object
Syntax

object.CopyData[= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	Code that specifies whether data is copied and whether existing data is replaced or appended to
Data Type

DTSTransfer_CopyDataOption

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetCopyData(DTSTransfer_CopyDataOption *pRetVal);

HRESULT SetCopyData(DTSTransfer_CopyDataOption NewValue);

Remarks

CopyData must be set to one of the DTSTransfer_CopyDataOption values. The default is DTSTransfer_ReplaceData.

See Also

CopyAllObjects Property

CopySchema Property

DropDestinationObjectsFirst Property

IncludeDependencies Property

IncludeLogins Property

IncludeUsers Property


CopySchema Property

The CopySchema property specifies whether Microsoft® SQL Server™ database objects are copied.

Applies To

TransferObjectsTask Object	TransferObjectsTask2 Object
Syntax

object.CopySchema[= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	Value indicating whether data is copied
Data Type

Boolean

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetCopySchema(VARIANT_BOOL *pRetVal);

HRESULT SetCopySchema(VARIANT_BOOL NewValue);

Remarks

The default is TRUE. If CopySchema is set to FALSE, the objects are not copied. If CopySchema is FALSE, data is copied only if the CopyData property is TRUE.

See Also

CopyAllObjects Property

CopyData Property

DropDestinationObjectsFirst Property

IncludeDependencies Property

IncludeLogins Property

IncludeUsers Property


Count Property

The Count property specifies the number of items in a Data Transformation Services (DTS) collection.

Applies To

Columns Collection	Properties Collection
Connections Collection	SavedPackageInfos Collection
DTSMQMessages Collection	ScriptingLanguageInfos Collection
DynamicPropertiesTaskAssignments Collection	Steps Collection
GlobalVariables Collection	TaskInfos Collection
Lookups Collection	Tasks Collection
OLEDBProperties Collection	TransformationInfos Collection
OLEDBProviderInfos Collection	Transformations Collection
PrecedenceConstraints Collection	TransformationSets Collection
Syntax

object.Count

Part	Description
object	Expression that evaluates to an object in the Applies To list
Data Type

Long

Modifiable

Read-only

Prototype (C/C++)

HRESULT GetCount(long *pRetVal);

See Also

Item Method


CreationDate Property

The CreationDate property specifies the date and time the Data Transformation Services (DTS) package was created.

Applies To

Package Object	PackageInfo Object
Package2 Object
Syntax

object.CreationDate

Part	Description
object	Expression that evaluates to an object in the Applies To list
Data Type

Date

Modifiable

Read-only

Prototype (C/C++)

HRESULT GetCreationDate(DATE *pRetVal);

See Also

CreatorComputerName Property

CreatorName Property

PackageCreationDate Property


CreatorComputerName Property

The CreatorComputerName property specifies the network name of the computer on which the Data Transformation Services (DTS) package was created.

Applies To

Package Object	Package2 Object
Syntax

object.CreatorComputerName

Part	Description
object	Expression that evaluates to an object in the Applies To list
Data Type

String

Modifiable

Read-only

Prototype (C/C++)

HRESULT GetCreatorComputerName(BSTR *pRetVal);

See Also

CreationDate Property

CreatorName Property


CreatorName Property

The CreatorName property specifies the name of the user who created the Data Transformation Services (DTS) package.

Applies To

Package Object	Package2 Object
Syntax

object.CreatorName

Part	Description
object	Expression that evaluates to an object in the Applies To list
Data Type

String

Modifiable

Read-only

Prototype (C/C++)

HRESULT GetCreatorName(BSTR *pRetVal);

Remarks

An application must not rely on the CreatorName property being set. For example, if a package is created on a computer running Microsoft® Windows® 98, in some cases, no value is entered for the user name.

See Also

CreationDate Property

CreatorComputerName Property


CustomTask Property

The CustomTask property returns a reference to the class-specific task object.

Applies To

Task Object

Syntax

object.CustomTask [= value]

Part	Description
object	Expression that evaluates to a Task object
value	Returns a reference to the class-specific task object
Data Type

Depends on the Data Transformation Services (DTS) task class being used.

Modifiable

Read-only

Prototype (C/C++)

HRESULT GetCustomTask(IDTSCustomTask **pRetVal);

Remarks

The New method of the Tasks collection creates a (generic) Task object and a class-specific task object.

Example

The relationship between the (generic) Task object, the class-specific task object and the Step2 object is illustrated by the following Microsoft® Visual Basic® code:

    Dim objPackage    As DTS.Package2

    Dim objTask       As DTS.Task             'This is the generic Task object.

    Dim objStep       As DTS.Step2

    Dim objDataPump   As DTS.DataPumpTask2    'This is the class-specific task.

    . . .

    Set objStep = objPackage.Steps.New

    objStep.Name = "LowerCaseStep"

    Set objTask = oPackage.Tasks.New("DTSDataPumpTask")

    Set objDataPump = objTask.CustomTask

    objDataPump.Name = "LowerCaseTask"

    objStep.TaskName = objDataPump.Name

    objPackage.Steps.Add oStep

    objPackage.Tasks.Add objTask

See Also

New (ID) Method

Step2 Object

Tasks Collection


CustomTaskID Property

The CustomTaskID property returns the programmatic identifier (ProgID) or class identifier (CLSID) of the class-specific object for this task.

Applies To

Task Object

Syntax

object.CustomTaskID

Part	Description
object	Expression that evaluates to a Task object
Data Type

String

Modifiable

Read-only

Prototype (C/C++)

HRESULT GetCustomTaskID(BSTR *pRetVal);

Remarks

This property returns the ProgID or CLSID used in the call to the New method or CoCreateInstance function that created the Task object.

See Also

New (ID) Method


 DataFile Property

The DataFile property specifies the universal naming convention (UNC) path of the file from which to load the data.

Applies To

BulkInsertTask Object

Syntax

object.DataFile[= value]

Part	Description
object	Expression that evaluates to a BulkInsertTask object
value	UNC path of the file
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetDataFile(BSTR *pRetVal);

HRESULT SetDataFile(BSTR NewValue);

Remarks

The UNC path is relative to the server on which the bulk insert command will run.

See Also

DataFileType Property

FormatFile Property


DataFileNonOverwritable Property

The DataFileNonOverwritable property returns or sets a value indicating whether a data file message can overwrite an existing data file.

Applies To

DTSMessageQueueTask Object

Syntax

object.DataFileNonOverwritable [= value]

Part	Description
object	Expression that evaluates to a DTSMessageQueueTask object
value	Boolean that specifies whether an existing data file can be overwritten
Data Type

Boolean

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetDataFileNonOverwritable(VARIANT_BOOL *pRetVal);

HRESULT SetDataFileNonOverwritable(VARIANT_BOOL NewValue);

Remarks

The step fails if the data file already exists and DataFileNonOverwritable is TRUE. DataFileNonOverwritable is ignored if ReceiveMessageType is other than DTSMQMessageType_DataFile.

See Also

DTSMQMessageType

ReceiveMessageType Property

SaveDataFileName Property


DataFileType Property

The DataFileType property specifies the type of the data file to insert.

Applies To

BulkInsertTask Object

Syntax

object.DataFileType [= value]

Part	Description
object	Expression that evaluates to a BulkInsertTask object
value	Type of the data file
Data Type

DTSBulkInsert_DataFileType

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetDataFileType(DTSBulkInsert_DataFileType *pRetVal);

HRESULT SetDataFileType(DTSBulkInsert_DataFileType NewValue);

Remarks

DataFileType must be set to one of the DTSBulkInsert_DataFileType values. The default is DTSBulkInsert_DataFileType_Char.

See Also

DataFile Property


DataPumpOptions Property

The DataPumpOptions property returns or sets extended Data Transformation Services (DTS) data pump options.

Applies To

DataPumpTask2 Object

Syntax

object.DataPumpOptions [= value]

Part	Description
object	Expression that evaluates to a DataPumpTask2 object
value	Value that specifies the extended options
Data Type

Long

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetDataPumpOptions(long *pRetVal);

HRESULT SetDataPumpOptions(long NewValue);

Remarks

The following table lists the valid values for the DataPumpOptions property.

Value	Description
0	Default
1	Commits all successful batches including the final batch, even if the data pump terminates. Use this option to support restartability.
See Also

FastLoadOptions Property

InsertCommitSize Property

UseFastLoad Property


DataSource Property

The DataSource property specifies a data source name appropriate to the OLE DB provider being used.

Applies To

Connection Object	Connection2 Object
Syntax

object.DataSource [= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	Data source name
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetDataSource(BSTR *pRetVal);

HRESULT SetDataSource(BSTR NewValue);

Remarks

The data source can be a Microsoft® SQL Server™ name, file name, or some other specification meaningful to the provider.

See Also

Catalog Property


DataType Property

The DataType property specifies the data type of a Column object.

Applies To

Column Object

Syntax

object.DataType [= value]

Part	Description
object	Expression that evaluates to a Column object
value	Column data type
Data Type

Long

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetDataType(LONG *pRetVal);

HRESULT SetDataType(LONG NewValue);

Remarks

Data Transformation Services (DTS) column data types match those used in Microsoft® ActiveX® Data Objects (ADO), both in name and value, and OLE DB type identifiers (DBTYPEs).

You can find the valid values for the DataType property by searching for DBTYPEENUM in the include file OLEDB.h. OLEDB.h is installed in c:\Program Files\Microsoft SQL Server\80\Tools\DevTools\include\ by default.

See Also

Flags Property

NumericScale Property

Precision Property

Size Property


Day?LongName Property

The Day?LongName property specifies or returns the string to be used for the full name of the indicated day of the week. ? is a number from 1 through 7 that indicates the day of the week.

Applies To

DataPumpTransformDateTimeString Object

Syntax

object.Day?LongName [= name]

Part	Description
object	Expression that evaluates to a DataPumpTransformDateTimeString object
?	Day of week number from 1 through 7
name	Full name of the specified day of week
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetDay?LongName(BSTR* pRetVal);

HRESULT SetDay?LongName(BSTR pRetVal);

Remarks

The default value is the English day of week name.

The property also can be referenced through the TransformServerProperties collection with the following code:

Set transprops = transform.TransformServerProperties
transprops("Day?LongName") [= name]

See Also

Day?ShortName Property

GetDayLongName Method

GetDayShortName Method

InputFormat Property

OutputFormat Property

SetDayLongName Method

SetDayShortName Method


Day?ShortName Property

The Day?ShortName property specifies or returns the string to be used for the short (3-character abbreviation) name of the indicated day of the week. ? is a number from 1 through 7 that indicates the number of the week.

Applies To

DataPumpTransformDateTimeString Object

Syntax

object.Day?ShortName [= name]

Part	Description
object	Expression that evaluates to a DataPumpTransformDateTimeString object
?	Day of week number from 1 through 7
name	Short (3-character abbreviation) name of the specified day of week
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetDay?ShortName(BSTR* pRetVal);

HRESULT SetDay?ShortName(BSTR pRetVal);

Remarks

The default value is the English abbreviation for the day of the week.

The property also can be referenced through the TransformServerProperties collection with the following code:

Set transprops = transform.TransformServerProperties
transprops("Day?ShortName") [= name]

See Also

Day?LongName Property

GetDayLongName Method

GetDayShortName Method

InputFormat Property

OutputFormat Property

SetDayLongName Method

SetDayShortName Method


DeleteQuery Property

The DeleteQuery property specifies a string of one or more parameterized SQL statements to execute at the destination as the Delete query.

Applies To

DataDrivenQueryTask Object	TransformationSet Object
DataDrivenQueryTask2 Object
Syntax

object.DeleteQuery [= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	Parameterized string of SQL statements
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetDeleteQuery(BSTR *pRetVal);

HRESULT SetDeleteQuery(BSTR NewValue);

Remarks

Although the name of a data driven query property is preset, its content is not enforced. Any of the queries may be used for any desired operation. The nomenclature is provided as a convenient means of identification, based upon the primary purpose of the operation. For example, the DeleteQuery property does not need to contain an Transact-SQL DELETE statement.

See Also

DeleteQueryColumns Property

InsertQuery Property

UpdateQuery Property

UserQuery Property


DeleteQueryColumns Property

The DeleteQueryColumns property returns a reference to a collection of columns whose values are to be placed into parameters, in sequential order, for the DeleteQuery property.

Applies To

DataDrivenQueryTask Object	TransformationSet Object
DataDrivenQueryTask2 Object
Syntax

object.DeleteQueryColumns

Part	Description
object	Expression that evaluates to an object in the Applies To list
Data Type

Columns Collection

Modifiable

Read-only

Prototype (C/C++)

HRESULT GetDeleteQueryColumns(IDTSColumns **pRetVal);

See Also

Column Object

DeleteQuery Property

InsertQueryColumns Property

UpdateQueryColumns Property

UserQueryColumns Property


Description Property

The Description property returns or sets the textual description of a Data Transformation Services (DTS) object.

Applies To

ActiveScriptTask Object	Package Object
BulkInsertTask Object	Package2 Object
Connection Object	PackageInfo Object
Connection2 Object	PackageLogRecord Object
CreateProcessTask Object	ParallelDataPumpTask Object
CreateProcessTask2 Object	SavedPackageInfo Object
CustomTask Object	ScriptingLanguageInfo Object
DataDrivenQueryTask Object	SendMailTask Object
DataDrivenQueryTask2 Object	Step Object
DataPumpTask Object	Step2 Object
DataPumpTask2 Object	Task Object
DTSMessageQueueTask Object	TaskInfo Object
DynamicPropertiesTask Object	TransferObjectsTask Object
ExecutePackageTask Object	TransferObjectsTask2 Object
ExecuteSQLTask Object	TransformationInfo Object
ExecuteSQLTask2 Object	TransformationSet Object
OLEDBProviderInfo Object
Syntax

object.Description [= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	Description of the associated object
Data Type

String

Modifiable

Varies

Prototype (C/C++)

HRESULT GetDescription(BSTR *pRetVal);

HRESULT SetDescription(BSTR NewValue);

Remarks

Description is usually a read/write property. However, it is a read-only property of informational objects such as the OLEDBProviderInfo, PackageInfo, SavedPackageInfo, ScriptingLangaugeInfo, TaskInfo and TransformationInfo objects.

When the associated object is a DTS class-specific task object, the Description property also can be referenced through the Properties collection of the Task object with the following code:

Set taskprops = task.Properties
taskprops("Description") [= value]

See Also

Name Property

Properties Collection

Task Object


DesignerSettings Property

The DesignerSettings property specifies the settings that control the features available in Data Transformation Services (DTS) Designer.

Applies To

Application Object

Syntax

object.DesignerSettings [= value]

Part	Description
object	Expression that evaluates to an Application object
value	Sum of values from DTSDesignerSettings constants
Data Type

DTSDesignerSettings

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetDesignerSettings(DTSDesignerSettings *pRetVal);

HRESULT SetDesignerSettings(DTSDesignerSettings NewValue);

See Also

JITDebug Property


DestinationColumnDefinitions Property

The DestinationColumnDefinitions property returns a reference to a Columns collection that contains the column definitions for a DataPumpTask2, DataDrivenQueryTask2, or ParallelDataPumpTask destination connection.

Applies To

DataDrivenQueryTask Object	DataPumpTask2 Object
DataDrivenQueryTask2 Object	TransformationSet Object
DataPumpTask Object
Syntax

object.DestinationColumnDefinitions [= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	Reference to a Columns collection that contains the destination column definitions
Data Type

Columns Collection

Modifiable

Read-only

Prototype (C/C++)

HRESULT GetDestinationColumnDefinitions(IDTSColumns **pRetVal);

Remarks

This collection is constructed from the rowset obtained by querying the destination.

See Also

Column Object


DestinationColumns Property

The DestinationColumns property returns a reference to a Columns collection that contains the definitions for the columns to which the transformation will write.

Applies To

Transformation Object	Transformation2 Object
Syntax

object.DestinationColumns

Part	Description
object	Expression that evaluates to an object in the Applies To list
Data Type

Columns Collection

Modifiable

Read-only

Prototype (C/C++)

HRESULT GetDestinationColumns(IDTSColumns **pRetVal);

Remarks

The Ordinal property of the Column objects in the DestinationColumns collection determines the order of columns the transformation will see at the destination. It is used to map these columns to the elements of the SourceColumns collection.

See Also

Column Object

Ordinal Property

SourceColumns Property


DestinationCommandProperties Property

The DestinationCommandProperties collection references an OLEDBProperties collection whose elements define the properties of the destination connection OLE DB provider.

Applies To

DataDrivenQueryTask Object	DataPumpTask2 Object
DataDrivenQueryTask2 Object	ParallelDataPumpTask Object
DataPumpTask Object
Syntax

object.DestinationCommandProperties

Part	Description
object	Expression that evaluates to an object in the Applies To list
Data Type

OLEDBProperties Collection

Modifiable

Read-only

Prototype (C/C++)

HRESULT GetDestinationCommandProperties(IDTSOleDBProperties **pRetVal);

See Also

Connection2 Object

OLEDBProperty Object

SourceCommandProperties Property


DestinationConnectionID Property

The DestinationConnectionID property specifies the connection ID to use at the data destination.

Applies To

DataDrivenQueryTask Object	DataPumpTask2 Object
DataDrivenQueryTask2 Object	ParallelDataPumpTask Object
DataPumpTask Object
Syntax

object.DestinationConnectionID [= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	Connection ID to use
Data Type

Long

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetDestinationConnectionID(LONG *pRetVal);

HRESULT SetDestinationConnectionID(LONG NewValue);

Remarks

The DestinationConnectionID property maps to the ID property of the connection.

See Also

ID Property

SourceConnectionID Property


DestinationDatabase Property

The DestinationDatabase property specifies the name of the destination database to use when you transfer Microsoft® SQL Server™ objects.

Applies To

TransferObjectsTask Object	TransferObjectsTask2 Object
Syntax

object.DestinationDatabase[= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	Name of the destination database
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetDestinationDatabase(BSTR *pRetVal);

HRESULT SetDestinationDatabase(BSTR NewValue);

See Also

DestinationLogin Property

DestinationPassword Property

DestinationServer Property

DestinationUseTrustedConnection Property


DestinationLogin Property

The DestinationLogin property specifies the login ID on a destination server.

Applies To

TransferObjectsTask Object	TransferObjectsTask2 Object
Syntax

object.DestinationLogin[= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	Login ID
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetDestinationLogin(BSTR *pRetVal);

HRESULT SetDestinationLogin(BSTR NewValue);

Remarks

DestinationLogin is required if an application is using SQL Server Authentication.

Note   It is recommended that you connect to an instance of Microsoft® SQL Server™ using Windows Authentication instead of SQL Server Authentication. To use Windows Authentication, set DestinationUseTrustedConnection to TRUE.

See Also

DestinationDatabase Property

DestinationPassword Property

DestinationServer Property

DestinationUseTrustedConnection Property


DestinationObjectName Property

The DestinationObjectName property specifies the name of a data destination.

Applies To

DataDrivenQueryTask Object	DataPumpTask2 Object
DataDrivenQueryTask2 Object	ParallelDataPumpTask Object
DataPumpTask Object
Syntax

object.DestinationObjectName [= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	Name of a data destination
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetDestinationObjectName(BSTR *pRetVal);

HRESULT SetDestinationObjectName(BSTR NewValue);

Remarks

Typically, a DestinationObjectName is a database table or view name or a Microsoft® Excel worksheet name.

A DataPumpTask2 object uses the DestinationObjectName property to open a simple rowset on the named destination object if nothing is specified for the DestinationSQLStatement property. A DataDrivenQueryTask2 object uses the DestinationObjectName property only to retrieve meta data and then releases the rowset.

Example

The following code illustrates how to specify a database table for the destination object name:

    objDataPump.DestinationObjectName = "pubs.dbo.authors"

The following code illustrates how to specify an Excel worksheet for the destination object name:

    objDataPump.DestinationObjectName = "DailyReport$"

See Also

DestinationSQLStatement Property

SourceObjectName Property


DestinationPassword Property

The DestinationPassword property specifies the password to use on a destination server.

Applies To

TransferObjectsTask Object	TransferObjectsTask2 Object
Syntax

object.DestinationPassword[= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	Password to use
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetDestinationPassword(BSTR *pRetVal);

HRESULT SetDestinationPassword(BSTR NewValue);

Remarks

DestinationPassword is required if an application is using SQL Server Authentication.

Note   It is recommended that you connect to an instance of Microsoft® SQL Server™ using Windows Authentication instead of SQL Server Authentication. To use Windows Authentication, set DestinationUseTrustedConnection to TRUE.

See Also

DestinationDatabase Property

DestinationLogin Property

DestinationServer Property

DestinationUseTrustedConnection Property


DestinationPropertyID Property

The DestinationPropertyID property sets or returns a string that defines the path through the Data Transformation Services (DTS) object model to the property to be modified by the DynamicPropertiesTask object.

Applies To

DynamicPropertiesTaskAssignment Object

Syntax

object.DestinationPropertyID [= objectpath]

Part	Description
object	Expression that evaluates to a DynamicPropertiesTaskAssignment object
objectpath	Path through the DTS package object model to the property to be modified
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT DestinationPropertyID(BSTR* pRetVal);

HRESULT DestinationPropertyID(BSTR pRetVal);

Remarks

The path is a list of objects, starting with the object or collection whose parent is the package, separated by a delimiter made up of three backticks (```). Objects are represented by the object names. Collections are represented by a string from the following set of Microsoft® Visual Basic® constant definitions. The following symbolic names do not need to be used, but the following case-sensitive string values must match exactly:

'These are the separators for the DestinationPropertyID strings.
Const DTS_OBJECT_SEPARATOR = "```"
Const DTS_GLOBAL_VARIABLES = "Global Variables"
Const DTS_TASKS = "Tasks"
Const DTS_TRANSFORMATIONS = "Transformations"
Const DTS_DESTINATION_COLUMN_DEFINITIONS = _
"DestinationColumnDefinitions"
Const DTS_USER_QUERY_COLUMNS = "UserQueryColumns"
Const DTS_UPDATE_QUERY_COLUMNS = "UpdateQueryColumns"
Const DTS_INSERT_QUERY_COLUMNS = "InsertQueryColumns"
Const DTS_DELETE_QUERY_COLUMNS = "DeleteQueryColumns"
Const DTS_DEST_COLUMNS = "DestinationColumns"
Const DTS_SOURCE_COLUMNS = "SourceColumns"
Const DTS_LOOKUPS = "Lookups"
Const DTS_PRECEDENCE_CONSTRAINTS = "PrecedenceConstraints"
Const DTS_STEPS = "Steps"
Const DTS_CONNECTIONS = "Connections"
Const DTS_PROPERTIES = "Properties"
Const DTS_DESTINATION_COMMAND_PROPERTIES = _
"DestinationCommandProperties"
Const DTS_SOURCE_COMMAND_PROPERTIES = "SourceCommandProperties"
Const DTS_OLE_DB_PROPERTIES = "OLEDBProperties"

Do not include the package object in the string.

Example

The following example assigns a property path string to DestinationPropertyID:

oAssign.DestinationPropertyID = _

"Connections```Pubs Authors Info```" & _

"OLEDBProperties```Column Lengths```Properties```Value"

See Also

DynamicPropertiesTask Object


DestinationServer Property

The DestinationServer property specifies the name of the destination server when you transfer Microsoft® SQL Server™ objects.

Applies To

TransferObjectsTask Object	TransferObjectsTask2 Object
Syntax

object.DestinationServer[= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	Name of the destination server
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetDestinationServer(BSTR *pRetVal);

HRESULT SetDestinationServer(BSTR NewValue);

See Also

DestinationDatabase Property

DestinationLogin Property

DestinationPassword Property

DestinationUseTrustedConnection Property


DestinationSQLStatement Property

The DestinationSQLStatement property specifies an SQL statement to execute at the data destination.

Applies To

DataDrivenQueryTask Object	DataPumpTask2 Object
DataDrivenQueryTask2 Object	ParallelDataPumpTask Object
DataPumpTask Object
Syntax

object.DestinationSQLStatement [= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	SQL statement to execute
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetDestinationSQLStatement(BSTR *pRetVal);

HRESULT SetDestinationSQLStatement(BSTR NewValue);

Remarks

A DataPumpTask object uses the DestinationSQLStatement property to open a rowset on destination connection. If no DestinationSQLStatement is specified, a simple rowset is opened on the named destination object (for example, a table or view). The rowset must support an Insert operation on the results of a query. A DataDrivenQueryTask object uses the DestinationSQLStatement property only to retrieve meta data and then immediately closes the rowset.

See Also

DestinationObjectName Property

SourceSQLStatement Property


DestinationTableName Property

The DestinationTableName property specifies the name of the table into which to load data.

Applies To

BulkInsertTask Object

Syntax

object.DestinationTableName [= value]

Part	Description
object	Expression that evaluates to a BulkInsertTask object
value	Name of the table
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetDestinationTableName(BSTR *pRetVal);

HRESULT SetDestinationTableName(BSTR NewValue);

Remarks

DestinationTableName can be fully qualified to override the database to which the application is connected (for example, [Northwind].[dbo].[Orders]).

See Also

ConnectionID Property

Connection2 Object


DestinationUseTrustedConnection Property

The DestinationUseTrustedConnection property specifies whether Windows Authentication is used.

Applies To

TransferObjectsTask Object	TransferObjectsTask2 Object
Syntax

object.DestinationUseTrustedConnection[= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	Boolean that specifies whether Windows Authentication is used
Data Type

Boolean

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetDestinationUseTrustedConnection(VARIANT_BOOL *pRetVal);

HRESULT SetDestinationUseTrustedConnection(VARIANT_BOOL NewValue);

Remarks

The default is FALSE.

Note   It is recommended that you connect to an instance of Microsoft® SQL Server™ using Windows Authentication instead of SQL Server Authentication. To use Windows Authentication, set DestinationUseTrustedConnection to TRUE.

See Also

DestinationDatabase Property

DestinationLogin Property

DestinationPassword Property

DestinationServer Property


DestSite Property

The DestSite property sets or returns the destination directory to which the transferred files will be moved by a file transfer protocol (FTP) task.

Applies To

DTSFTPTask

Syntax

object.DestSite [= value]

Part	Description
object	Expression that evaluates to a DTSFTPTask object
value	Destination directory to which the transferred files will be moved
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetDestSite(BSTR* pVal);

HRESULT SetDestSite(BSTR pVal);

Remarks

The property also can be referenced through the Properties collection of the Task object with the following code:

Set taskprops = task.Properties
taskprops("DestSite") [= value]

See Also

SourceLocation Property

SourceSite Property


DestTranslateChar Property

The DestTranslateChar property sets or returns a value indicating whether translation is performed for character data on the destination server.

Applies To

TransferObjectsTask2 Object

Syntax

object.DestTranslateChar [= boolean]

Part	Description
object	Expression that evaluates to a TransferObjectsTask2 object.
boolean	Boolean that specifies whether translation is performed for character data on the destination server.
Data Type

Boolean

Modifiable

Read/write

Prototype (C/C++)

HRESULT DestTranslateChar(VARIANT_BOOL* pRetVal);

HRESULT DestTranslateChar(VARIANT_BOOL pRetVal);

Remarks

The default is TRUE. Translation is performed.

See Also

SourceTranslateChar Property


DestUseTransaction Property

The DestUseTransaction property sets or returns a value indicating whether the operations of the task are performed within a transaction on the destination server.

Applies To

TransferObjectsTask2 Object

Syntax

object.DestUseTransaction [= boolean]

Part	Description
object	Expression that evaluates to a TransferObjectsTask2 object.
boolean	Boolean that specifies whether operations are performed within a transaction on the destination server.
Data Type

Boolean

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetDestUseTransaction(VARIANT_BOOL* pRetVal);

HRESULT SetDestUseTransaction(VARIANT_BOOL pRetVal);

Remarks

The default is FALSE. Operations do not use a transaction.


DisableStep Property

The DisableStep property specifies whether a step should be executed.

Applies To

Step Object	Step2 Object
Syntax

object.DisableStep[= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	Boolean that specifies whether a step is executed
Data Type

Boolean

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetDisableStep(VARIANT_BOOL *pRetVal);

HRESULT SetDisableStep(VARIANT_BOOL NewValue);

Remarks

If set to TRUE, the step is not executed. This can be a useful setting when you are debugging complex Data Transformation Services (DTS) packages.

See Also

ExecutionStatus Property


DropDestinationObjectsFirst Property

The DropDestinationObjectsFirst property specifies whether to drop objects if they already exist on the destination.

Applies To

TransferObjectsTask Object	TransferObjectsTask2 Object
Syntax

object.DropDestinationObjectsFirst[= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	Value indicating whether to drop objects
Data Type

Boolean

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetDropDestinationObjectsFirst(VARIANT_BOOL *pRetVal);

HRESULT SetDropDestinationObjectsFirst(VARIANT_BOOL NewValue);

Remarks

The default is FALSE.

See Also

CopyAllObjects Property

CopyData Property

CopySchema Property

IncludeDependencies Property

IncludeLogins Property

IncludeUsers Property


DTSMessageLineageID Property

The DTSMessageLineageID property sets or returns the globally unique identifier (GUID) of the lineage information that was saved with the Data Transformation Services (DTS) package in Microsoft® SQL Server™ 2000 Meta Data Services.

Applies To

DTSMessageQueueTask Object

Syntax

object.DTSMessageLineageID [= GUID]

Part	Description
object	Expression that evaluates to a DTSMessageQueueTask object
GUID	The GUID of the package lineage information saved in Meta Data Services
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetDTSMessageLineageID(BSTR* pVal);

HRESULT SetDTSMessageLineageID(BSTR pVal);

Remarks

The syntax of GUIDs is:

{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}

where X represents hexadecimal digits. The groupings are 8, 4, 4, 4, and 12 digits. The curly brackets are required. Spaces cannot be embedded for readability.

The property also can be referenced through the Properties collection of the Task object with the following code:

Set taskprops = task.Properties
taskprops("DTSMessageLineageID") [= GUID]

See Also

DTSMessagePackageID Property

DTSMessageVersionID Property


DTSMessagePackageID Property

The DTSMessagePackageID property sets or returns the globally unique identifier (GUID) of the Data Transformation Services (DTS) package that is the source of the message this DTSMessageQueueTask object is to receive.

Applies To

DTSMessageQueueTask Object

Syntax

object.DTSMessagePackageID [= GUID]

Part	Description
object	Expression that evaluates to a DTSMessageQueueTask object
GUID	The GUID of the package that is the message source
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetDTSMessagePackageID(BSTR* pVal);

HRESULT SetDTSMessagePackageID(BSTR pVal);

Remarks

The DTSMessagePackageID affects only DTSMessageQueueTask objects that are message receivers.

To determine the package ID of a DTS package, open the package in DTS Designer. In the Package/Properties dialog box, click the General tab.

The syntax of GUIDs is:

{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}

where X represents hexadecimal digits. The groupings are 8, 4, 4, 4, and 12 digits. The curly brackets are required. Spaces cannot be embedded for readability.

The property also can be referenced through the Properties collection of the Task object with the following code:

Set taskprops = task.Properties
taskprops("DTSMessagePackageID") [= GUID]

Example

The following example assigns a GUID string to the DTSMessagePackageID property:

oCustTask.DTSMessagePackageID = _

"{4E078447-0EFE-11D3-8DFE-00C04FD7B78D}"

See Also

DTSMessageLineageID Property

DTSMessageVersionID Property


DTSMessageVersionID Property

The DTSMessageVersionID property sets or returns the globally unique identifier (GUID) of the Data Transformation Services (DTS) package version that is the source of the message this DTSMessageQueueTask object is to receive.

Applies To

DTSMessageQueueTask Object

Syntax

object.DTSMessageVersionID [= GUID]

Part	Description
object	Expression that evaluates to a DTSMessageQueueTask object
GUID	The GUID of the package version that is the message source
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT DTSMessageVersionID(BSTR* pVal);

HRESULT DTSMessageVersionID(BSTR pVal);

Remarks

The DTSMessageVersionID affects only DTSMessageQueueTask objects that are message receivers.

To determine the version ID of a DTS package, open the package in DTS Designer. In the Package/Properties dialog box, click the General tab.

The syntax of GUIDs is:

{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}

where X represents hexadecimal digits. The groupings are 8, 4, 4, 4, and 12 digits. The curly brackets are required. Spaces cannot be embedded for readability.

The property also can be referenced through the Properties collection of the Task object with the following code:

Set taskprops = task.Properties
taskprops("DTSMessageVersionID") [= GUID]

Example

The following example assigns a GUID string to the DTSMessageVersionID property:

oCustTask.DTSMessageVersionID = _

"{4E078447-0EFE-11D3-8DFE-00C04FD7B78D}"

See Also

DTSMessageLineageID Property

DTSMessagePackageID Property


EOF Property

The EOF property specifies whether all the elements have been fetched while iterating through the associated collection.

Applies To

PackageInfos Collection	StepLineages Collection
PackageLineages Collection	StepLogRecords Collection
PackageLogRecords Collection	TaskLogRecords Collection
Syntax

collection.EOF

Part	Description
collection	Expression that evaluates to a collection in the Applies To list
Data Type

Boolean

Modifiable

Read-only

Prototype (C/C++)

HRESULT GetEOF(VARIANT_BOOL *pRetVal);

Remarks

Iterate through a collection by checking the EOF property after calling the Next method. If EOF is TRUE, Next will have returned Nothing and all of the elements will have been fetched. The following Microsoft® Visual Basic® code shows this process:

Set object = collection.Next

Do Until collection.EOF

. . .

Set object = collection.Next

Loop

The collections in the Applies To list also can be processed using For Each ... Next in Visual Basic:

For Each object In collection

. . .

Next object

See Also

Next Method


ErrorCode Property

The ErrorCode property specifies the code for the error that occurred with the associated object.

Applies To

DTSTransformPhaseInfo Object	StepLogRecord Object
PackageLogRecord Object	TaskLogRecord Object
StepLineage Object
Syntax

object.ErrorCode

Part	Description
object	Expression that evaluates to an object in the Applies To list
Data Type

Long

Modifiable

Read-only

Prototype (C/C++)

HRESULT GetErrorCode(long *pRetVal);

Remarks

The following table explains how the interpretation of the ErrorCode property depends on the object with which it is associated.

Object	Description
DTSTransformPhaseInfo	Error code for the operation preceding the current transformation phase.
PackageLogRecord	Error code returned from package Execute method.
StepLineage, StepLogRecord	Error code returned from step Execute method.
TaskLogRecord	Error code associated with this log record, as determined by the logging task.
See Also

DTSDataPumpError

DTSPackageError


ErrorDescription Property

The ErrorDescription property specifies a textual description for the error that occurred with the associated object.

Applies To

PackageLogRecord Object	StepLogRecord Object
StepLineage Object	TaskLogRecord Object
Syntax

object.ErrorDescription

Part	Description
object	Expression that evaluates to an object in the Applies To list
Data Type

String

Modifiable

Read-only

Prototype (C/C++)

HRESULT GetErrorDescription(BSTR *pRetVal);

Remarks

The following table explains how the interpretation of the ErrorDescription property depends on the object with which it is associated.

Object	Description
PackageLogRecord object	Error description returned from package Execute method.
StepLineage, StepLogRecord objects	Error description returned from step Execute method.
TaskLogRecord object	Error description associated with this log record, as determined by the logging task.
See Also

DTSDataPumpError

DTSPackageError

ErrorCode Property


ErrorHelpContext Property

The ErrorHelpContext property specifies a context ID for the error that was returned by the step Execute method.

Applies To

StepLineage Object

Syntax

object.ErrorHelpContext

Part	Description
object	Expression that evaluates to a StepLineage object
Data Type

Long

Modifiable

Read-only

Prototype (C/C++)

HRESULT GetErrorHelpContext(LONG *pRetVal);

Remarks

The context ID returned by ErrorHelpContext can be used to identify the topic that describes the error in the help file specified by the ErrorHelpFile property.

See Also

ErrorCode Property

ErrorDescription Property

ErrorHelpFile Property

ErrorSource Property


ErrorHelpFile Property

The ErrorHelpFile property specifies the name and path of a help file that contains information relevant to the error returned by the step Execute method.

Applies To

StepLineage Object

Syntax

object.ErrorHelpFile

Part	Description
object	Expression that evaluates to a StepLineage object
Data Type

String

Modifiable

Read-only

Prototype (C/C++)

HRESULT GetErrorHelpFile(BSTR *pRetVal);

Remarks

The context ID returned by the ErrorHelpContext property can be used to identify the topic that describes the error in the help file specified by ErrorHelpFile.

See Also

ErrorCode Property

ErrorDescription Property

ErrorHelpContext Property

ErrorSource Property


ErrorIfFileExists Property

The ErrorIfFileExists property specifies or returns a value indicating whether an error is raised if a destination file already exists.

Applies To

DataPumpTransformWriteFile Object

Syntax

object.ErrorIfFileExists [= boolean]

Part	Description
object	Expression that evaluates to a DataPumpTransformWriteFile object
boolean	Boolean that specifies whether an error is raised if the destination file already exists
Data Type

Boolean

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetErrorIfFileExists(VARIANT_BOOL* pRetVal);

HRESULT SetErrorIfFileExists(VARIANT_BOOL pRetVal);

Remarks

If FALSE, the existing file is overwritten.

The property also can be referenced through the TransformServerProperties collection with the following code:

Set transprops = transform.TransformServerProperties
transprops("ErrorIfFileExists") [= boolean]

See Also

AppendIfFileExists Property

ErrorIfFileNotFound Property


ErrorIfFileNotFound Property

The ErrorIfFileNotFound property specifies or returns a value indicating whether an error is raised if a file named by a source column does not exist.

Applies To

DataPumpTransformReadFile Object

Syntax

object.ErrorIfFileNotFound [= boolean]

Part	Description
object	Expression that evaluates to a DataPumpTransformReadFile object
boolean	Boolean that specifies whether an error is raised when the file named by a source column does not exist
Data Type

Boolean

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetErrorIfFileNotFound(VARIANT_BOOL* pRetVal);

HRESULT SetErrorIfFileNotFound(VARIANT_BOOL pRetVal);

Remarks

If FALSE, NULL is written to the destination column.

The property also can be referenced through the TransformServerProperties collection with the following code:

Set transprops = transform.TransformServerProperties
transprops("ErrorIfFileNotFound") [= boolean]

See Also

ErrorIfFileExists Property


ErrorIfReceiveMessageTimeout Property

The ErrorIfReceiveMessageTimeout property sets or returns a value indicating whether an error is raised if a message is not found in the specified queue after the specified time-out value.

Applies To

DTSMessageQueueTask

Syntax

object.ErrorIfReceiveMessageTimeout [= boolean]

Part	Description
object	Expression that evaluates to a DTSMessageQueueTask object
boolean	Boolean that specifies whether an error is raised if a message is not found in the queue after the time-out expires
Data Type

Boolean

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetErrorIfReceiveMessageTimeout(VARIANT_BOOL* pVal);

HRESULT GetErrorIfReceiveMessageTimeout(VARIANT_BOOL pVal);

Remarks

Default is FALSE.

The property also can be referenced through the Properties collection of the Task object with the following code:

Set taskprops = task.Properties
taskprops("ErrorIfReceiveMessageTimeout") [= boolean]

See Also

ReceiveMessageTimeout Property


ErrorSource Property

The ErrorSource property specifies the name of the component that generated the error returned by the step Execute method.

Applies To

StepLineage Object

Syntax

object.ErrorSource

Part	Description
object	Expression that evaluates to a StepLineage object
Data Type

String

Modifiable

Read-only

Prototype (C/C++)

HRESULT GetErrorSource(BSTR *pRetVal);

See Also

ErrorCode Property

ErrorDescription Property

ErrorHelpContext Property

ErrorHelpFile Property


ExceptionFileColumnDelimiter Property

The ExceptionFileColumnDelimiter property specifies the column delimiter in the exception file.

Applies To

DataDrivenQueryTask Object	DataPumpTask2 Object
DataDrivenQueryTask2 Object	TransformationSet Object
DataPumpTask Object
Syntax

object.ExceptionFileColumnDelimiter [= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	Column delimiter for the exception file
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetExceptionFileColumnDelimiter(BSTR *pRetVal);

HRESULT SetExceptionFileColumnDelimiter(BSTR NewValue);

Remarks

The default is "|".

See Also

ExceptionFileName Property

ExceptionFileOptions Property

ExceptionFileRowDelimiter Property

ExceptionFileTextQualifier Property


ExceptionFileName Property

The ExceptionFileName property specifies the file name path where exception rows are written.

Applies To

DataDrivenQueryTask Object	DataPumpTask2 Object
DataDrivenQueryTask2 Object	TransformationSet Object
DataPumpTask Object
Syntax

object.ExceptionFileName [= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	Exception file specification
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetExceptionFileName(BSTR *pRetVal);

HRESULT SetExceptionFileName(BSTR NewValue);

Remarks

After the task is complete, this file can be used to edit and resubmit the rows manually.

See Also

ExceptionFileColumnDelimiter Property

ExceptionFileOptions Property

ExceptionFileRowDelimiter Property

ExceptionFileTextQualifier Property


ExceptionFileOptions Property

The ExceptionFileOptions property specifies how Data Transformation Services (DTS) data pump errors and exception rows are written to the exception and error files.

Applies To

DataDrivenQueryTask2 Object	TransformationSet Object
DataPumpTask2 Object
Syntax

object.ExceptionFileOptions [= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	A sum of values from DTSExceptionFileOptions
Data Type

DTSExceptionFileOptions

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetExceptionFileOptions(DTSExceptionFileOptions *pRetVal);

HRESULT SetExceptionFileOptions(DTSExceptionFileOptions NewValue);

See Also

ExceptionFileColumnDelimiter Property

ExceptionFileName Property

ExceptionFileRowDelimiter Property

ExceptionFileTextQualifier Property


ExceptionFileRowDelimiter Property

The ExceptionFileRowDelimiter property specifies the row delimiter for the data in the exception file.

Applies To

DataDrivenQueryTask Object	DataPumpTask2 Object
DataDrivenQueryTask2 Object	TransformationSet Object
DataPumpTask Object
Syntax

object.ExceptionFileRowDelimiter [= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	Exception file row delimiter
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetExceptionFileRowDelimiter(BSTR *pRetVal);

HRESULT SetExceptionFileRowDelimiter(BSTR NewValue);

Remarks

The default is carriage return/line feed (CR/LF).

See Also

ExceptionFileColumnDelimiter Property

ExceptionFileName Property

ExceptionFileOptions Property

ExceptionFileTextQualifier Property


ExceptionFileTextQualifier Property

The ExceptionFileTextQualifier property specifies the text qualifier for the data in the exception file.

Applies To

DataDrivenQueryTask2 Object	TransformationSet Object
DataPumpTask2 Object
Syntax

object.ExceptionFileTextQualifier [= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	Exception file text qualifier
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetExceptionFileTextQualifier(BSTR *pRetVal);

HRESULT SetExceptionFileTextQualifier(BSTR NewValue);

Remarks

The default is no text qualifier.

See Also

ExceptionFileColumnDelimiter Property

ExceptionFileName Property

ExceptionFileOptions Property

ExceptionFileRowDelimiter Property


ExecuteInMainThread Property

The ExecuteInMainThread property specifies whether the step executes in the main thread of the Data Transformation Services (DTS) package or a worker thread.

Applies To

Step Object	Step2 Object
Syntax

object.ExecuteInMainThread [= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	Whether the step executes in the main thread of the package
Data Type

Boolean

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetExecuteInMainThread(VARIANT_BOOL *pRetVal);

HRESULT SetExecuteInMainThread(VARIANT_BOOL NewValue);

Remarks

The default is FALSE.

If you are implementing package event handlers in Microsoft® Visual Basic®, set ExecuteInMainThread to TRUE for all steps in the package.

See Also

DTS Package Events in Visual Basic


ExecutionDate Property

The ExecutionDate property specifies the date and time a Data Transformation Services (DTS) package lineage record was written.

Applies To

PackageLineage Object

Syntax

object.ExecutionDate

Part	Description
object	Expression that evaluates to a PackageLineage object
Data Type

Date

Modifiable

Read-only

Prototype (C/C++)

HRESULT GetExecutionDate(DATE *pRetVal);

See Also

ExecutionTime Property

StartTime Property


ExecutionResult Property

The ExecutionResult property returns the step execution result.

Applies To

Step Object	Step2 Object
Syntax

object.ExecutionResult

Part	Description
object	Expression that evaluates to an object in the Applies To list
Data Type

DTSStepExecResult

Modifiable

Read-only

Prototype (C/C++)

HRESULT GetExecutionResult(DTSStepExecResult *pRetVal);

Remarks

The ExecutionResult value indicates success or failure.

See Also

ExecutionStatus Property

StepExecutionResult Property


ExecutionStatus Property

The ExecutionStatus property specifies the status of the step.

Applies To

Step Object	Step2 Object
Syntax

object.ExecutionStatus

Part	Description
object	Expression that evaluates to an object in the Applies To list
Data Type

DTSStepExecStatus

Modifiable

Read-only

Prototype (C/C++)

HRESULT GetExecutionStatus(DTSStepExecStatus *pRetVal);

Remarks

Use the step ExecutionStatus to determine whether a step:

•	Is waiting to be executed.

•	Is in progress.

•	Has completed with success or failure.

•	Has been skipped.

See Also

ExecutionResult Property

StepExecutionStatus Property


ExecutionTime Property

The ExecutionTime property specifies the total execution time, in seconds, of the associated object.

Applies To

PackageLogRecord Object	StepLineage Object
Step Object	StepLogRecord Object
Step2 Object
Syntax

object.ExecutionTime

Part	Description
object	Expression that evaluates to an object in the Applies To list
Data Type

Double

Modifiable

Read-only

Prototype (C/C++)

HRESULT GetExecutionTime(double *pRetVal);

Remarks

ExecutionTime of a PackageLogRecord is the total execution time of the Data Transformation Services (DTS) package. For the other objects, ExecutionTime refers to an individual step.

See Also

FinishTime Property

StartTime Property


ExplicitGlobalVariables Property

The ExplicitGlobalVariables property sets or returns a value indicating whether Data Transformation Services (DTS) package global variables must be explicitly added to the GlobalVariables collection with the AddGlobalVariable method before being referenced.

Applies To

Package2 Object

Syntax

object.ExplicitGlobalVariables [= boolean]

Part	Description
object	Expression that evaluates to a Package2 object.
boolean	If TRUE, package global variables must be explicitly added with AddGlobalVariable method. If FALSE, reference to global variables that do not exist cause them to be created.
Data Type

Boolean

Modifiable

Read/write

Prototype (C/C++)

HRESULT ExplicitGlobalVariables(VARIANT_BOOL* pVal);

HRESULT ExplicitGlobalVariables(VARIANT_BOOL pVal);

See Also

AddGlobalVariable Method

AddGlobalVariables Property

GlobalVariables Collection


 FailOnError Property

The FailOnError property specifies whether Data Transformation Services (DTS) package execution stops when there is an error in any step.

Applies To

Package Object	Package2 Object
Syntax

object.FailOnError [= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	Boolean that specifies whether the package execution stops when there is an error
Data Type

Boolean

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetFailOnError(VARIANT_BOOL *pRetVal);

HRESULT SetFailOnError(VARIANT_BOOL NewValue);

Remarks

The default is FALSE.

In Microsoft® Visual Basic®, errors will not be raised for the caller of the Execute method unless FailOnError is TRUE or FailPackageOnError is TRUE for the step in which the error occurs. When that happens, the error description will identify only the step that failed. To determine the reason for failure, use the GetExecutionErrorInfo method of the step.

See Also

Execute Method

FailPackageOnError Property

GetExecutionErrorInfo Method


FailPackageOnError Property

The FailPackageOnError property specifies whether Data Transformation Services (DTS) package execution stops when there is an error in the step with which it is associated.

Applies To

Step2 Object

Syntax

object.FailPackageOnError [= value]

Part	Description
Object	Expression that evaluates to a Step2 object
Value	Whether the package execution stops when there is an error in the step
Data Type

Boolean

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetFailPackageOnError(VARIANT_BOOL *pRetVal);

HRESULT SetFailPackageOnError(VARIANT_BOOL NewValue);

Remarks

The default is FALSE.

In Microsoft® Visual Basic®, errors will not be raised for the caller of the Execute method unless the package FailOnError is TRUE or FailPackageOnError is TRUE for the step in which the error occurs. When that happens, the error description will identify only the step that failed. To determine the reason for failure, use the GetExecutionErrorInfo method of the step.

See Also

Execute Method

FailOnError Property

GetExecutionErrorInfo Method


FailPackageOnLogFailure Property

The FailPackageOnLogFailure property sets or returns a value indicating whether the Data Transformation Services (DTS) package will fail if there is a failure during the logging of the package.

Applies To

Package2 Object

Syntax

object.FailPackageOnLogFailure [= boolean]

Part	Description
Object	Expression that evaluates to a Package2 object.
Boolean	If TRUE, the package fails if there is a failure during logging.
Data Type

Boolean

Modifiable

Read/write

Prototype (C/C++)

HRESULT FailPackageOnLogFailure(VARIANT_BOOL* pVal);

HRESULT FailPackageOnLogFailure(VARIANT_BOOL pVal);

Remarks

The default is FALSE.

See Also

LogServerFlags Property

LogServerName Property

LogServerPassword Property

LogServerUserName Property

LogToSQLServer Property


FailPackageOnTimeout Property

The FailPackageOnTimeout property specifies whether the Data Transformation Services (DTS) package fails if the task is terminated by the expiration of the time-out period.

Applies To

CreateProcessTask Object	CreateProcessTask2 Object
Syntax

object.FailPackageOnTimeout [= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	Boolean that specifies whether the package fails if the task is terminated by the expiration of the time-out period
Data Type

Variant Boolean

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetFailPackageOnTimeout(VARIANT_BOOL *pRetVal);

HRESULT SetFailPackageOnTimeout(VARIANT_BOOL NewValue);

Remarks

The default is TRUE.

The TerminateProcessAfterTimeout property determines if the created process is terminated after the time-out occurs.

See Also

TerminateProcessAfterTimeout Property

Timeout Property


FastLoadOptions Property

The FastLoadOptions property specifies SQLOLEDB destination connection options specific for the UseFastLoad property.

Applies To

DataPumpTask Object	DataPumpTask2 Object
Syntax

object.FastLoadOptions[= value]

Part	Description
Object	Expression that evaluates to an object in the Applies To list
value	SQLOLEDB destination connection options
Data Type

DTSFastLoadOptions

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetFastLoadOptions(DTSFastLoadOptions *pRetVal);

HRESULT SetFastLoadOptions(DTSFastLoadOptions NewValue);

Remarks

FastLoadOptions must be set to the sum of one or more of the DTSFastLoadOptions values.

See Also

InsertCommitSize Property

UseFastLoad Property


FetchBufferSize Property

The FetchBufferSize property specifies the number of rows to fetch in a single operation from the OLE DB source.

Applies To

DataDrivenQueryTask Object	DataPumpTask2 Object
DataDrivenQueryTask2 Object	TransformationSet Object
DataPumpTask Object
Syntax

object.FetchBufferSize [= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	Number of rows to fetch in a single operation
Data Type

Long

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetFetchBufferSize(LONG *pRetVal);

HRESULT SetFetchBufferSize(LONG NewValue);

Remarks

Each row may be buffered by the OLE DB provider. When calling IRowset::GetNextRows, adjust the FetchBufferSize property to achieve the best balance between memory usage and reduced overhead. A value greater than 1 is ignored if the data source uses binary large object (BLOB) storage. The default is 100.

See Also

InsertCommitSize Property


FieldTerminator Property

The FieldTerminator property specifies the field or column terminator for files that support char and widechar data types.

Applies To

BulkInsertTask Object

Syntax

object.FieldTerminator [= value]

Part	Description
object	Expression that evaluates to a BulkInsertTask object
value	Field terminator
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetFieldTerminator(BSTR *pRetVal);

HRESULT SetFieldTerminator(BSTR NewValue);

Remarks

Typical values are ",", ";", tab and "|". These values are also valid in the bulk copy program. The default is tab. It must not be the same as the RowTerminator property.

See Also

RowTerminator Property


FileAttachments Property

The FileAttachments property specifies the name and path of file attachments.

Applies To

SendMailTask Object

Syntax

object.FileAttachments[= value]

Part	Description
object	Expression that evaluates to a SendMailTask object
value	File specifications of attachments
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetFileAttachments(BSTR *pRetVal);

HRESULT SetFileAttachments(BSTR NewValue);

Remarks

Multiple attachment file specifications are separated by semicolons.

See Also

CCLine Property

Subject Property

ToLine Property


FileColumnName Property

The FileColumnName property specifies or returns the name of the source column that contains the name of the file to be written. It must be one of the two source columns of the transformation.

Applies To

DataPumpTransformWriteFile Object

Syntax

object.FileColumnName [= string]

Part	Description
object	Expression that evaluates to a DataPumpTransformWriteFile object
string	Name of the source column that contains the name and optional path of file to be written
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetFileColumnName(BSTR* pRetVal);

HRESULT SetFileColumnName(BSTR pRetVal);

Remarks

The FileColumnName must be a string data type. It cannot be NULL or empty, and the data column to which it refers cannot be NULL or empty. If the file name column contains a path, it can use either a drive letter or a universal naming convention (UNC) name.

If no path is present, the FilePath property can be used to supply the path. However, FilePath is always used when it is contains a value, even when the file name column contains a path.

The property also can be referenced through the TransformServerProperties collection with the following code:

Set transprops = transform.TransformServerProperties
transprops("FileColumnName") [= string]

See Also

FilePath Property


FileName Property

The FileName property sets or returns the name and path of the file that contains a Data Transformation Services (DTS) package to be run by an Execute Package Task object.

Applies To

ExecutePackageTask Object

Syntax

object.FileName [= filespec]

Part	Description
object	Expression that evaluates to an ExecutePackageTask object
filespec	Name and path of the file that contains the package
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetFileName(BSTR* pRetVal);

HRESULT SetFileName(BSTR pRetVal);

Remarks

If the FileName property is empty, the ExecutePackageTask object looks in Microsoft® SQL Server™ 2000 Meta Data Services or in the SQL Server msdb database (depending on the setting of the UseRepository property) on the specified server to find the package to be run.

This property also can be referenced through the Properties collection of the Task object with the following code:

Set taskprops = task.Properties
taskprops("FileName") [= filespec]

Example

The following example assigns a file specification to the FileName property:

objCustTask.FileName = "C:\DTS_UE\TestPkg\WriteFileTest.dts"

See Also

PackageName Property

UseRepository Property


FilePath Property

The FilePath property specifies or returns the path you want to prefix to the file name column in a custom transformation.

Applies To

DataPumpTransformReadFile Object	DataPumpTransformWriteFile Object
Syntax

object.FilePath [= string]

Part	Description
object	Expression that evaluates to an object in the Applies To list
string	Path to prefix to the file name column when it contains no path
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetFilePath(BSTR* pRetVal);

HRESULT SetFilePath(BSTR pRetVal);

Remarks

"\" will be appended to the FilePath property, when necessary, to separate the path from the file name in the source column. If a value for FilePath is provided, the value will be prefixed to the file name even when it already includes a path.

The property also can be referenced through the TransformServerProperties collection with the following code:

Set transprops = transform.TransformServerProperties
transprops(“FilePath”) [= string]

See Also

FileColumnName Property


FinishTime Property

The FinishTime property specifies the date and time when the associated object completed its execution.

Applies To

PackageLogRecord Object	StepLineage Object
Step Object	StepLogRecord Object
Step2 Object
Syntax

object.FinishTime

Part	Description
object	Expression that evaluates to an object in the Applies To list
Data Type

Date

Modifiable

Read-only

Prototype (C/C++)

HRESULT GetFinishTime(DATE *pRetVal);

See Also

ExecutionTime Property

StartTime Property


FirstRow Property

The FirstRow property specifies the first source row to copy.

Applies To

BulkInsertTask Object	DataPumpTask Object
DataDrivenQueryTask Object	DataPumpTask2 Object
DataDrivenQueryTask2 Object	TransformationSet Object
Syntax

object.FirstRow[= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	First source row to copy
Data Type

Variant

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetFirstRow(VARIANT *pRetVal);

HRESULT SetFirstRow(VARIANT NewValue);

Remarks

The default is 1, which specifies the first row.

See Also

LastRow Property


Flags Property

The Flags property specifies the OLE DB DBCOLUMN values that describe a column.

Applies To

Column Object

Syntax

object.Flags [= value]

Part	Description
object	Expression that evaluates to a Column object
value	Sum of OLE DB DBCOLUMN values
Data Type

Long

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetFlags(LONG *pRetVal);

HRESULT SetFlags(LONG NewValue);

Remarks

You can find the valid values for the Flags property by searching for DBCOLUMNFLAGS_ in the include file OLEDB.h. This default location for this file is C:\Program Files\Microsoft SQL Server\80\Tools\DevTools\include\.

See Also

DataType Property


ForceBlobsInMemory Property

The ForceBlobsInMemory property specifies whether to store each source binary large object (BLOB) column in a transformation as a single memory allocation, even if storage objects are available from the OLE DB provider.

Applies To

Transformation Object	Transformation2 Object
Syntax

object.ForceBlobsInMemory [= value]

Part	Description
Object	Expression that evaluates to an object in the Applies To list
Value	Boolean that specifies whether to store each source BLOB column in a transformation as a single memory allocation
Data Type

Boolean

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetForceBlobsInMemory(VARIANT_BOOL *pRetVal);

HRESULT SetForceBlobsInMemory(VARIANT_BOOL NewValue);

Remarks

BLOBs are image, ntext, and text data types.

See Also

ForceSourceBlobsBuffered Property


ForceSourceBlobsBuffered Property

The ForceSourceBlobsBuffered property specifies whether to buffer each source binary large object (BLOB) column in a transformation if storage objects are used.

Applies To

Transformation Object	Transformation2 Object
Syntax

object.ForceSourceBlobsBuffered [= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	A value indicating whether to buffer each source BLOB column in a transformation
Data Type

DTSForceMode

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetForceSourceBlobsBuffered(DTSForceMode *pRetVal);

HRESULT SetForceSourceBlobsBuffered(DTSForceMode NewValue);

Remarks

BLOBs are image, ntext, and text data types.

ForceSourceBlobsBuffered must be set to one of the DTSForceMode values.

See Also

ForceBlobsInMemory Property


FormatFile Property

The FormatFile property specifies the name and path of a bulk copy data file to use for the load operation.

Applies To

BulkInsertTask Object

Syntax

object.FormatFile [= value]

Part	Description
object	Expression that evaluates to a BulkInsertTask object
value	Specification for the bulk copy data file
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetFormatFile(BSTR *pRetVal);

HRESULT SetFormatFile(BSTR NewValue);

Remarks

The format of the bulk copy data file must be acceptable to the bcp utility.

See Also

DataFile Property


FunctionEntry Property

The FunctionEntry property specifies or returns the name of the script function that is to be called for the transformation.

Applies To

DataPumpTransformationScript Object	DTSTransformScriptProperties2 Object
Syntax

object.FunctionEntry [= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	Function to call in the script
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetFunctionEntry(*pRetVal);

HRESULT SetFunctionEntry(NewValue);

Remarks

In the DTSTransformScriptProperties2 object, the FunctionEntry property specifies the function name for the Transform phase. In the DataPumpTransformScript object, the Transform phase is the only transformation phase.

The script function specified by FunctionEntry has read access to the columns of the DTSSource collection and write access to the columns of the DTSDestination collection. The valid function return values are specified by the DTSTransformStatus constants.

The property also can be referenced through the TransformServerProperties collection with the following code:

Set transprops = transform.TransformServerProperties
transprops("FunctionEntry") [= string]

See Also

BatchCompleteFunctionEntry Property

DataDrivenQueryTask2 Object

DataPumpTask2 Object

DTSTransformStatus

InsertFailureFunctionEntry Property

InsertSuccessFunctionEntry Property

ParallelDataPumpTask Object

PostSourceDataFunctionEntry Property

PreSourceDataFunctionEntry Property

PumpCompleteFunctionEntry Property

TransformFailureFunctionEntry Property


FunctionName Property

The FunctionName property specifies the function name to call in the Microsoft® ActiveX® script associated with a script task or step.

Applies To

ActiveScriptTask Object	Step2 Object
Step Object
Syntax

object.FunctionName [= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	Function name that is the script entry point for the step or ActiveX Script task
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetFunctionName(BSTR *pRetVal);

HRESULT SetFunctionName(BSTR NewValue);

See Also

ActiveXScript Property

ScriptLanguage PropertyFunctionEntry Property


Get Property

The Get property specifies whether a property value can be read.

Applies To

Property Object

Syntax

object.Get

Part	Description
object	Expression that evaluates to a Property object
Data Type

Boolean

Modifiable

Read-only

Prototype (C/C++)

HRESULT GetGet(VARIANT_BOOL *pRetVal);

See Also

Set Property


IconFile Property

The IconFile property returns the name and path of the resource file that contains the icon for the task class.

Applies To

TaskInfo Object

Syntax

object.IconFile

Part	Description
object	Expression that evaluates to a TaskInfo object
Data Type

String

Modifiable

Read-only

Prototype (C/C++)

HRESULT GetIconFile(BSTR* pRetVal);

Example

The following example shows a value returned by the IconFile property:

C:\Program Files\Microsoft SQL Server\80\Tools\Binn\Resources\1033\custtask.RLL

See Also

IconIndex Property


IconIndex Property

The IconIndex property returns an index that identifies the icon for the task class in the resource file that contains it.

Applies To

TaskInfo Object

Syntax

object.IconIndex

Part	Description
object	Expression that evaluates to a TaskInfo object
Data Type

Long

Modifiable

Read-only

Prototype (C/C++)

HRESULT GetIconIndex(long* pRetVal);

Remarks

The IconIndex property is zero based.

The resource file specification is available from the IconFile property.

See Also

IconFile Property


ID Property

The ID property returns a unique numeric identifier assigned to a connection.

Applies To

Connection Object	Connection2 Object
Syntax

object.ID [= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	Unique numeric identifier assigned to a connection
Data Type

Long

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetID(LONG *pRetVal);

HRESULT SetID(LONG NewValue);

Remarks

Other Data Transformation Services (DTS) objects that use connections use the ID property to link to those connections.

See Also

ConnectionID Property

DestinationConnectionID Property

SourceConnectionID Property

SourceQueryConnectionID Property


ImplementationFileName Property

The ImplementationFileName property returns the name and path of the library file that implements the object class.

Applies To

OLEDBProviderInfo Object	TaskInfo Object
ScriptingLanguageInfo Object	TransformationInfo Object
Syntax

object.ImplementationFileName

Part	Description
object	Expression that evaluates to an object in the Applies To list
Data Type

String

Modifiable

Read-only

Prototype (C/C++)

HRESULT GetImplementationFileName(BSTR* pRetVal);

Example

The following example shows a value returned by the ImplementationFileName property:

C:\Program Files\Common Files\System\OLE DB\sqloledb.dll

See Also

ImplementationFileVersionString Property


ImplementationFileVersionString Property

The ImplementationFileVersionString property returns the version number of the library file that implements the object class.

Applies To

OLEDBProviderInfo Object	TaskInfo Object
ScriptingLanguageInfo Object	TransformationInfo Object
Syntax

object.ImplementationFileVersionString

Part	Description
object	Expression that evaluates to an object in the Applies To list
Data Type

String

Modifiable

Read-only

Prototype (C/C++)

HRESULT GetImplementationFileVersionString(BSTR* pRetVal);

Example

The following examples show values returned by the ImplementationFileVersionString property. No particular syntax is enforced:

08.00.0045

2000.02.04

See Also

ImplementationFileName Property


IncludeDependencies Property

The IncludeDependencies property specifies whether dependent objects are scripted and transferred during a transfer of Microsoft® SQL Server™ objects.

Applies To

TransferObjectsTask Object	TransferObjectsTask2 Object
Syntax

object.IncludeDependencies[= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	A value indicating whether dependent objects are scripted and transferred
Data Type

Boolean

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetIncludeDependencies(VARIANT_BOOL *pRetVal);

HRESULT SetIncludeDependencies(VARIANT_BOOL NewValue);

Remarks

The default is FALSE.

See Also

CopyAllObjects Property

CopyData Property

CopySchema Property

DropDestinationObjectsFirst Property

IncludeLogins Property

IncludeUsers Property


IncludeLogins Property

The IncludeLogins property specifies whether the logins on the source are scripted and transferred during a transfer of Microsoft® SQL Server™ objects.

Applies To

TransferObjectsTask Object	TransferObjectsTask2 Object
Syntax

object.IncludeLogins[= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	A value indicating whether the logins on the source are scripted and transferred
Data Type

Boolean

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetIncludeLogins(VARIANT_BOOL *pRetVal);

HRESULT SetIncludeLogins(VARIANT_BOOL NewValue);

Remarks

The default is FALSE.

See Also

CopyAllObjects Property

CopyData Property

CopySchema Property

DropDestinationObjectsFirst Property

IncludeDependencies Property

IncludeUsers Property


IncludeUsers Property

The IncludeUsers property specifies whether the database users on the source are scripted and transferred during the transfer of Microsoft® SQL Server™ objects.

Applies To

TransferObjectsTask Object	TransferObjectsTask2 Object
Syntax

object.IncludeUsers[= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	Boolean that specifies whether the database users on the source are scripted and transferred
Data Type

Boolean

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetIncludeUsers(VARIANT_BOOL *pRetVal);

HRESULT SetIncludeUsers(VARIANT_BOOL NewValue);

Remarks

The default is FALSE.

See Also

CopyAllObjects Property

CopyData Property

CopySchema Property

DropDestinationObjectsFirst Property

IncludeDependencies Property

IncludeLogins Property


InMemoryBlobSize Property

The InMemoryBlobSize property specifies the byte size of per-column allocation for in-memory binary large objects (BLOBs) in a transformation.

Applies To

Transformation Object	Transformation2 Object
Syntax

object.InMemoryBlobSize [= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	Byte size of per-column allocation for in-memory BLOBs
Data Type

Long

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetInMemoryBlobSize(LONG *pRetVal);

HRESULT SetInMemoryBlobSize(LONG NewValue);

Remarks

BLOBs are image, ntext, and text data types.

See Also

ForceSourceBlobsBuffered Property


InputFormat Property

The InputFormat property specifies or returns a string that defines the format of the datetime string in the source column. This format string consists of tokens and delimiters: the tokens represent components of the date and time, and the delimiters must explicitly appear in the source column.

Applies To

DataPumpTransformDateTimeString Object

Syntax

object.InputFormat [= formatstring]

Part	Description
object	Expression that evaluates to a DataPumpTransformDateTimeString object.
formatstring	String consisting of tokens and delimiters, which define the format of the source column.
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT InputFormat(BSTR* pRetVal);

HRESULT InputFormat(BSTR pRetVal);

Remarks

For more information about token definitions, see OutputFormat Property.

The property also can be referenced through the TransformServerProperties collection with the following code:

Set transprops = transform.TransformServerProperties
transprops("InputFormat") [= name]

See Also

AMSymbol Property

Day?LongName Property

Day?ShortName Property

GetDayLongName Method

GetDayShortName Method

GetMonthLongName Method

GetMonthShortName Method

Month??LongName Property

Month??ShortName Property

PMSymbol Property

SetDayLongName Method

SetDayShortName Method

SetMonthLongName Method

SetMonthShortName Method

ShortYear2000Cutoff Property


InputGlobalVariableNames Property

The InputGlobalVariableNames property returns or specifies a list of Data Transformation Services (DTS) global variable names that are to be used as parameters in a query or created in a subpackage.

Applies To

DataDrivenQueryTask2 Object	ExecuteSQLTask2 Object
DataPumpTask2 Object	ParallelDataPumpTask Object
ExecutePackageTask Object
Syntax

object.InputGlobalVariableNames [= list]

Part	Description
object	Expression that evaluates to an object in the Applies To list
list	List of global variable names
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetInputGlobalVariableNames(BSTR *pRetVal);

HRESULT SetInputGlobalVariableNames(BSTR NewValue);

Remarks

The format of the InputGlobalVariableNames string is a semicolon delimited, optionally double-quoted or single-quoted list. Quoting is required only when the name contains an embedded delimiter. Embedded delimiters must be doubled. A double-delimiter or a trailing delimiter indicates an empty item. For example:

"gv1";gv2       - delimiters not required here

gv1;"gv""2"     - gv"2 embedded delimiter is doubled

gv1;;gv2;       - contains an empty second and fourth item

The following table describes how the usage of the InputGlobalVariableNames list depends on the associated object.

Associated Object	Usage
ExecutePackageTask	Global variables from the collection of the outer DTS package are created or assigned to global variables in the target package. Empty items in the list are skipped.
DataDrivenQueryTask2 DataPumpTask2 ExecuteSQLTask2 ParallelDataPumpTask	Global variables from the collection of the package are substituted for parameters in the source query. Empty items in the list cause the corresponding parameter in the query to be bound to NULL.
See Also

GlobalVariables Collection

SourceSQLStatement Property

SQLStatement Property


InsertCommitSize Property

The InsertCommitSize property specifies the number of rows that are inserted in a single transaction when the FastLoad option is being used.

Applies To

DataPumpTask Object	DataPumpTask2 Object
Syntax

object.InsertCommitSize [= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	Number of rows inserted as a single transaction
Data Type

Long

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetInsertCommitSize(LONG *pRetVal);

HRESULT SetInsertCommitSize(LONG NewValue);

Remarks

The default is 0. This means all inserts into the table are batched in a single transaction.

See Also

FastLoadOptions Property

UseFastLoad Property


InsertFailureFunctionEntry Property

The InsertFailureFunctionEntry property specifies or returns the name of the script function that is to be called for the OnInsertFailure transformation phase.

Applies To

DTSTransformScriptProperties2 Object

Syntax

object.InsertFailureFunctionEntry [= name]

Part	Description
object	Expression that evaluates to a DTSTransformScriptProperties2 object
name	Name of the script function that supports the OnInsertFailure phase
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT InsertFailureFunctionEntry(BSTR* pRetVal);

HRESULT InsertFailureFunctionEntry(BSTR pRetVal);

Remarks

The OnInsertFailure phase occurs when an Insert to the destination fails in the DataPumpTask2 or ParallelDataPumpTask object or after the failure of any of the queries in the DataDrivenQueryTask2 object.

The OnInsertFailure script function has read access to the columns of the DTSSource collection and no access to the columns of the DTSDestination collection. The only valid return values are DTSTransformStat_OK and DTSTransformStat_AbortPump.

The property also can be referenced through the TransformServerProperties collection with the following code:

Set transprops = transform.TransformServerProperties
transprops("InsertFailureFunctionEntry") [= string]

See Also

BatchCompleteFunctionEntry Property

DataDrivenQueryTask2 Object

DataPumpTask2 Object

DTSTransformStatus

FunctionEntry Property

InsertSuccessFunctionEntry Property

ParallelDataPumpTask Object

PostSourceDataFunctionEntry Property

PreSourceDataFunctionEntry Property

PumpCompleteFunctionEntry Property

TransformFailureFunctionEntry Property


InsertQuery Property

The InsertQuery property specifies a string of one or more parameterized SQL statements to execute at the destination as the insert query.

Applies To

DataDrivenQueryTask Object	TransformationSet Object
DataDrivenQueryTask2 Object
Syntax

object.InsertQuery [= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	Parameterized string of SQL statements
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetInsertQuery(BSTR *pRetVal);

HRESULT SetInsertQuery(BSTR NewValue);

Remarks

Although the name of a data-driven query property is preset, its content is not enforced. Any of the queries may be used for any desired operation. The nomenclature is provided as a convenient means of identification, based upon the primary purpose of the operation. For example, the InsertQuery property does not need to contain an INSERT statement.

See Also

DeleteQuery Property

DTS Query Strings in Visual BasicInsertQueryColumns Property

UpdateQuery Property

UserQuery Property


InsertQueryColumns Property

The InsertQueryColumns property returns a reference to a collection of column parameters in sequential order for the InsertQuery parameter.

Applies To

DataDrivenQueryTask Object	TransformationSet Object
DataDrivenQueryTask2 Object
Syntax

object.InsertQueryColumns

Part	Description
object	Expression that evaluates to an object in the Applies To list
Data Type

Columns Collection

Modifiable

Read-only

Prototype (C/C++)

HRESULT GetInsertQueryColumns(IDTSColumns **pRetVal);

See Also

Column Object

DeleteQueryColumns Property

DTS Query Strings in Visual Basic

InsertQuery Property

UpdateQueryColumns Property

UserQueryColumns Property


InsertSuccessFunctionEntry Property

The InsertSuccessFunctionEntry property specifies or returns the name of the script function that is to be called for the OnInsertSuccess transformation phase.

Applies To

DTSTransformScriptProperties2 Object

Syntax

object.InsertSuccessFunctionEntry [= name]

Part	Description
object	Expression that evaluates to a DTSTransformScriptProperties2 object
name	Name of the script function that supports the OnInsertSuccess phase
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT InsertSuccessFunctionEntry(BSTR* pRetVal);

HRESULT InsertSuccessFunctionEntry(BSTR pRetVal);

Remarks

The OnInsertSuccess phase occurs when an Insert to the destination succeeds in the DataPumpTask2 or ParallelDataPumpTask object or after the success of any of the queries in the DataDrivenQueryTask2 object.

The OnInsertSuccess script function has read access to the columns of the DTSSource collection and no access to the columns of the DTSDestination collection. The only valid return values are DTSTransformStat_OK and DTSTransformStat_AbortPump.

The property also can be referenced through the TransformServerProperties collection with the following code:

Set transprops = transform.TransformServerProperties
transprops("InsertSuccessFunctionEntry") [= string]

See Also

BatchCompleteFunctionEntry Property

DataDrivenQueryTask2 Object

DataPumpTask2 Object

DTSTransformStatus

FunctionEntry Property

InsertFailureFunctionEntry Property

ParallelDataPumpTask Object

PostSourceDataFunctionEntry Property

PreSourceDataFunctionEntry Property

PumpCompleteFunctionEntry Property

TransformFailureFunctionEntry Property


InTransaction Property

The InTransaction property specifies whether the connection is included in the current Data Transformation Services (DTS) package transaction, if one exists.

Applies To

Connection Object	Connection2 Object
Syntax

object.InTransaction

Part	Description
object	Expression that evaluates to an object in the Applies To list
Data Type

Boolean

Modifiable

Read-only

Prototype (C/C++)

HRESULT GetInTransaction(VARIANT_BOOL *pRetVal);

See Also

JoinTransactionIfPresent Property

TransactionIsolationLevel Property

UseTransaction Property


InUse Property

The InUse property specifies whether the connection is currently in use by a task.

Applies To

Connection Object	Connection2 Object
Syntax

object.InUse

Part	Description
object	Expression that evaluates to an object in the Applies To list
Data Type

Boolean

Modifiable

Read-only

Prototype (C/C++)

HRESULT GetInUse(VARIANT_BOOL *pRetVal);

Remarks

When an application calls the connection AcquireConnection method, the InUse property is set to TRUE.

See Also

AcquireConnection Method

ReleaseConnection Method


IsDefaultValue Property

The IsDefaultValue property specifies whether the OLE DB property to which it refers has not been explicitly set to a value.

Applies To

OLEDBProperty2 Object

Syntax

oledbprop.IsDefaultValue

Part	Description
oledbprop	Expression that evaluates to a OLEDBProperty2 object
Data Type

Boolean

Modifiable

Read-only

Prototype (C/C++)

HRESULT GetIsDefaultValue(VARIANT_BOOL *pRetVal);

Remarks

The IsDefaultValue property is TRUE if the value of the corresponding OLEDBProperty2 object has not been explicitly set or has been set to VT_EMPTY. In the OLE DB specification, VT_EMPTY means restore the default value. If the OLEDBProperty2 object was explicitly set to any other value, including the default value, the IsDefaultValue property is FALSE.

See Also

Value Property


IsNTService Property

The IsNTService property specifies whether the caller is a Microsoft® Windows NT® 4.0 or Microsoft Windows® 2000 Service.

Applies To

SendMailTask Object

Syntax

object.IsNTService[= value]

Part	Description
object	Expression that evaluates to a SendMailTask object
value	Boolean that specifies whether the caller is a Windows NT 4.0 and Windows 2000 Service
Data Type

Boolean

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetIsNTService(VARIANT_BOOL *pRetVal);

HRESULT SetIsNTService(VARIANT_BOOL NewValue);

Remarks

The default is FALSE.

Set IsNTService to TRUE only if the program that calls the package Execute method is installed as a Windows NT 4.0 or Windows 2000 Service.

See Also

Execute Method (Package)


IsOwner Property

The IsOwner property specifies whether the login under which the program retrieving the Data Transformation Services (DTS) package information is running is the same as the owner of the package.

Applies To

PackageInfo Object

Syntax

object.IsOwner

Part	Description
object	Expression that evaluates to a PackageInfo object
Data Type

Boolean

Modifiable

Read-only

Prototype (C/C++)

HRESULT GetIsOwner(VARIANT_BOOL *pRetVal);

See Also

Owner Property


IsPackageDSORowset Property

The IsPackageDSORowset property specifies whether the current step executes and returns a rowset when the Data Transformation Services (DTS) package is a rowset provider.

Applies To

Step Object	Step2 Object
Syntax

object.IsPackageDSORowset [= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list.
value	A value indicating whether the current step executes and returns a rowset
Data Type

Boolean

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetIsPackageDSORowset(VARIANT_BOOL *pRetVal);

HRESULT SetIsPackageDSORowset(VARIANT_BOOL NewValue);

Remarks

The default is FALSE.

The IsPackageDSORowset property cannot be set to TRUE for steps that reference the DTS flat file OLE DB provider, because that provider does not support the IDBSchemaRowset interface. Other providers that do not support IDBSchemaRowset also cannot be referenced by steps that return DSO rowsets.

See Also

Querying a Package with OPENROWSET

Issuing Distributed Queries Against Package Data


IsVersionEncrypted Property

The IsVersionEncrypted property specifies whether a version of the Data Transformation Services (DTS) package was encrypted when saved.

Applies To

SavedPackageInfo Object

Syntax

object.IsVersionEncrypted

Part	Description
object	Expression that evaluates to a SavedPackageInfo object
Data Type

Boolean

Modifiable

Read-only

Prototype (C/C++)

HRESULT GetIsVersionEncrypted(VARIANT_BOOL *pRetVal);

Remarks

The package version will be encrypted if either an owner password or a user password was specified when the package was saved.

See Also

SaveToStorageFile Method

SaveToStorageFileAs Method


JITDebug Property

The JITDebug property specifies whether a run-time error in a Microsoft® ActiveX® script causes a scripting debugger session to be opened.

Applies To

Application Object

Syntax

object.JITDebug [= value]

Part	Description
object	Expression that evaluates to an Application object.
value	If TRUE, the script debugger is entered.
Data Type

Boolean

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetJITDebug(VARIANT_BOOL *pRetVal);

HRESULT SetJITDebug(VARIANT_BOOL NewValue);

Remarks

If JITDebug is TRUE, the following behavior occurs in response to different error types.

Error Type	Behavior
Hard break (for example, a Microsoft Visual Basic® Scripting Edition (VBScript) Stop statement)	The Script Debugger is entered if you agree to debug the script.
Run-time errors and errors raised by objects	The Script Debugger is entered without prompting.
If JITDebug is FALSE, the following behavior occurs in response to different error types.

Error Type	Behavior
Hard break (for example, a VBScript Stop statement)	The break is ignored, and the script continues to execute.
Run-time errors	The script fails and an error message is displayed.
Errors raised by objects	An error message supplied by the object is displayed.
See Also

DesignerSettings Property


JoinTransactionIfPresent Property

The JoinTransactionIfPresent property specifies whether a step executes within the Data Transformation Services (DTS) package transaction.

Applies To

Step Object	Step2 Object
Syntax

object.JoinTransactionIfPresent[= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	A value indicating whether a step executes within the package transaction
Data Type

Boolean

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetJoinTransactionIfPresent(VARIANT_BOOL *pRetVal);

HRESULT SetJoinTransactionIfPresent(VARIANT_BOOL NewValue);

Remarks

JoinTransactionIfPresent can be set to TRUE if the package UseTransaction property is TRUE.

See Also

InTransaction Property

TransactionIsolationLevel Property

UseTransaction Property


KeepIdentity Property

The KeepIdentity property indicates whether the data in the file is used for the values of identity columns.

Applies To

BulkInsertTask Object

Syntax

object.KeepIdentity [= value]

Part	Description
object	Expression that evaluates to a BulkInsertTask object
value	A value indicating whether the data in the file is used for the values of identity columns
Data Type

Boolean

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetKeepIdentity(VARIANT_BOOL *pRetVal);

HRESULT SetKeepIdentity(VARIANT_BOOL NewValue);

Remarks

The default is FALSE, which causes the database to assign values to identity columns upon insertion.

See Also

KeepNulls Property


KeepNulls Property

The KeepNulls property returns or sets a value indicating whether NULL columns should keep NULL values even if defaults exists on destination columns.

Applies To

BulkInsertTask Object

Syntax

object.KeepNulls [= value]

Part	Description
object	Expression that evaluates to a BulkInsertTask object
value	A value indicating whether NULL columns keep NULL values
Remarks

The default is FALSE, which causes the database to assign the default value upon insertion.

Data Type

Boolean

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetKeepNulls(VARIANT_BOOL *pRetVal);

HRESULT SetKeepNulls(VARIANT_BOOL NewValue);

See Also

KeepIdentity Property


Language Property

The Language property specifies the Microsoft® ActiveX® scripting language the transformation is using.

Applies To

DataPumpTransformScript Object	DTSTransformScriptProperties2 Object
Syntax

object.Language [= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	Scripting language being used
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetLanguage(BSTR *pRetVal);

HRESULT SetLanguage(BSTR NewValue);

Remarks

The default is Microsoft Visual Basic® Scripting Edition (VBScript).

Script languages available on a particular system can be determined by enumerating the ScriptingLanguageInfos collection of the Application object. For more information about which scripting language to use with Data Transformation Services (DTS), see ScriptingLanguageInfo Object.

The property also can be referenced through the TransformServerProperties collection with the following code:

Set transprops = transform.TransformServerProperties
transprops("Language") [= string]

See Also

Application Object

ScriptingLanguageInfos Collection

ScriptLanguage Property

Text Property


LastOwnerTaskName Property

The LastOwnerTaskName property specifies the last task to use the connection.

Applies To

Connection Object	Connection2 Object
Syntax

object.LastOwnerTaskName

Part	Description
object	Expression that evaluates to an object in the Applies To list
Data Type

String

Modifiable

Read-only

Prototype (C/C++)

HRESULT GetLastOwnerTaskName(BSTR *pRetVal);

See Also

Connected Property

ReleaseConnection Method


LastRow Property

The LastRow property specifies the last source row to copy.

Applies To

BulkInsertTask Object	DataPumpTask Object
DataDrivenQueryTask Object	DataPumpTask2 Object
DataDrivenQueryTask2 Object	TransformationSet Object
Syntax

object.LastRow[= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	Last source row to copy
Data Type

Variant (Long in the BulkInsertTask object)

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetLastRow(VARIANT *pRetVal);

HRESULT SetLastRow(VARIANT NewValue);

Remarks

The default is 0, which specifies that all rows are to be copied.

See Also

FirstRow Property


LineageFullID Property

The LineageFullID property specifies a globally unique identifier (GUID) that uniquely identifies the lineage record for the execution of a Data Transformation Services (DTS) package stored in Microsoft® SQL Server™ 2000 Meta Data Services.

Applies To

PackageLineage Object	StepLogRecord Object
PackageLogRecord Object
Syntax

object.LineageFullID

Part	Description
object	Expression that evaluates to an object in the Applies To list
Data Type

String

Modifiable

Read-only

Prototype (C/C++)

HRESULT GetLineageFullID(BSTR *pRetVal);

Remarks

If the package is not hosted in Meta Data Services, a unique LineageFullID is generated by DTS for each execution of the package.

The syntax of GUIDs is:

{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}

where X represents hexadecimal digits. The groupings are 8, 4, 4, 4, and 12 digits.

See Also

GetLastExecutionLineage Method

LineageOptions Property

LineageShortID Property

RepositoryMetadataOptions Property

Using the Data Lineage Feature


LineageOptions Property

The LineageOptions property specifies how Data Transformation Services (DTS) package execution lineage is presented and recorded.

Applies To

Package Object	Package2 Object
Syntax

object.LineageOptions[= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	The way package execution lineage is presented and recorded
Data Type

DTSLineageOptions

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetLineageOptions(DTSLineageOptions *pRetVal);

HRESULT SetLineageOptions(DTSLineageOptions NewValue);

Remarks

LineageOptions must be set to one of the DTSLineageOptions values.

See Also

GetLastExecutionLineage Method

RepositoryMetadataOptions Property

Using the Data Lineage Feature


LineageShortID Property

The LineageShortID property specifies a value that uniquely identifies the lineage record for the execution of a Data Transformation Services (DTS) package that is stored in Microsoft® SQL Server™ 2000 Meta Data Services.

Applies To

PackageLineage Object	PackageLogRecord Object
Syntax

object.LineageShortID

Part	Description
object	Expression that evaluates to an object in the Applies To list
Data Type

Long

Modifiable

Read-only

Prototype (C/C++)

HRESULT GetLineageShortID(BSTR *pRetVal);

Remarks

If the package is not hosted in Meta Data Services, a unique LineageShortID property is generated by DTS for each execution of the package. Because LineageShortID is a long value, it is more convenient to use for indexed columns in a database than the LineageFullID, which is a globally unique identifier (GUID) string.

See Also

GetLastExecutionLineage Method

LineageFullID Property

LineageOptions Property

RepositoryMetadataOptions Property

Using the Data Lineage Feature


LogDate Property

The LogDate property specifies the date and time that the Data Transformation Services (DTS) package log record was written.

Applies To

PackageLogRecord Object

Syntax

object.LogDate

Part	Description
object	Expression that evaluates to a PackageLogRecord object
Data Type

Date

Modifiable

Read-only

Prototype (C/C++)

HRESULT GetLogDate(DATE *pRetVal);

See Also

FinishTime Property

StartTime Property


LogFileName Property

The LogFileName property specifies the name and path of the error log file.

Applies To

Package Object	Package2 Object
Syntax

object.LogFileName [= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	Name of the log file
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetLogFileName(BSTR *pRetVal);

HRESULT SetLogFileName(BSTR NewValue);

Remarks

If LogFileName is specified, Data Transformation Services (DTS) package error entries are copied to this file.

See Also

FailOnError Property

WriteCompletionStatusToNTEventLog Property


LogServerFlags Property

The LogServerFlags property sets or returns a value indicating whether Windows Authentication is used to validate access to the log server.

Applies To

Package2 Object

Syntax

object.LogServerFlags [= value]

Part	Description
object	Expression that evaluates to a Package2 object
value	Code that defines the type of user authentication used when accessing the log server
Data Type

DTSSQLServerStorageFlags

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetLogServerFlags(DTSSQLServerStorageFlags* pVal);

HRESULT SetLogServerFlags(DTSSQLServerStorageFlags pVal);

See Also

FailPackageOnLogFailure Property

LogServerName Property

LogServerPassword Property

LogServerUserName Property

LogToSQLServer Property


LogServerName Property

The LogServerName property sets or returns the name of the computer running an instance of Microsoft® SQL Server™ to which package logs are written.

Applies To

Package2 Object

Syntax

object.LogServerName [= name]

Part	Description
object	Expression that evaluates to a Package2 object
name	Name of the server to which logs are written
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetLogServerName(BSTR* pVal);

HRESULT SetLogServerName(BSTR pVal);

See Also

FailPackageOnLogFailure Property

LogServerFlags Property

LogServerPassword Property

LogServerUserName Property

LogToSQLServer Property


LogServerPassword Property

The LogServerPassword property sets or returns the password used to log in to the instance of Microsoft® SQL Server™ to which package logs are written.

Applies To

Package2 Object

Syntax

object.LogServerPassword [= string]

Part	Description
object	Expression that evaluates to a Package2 object
string	Password to log in to the instance of SQL Server to which logs are written
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetLogServerPassword(BSTR* pVal);

HRESULT SetLogServerPassword(BSTR pVal);

Remarks

This property is used only when the LogServerFlags has the value DTSSQLStgFlag_Default.

See Also

FailPackageOnLogFailure Property

LogServerFlags Property

LogServerName Property

LogServerUserName Property

LogToSQLServer Property


LogServerUserName Property

The LogServerUserName property sets or returns the user name used to log in to the instance of Microsoft® SQL Server™ to which package logs are written.

Applies To

Package2 Object

Syntax

object.LogServerUserName [= string]

Part	Description
object	Expression that evaluates to a Package2 object
string	User name to log in to the instance of SQL Server to which logs are written
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetLogServerUserName(BSTR* pVal);

HRESULT SetLogServerUserName(BSTR pVal);

Remarks

This property is used only when the LogServerFlags has the value DTSSQLStgFlag_Default.

See Also

FailPackageOnLogFailure Property

LogServerFlags Property

LogServerName Property

LogServerPassword Property

LogToSQLServer Property


LogToSQLServer Property

The LogToSQLServer property sets or returns a value indicating whether Data Transformation Services (DTS) package execution is logged to the specified Microsoft® SQL Server™ 2000 msdb database.

Applies To

Package2 Object

Syntax

object.LogToSQLServer [= boolean]

Part	Description
object	Expression that evaluates to a Package2 object
boolean	Boolean that specifies whether package execution is logged to the specified msdb database
Data Type

Boolean

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetLogToSQLServer(VARIANT_BOOL* pRetVal);

HRESULT SetLogToSQLServer(VARIANT_BOOL pRetVal);

Remarks

The default is FALSE, package execution is logged to a log file or the Microsoft Windows® event log. If TRUE, the LogServerName property specifies the instance of SQL Server to which logs are written.

See Also

FailPackageOnLogFailure Property

LogServerFlags Property

LogServerName Property

LogServerPassword Property

LogServerUserName Property


LowerCaseString Property

The LowerCaseString property specifies or returns a value indicating whether the alphabetical characters in the source column string copied by custom transformations are converted to lowercase characters.

Applies To

DataPumpTransformMidString Object	DataPumpTransformTrimString Object
Syntax

transerver.LowerCaseString [= logical]

Part	Description
transerver	Expression that evaluates to a transformation object from the Applies To list
logical	Boolean that specifies whether the alpha characters in the source string are converted to uppercase
Data Type

Boolean

Modifiable

Read/write

Prototype (C/C++)

HRESULT LowerCaseString(VARIANT_BOOL* pRetVal);

HRESULT LowerCaseString(VARIANT_BOOL pRetVal);

Remarks

The default is FALSE.

The property also can be referenced through the TransformServerProperties collection with the following code:

Set transprops = transform.TransformServerProperties
transprops("LowerCaseString") [= logical]

See Also

DataPumpTransformLowerString Object

UpperCaseString Property


MaxCacheRows Property

The MaxCacheRows property specifies the maximum number of rows to cache.

Applies To

Lookup Object

Syntax

object.MaxCacheRows [= value]

Part	Description
object	Expression that evaluates to a Lookup object
value	Maximum number of rows that are cached
Data Type

Long

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetMaxCacheRows(LONG *pRetVal);

HRESULT SetMaxCacheRows(LONG NewValue);

Remarks

The Execute method of the DTSLookups scripting object checks the cache of the Lookup object for the requested row before querying the lookup's data source. This results in significant performance improvement if the target row is usually found in the cache.

A value of 0 means no rows are cached. The default is 100.

See Also

ConnectionID Property

Execute Method (DTS)


MaxConcurrentSteps Property

The MaxConcurrentSteps property specifies the maximum number of Data Transformation Services (DTS) steps executing concurrently on separate threads.

Applies To

Package Object	Package2 Object
Syntax

object.MaxConcurrentSteps [= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	Maximum number of steps executing concurrently
Data Type

Long

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetMaxConcurrentSteps(LONG *pRetVal);

HRESULT SetMaxConcurrentSteps(LONG NewValue);

Remarks

The default is 4.

See Also

ExecuteInMainThread Property


MaximumErrorCount Property

The MaximumErrorCount property specifies the maximum number of error rows before the data pump terminates.

Applies To

DataDrivenQueryTask Object	DataPumpTask2 Object
DataDrivenQueryTask2 Object	TransformationSet Object
DataPumpTask Object
Syntax

object.MaximumErrorCount [= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	Maximum number of error rows before the data pump terminates
Data Type

Long

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetMaximumErrorCount(LONG *pRetVal);

HRESULT SetMaximumErrorCount(LONG NewValue);

Remarks

The default is 0.

See Also

FailOnError Property

FailPackageOnError Property

GetExecutionErrorInfo Method


MaximumErrors Property

The MaximumErrors property specifies the maximum number of errors that can occur before the server terminates the load operation.

Applies To

BulkInsertTask Object

Syntax

object.MaximumErrors [= value]

Part	Description
object	Expression that evaluates to a BulkInsertTask object
value	Maximum number of errors that can occur
Data Type

Long

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetMaximumErrors(LONG *pRetVal);

HRESULT SetMaximumErrors(LONG NewValue);

Remarks

The default is 10.

Transformations will fail at the first error if Fastload is being used as long as the BatchSize property is 0, even if MaximumErrors is changed. This failure occurs because all the rows are batched in a single transaction. If you want to log more errors to the exception file, either do not use Fastload or set the BatchSize property to another value, such as 1.

See Also

BatchSize Property


MessageDataFile Property

The MessageDataFile property sets or returns the name and path of the file that provides the data for a DTSMessageQueueTask object data file message.

Applies To

DTSMQMessage Object

Syntax

object.MessageDataFile [= filespec]

Part	Description
object	Expression that evaluates to a DTSMQMessage object
filespec	Name and path of the file that provides the data for the message
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT MessageDataFile(BSTR* pVal);

HRESULT MessageDataFile(BSTR pVal);

Remarks

The MessageDataFile property must be defined if the MessageType property is DTSMQMessageType_DataFile.

See Also

DTSMQMessageType

MessageGlobalVariables Property

MessageString Property

MessageType Property


MessageGlobalVariables Property

The MessageGlobalVariables property sets or returns a list of the names of the global variables that provides the data for a DTSMessageQueueTask object global variables message.

Applies To

DTSMQMessage Object

Syntax

object.MessageGlobalVariables [= list]

Part	Description
object	Expression that evaluates to a DTSMQMessage object
list	Semicolon-separated list of the Data Transformation Services (DTS) global variables used to construct the message
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT MessageGlobalVariables(BSTR* pVal);

HRESULT MessageGlobalVariables(BSTR pVal);

Remarks

The MessageGlobalVariables property must be defined if the MessageType property is DTSMQMessageType_DTSGlobalVariables. The global variables must be defined in the package that contains the DTSMessageQueueTask object.

See Also

DTSMQMessageType

MessageDataFile Property

MessageString Property

MessageType Property


MessageString Property

The MessageString property sets or returns the string used as the data for a DTSMessageQueueTask object string message.

Applies To

DTSMQMessage Object

Syntax

object.MessageString [= string]

Part	Description
object	Expression that evaluates to a DTSMQMessage object
string	String used as the data for the message
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT MessageString(BSTR* pVal);

HRESULT MessageString(BSTR pVal);

Remarks

The MessageString property must be defined if the MessageType property is DTSMQMessageType_String.

See Also

DTSMQMessageType

MessageDataFile Property

MessageGlobalVariables Property

MessageType Property


MessageText Property

The MessageText property is the body of an e-mail message.

Applies To

SendMailTask Object

Syntax

object.MessageText[= value]

Part	Description
object	Expression that evaluates to a SendMailTask object
value	Text string that is the body of an e-mail message
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetMessageText(BSTR *pRetVal);

HRESULT SetMessageText(BSTR NewValue);

See Also

CCLine Property

Subject Property

ToLine Property


MessageType Property

The MessageType property sets or returns the type of message defined by the DTSMQMessage object.

Applies To

DTSMQMessage Object

Syntax

object.MessageType [= value]

Part	Description
object	Expression that evaluates to a DTSMQMessage object
value	Code that defines the message type
Data Type

Long

Modifiable

Read/write

Prototype (C/C++)

HRESULT MessageType(long* pVal);

HRESULT MessageType(long pVal);

Remarks

The valid values for this property are defined by the DTSMQMessageType constants.

See Also

DTSMQMessageType

MessageDataFile Property

MessageGlobalVariables Property

MessageString Property


Month??LongName Property

The Month??LongName property specifies or returns the string to be used for the long (full) name of the indicated month. ?? is a month number from 1 through 12.

Applies To

DataPumpTransformDateTimeString Object

Syntax

object.Month??LongName [= name]

Part	Description
object	Expression that evaluates to a DataPumpTransformDateTimeString object.
??	Month number from 1 through 12, without a leading 0.
name	Long (full) name of the specified month.
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT Month??LongName(BSTR* pRetVal);

HRESULT Month??LongName(BSTR pRetVal);

Remarks

The default value is the English month name.

The property also can be referenced through the TransformServerProperties collection with the following code:

Set transprops = transform.TransformServerProperties
transprops("Month??LongName") [= name]

See Also

GetMonthLongName Method

GetMonthShortName Method

InputFormat Property

Month??ShortName Property

OutputFormat Property

SetMonthLongName Method

SetMonthShortName Method


Month??ShortName Property

The Month??ShortName property specifies or returns the string to be used for the short (3-character abbreviation) name of the indicated month. ?? is a month number from 1 through 12.

Applies To

DataPumpTransformDateTimeString Object

Syntax

object.Month??ShortName [= name]

Part	Description
Object	Expression that evaluates to a DataPumpTransformDateTimeString object.
??	Month number from 1 through 12, without a leading 0.
name	Short (3-character abbreviation) name of the specified month.
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT Month??ShortName(BSTR* pRetVal);

HRESULT Month??ShortName(BSTR pRetVal);

Remarks

The default value is the English month abbreviation.

The property also can be referenced through the TransformServerProperties collection with the following code:

Set transprops = transform.TransformServerProperties
transprops("Month??ShortName") [= name]

See Also

GetMonthLongName Method

GetMonthShortName Method

InputFormat Property

Month??LongName Property

OutputFormat Property

SetMonthLongName Method

SetMonthShortName Method


Name Property

The Name property specifies the name of a Data Transformation Services (DTS) object.

Applies To

ActiveScriptTask Object	OLEDBProviderInfo Object
BulkInsertTask Object	Package Object
Column Object	Package2 Object
Connection Object	PackageInfo Object
Connection2 Object	PackageLineage Object
CreateProcessTask Object	PackageLogRecord Object
CreateProcessTask2 Object	PackageRepository Object
CustomTask Object	PackageSQLServer Object
DataDrivenQueryTask Object	ParallelDataPumpTask Object
DataDrivenQueryTask2 Object	Property Object
DataPumpTask Object	ScriptingLanguageInfo Object
DataPumpTask2 Object	SendMailTask Object
DTSFTPTask Object	Step Object
DTSMessageQueueTask Object	Step2 Object
DynamicPropertiesTask Object	StepLineage Object
ExecutePackageTask Object	StepLogRecord Object
ExecuteSQLTask Object	Task Object
ExecuteSQLTask2 Object	TaskInfo Object
GlobalVariable Object	TransferObjectsTask Object
GlobalVariable2 Object	TransferObjectsTask2 Object
Lookup Object	Transformation Object
OLEDBProperty Object	Transformation2 Object
OLEDBProperty2 Object	TransformationSet Object
Syntax

object.Name [= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	Name of a DTS object
Data Type

Object

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetName(BSTR *pRetVal);

HRESULT SetName(BSTR NewValue);

Remarks

Name is a unique, user-defined text label for a Package2 object. When saved to an instance of Microsoft® SQL Server™ or SQL Server 2000 Meta Data Services, this name is used as a primary key.

A nonempty value for the Name property is required for most other DTS objects, as well.

See Also

Description Property


NestedExecutionLevel Property

The NestedExecutionLevel property specifies the number of times a Data Transformation Services (DTS) package that contains an Execute Package task recursively executes the same or another package that also contains an Execute package task.

Applies To

Package2 Object

Syntax

object.NestedExecutionLevel [= value]

Part	Description
object	Expression that evaluates to a Package2 object
value	Nesting depth of Execute Package invocations
Data Type

Long

Modifiable

Read-only

Prototype (C/C++)

HRESULT GetNestedExecutionLevel(long *pVal);

Remarks

The innermost package in the calling sequence will fail if the NestedExecutionLevel property reaches a preset value (32). This property can be used to detect excessive recursive calls by Execute Package tasks before this limit is reached.

See Also

ExecutePackageTask Object


NonOverwritable Property

The NonOverwritable property sets or returns a value indicating whether a destination file will be overwritten if it already exists, when copied by a DTSFTPTask object.

Applies To

DTSFTPTask Object

Syntax

object.NonOverwritable [= boolean]

Part	Description
object	Expression that evaluates to a DTSFTPTask object.
boolean	If TRUE, transfer of a source file is inhibited if the destination file already exists. If FALSE, the destination file is overwritten.
Data Type

Boolean

Modifiable

Read/write

Prototype (C/C++)

HRESULT NonOverwritable(VARIANT_BOOL* pVal);

HRESULT NonOverwritable(VARIANT_BOOL pVal);

Remarks

No error is raised when the transfer of a source file is inhibited by the NonOverwritable property.

The property also can be referenced through the Properties collection of the Task object with the following code:

Set taskprops = task.Properties
taskprops("NonOverwritable") [= boolean]

See Also

DestSite Property


Nullable Property

The Nullable property specifies whether a column can contain null values.

Applies To

Column Object

Syntax

object.Nullable [= value]

Part	Description
object	Expression that evaluates to a Column object
value	A value indicating whether a column can contain null values
Data Type

Boolean

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetNullable(VARIANT_BOOL *pRetVal);

HRESULT SetNullable(VARIANT_BOOL NewValue);

See Also

DataType Property

Flags Property


NumericScale Property

The NumericScale property specifies the numeric scale of the column if it has a decimal or numeric data type.

Applies To

Column Object

Syntax

object.NumericScale [= value]

Part	Description
object	Expression that evaluates to a Column object
value	Numeric scale of the column
Data Type

Long

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetNumericScale(LONG *pRetVal);

HRESULT SetNumericScale(LONG NewValue);

See Also

DataType Property

Flags Property


NumRetriesOnSource Property

The NumRetriesOnSource property sets or returns the number of times a connection to the source will be attempted before a DTSFTPTask object considers it failed.

Applies To

DTSFTPTask Object

Syntax

object.NumRetriesOnSource [= number]

Part	Description
object	Expression that evaluates to a DTSFTPTask object
number	Number of times connection to the source will be attempted before considered failed
Data Type

Long

Modifiable

Read/write

Prototype (C/C++)

HRESULT NumRetriesOnSource(long* pVal);

HRESULT NumRetriesOnSource(long pVal);

Remarks

No error is raised when the transfer of a source file is inhibited by the NonOverwritable property.

The property also can be referenced through the Properties collection of the Task object with the following code:

Set taskprops = task.Properties
taskprops("NumRetriesOnSource") [= number]

See Also

SourceLocation Property

SourceSite Property


OEMFile Property

The OEMFile property specifies or returns a value indicating whether the data read from or written to files by custom transformations is translated from or to the client OEM code page.

Applies To

DataPumpTransformReadFile Object	DataPumpTransformWriteFile Object
Syntax

transerver.OEMFile [= boolean]

Part	Description
transerver	Expression that evaluates to an object in the Applies To list.
boolean	If TRUE, the file data is translated through the client OEM code page. Default is FALSE.
Data Type

Boolean

Modifiable

Read/write

Prototype (C/C++)

HRESULT OEMFile(VARIANT_BOOL* pRetVal);

HRESULT OEMFile(VARIANT_BOOL pRetVal);

Remarks

If the UnicodeFile property is TRUE, the OEMFile property is ignored.

For Read File, the file is translated through the client OEM code page to Unicode if the OEMFile property is TRUE. If the destination column is not Unicode, the data is translated again from Unicode to ANSI.

For Write File, the source column data has already been translated to Unicode, if necessary. It is then translated through the client OEM code page if the OEMFile property is TRUE.

The property also can be referenced through the TransformServerProperties collection with the following code:

Set transprops = transform.TransformServerProperties
transprops("OEMFile") [= boolean]

See Also

UnicodeFile Property


Operator Property

The Operator property specifies the logged-in user that ran the Data Transformation Services (DTS) package for which a lineage or log record was written.

Applies To

PackageLineage Object	PackageLogRecord Object
Syntax

object.Computer

Part	Description
object	Expression that evaluates to an object in the Applies To list
Data Type

String

Modifiable

Read-only

Prototype (C/C++)

HRESULT GetOperator(BSTR *pRetVal);

See Also

Computer Property


Ordinal Property

The Ordinal property specifies the ordinal position of a column in a table or rowset.

Applies To

Column Object

Syntax

object.Ordinal [= value]

Part	Description
object	Expression that evaluates to a Column object
value	Ordinal position of a column
Data Type

Long

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetOrdinal(LONG *pRetVal);

HRESULT SetOrdinal(LONG NewValue);

Remarks

The value of the Ordinal property for the first column is 1.

See Also

ColumnID Property


OutputAsRecordset Property

The OutputAsRecordset property returns or specifies whether the entire rowset generated by the Execute SQL task query should be stored in a global variable.

Applies To

ExecuteSQLTask2 Object

Syntax

object.OutputAsRecordset [= value]

Part	Description
object	Expression that evaluates to an ExecuteSQLTask2 object
value	Whether the entire rowset should be stored in a global variable
Data Type

Boolean

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetOutputAsRecordset(VARIANT_BOOL *pRetVal);

HRESULT SetOutputAsRecordset(VARIANT_BOOL NewValue);

Remarks

The rowset is placed in the first named global variable in the OutputGlobalVariableNames list as a disconnected Microsoft® ActiveX® Data Objects (ADO) recordset. The variable is set to Nothing if no rowset is returned from the query.

See Also

OutputGlobalVariableNames Property

SQLStatement Property


OutputFormat Property

The OutputFormat property specifies or returns a string that defines the format of the datetime string in the destination column. This format string consists of tokens and delimiters, which define how components of the date and time are to be formatted. The delimiters are explicitly written to the destination column.

Applies To

DataPumpTransformDateTimeString Object

Syntax

object.OutputFormat [= formatstring]

Part	Description
object	Expression that evaluates to a DataPumpTransformDateTimeString object.
formatstring	String consisting of tokens and delimiters, which define the format of the source column.
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT OutputFormat(BSTR* pRetVal);

HRESULT OutputFormat(BSTR pRetVal);

Remarks

The tokens that can be used in the InputFormat and OutputFormat properties are defined as follows.

Token	Description
yyyy	4 digit year.
yy	2 digit year.
MMMM	Month long name.
MMM	Month 3-char abbreviation.
MM	2-digit month number 01..12.
M	1- or 2-digit month number, 1..12.
dddd	Day of week long name.
ddd	Day of week 3-char abbreviation.
dd	2-digit day number 01..31.
d	1- or 2-digit day number 1..31.
hh	2-digit hours 01..12.
h	1- or 2-digit hours 1..12.
HH	2-digit hours 00..23.
H	1- or 2-digit hours 0..23.
mm	2-digit minutes 00..59.
m	1- or 2-digit minutes 0..59.
ss	2-digit seconds 00..59.
s	1- or 2-digit seconds 0..59.
f[f[f...]]]	Fraction of second, in the number of digits as "f"s specified.
tt	Symbol for A.M. or P.M.
The property also can be referenced through the TransformServerProperties collection with the following code:

Set transprops = transform.TransformServerProperties
transprops("OutputFormat") [= formatstring]

See Also

AMSymbol Property

Day?LongName Property

Day?ShortName Property

GetDayLongName Method

GetDayShortName Method

GetMonthLongName Method

GetMonthShortName Method

InputFormat Property

Month??LongName Property

Month??ShortName Property

PMSymbol Property

SetDayLongName Method

SetDayShortName Method

SetMonthLongName Method

SetMonthShortName Method

ShortYear2000Cutoff Property


OutputGlobalVariableNames Property

The OutputGlobalVariableNames property returns or specifies a list of Data Transformation Services (DTS) global variable names that are to receive values from fields of a rowset or the entire rowset. The values and rowsets are generated by the Execute SQL task query.

Applies To

ExecuteSQLTask2 Object

Syntax

object.OutputGlobalVariableNames [= list]

Part	Description
object	Expression that evaluates to an ExecuteSQLTask2 object
list	List of global variable names
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetOutputGlobalVariableNames(BSTR *pRetVal);

HRESULT SetOutputGlobalVariableNames(BSTR NewValue);

Remarks

The format of the OutputGlobalVariableNames string is a semicolon delimited, optionally double-quoted or single-quoted list. Quoting is required only when the name contains an embedded delimiter. Embedded delimiters must be doubled. A double-delimiter or a trailing delimiter indicates an empty item. For example:

"gv1";gv2       - delimiters not required here

gv1;"gv""2"     - gv"2 embedded delimiter is doubled

gv1;;gv2;       - contains an empty second and fourth item

Values from the first row of the rowset are placed into the global variables in the list by ordinal position. Empty items in the list cause rowset columns to be skipped. If the global variable does not already exist, one is created unless the DTS package ExplicitGlobalVariables property is set. In this case, an error occurs.

If the OutputAsRecordset property is set, the entire rowset is placed in the first named global variable as a disconnected Microsoft® ActiveX® Data Objects (ADO) recordset. The variable is set to Nothing if no rowset is returned from the query.

See Also

GlobalVariables Collection

InputGlobalVariableNames Property

OutputAsRecordset Property

SQLStatement Property


Owner Property

The Owner property specifies the login of the owner of the Data Transformation Services (DTS) package.

Applies To

PackageInfo Object

Syntax

object.Owner

Part	Description
object	Expression that evaluates to a PackageInfo object
Data Type

String

Modifiable

Read-only

Prototype (C/C++)

HRESULT GetOwner(BSTR *pRetVal);

Remarks

The following code illustrates the value returned by the Owner property:

REDMOND\johndoe

See Also

IsOwner Property


PackageCreationDate Property

The PackageCreationDate property specifies the date and time that the Data Transformation Services (DTS) package was first created.

Applies To

SavedPackageInfo Object

Syntax

[date =] object.PackageCreationDate

Part	Description
object	Expression that evaluates to a SavedPackageInfo object
date	Date the package version was created
Data Type

Date

Modifiable

Read-only

Prototype (C/C++)

HRESULT GetPackageCreationDate(DATE *pRetVal);

See Also

CreationDate Property


PackageDataSize Property

The PackageDataSize property specifies the size of the Data Transformation Services (DTS) package in Microsoft® SQL Server™ storage.

Applies To

PackageInfo Object

Syntax

object.PackageDataSize

Part	Description
object	Expression that evaluates to a PackageInfo object
Data Type

Long

Modifiable

Read-only

Prototype (C/C++)

HRESULT GetPackageDataSize(long *pRetVal);

Remarks

The PackageDataSize is specified in bytes. It is not available for packages stored in SQL Server 2000 Meta Data Services (0 is returned).

See Also

EnumPackageInfos Method

PackageInfos Collection


PackageID Property

The PackageID property specifies the globally unique Data Transformation Services (DTS) package identifier, which is a string representation of a globally unique identifier (GUID).

Applies To

ExecutePackageTask Object	PackageLineage Object
Package Object	PackageLogRecord Object
Package2 Object	SavedPackageInfo Object
PackageInfo Object
Syntax

[guidstring =] object.PackageID

Part	Description
object	Expression that evaluates to an object in the Applies To list
guidstring	Package ID of the referenced package
Data Type

String

Modifiable

Read-write for the ExecutePackageTask object. Read-only for the others.

Prototype (C/C++)

HRESULT GetPackageID(BSTR *pRetVal);

Remarks

For the ExecutePackageTask object, the PackageID does not need to be specified if sufficient other information is specified to identify the package. If the VersionID is not specified, the most recent version of the package is run.

To determine the package ID of a package, open the package in DTS Designer. In the DTS Package Properties dialog box, click the General tab.

The syntax of GUIDs is:

{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}

where X represents hexadecimal digits. The groupings are 8, 4, 4, 4, and 12 digits.

See Also

VersionID Property


PackageName Property

The PackageName property sets or returns the name of the Data Transformation Services (DTS) package.

Applies To

ExecutePackageTask Object	SavedPackageInfo Object
Syntax

[name =] object.PackageName

Part	Description
object	Expression that evaluates to an object in the Applies To list
name	Package name
Data Type

String

Modifiable

Read/write for the ExecutePackageTask object. Read-only for the others.

Prototype (C/C++)

HRESULT GetPackageName(BSTR *pRetVal);

Remarks

For the ExecutePackageTask object, the PackageName property does not need to be set if either the PackageID or VersionID properties are specified or there is only one package in its containing file.

For the ExecutePackageTask object, this property also can be referenced through the Properties collection of the Task object with the following code:

Set taskprops = task.Properties
taskprops("PackageName") [= name]

See Also

PackageID Property

VersionID Property


PackagePassword Property

The PackagePassword property sets or returns the password of the Data Transformation Services (DTS) package to be run by an ExecutePackageTask object.

Applies To

ExecutePackageTask Object

Syntax

object.PackagePassword [= password]

Part	Description
object	Expression that evaluates to an ExecutePackageTask object
password	Owner or user password of the DTS package to be run
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT PackagePassword(BSTR* pRetVal);

HRESULT PackagePassword(BSTR pRetVal);

Remarks

Either the owner or user password can be used to run the package.

This property also can be referenced through the Properties collection of the Task object with the following code:

Set taskprops = task.Properties
taskprops("PackagePassword") [= password]

See Also

PackageID Property

PackageName Property


PackagePriorityClass Property

The PackagePriorityClass property specifies the Microsoft® Win32® thread priority class of the Data Transformation Services (DTS) package process.

Applies To

Package Object	Package2 Object
Syntax

object.PackagePriorityClass [= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	Win32 thread priority class of the package process
Data Type

DTSPackagePriorityClass

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetPackagePriorityClass(DTSPackagePriorityClass *pRetVal);

HRESULT SetPackagePriorityClass(DTSPackagePriorityClass NewValue);

Remarks

PackagePriorityClass must be set to one of the DTSPackagePriorityClass values.

See Also

RelativePriority Property


PackageType Property

The PackageType property sets or returns a code that identifies the tool that created the Data Transformation Services (DTS) package.

Applies To

Package2 Object	PackageInfo Object
Syntax

object.PackageType [= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	Code that identifies the tool that created the package
Data Type

DTSPackageType

Modifiable

Read/write

Prototype (C/C++)

HRESULT PackageType(DTSPackageType* pRetVal);

HRESULT PackageType(DTSPackageType pRetVal);

Remarks

The valid values for this property are defined by the DTSPackageType constants.

See Also

CreatorComputerName Property

PackagePriorityClass Property


Parent Property

The Parent property specifies a parent object or collection.

Applies To

Nearly all objects and collections in the Data Transformation Services (DTS) hierarchy have a Parent property.

Syntax

object.Parent

Part	Description
object	Expression that evaluates to an object in the Applies To list
Data Type

IDTSStdObject

Modifiable

Read-only

Prototype (C/C++)

HRESULT GetParent(IDTSStdObject **pRetVal);

Remarks

The parent of an object is the collection of which it is a member in the DTS hierarchy. The parent of a collection is the object above it in the hierarchy. The parent of the Package object is itself.

Note   Microsoft® Visual C++® and C applications obtain references on the parent object. The applications must release their references using the IUnknown::Release method.


ParseName Property

The ParseName property returns the moniker parse name for the OLE DB data source provider class.

Applies To

OLEDBProviderInfo Object

Syntax

object.ParseName

Part	Description
object	Expression that evaluates to a OLEDBProviderInfo object
Data Type

String

Modifiable

Read-only

Prototype (C/C++)

HRESULT GetParseName(BSTR* pRetVal);

Remarks

Typically, the ParseName property returns the ClassID of the OLE DB provider.

See Also

ClassID Property


Password Property

The Password property specifies the password to use when making the connection.

Applies To

Connection Object	SendMailTask Object
Connection2 Object
Syntax

object.Password [= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	Password to use
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetPassword(BSTR *pRetVal);

HRESULT SetPassword(BSTR NewValue);

Remarks

Use the Password property in conjunction with the UserID property to make the connection. You must provide values for Password and UserID unless UseTrustedConnection is TRUE.

Note   The recommended way to connect to an instance of Microsoft® SQL Server™ is to use Windows Authentication instead of SQL Server Authentication. Set UseTrustedConnection to TRUE to use Windows Authentication.

See Also

UserID Property

UseTrustedConnection Property


PMSymbol Property

The PMSymbol property specifies or returns the string to be used to indicate a time format after noon when a 12-hour time format is specified.

Applies To

DataPumpTransformDateTimeString Object

Syntax

object.PMSymbol [= string]

Part	Description
object	Expression that evaluates to a DataPumpTransformDateTimeString object
string	Suffix string to indicate a time format after noon for a 12-hour time format
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT PMSymbol(BSTR* pRetVal);

HRESULT PMSymbol(BSTR pRetVal);

Remarks

The default value is the English "PM".

The property also can be referenced through the TransformServerProperties collection with the following code:

Set transprops = transform.TransformServerProperties
transprops("PMSymbol") [= string]

See Also

AMSymbol Property

InputFormat Property

OutputFormat Property


PostSourceDataFunctionEntry Property

The PostSourceDataFunctionEntry property specifies or returns the name of the script function that is to be called for the PostSourceData transformation phase.

Applies To

DTSTransformScriptProperties2 Object

Syntax

object.PostSourceDataFunctionEntry [= name]

Part	Description
object	Expression that evaluates to a DTSTransformScriptProperties2 object
name	Name of the script function that supports PostSourceData phase
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT PostSourceDataFunctionEntry(BSTR* pRetVal);

HRESULT PostSourceDataFunctionEntry(BSTR pRetVal);

Remarks

The PostSourceData phase occurs after the last source row is processed in the DataPumpTask2 or DataDrivenQueryTask2 object or after the last row of a constituent rowset is processed in the source hierarchical rowset of the ParallelDataPumpTask object.

The PostSourceData script function has no access to the columns of the DTSSource collection and write access to the columns of the DTSDestination collection. Any return values that are valid during the Transform phase can be returned.

The property also can be referenced through the TransformServerProperties collection with the following code:

Set transprops = transform.TransformServerProperties
transprops("PostSourceDataFunctionEntry") [= string]

See Also

BatchCompleteFunctionEntry Property

DataDrivenQueryTask2 Object

DataPumpTask2 Object

DTSTransformStatus

FunctionEntry Property

InsertFailureFunctionEntry Property

InsertSuccessFunctionEntry Property

ParallelDataPumpTask Object

PreSourceDataFunctionEntry Property

PumpCompleteFunctionEntry Property

TransformFailureFunctionEntry Property


PrecedenceBasis Property

The PrecedenceBasis property specifies whether to use the current execution status of a Step object or the execution results in determining whether its precedence constraint has been satisfied.

Applies To

PrecedenceConstraint Object

Syntax

object.PrecedenceBasis [= value]

Part	Description
object	Expression that evaluates to a PrecedenceConstraint object
value	Value indicating whether to use current execution status of a Step object or execution results
Data Type

DTSStepPrecedenceBasis

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetPrecedenceBasis(DTSStepPrecedenceBasis *pRetVal);

HRESULT SetPrecedenceBasis(DTSStepPrecedenceBasis NewValue);

Remarks

PrecedenceBasis must be set to one of the DTSStepPrecedenceBasis values. The default is DTSStepPrecedenceBasis_ExecResult.

See Also

DTSStepExecResult

DTSStepExecStatus


Precision Property

The Precision property specifies column precision, if it has a decimal or numeric data type.

Applies To

Column Object

Syntax

object.Precision [= value]

Part	Description
object	Expression that evaluates to a Column object
value	Column precision
Data Type

Long

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetPrecision(LONG *pRetVal);

HRESULT SetPrecision(LONG NewValue);

See Also

DataType Property

NumericScale Property


PreSourceDataFunctionEntry Property

The PreSourceDataFunctionEntry property specifies or returns the name of the script function that is to be called for the PreSourceData transformation phase.

Applies To

DTSTransformScriptProperties2 Object

Syntax

object.PreSourceDataFunctionEntry [= name]

Part	Description
object	Expression that evaluates to a DTSTransformScriptProperties2 object
name	Name of the script function that supports the PreSourceData phase
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT PreSourceDataFunctionEntry(BSTR* pRetVal);

HRESULT PreSourceDataFunctionEntry(BSTR pRetVal);

Remarks

The PreSourceData phase occurs before the first source row is processed in the DataPumpTask2 or DataDrivenQueryTask2 objects, or before the first row of a constituent rowset is processed in the source hierarchical rowset of the ParallelDataPumpTask object.

The PreSourceData script function has no access to the columns of the DTSSource collection and write access to the columns of the DTSDestination collection. Any return values that are valid during the Transform phase can be returned.

The property also can be referenced through the TransformServerProperties collection with the following code:

Set transprops = transform.TransformServerProperties
transprops("PreSourceDataFunctionEntry") [= string]

See Also

BatchCompleteFunctionEntry Property

DataDrivenQueryTask2 Object

DataPumpTask2 Object

DTSTransformStatus

FunctionEntry Property

InsertFailureFunctionEntry Property

InsertSuccessFunctionEntry Property

ParallelDataPumpTask Object

PostSourceDataFunctionEntry Property

PumpCompleteFunctionEntry Property

TransformFailureFunctionEntry Property


ProcessCommandLine Property

The ProcessCommandLine property specifies the universal naming convention (UNC) file name of the file to execute and any command prompt arguments.

Applies To

CreateProcessTask Object	CreateProcessTask2 Object
Syntax

object.ProcessCommandLine [= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	Process command prompt arguments
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetProcessCommandLine(BSTR *pRetVal);

HRESULT SetProcessCommandLine(BSTR NewValue);

Remarks

The command line parameters can include environment variables. The GetExpandedProcessCommandLine method returns the command line with the environment variables substituted with their values.

See Also

GetExpandedProcessCommandLine Method


Profile Property

The Profile property specifies the profile to use when sending an e-mail message.

Applies To

SendMailTask Object

Syntax

object.Profile[= value]

Part	Description
object	Expression that evaluates to a SendMailTask object
value	Profile to use
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetProfile(BSTR *pRetVal);

HRESULT SetProfile(BSTR NewValue);

See Also

GetDefaultProfileName Method


ProgressCount Property

The ProgressCount property specifies the intervals (typically rows) processed during this step.

Applies To

StepLogRecord Object

Syntax

object.ProgressCount

Part	Description
object	Expression that evaluates to a StepLogRecord object
Data Type

Variant

Modifiable

Read-only

Prototype (C/C++)

HRESULT GetProgressCount(VARIANT *pRetVal);

See Also

FirstRow Property

LastRow Property

ProgressRowCount Property


ProgressRowCount Property

The ProgressRowCount property specifies the numbers of rows that are returned between notifications to the connection point event during data pump execution.

Applies To

DataDrivenQueryTask Object	DataPumpTask2 Object
DataDrivenQueryTask2 Object	TransformationSet Object
DataPumpTask Object
Syntax

object.ProgressRowCount [= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	Frequency in which notifications are sent to the connection point event
Data Type

Long

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetProgressRowCount(LONG *pRetVal);

HRESULT SetProgressRowCount(LONG NewValue);

Remarks

The OnProgress event is raised after every ProgressRowCount row has been processed. The default is 1000 rows.

See Also

OnProgress Event

ProgressCount Property


PropertyID Property

The PropertyID property specifies an OLEDBProperty object identifier (DBPROPID).

Applies To

OLEDBProperty Object	OLEDBProperty2 Object
Syntax

object.PropertyID

Part	Description
object	Expression that evaluates to an object in the Applies To list
Data Type

Long

Modifiable

Read-only

Prototype (C/C++)

HRESULT GetPropertyID(LONG *pRetVal);

See Also

PropertySet Property


PropertySet Property

The PropertySet property specifies the globally unique identifier (GUID) of the OLE DB property set.

Applies To

OLEDBProperty Object	OLEDBProperty2 Object
Syntax

object.PropertySet

Part	Description
object	Expression that evaluates to an object in the Applies To list
Data Type

String

Modifiable

Read-only

Prototype (C/C++)

HRESULT GetPropertySet(BSTR *pRetVal);

Remarks

The syntax of GUIDs is:

{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}

where X represents hexadecimal digits. The groupings are 8, 4, 4, 4, and 12 digits.

See Also

PropertyID Property


ProviderID Property

The ProviderID property returns the program ID of the OLE DB provider.

Applies To

Connection Object	Connection2 Object
Syntax

object.ProviderID

Part	Description
object	Expression that evaluates to an object in the Applies To list
Data Type

String

Modifiable

Read-only

Prototype (C/C++)

HRESULT GetProviderID(BSTR *pRetVal);

Remarks

A user-implemented OLE DB provider must support the following features if it is to be used with Data Transformation Services (DTS):

Interfaces

This is the interface support that DTS requires.

Interface	Requirement
IDBInitialize	Necessary.
IDBProperties	Necessary.
IDBCreateSession	Necessary.
ISessionProperties	Necessary.
IDBCreateCommand	Optional (for example, used for create table and queries).
IDBInfo	Necessary.
IOpenRowset	Necessary.
ICommandText	Optional (for example, used for create table and queries).
ICommandPrepare	Optional (for example, used for create table and queries).
IColumnsInfo	Necessary.
IRowset	Necessary.
IAccessor	Necessary.
ICommandWithParameters	Optional. Used for data driven queries.
IDBSchemaRowset	Necessary.
In addition to these interfaces, the DTS package requires that a provider have a DataSource property.

Schema

These are the schema that DTS requests:

•	DBSCHEMA_TABLES

•	DBSCHEMA_CATALOGS

•	DBSCHEMA_PROVIDER_TYPES. This is the only one that must be supported.

•	DBSCHEMA_PRIMARY_KEYS

•	DBSCHEMA_FOREIGN_KEYS

•	DBSCHEMA_INDEXES

•	DBSCHEMA_TABLE_CONSTRAINTS

•	DBSCHEMA_CHECK_CONSTRAINTS

See Also

New (ID) Method


PumpCompleteFunctionEntry Property

The PumpCompleteFunctionEntry property specifies or returns the name of the script function that is to be called for the OnPumpComplete transformation phase.

Applies To

DTSTransformScriptProperties2 Object

Syntax

object.PumpCompleteFunctionEntry [= name]

Part	Description
object	Expression that evaluates to a DTSTransformScriptProperties2 object
name	Name of the script function that supports OnPumpComplete phase
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT PumpCompleteFunctionEntry(BSTR* pRetVal);

HRESULT PumpCompleteFunctionEntry(BSTR pRetVal);

Remarks

The PostSourceData phase occurs after all other processing in the DataPumpTask2, DataDrivenQueryTask2 or ParallelDataPumpTask objects is complete.

The OnPumpComplete script function has no access to the columns of the DTSSource and DTSDestination collections. The only valid return values are DTSTransformStat_OK and DTSTransformStat_AbortPump.

The property also can be referenced through the TransformServerProperties collection with the following code:

Set transprops = transform.TransformServerProperties
transprops("PumpCompleteFunctionEntry") [= string]

See Also

BatchCompleteFunctionEntry Property

DataDrivenQueryTask2 Object

DataPumpTask2 Object

DTSTransformStatus

FunctionEntry Property

InsertFailureFunctionEntry Property

InsertSuccessFunctionEntry Property

ParallelDataPumpTask Object

PostSourceDataFunctionEntry Property

PreSourceDataFunctionEntry Property

TransformFailureFunctionEntry Property


Query Property

The Query property specifies a parameterized query to execute.

Applies To

Lookup Object

Syntax

object.Query [= value]

Part	Description
object	Expression that evaluates to a Lookup object
value	Parameterized query to execute
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetQuery(BSTR *pRetVal);

HRESULT SetQuery(BSTR NewValue);

See Also

Adding DTS Lookups and Global Variables


QueuePath Property

The QueuePath property sets or returns the full path of the Message Queuing queue used to send or receive messages.

Applies To

DTSMessageQueueTask Object

Syntax

object.QueuePath [= path]

Part	Description
object	Expression that evaluates to a DTSMessageQueueTask object
path	Full path of the message queue
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT QueuePath(BSTR* pVal);

HRESULT QueuePath(BSTR pVal);

Remarks

The syntax of the queue path is servername\[PRIVATE$]\queuename. To refer to the local computer, use a period (.) in the servername field. For public queues, nothing is coded between the back slashes (\\).

The property also can be referenced through the Properties collection of the Task object with the following code:

Set taskprops = task.Properties
taskprops("QueuePath") [= path]

Example

This example assigns a globally unique identifier (GUID) string to the PackageID property:

oCustTask.QueuePath = "DTS_SERV\\DTS_QUE"

See Also

RemoveFromQueue Property


ReceiveMessageTimeout Property

The ReceiveMessageTimeout property sets or returns the time after which the DTSMessageQueueTask object will terminate if a message is not found in the specified queue.

Applies To

DTSMessageQueueTask Object

Syntax

object.ReceiveMessageTimeout [= seconds]

Part	Description
object	Expression that evaluates to a DTSMessageQueueTask object
seconds	Seconds after which task will terminate if message is not received
Data Type

Long

Modifiable

Read/write

Prototype (C/C++)

HRESULT ReceiveMessageTimeout(long* pVal);

HRESULT ReceiveMessageTimeout(long pVal);

Remarks

The property also can be referenced through the Properties collection of the Task object with the following code:

Set taskprops = task.Properties
taskprops("ReceiveMessageTimeout") [= seconds]

See Also

ErrorIfReceiveMessageTimeout Property


ReceiveMessageType Property

The ReceiveMessageType property sets or returns the type of message for which a DTSMessageQueueTask object that is a receiver is waiting.

Applies To

DTSMessageQueueTask Object

Syntax

object.ReceiveMessageType [= value]

Part	Description
object	Expression that evaluates to a DTSMessageQueueTask object
value	Code for the message type from the DTSMQMessageType constants
Data Type

Long

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetReceiveMessageType(long* pVal);

HRESULT SetReceiveMessageType(long pVal);

Remarks

The property also can be referenced through the Properties collection of the Task object with the following code:

Set taskprops = task.Properties
taskprops("ReceiveMessageType") [= value]

See Also

DTSMQMessageType

TaskType Property


RelativePriority Property

The RelativePriority property specifies the Microsoft® Win32® priority of the thread on which a step is running, within the priority class of the Data Transformation Services (DTS) package process.

Applies To

Step Object	Step2 Object
Syntax

object.RelativePriority [= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	Win32 priority of a thread of a step
Data Type

DTSStepRelativePriority

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetRelativePriority(DTSStepRelativePriority *pRetVal);

HRESULT SetRelativePriority(DTSStepRelativePriority NewValue);

Remarks

RelativePriority must be set to one of the DTSStepRelativePriority values.

See Also

PackagePriorityClass Property


RemoveFromQueue Property

The RemoveFromQueue property sets or returns a value indicating whether a message is to be removed from the queue after it is received.

Applies To

DTSMessageQueueTask Object

Syntax

object.RemoveFromQueue [= boolean]

Part	Description
object	Expression that evaluates to a DTSMessageQueueTask object.
boolean	If TRUE, a message is removed from the queue after it is received. Default is FALSE.
Data Type

Boolean

Modifiable

Read/write

Prototype (C/C++)

HRESULT RemoveFromQueue(VARIANT_BOOL* pVal);

HRESULT RemoveFromQueue(VARIANT_BOOL pVal);

Remarks

The property also can be referenced through the Properties collection of the Task object with the following code:

Set taskprops = task.Properties
taskprops("RemoveFromQueue") [= boolean]

See Also

QueuePath Property


RepositoryDatabaseName Property

The RepositoryDatabaseName property sets or returns the name of the database that contains the instance of Microsoft® SQL Server™ 2000 Meta Data Services to be used by the ExecutePackageTask object.

Applies To

ExecutePackageTask Object

Syntax

object.RepositoryDatabaseName [= name]

Part	Description
object	Expression that evaluates to an ExecutePackageTask object
name	Name of the database containing the instance of Meta Data Services
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT RepositoryDatabaseName(BSTR* pRetVal);

HRESULT RepositoryDatabaseName(BSTR pRetVal);

Remarks

If RepositoryDatabaseName property is not provided, the default Meta Data Services database is used. RepositoryDatabaseName is also not needed if the Data Transformation Services (DTS) package to be run is in SQL Server storage or a data file.

This property also can be referenced through the Properties collection of the Task object with the following code:

Set taskprops = task.Properties
taskprops("RepositoryDatabaseName") [= password]

See Also

ServerName Property

UseRepository Property


RepositoryMetadataOptions Property

The RepositoryMetadataOptions property specifies meta data scanning and resolution options when storing a Data Transformation Services (DTS) package to Microsoft® SQL Server™ 2000 Meta Data Services.

Applies To

Package Object	Package2 Object
Syntax

object.RepositoryMetadataOptions[= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	Meta data scanning and resolution options
Data Type

DTSRepositoryMetadataOptions

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetRepositoryMetadataOptions(
DTSRepositoryMetadataOptions *pRetVal);

HRESULT SetRepositoryMetadataOptions(
DTSRepositoryMetadataOptions NewValue);

Remarks

RepositoryMetadataOptions must be set to one of the DTSRepositoryMetadataOptions values.

See Also

LineageOptions Property

LoadFromRepository Method

SaveToRepository Method

SaveToRepositoryAs Method


Reusable Property

The Reusable property specifies whether a connection is reusable by multiple steps.

Applies To

Connection Object	Connection2 Object
Syntax

object.Reusable [= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	A value indicating whether a connection is reusable
Data Type

Boolean

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetReusable(VARIANT_BOOL *pRetVal);

HRESULT SetReusable(VARIANT_BOOL NewValue);

Remarks

The default is TRUE.

See Also

AcquireConnection Method

InUse Property

ReleaseConnection Method


RollbackFailure Property

The RollbackFailure property specifies whether to roll back the Data Transformation Services (DTS) package transaction if there is a step failure.

Applies To

Step Object	Step2 Object
Syntax

object.RollbackFailure [= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	Boolean that specifies whether to roll back the transaction
Data Type

Boolean

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetRollbackFailure(VARIANT_BOOL *pRetVal);

HRESULT SetRollbackFailure(VARIANT_BOOL NewValue);

See Also

CommitSuccess Property

JoinTransactionIfPresent Property

UseTransaction Property


RowsComplete Property

The RowsComplete property returns the number of source rows, including rows for which errors occurred, processed by the task or transformation set.

Applies To

DataDrivenQueryTask2 Object	TransformationSet Object
DataPumpTask2 Object
Syntax

object.RowsComplete

Part	Description
object	Expression that evaluates to an object in the Applies To list
Data Type

Variant

Modifiable

Read-only

Prototype (C/C++)

HRESULT RowsComplete(VARIANT* pRowsComplete);

Remarks

The property value is returned from the IDTSDatapump::Execute method.

See Also

RowsInError Property


RowsInError Property

The RowsInError property returns the number of rows for which an error occurred while being processed by the Data Transformation Services (DTS) task or transformation set.

Applies To

DataDrivenQueryTask2 Object	TransformationSet Object
DataPumpTask2 Object
Syntax

object.RowsInError

Part	Description
object	Expression that evaluates to an object in the Applies To list
Data Type

Variant

Modifiable

Read-only

Prototype (C/C++)

HRESULT RowsInError(VARIANT* pRowsInError);

Remarks

The property value is returned from the IDTSDatapump::Execute method.

See Also

RowsComplete Property


RowTerminator Property

The RowTerminator property specifies the row terminator for the Bulk Insert task. The same set of row terminators that apply to the bulk copy program also apply to the Bulk Insert task.

Applies To

BulkInsertTask Object

Syntax

object.RowTerminator [= value]

Part	Description
object	Expression that evaluates to a BulkInsertTask object
value	A row terminator
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetRowTerminator(BSTR *pRetVal);

HRESULT SetRowTerminator(BSTR NewValue);

Remarks

Typical values are CR, CR/LF, LF, ",", ";", tab and "|". The default is a line feed character. It should not be the same as the FieldTerminator property.

See Also

FieldTerminator Property


SaveDataFileName Property

The SaveDataFileName property sets or returns the name and path of the file into which a received data file is written by a DTSMessageQueueTask object.

Applies To

DTSMessageQueueTask

Syntax

object.SaveDataFileName [= value]

Part	Description
object	Expression that evaluates to a DTSMessageQueueTask object
value	File specification where message is to be written
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetSaveDataFileName(BSTR *pVal);

HRESULT SetSaveDataFileName(BSTR pVal);

Remarks

The property also can be referenced through the Properties collection of the Task object with the following code:

Set taskprops = task.Properties
taskprops("SaveDataFileName") [= value]

See Also

ReceiveMessageType Property

TaskType Property


SaveMailInSentItemsFolder Property

The SaveMailInSentItemsFolder property specifies whether to save outgoing e-mail messages in the Sent Items folder.

Applies To

SendMailTask Object

Syntax

object.SaveMailInSentItemsFolder[= value]

Part	Description
object	Expression that evaluates to a SendMailTask object
value	Boolean that specifies whether to save outgoing e-mail messages in the Sent Items folder
Data Type

Boolean

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetSaveMailInSentItemsFolder(VARIANT_BOOL *pRetVal);

HRESULT SetSaveMailInSentItemsFolder(VARIANT_BOOL NewValue);

Remarks

The default is TRUE. Outgoing e-mail messages are saved in the Sent Items folder.


ScriptFileDirectory Property

The ScriptFileDirectory property specifies the directory to which the script file and log files are written.

Applies To

TransferObjectsTask Object	TransferObjectsTask2 Object
Syntax

object.ScriptFileDirectory[= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	Directory to which the script file and log files are written
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetScriptFileDirectory(BSTR *pRetVal);

HRESULT SetScriptFileDirectory(BSTR NewValue);

Remarks

The script file directory must exist on the computer on which the task runs.

See Also

ScriptOption Property

ScriptOptionEx Property


ScriptLanguage Property

The ScriptLanguage property specifies the Microsoft® ActiveX® script language needed to execute a script (for example, Microsoft Visual Basic® Scripting Edition (VBScript), Microsoft JScript®, or PerlScript).

Applies To

ActiveScriptTask Object	Step2 Object
Step Object
Syntax

object.ScriptLanguage [= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	ActiveX script language needed to execute a script
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetScriptLanguage(BSTR *pRetVal);

HRESULT SetScriptLanguage(BSTR NewValue);

Remarks

The default is VBScript.

Script languages available on a particular system can be determined by enumerating the ScriptingLanguageInfos collection of the Application object. For more information about which scripting language to use with Data Transformation Services (DTS), see ScriptingLanguageInfo Object.

See Also

Application Object

ActiveXScript Property

FunctionName Property

Language Property

ScriptingLanguageInfos Collection


ScriptOption Property

The ScriptOption property specifies which scripting option to use during an object transfer operation.

Applies To

TransferObjectsTask Object	TransferObjectsTask2 Object
Syntax

object.ScriptOption[= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	Scripting option to use
Data Type

DTSTransfer_ScriptOption

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetScriptOption(DTSTransfer_ScriptOption *pRetVal);

HRESULT SetScriptOption(DTSTransfer_ScriptOption NewValue);

Remarks

ScriptOption must be set to one of the DTSTransfer_ScriptOption values. The default is DTSTransfer_Script_TransferDefault.

See Also

ScriptFileDirectory Property

ScriptOptionEx Property


ScriptOptionEx Property

The ScriptOptionEx property specifies the extended scripting option to use during an object transfer operation.

Applies To

TransferObjectsTask Object	TransferObjectsTask2 Object
Syntax

object.ScriptOptionEx[= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	Extended scripting option to use
Data Type

DTSTransfer_ScriptOptionEx

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetScriptOptionEx(DTSTransfer_ScriptOptionEx *pRetVal);

HRESULT SetScriptOptionEx(DTSTransfer_ScriptOptionEx NewValue);

Remarks

ScriptOptionEx must be set to one of the DTSTransfer_ScriptOptionEx values. The default is DTSTransfer_ScriptEx_TransferDefault.

See Also

ScriptFileDirectory Property

ScriptOption Property


SequenceID Property

The SequenceID property specifies a sequence number for the task log record.

Applies To

TaskLogRecord Object

Syntax

object.SequenceID

Part	Description
object	Expression that evaluates to a TaskLogRecord object
Data Type

Long

Modifiable

Read-only

Prototype (C/C++)

HRESULT GetSequenceID(long *pRetVal);

Remarks

Task log records are written by custom tasks if they are implemented to do so. The Data Transformation Services (DTS) task classes supplied with Microsoft® SQL Server™ 2000 do not write task log records.

See Also

ErrorCode Property

ErrorDescription Property


ServerName Property

The ServerName property sets or returns the name of the server on which the Data Transformation Services (DTS) package to be run by an ExecutePackageTask object is located.

Applies To

ExecutePackageTask Object

Syntax

object.ServerName [= name]

Part	Description
object	Expression that evaluates to an ExecutePackageTask object
name	Name of the server on which the DTS package to be run is located
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT ServerName(BSTR* pRetVal);

HRESULT ServerName(BSTR pRetVal);

Remarks

If ServerName property is not provided, the local computer is used; you can also specify "(local)".

This property also can be referenced through the Properties collection of the Task object with the following code:

Set taskprops = task.Properties
taskprops("PackagePassword") [= password]

See Also

ServerPassword Property

ServerUserName Property

UseTrustedConnection Property


ServerPassword Property

The ServerPassword property sets or returns the login password for the instance of Microsoft® SQL Server™ that contains the Data Transformation Services (DTS) package to be run by an ExecutePackageTask object.

Applies To

ExecutePackageTask Object

Syntax

object.ServerPassword [= password]

Part	Description
object	Expression that evaluates to an ExecutePackageTask object
password	Login password for the instance of SQL Server that contains the DTS package to be run
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT ServerPassword(BSTR* pRetVal);

HRESULT ServerPassword(BSTR pRetVal);

Remarks

The ServerPassword and ServerUserName properties must be provided unless UseTrustedConnection is TRUE or the DTS package is contained in a storage file.

Note   It is recommended that you connect to an instance of SQL Server using Windows Authentication instead of SQL Server Authentication. To use Windows Authentication, set UseTrustedConnection to TRUE.

This property also can be referenced through the Properties collection of the Task object with the following code:

Set taskprops = task.Properties
taskprops("ServerPassword") [= password]

See Also

ServerName Property

ServerUserName Property

UseTrustedConnection Property


ServerUserName Property

The ServerUserName property sets or returns the login user name for the instance of Microsoft® SQL Server™ containing the Data Transformation Services (DTS) package to be run by an ExecutePackageTask object.

Applies To

ExecutePackageTask Object

Syntax

object.ServerUserName [= username]

Part	Description
object	Expression that evaluates to an ExecutePackageTask object
username	Login ID for the instance of SQL Server containing the DTS package to be run
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT ServerUserName(BSTR* pRetVal);

HRESULT ServerUserName(BSTR pRetVal);

Remarks

The ServerUserName and ServerPassword properties must be provided unless UseTrustedConnection is TRUE or the DTS package is contained in a storage file.

Note   It is recommended that you connect to an instance of SQL Server using Windows Authentication instead of SQL Server Authentication. To use Windows Authentication, set UseTrustedConnection to TRUE.

This property also can be referenced through the Properties collection of the Task object with the following code:

Set taskprops = task.Properties
taskprops("ServerUserName") [= username]

See Also

ServerName Property

ServerPassword Property

UseTrustedConnection Property


Set Property

The Set property returns TRUE when the referenced object property is read/write rather than read-only.

Applies To

Property Object

Syntax

object.Set

Part	Description
object	Expression that evaluates to a Property object
Data Type

Boolean

Modifiable

Read-only

Prototype (C/C++)

HRESULT GetSet(VARIANT_BOOL *pRetVal);

Remarks

When TRUE, the property referenced is read/write or write-only. However, an application attempt to change the property value is not guaranteed to succeed.

When FALSE, the property referenced is read-only.

See Also

Get Property


ShortYear2000Cutoff Property

The ShortYear2000Cutoff property specifies or returns the two-digit year below which the year is assumed to be 20yy. If the two-digit year is equal to or above the ShortYear2000Cutoff property, the year is 19yy.

Applies To

DataPumpTransformDateTimeString Object

Syntax

object.ShortYear2000Cutoff [= yy]

Part	Description
object	Expression that evaluates to a DataPumpTransformDateTimeString object
yy	Two-digit number specifying the lowest year that is to be considered 19yy
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT ShortYear2000Cutoff(long* pRetVal);

HRESULT ShortYear2000Cutoff(long pRetVal);

Remarks

The default value is 30.

The property also can be referenced through the TransformServerProperties collection with the following code:

Set transprops = transform.TransformServerProperties
transprops("ShortYear2000Cutoff") [= yy]

See Also

InputFormat Property

OutputFormat Property


Size Property

The Size property specifies the maximum size of the column.

Applies To

Column Object

Syntax

object.Size [= value]

Part	Description
object	Expression that evaluates to a Column object
value	Maximum size of the column
Data Type

Long

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetSize(LONG *pRetVal);

HRESULT SetSize(LONG NewValue);

Remarks

The Size property is ignored for columns that have fixed-length data types.

See Also

DataType Property

NumericScale Property

Precision Property


SortedData Property

The SortedData property specifies a string that corresponds to the ORDER clause in the Transact-SQL BULK INSERT statement.

Applies To

BulkInsertTask Object

Syntax

object.SortedData [= value]

Part	Description
object	Expression that evaluates to a BulkInsertTask object
value	String that corresponds to the ORDER clause in the Transact-SQL BULK INSERT statement
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetSortedData(BSTR *pRetVal);

HRESULT SetSortedData(BSTR NewValue);

See Also

BULK INSERT


SourceColumns Property

The SourceColumns property returns a reference to a Columns collection that contains the source columns the transformation uses.

Applies To

Transformation Object	Transformation2 Object
Syntax

[Set columns =] object.SourceColumns

Part	Description
object	Expression that evaluates to an object in the Applies To list
columns	Reference to collection containing source columns
Data Type

Columns Collection

Modifiable

Read-only

Prototype (C/C++)

HRESULT GetSourceColumns(IDTSColumns **pRetVal);

Remarks

For this collection, either the name or the ordinal can be used to reference individual elements.

See Also

Column Object

DestinationColumns Property


SourceCommandProperties Property

The SourceCommandProperties property specifies an OLEDBProperties collection of properties of the OLE DB provider used by the source connection.

Applies To

DataDrivenQueryTask Object	DataPumpTask2 Object
DataDrivenQueryTask2 Object	ParallelDataPumpTask Object
DataPumpTask Object
Syntax

object.SourceCommandProperties

Part	Description
object	Expression that evaluates to an object in the Applies To list
Data Type

OLEDBProperties Collection

Modifiable

Read-only

Prototype (C/C++)

HRESULT GetSourceCommandProperties(IDTSOleDBProperties **pRetVal);

See Also

Connection2 Object

DestinationCommandProperties Property

OLEDBProperty Object


SourceConnectionID Property

The SourceConnectionID property specifies the ID of the source connection.

Applies To

DataDrivenQueryTask Object	DataPumpTask2 Object
DataDrivenQueryTask2 Object	ParallelDataPumpTask Object
DataPumpTask Object
Syntax

object.SourceConnectionID [= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	Source connection ID
Data Type

Long

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetSourceConnectionID(LONG *pRetVal);

HRESULT SetSourceConnectionID(LONG NewValue);

Remarks

This property is the linkage between a data pump task and the source Connection2 object.

See Also

Connection2 Object

DestinationConnectionID Property


SourceConstantValue Property

The SourceConstantValue property sets or returns the value to which a Data Transformation Services (DTS) package object property will be set by the DynamicPropertiesTask object, when the SourceType property is DTSDynamicPropertiesSourceType_Constant.

Applies To

DynamicPropertiesTaskAssignment Object

Syntax

object.SourceConstantValue [= string]

Part	Description
object	Expression that evaluates to a DynamicPropertiesTaskAssignment object
string	Value to which a DTS package object property will be set
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT SourceConstantValue(BSTR* pRetVal);

HRESULT SourceConstantValue(BSTR pRetVal);

Example

The following example sets the SourceConstantValue property to a string:

oAssign.SourceConstantValue = "C:\DTS_UE\TestData\PubsAuthors.txt"

See Also

DynamicPropertiesTask Object

SourceType Property


SourceDatabase Property

The SourceDatabase property specifies the name of the source database.

Applies To

TransferObjectsTask Object	TransferObjectsTask2 Object
Syntax

object.SourceDatabase[= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	Name of the source database
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetSourceDatabase(BSTR *pRetVal);

HRESULT SetSourceDatabase(BSTR NewValue);

See Also

DestinationDatabase Property

SourceLogin Property

SourceServer Property

SourcePassword Property

SourceUseTrustedConnection Property


SourceDataFileFileName Property

The SourceDataFileFileName property sets or returns a string that is the name and path of a file that contains the value to which a Data Transformation Services (DTS) package object property will be set by the DynamicPropertiesTask object, when the SourceType property is DTSDynamicPropertiesSourceType_DataFile.

Applies To

DynamicPropertiesTaskAssignment Object

Syntax

object.SourceDataFileFileName [= filespec]

Part	Description
object	Expression that evaluates to a DynamicPropertiesTaskAssignment object
filespec	Name and path of file containing value to which a DTS package object property will be set
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT SourceDataFileFileName(BSTR* pRetVal);

HRESULT SourceDataFileFileName(BSTR pRetVal);

Example

The following example sets the SourceDataFileName property to a file specification:

oAssign.SourceDataFileFileName = "C:\DTS_UE\TestData\PubsAuthors.txt"

See Also

DynamicPropertiesTask Object

SourceType Property


SourceEnvironmentVariable Property

The SourceEnvironmentVariable property sets or returns the name of an environment variable that contains the value to which a Data Transformation Services (DTS) package object property will be set by the DynamicPropertiesTask object, when the SourceType property is DTSDynamicPropertiesSourceType_EnvironmentVariable.

Applies To

DynamicPropertiesTaskAssignment Object

Syntax

object.SourceEnvironmentVariable [= name]

Part	Description
object	Expression that evaluates to a DynamicPropertiesTaskAssignment object
name	Name of environment variable containing value to which a DTS package object property will be set
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT SourceEnvironmentVariable(BSTR* pRetVal);

HRESULT SourceEnvironmentVariable(BSTR pRetVal);

Remarks

Only system environment variables can be referenced with this property.

Example

The following example sets the SourceEnvironmentVariable property to a name:

oAssign.SourceEnvironmentVariable = "DTS_UE_Env"

See Also

DynamicPropertiesTask Object

SourceType Property


SourceFilename Property

The SourceFilename property sets or returns a list of files, with path and size, to be transferred from the source by a DTSFTPTask object.

Applies To

DTSFTPTask Object

Syntax

object.SourceFilename [= 'name';'path';'size';'name';'path';'size'; …]

Part	Description
object	Expression that evaluates to a DTSFTPTask object
name	Name of file to be transferred from the source
path	Path of file specified by name
size	Size of file specified by name and path
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT SourceFilename(BSTR* pVal);

HRESULT SourceFilename(BSTR pVal);

Remarks

If a path or site is specified by the SourceSite property, the path from the SourceFilename list is appended to the SourceSite property, and this value is used as the full path.

The size field is used by Data Transformation Services (DTS) Designer. It is not necessary to provide a size value when referencing the SourceFilename property programmatically. However, the enclosing apostrophes should still be coded.

The property also can be referenced through the Properties collection of the Task object with the following code:

Set taskprops = task.Properties
taskprops("SourceFilename") [= list]

Example

The following example sets the SourceFilename property to a list of two file names:

    oCustTask.SourceFilename = _

            "'File3.dat';'';'123';'NWProdWiz.xls';'';'458240';"

See Also

SourceLocation Property

SourcePassword (DTSFTPTask) Property

SourceSite Property

SourceUsername Property


SourceGlobalVariable Property

The SourceGlobalVariable property sets or returns the name of a Data Transformation Services (DTS) package global variable that contains the value to which a package object property will be set by the DynamicPropertiesTask object, when the SourceType property is DTSDynamicPropertiesSourceType_GlobalVariable.

Applies To

DynamicPropertiesTaskAssignment Object

Syntax

object.SourceGlobalVariable [= name]

Part	Description
object	Expression that evaluates to a DynamicPropertiesTaskAssignment object
name	Name of a package global variable containing value to which a package object property will be set
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT SourceGlobalVariable(BSTR* pRetVal);

HRESULT SourceGlobalVariable(BSTR pRetVal);

See Also

DynamicPropertiesTask Object

SourceType Property


SourceIniFileFileName Property

The SourceIniFileFileName property sets or returns a string that is the name and path of an .ini file, which contains the value to which a Data Transformation Services (DTS) package object property will be set by the DynamicPropertiesTask object, when the SourceType property is DTSDynamicPropertiesSourceType_IniFile.

Applies To

DynamicPropertiesTaskAssignment Object

Syntax

object.SourceIniFileFileName [= filespec]

Part	Description
object	Expression that evaluates to a DynamicPropertiesTaskAssignment object
filespec	Name and path of .ini file containing value to which a package object property will be set
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT SourceIniFileFileName(BSTR* pRetVal);

HRESULT SourceIniFileFileName(BSTR pRetVal);

Example

The following code sets the SourceIniFileName property:

oAssign.SourceIniFileFileName = "C:\DTS_UE\TestData\DynProp.ini"
oAssign.SourceIniFileSection = "FlatFile"
oAssign.SourceIniFileKey = "Lengths"

See Also

DynamicPropertiesTask Object

SourceIniFileKey Property

SourceIniFileSection Property

SourceType Property


SourceIniFileKey Property

The SourceIniFileKey property sets or returns the name of a key within an .ini file that identifies the value to which a Data Transformation Services (DTS) package object property will be set by the DynamicPropertiesTask object, when the SourceType property is DTSDynamicPropertiesSourceType_IniFile.

Applies To

DynamicPropertiesTaskAssignment Object

Syntax

object.SourceIniFileKey [= key]

Part	Description
object	Expression that evaluates to a DynamicPropertiesTaskAssignment object
key	Name of key within an .ini file identifying value to which a package object property will be set
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT SourceIniFileKey(BSTR* pRetVal);

HRESULT SourceIniFileKey(BSTR pRetVal);

Remarks

Do not include the equal sign (=) that follows the key name in the .ini file with the key name when setting this property.

The specified key must appear in the section specified by the SourceIniFileSection property, which in turn must appear within the .ini file specified by the SourceIniFileFileName property.

Example

The following code sets the SourceIniFileKey property:

oAssign.SourceIniFileFileName = "C:\DTS_UE\TestData\DynProp.ini"
oAssign.SourceIniFileSection = "FlatFile"
oAssign.SourceIniFileKey = "Lengths"

See Also

DynamicPropertiesTask Object

SourceIniFileFileName Property

SourceIniFileSection Property

SourceType Property


SourceIniFileSection Property

The SourceIniFileSection property sets or returns the name of a section within an .ini file that contains the value to which a Data Transformation Services (DTS) package object property will be set by the DynamicPropertiesTask object, when the SourceType property is DTSDynamicPropertiesSourceType_IniFile.

Applies To

DynamicPropertiesTaskAssignment Object

Syntax

object.SourceIniFileSection [= section]

Part	Description
object	Expression that evaluates to a DynamicPropertiesTaskAssignment object
section	Name of section within an .ini file containing value to which a package object property will be set
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT SourceIniFileSection(BSTR* pRetVal);

HRESULT SourceIniFileSection(BSTR pRetVal);

Remarks

Do not include the square brackets "[]" that enclose the section name in the .ini file with the section name when setting this property.

The specified section must appear within the .ini file specified by the SourceIniFileFileName property.

Example

The following code sets the SourceIniFileSection property:

oAssign.SourceIniFileFileName = "C:\DTS_UE\TestData\DynProp.ini"
oAssign.SourceIniFileSection = "FlatFile"
oAssign.SourceIniFileKey = "Lengths"

See Also

DynamicPropertiesTask Object

SourceIniFileFileName Property

SourceIniFileKey Property

SourceType Property


SourceLocation Property

The SourceLocation property sets or returns the source location type, an Internet site, or a network directory to be used by a DTSFTPTask object.

Applies To

DTSFTPTask Object

Syntax

object.SourceLocation [= value]

Part	Description
object	Expression that evaluates to a DTSFTPTask object
value	Code that defines the source location type
Data Type

Long

Modifiable

Read/write

Prototype (C/C++)

HRESULT SourceLocation(long* pVal);

HRESULT SourceLocation(long pVal);

Remarks

The valid values for this property are defined by the DTSFTPSourceLocation enumeration in the DTSCustTasks library (CustTask.dll).

The property also can be referenced through the Properties collection of the Task object with the following code:

Set taskprops = task.Properties
taskprops("SourceLocation") [= list]

See Also

DTSFTPSourceLocation

SourceFilename Property

SourcePassword (DTSFTPTask) Property

SourceSite Property

SourceUsername Property


SourceLogin Property

The SourceLogin property specifies the login ID on the source server.

Applies To

TransferObjectsTask Object	TransferObjectsTask2 Object
Syntax

object.SourceLogin[= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	Login ID
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetSourceLogin(BSTR *pRetVal);

HRESULT SetSourceLogin(BSTR NewValue);

Remarks

SourceLogin is required if an application is using SQL Server Authentication security mode.

Note   It is recommended that you connect to an instance of Microsoft® SQL Server™ using Windows Authentication instead of SQL Server Authentication. To use Windows Authentication, set SourceUseTrustedConnection to TRUE.

See Also

DestinationLogin Property

SourceDatabase Property

SourceServer Property

SourcePassword Property

SourceUseTrustedConnection Property


SourceObjectName Property

The SourceObjectName property specifies the source object name if no value for the SourceSQLStatement property is specified.

Applies To

DataDrivenQueryTask Object	DataPumpTask2 Object
DataDrivenQueryTask2 Object	ParallelDataPumpTask Object
DataPumpTask Object
Syntax

object.SourceObjectName [= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	Source object name
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetSourceObjectName(BSTR *pRetVal);

HRESULT SetSourceObjectName(BSTR NewValue);

Remarks

The SourceObjectName property is typically a database table name or worksheet name.

Example

The following code sets the SourceObjectName property:

objDataPump.SourceObjectName = "pubs..authors"

See Also

DestinationObjectName Property

SourceSQLStatement Property


SourcePassword Property

The SourcePassword property specifies the password on the source server.

Applies To

TransferObjectsTask Object	TransferObjectsTask2 Object
Syntax

object.SourcePassword[= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	Password on the source server
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetSourcePassword(BSTR *pRetVal);

HRESULT SetSourcePassword(BSTR NewValue);

Remarks

Note   It is recommended that you connect to an instance of Microsoft® SQL Server™ using Windows Authentication instead of SQL Server Authentication. To use Windows Authentication, set SourceUseTrustedConnection to TRUE.

See Also

DestinationPassword Property

SourceDatabase Property

SourceServer Property

SourceLogin Property

SourceUseTrustedConnection Property


SourcePassword (DTSFTPTask) Property

The SourcePassword property sets or returns the password that will be used to connect to the Internet File Transfer Protocol (FTP) site by a DTSFTPTask object.

Applies To

DTSFTPTask Object

Syntax

object.SourcePassword [= value]

Part	Description
object	Expression that evaluates to a DTSFTPTask object
value	Password that will be used to connect to the Internet FTP site
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT SourcePassword(BSTR* pVal);

HRESULT SourcePassword(BSTR pVal);

Remarks

Typically, if "anonymous" is used for the user name when connecting to the FTP site, the e-mail address of the user is used as the password.

The property also can be referenced through the Properties collection of the Task object with the following code:

Set taskprops = task.Properties
taskprops("SourcePassword") [= value]

Example

This example sets the SourcePassword property to a string.

oCustTask.SourcePassword = "user@microsoft.com"

See Also

SourceFilename Property

SourceLocation Property

SourceSite Property

SourceUsername Property


SourceQueryConnectionID Property

The SourceQueryConnectionID property sets or returns the connection ID of the connection against which a query will be run. The query provides the value to which a Data Transformation Services (DTS) package object property will be set by the DynamicPropertiesTask object, when the SourceType property is DTSDynamicPropertiesSourceType_Query.

Applies To

DynamicPropertiesTaskAssignment Object

Syntax

object.SourceQueryConnectionID [= number]

Part	Description
object	Expression that evaluates to a DynamicPropertiesTaskAssignment object
number	Connection ID against which a query will be run to provide the value to which a DTS package object property will be set
Data Type

Long

Modifiable

Read/write

Prototype (C/C++)

HRESULT SourceQueryConnectionID(long* pRetVal);

HRESULT SourceQueryConnectionID(long pRetVal);

Remarks

The SQL query to be run is specified by the SourceQuerySQL property.

See Also

SourceQuerySQL Property

SourceType Property


SourceQuerySQL Property

The SourceQuerySQL property sets or returns a string that is an SQL query. The query provides the value to which a Data Transformation Services (DTS) package object property is set by the DynamicPropertiesTask object, when the SourceType property is DTSDynamicPropertiesSourceType_Query.

Applies To

DynamicPropertiesTaskAssignment Object

Syntax

object.SourceQuerySQL [= query]

Part	Description
object	Expression that evaluates to a DynamicPropertiesTaskAssignment object
query	SQL query that provides the value to which a DTS package object property is set
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT SourceQuerySQL(BSTR* pRetVal);

HRESULT SourceQuerySQL(BSTR pRetVal);

Remarks

In general, it is recommended that you program the SQL query to return a single row containing a single field. Only the first field of the first row is used to set the specified package object property.

The query is run against the connection identified by the SourceQueryConnectionID property.

See Also

SourceQueryConnectionID Property

SourceType Property


SourceServer Property

The SourceServer property specifies the name of the source server.

Applies To

TransferObjectsTask Object	TransferObjectsTask2 Object
Syntax

object.SourceServer[= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	Name of the source server
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetSourceServer(BSTR *pRetVal);

HRESULT SetSourceServer(BSTR NewValue);

See Also

DestinationServer Property

SourceDatabase Property

SourceLogin Property

SourcePassword Property

SourceUseTrustedConnection Property


SourceSite Property

The SourceSite property sets or returns the location from which the files will be transferred by a DTSFTPTask object.

Applies To

DTSFTPTask Object

Syntax

object.SourceSite [= string]

Part	Description
object	Expression that evaluates to a DTSFTPTask object
string	Location from which the files will be transferred, either an Internet FTP site or a network directory
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT SourceSite(BSTR* pVal);

HRESULT SourceSite(BSTR pVal);

Remarks

If the SourceLocation property specifies an Internet site, the SourceSite property must be defined.

The property also can be referenced through the Properties collection of the Task object with the following code:

Set taskprops = task.Properties
taskprops("SourceSite") [= string]

Example

The following example sets the SourceSite property to a File Transfer Protocol (FTP) site name:

oCustTask.SourceSite = "ftp.microsoft.com"

See Also

SourceFilename Property

SourceLocation Property

SourcePassword (DTSFTPTask) Property

SourceUsername Property


SourceSQLStatement Property

The SourceSQLStatement property specifies the SQL statement used to execute on the source rowset.

Applies To

DataDrivenQueryTask Object	DataPumpTask2 Object
DataDrivenQueryTask2 Object	ParallelDataPumpTask Object
DataPumpTask Object
Syntax

object.SourceSQLStatement [= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	SQL statement used to execute on the source rowset
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetSourceSQLStatement(BSTR *pRetVal);

HRESULT SetSourceSQLStatement(BSTR NewValue);

Remarks

The SQL statement specified by this property can contain ? tokens that are replaced by the values of global variables named by the InputGlobalVariableNames property.

See Also

DestinationSQLStatement Property

InputGlobalVariableNames Property


SourceTranslateChar Property

The SourceTranslateChar property sets or returns a value indicating whether translation is performed for character data on the source server.

Applies To

TransferObjectsTask2 Object

Syntax

object.SourceTranslateChar [= boolean]

Part	Description
object	Expression that evaluates to a TransferObjectsTask2 object.
boolean	Boolean that specifies whether translation is performed for character data on the source server.
Data Type

Boolean

Modifiable

Read/write

Prototype (C/C++)

HRESULT SourceTranslateChar(VARIANT_BOOL* pRetVal);

HRESULT SourceTranslateChar(VARIANT_BOOL pRetVal);

Remarks

The default is TRUE; translation is performed.

See Also

DestTranslateChar Property


SourceType Property

The SourceType property sets or returns a code for the type of source object that provides the value to which a Data Transformation Services (DTS) package object property will be set by the DynamicPropertiesTask object.

Applies To

DynamicPropertiesTaskAssignment Object

Syntax

object.SourceType [= value]

Part	Description
object	Expression that evaluates to a DynamicPropertiesTaskAssignment object
value	Code for the type of source object that provides the value to which a DTS package object property will be set
Data Type

Long

Modifiable

Read/write

Prototype (C/C++)

HRESULT SourceType(long* pRetVal);

HRESULT SourceType(long pRetVal);

Remarks

The valid values for this property are defined by the DynamicPropertiesTaskSourceType constants.

Example

The following example sets the SourceType property to a value from a DTS enumeration:

oAssign.SourceType = DTSDynamicPropertiesSourceType_IniFile

See Also

DynamicPropertiesTaskSourceType

SourceConstantValue Property

SourceDataFileFileName Property

SourceEnvironmentVariable Property

SourceGlobalVariable Property

SourceIniFileFileName Property

SourceIniFileKey Property

SourceIniFileSection Property

SourceQueryConnectionID Property

SourceQuerySQL Property


SourceUsername Property

The SourceUsername property sets or returns the user name that will be used to connect to the Internet File Transfer Protocol (FTP) site by a DTSFTPTask object.

Applies To

DTSFTPTask Object

Syntax

object.SourceUsername [= value]

Part	Description
object	Expression that evaluates to a DTSFTPTask object
value	User name that will be used to connect to the Internet FTP site
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT SourceUsername(BSTR* pVal);

HRESULT SourceUsername(BSTR pVal);

Remarks

Typically, "anonymous" can be used for the user name when establishing a read-only connection to an Internet FTP site, such as by the DTSFTPTask.

The property also can be referenced through the Properties collection of the Task object with the following code:

Set taskprops = task.Properties
taskprops("SourceUsername") [= value]

Example

The following example sets the SourceUsername property to a string:

oCustTask.SourceUsername = "anonymous"

See Also

SourceFilename Property

SourceLocation Property

SourcePassword (DTSFTPTask) Property

SourceSite Property


SourceUseTrustedConnection Property

The SourceUseTrustedConnection property specifies whether the Windows Authentication security mode is used.

Applies To

TransferObjectsTask Object	TransferObjectsTask2 Object
Syntax

object.SourceUseTrustedConnection[= value]

Part	Description
object	An expression that evaluates to an object in the Applies To list
value	Boolean that specifies whether the Windows Authentication security mode is to be used
Data Type

Boolean

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetSourceUseTrustedConnection(VARIANT_BOOL *pRetVal);

HRESULT SetSourceUseTrustedConnection(VARIANT_BOOL NewValue);

Remarks

The default is FALSE.

Note   It is recommended that you connect to an instance of Microsoft® SQL Server™ using Windows Authentication instead of SQL Server Authentication. To use Windows Authentication, set SourceUseTrustedConnection to TRUE.

See Also

DestinationUseTrustedConnection Property

SourceDatabase Property

SourceLogin Property

SourcePassword Property

SourceServer Property


SQLStatement Property

The SQLStatement property specifies a sequence of one or more SQL statements or stored procedure references to be executed.

Applies To

ExecuteSQLTask Object	ExecuteSQLTask2 Object
Syntax

object.SQLStatement [= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	Query that is a sequence of one or more SQL statements or stored procedure references
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetSQLStatement(BSTR *pRetVal);

HRESULT SetSQLStatement(BSTR NewValue);

Remarks

In the ExecuteSQLTask2 object, the SQLStatement query can contain ? tokens that are replaced by the values of global variables specified by the InputGlobalVariableNames property. Fields from the first row of the rowset generated by the query are assigned to the global variables specified by the OutputGlobalVariableNames property. The entire rowset can be written to a global variable as a disconnected Microsoft® ActiveX® Data Objects (ADO) recordset if the OutputAsRecordset property is set.

See Also

InputGlobalVariableNames Property

OutputAsRecordset Property

OutputGlobalVariableNames Property


StartTime Property

The StartTime property specifies when the Data Transformation Services (DTS) package or step execution started.

Applies To

PackageLogRecord Object	StepLineage Object
Step Object	StepLogRecord Object
Step2 Object
Syntax

object.StartTime

Part	Description
object	Expression that evaluates to an object in the Applies To list
Data Type

Date

Modifiable

Read-only

Prototype (C/C++)

HRESULT GetStartTime(DATE *pRetVal);

See Also

ExecutionTime Property

FinishTime Property


StepExecutionID Property

The StepExecutionID property specifies a sequence number for the step log record.

Applies To

StepLogRecord Object

Syntax

object.StepExecutionID

Part	Description
object	Expression that evaluates to a StepLogRecord object
Data Type

Long

Modifiable

Read-only

Prototype (C/C++)

HRESULT GetStepExecutionID(long *pRetVal);

Remarks

StepExecutionID can be specified as a parameter when enumerating or removing step log records and task log records.

See Also

EnumStepLogRecords Method

EnumTaskLogRecords Method

RemoveStepLogRecords Method

RemoveTaskLogRecords Method

StepExecutionResult Property

StepExecutionStatus Property


StepExecutionResult Property

The StepExecutionResult property returns the result of the logged step execution.

Applies To

StepLineage Object	StepLogRecord Object
Syntax

object.StepExecutionResult

Part	Description
object	Expression that evaluates to an object in the Applies To list
Data Type

DTSStepExecResult

Modifiable

Read-only

Prototype (C/C++)

HRESULT GetStepExecutionResult(DTSStepExecResult *pRetVal);

Remarks

The StepExecutionResult value indicates success or failure of the logged step.

See Also

ExecutionResult Property

ExecutionStatus Property

StepExecutionStatus Property


StepExecutionStatus Property

The StepExecutionStatus property returns the status of the logged step execution.

Applies To

StepLineage Object	StepLogRecord Object
Syntax

object.StepExecutionStatus

Part	Description
object	Expression that evaluates to an object in the Applies To list
Data Type

DTSStepExecStatus

Modifiable

Read-only

Prototype (C/C++)

HRESULT GetStepExecutionStatus(DTSStepExecStatus *pRetVal);

Remarks

Typically, you will see DTSStepExecStat_Completed (4) for StepExecutionStatus logged step execution records.

See Also

ExecutionResult Property

ExecutionStatus Property

StepExecutionResult Property


StepName Property

The StepName property specifies the name of the step whose status or result is evaluated when determining if this constraint is satisfied.

Applies To

PrecedenceConstraint Object

Syntax

object.StepName [= value]

Part	Description
object	Expression that evaluates to a PrecedenceConstraint object
value	Name of the step that is evaluated
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetStepName(BSTR *pRetVal);

HRESULT SetStepName(THIS_ DTS_IN BSTR NewValue);

See Also

PrecedenceBasis Property

Step2 Object


StringCompareType Property

The StringCompareType property sets or returns the type of comparison to be performed on a received string message.

Applies To

DTSMessageQueueTask Object

Syntax

object.StringCompareType [= value]

Part	Description
object	Expression that evaluates to a DTSMessageQueueTask object
value	Code that defines the string comparison type
Data Type

Long

Modifiable

Read/write

Prototype (C/C++)

HRESULT StringCompareType(long* pVal);

HRESULT StringCompareType(long pVal);

Remarks

The comparison is performed between the received message and the value of the StringCompareValue property.

The valid values for this property are defined by the DTSMQStringMessageCompare constants.

The property also can be referenced through the Properties collection of the Task object with the following code:

Set taskprops = task.Properties
taskprops("StringCompareType") [= value]

See Also

DTSMQStringMessageCompare

StringCompareValue Property


StringCompareValue Property

The StringCompareValue property sets or returns the string to be compared with a received string message.

Applies To

DTSMessageQueueTask Object

Syntax

object.StringCompareValue [= string]

Part	Description
object	Expression that evaluates to a DTSMessageQueueTask object
string	String to be compared with a received string message
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT StringCompareValue(BSTR* pVal);

HRESULT StringCompareValue(BSTR pVal);

Remarks

The type of comparison is specified by the StringCompareType property. The StringCompareValue property must be defined unless the comparison type is None.

The property also can be referenced through the Properties collection of the Task object with the following code:

Set taskprops = task.Properties
taskprops("StringCompareValue") [= string]

See Also

StringCompareType Property


Subject Property

The Subject property specifies the Subject: line of an e-mail message.

Applies To

SendMailTask Object

Syntax

object.Subject[= value]

Part	Description
object	Expression that evaluates to a SendMailTask object
value	Subject line of an e-mail message
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetSubject(BSTR *pRetVal);

HRESULT SetSubject(BSTR NewValue);

See Also

CCLine Property

MessageText Property

ToLine Property


SuccessReturnCode Property

The SuccessReturnCode property specifies a return code that indicates whether the task completed successfully.

Applies To

CreateProcessTask Object	CreateProcessTask2 Object
Syntax

object.SuccessReturnCode [= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	Return code from the process
Data Type

Long

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetSuccessReturnCode(LONG *pRetVal);

HRESULT SetSuccessReturnCode(LONG NewValue);

Remarks

If the process exit code does not match the value specified by SuccessReturnCode, the task fails. The default value is 0.

See Also

FailPackageOnTimeout Property

TerminateProcessAfterTimeout Property

Timeout Property


TableLock Property

The TableLock property indicates whether an entire table is locked during a load operation.

Applies To

BulkInsertTask Object

Syntax

object.TableLock [= value]

Part	Description
object	Expression that evaluates to a BulkInsertTask object
value	Boolean that specifies whether an entire table is locked
Data Type

Boolean

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetTableLock(VARIANT_BOOL *pRetVal);

HRESULT SetTableLock(VARIANT_BOOL NewValue);

Remarks

The default is FALSE.

See Also

DestinationTableName Property


TaskName Property

The TaskName property specifies the name of the task to execute.

Applies To

Step Object	Step2 Object
Syntax

object.TaskName [= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	Name of the task to execute
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetTaskName(BSTR *pRetVal);

HRESULT SetTaskName(BSTR NewValue);

Remarks

The TaskName property is the link between the Task object and the step that contains it. Typically, set:

Step2.TaskName = Task.Name

See Also

Task Object

Tasks Collection


TaskType Property

The TaskType property sets or returns the type of the DTSMessageQueueTask object, sender, or receiver.

Applies To

DTSMessageQueueTask Object

Syntax

object.TaskType [= value]

Part	Description
Object	Expression that evaluates to a DTSMessageQueueTask object
Value	Code that defines the task type, sender, or receiver
Data Type

Long

Modifiable

Read/write

Prototype (C/C++)

HRESULT TaskType(long* pVal);

HRESULT TaskType(long pVal);

Remarks

The valid values for this property are defined by the DTSMQType constants.

The property also can be referenced through the Properties collection of the Task object with the following code:

Set taskprops = task.Properties
taskprops("TaskType") [= value]

See Also

DTSMQType


TerminateProcessAfterTimeout Property

The TerminateProcessAfterTimeout property specifies whether to terminate the process after the time-out period has expired.

Applies To

CreateProcessTask Object	CreateProcessTask2 Object
Syntax

object.TerminateProcessAfterTimeout [= value]

Part	Description
Object	Expression that evaluates to an object in the Applies To list
Value	Boolean that specifies whether to terminate the process
Data Type

Boolean

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetTerminateProcessAfterTimeout(VARIANT_BOOL *pRetVal);

HRESULT SetTerminateProcessAfterTimeout(VARIANT_BOOL NewValue);

Remarks

If TerminateProcessAfterTimeout is FALSE (the default), the task fails after the time-out without terminating the created process. The FailPackageOnTimeout property determines if the entire package is terminated after the time-out occurs.

See Also

FailPackageOnTimeout Property

Timeout Property


Text Property

The Text property specifies or returns the text of a Microsoft® ActiveX® script.

Applies To

DataPumpTransformScript Object	DTSTransformScriptProperties2 Object
Syntax

object.Text [= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	ActiveX script text
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetText(BSTR *pRetVal);

HRESULT SetText(BSTR NewValue);

Remarks

The scripting language is specified by the Language property.

The property also can be referenced through the TransformServerProperties collection with the following code:

Set transprops = transform.TransformServerProperties
transprops("Text") [= string]

See Also

FunctionEntry Property

Language Property


Timeout Property

The Timeout property specifies the number of seconds in the time-out period.

Applies To

CreateProcessTask Object	CreateProcessTask2 Object
Syntax

object.Timeout [= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	Number of seconds in the time-out period
Data Type

Long

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetTimeout(LONG *pRetVal);

HRESULT SetTimeout(LONG NewValue);

Remarks

A value of 0 (default) indicates no time-out period. Otherwise, the task fails after the time-out period elapses. If the FailPackageOnTimeout property is set, the entire package fails. If the TerminateProcessAfterTimeout property is set, the created process is failed.

See Also

FailPackageOnTimeout Property

TerminateProcessAfterTimeout Property


ToLine Property

The ToLine property specifies e-mail addresses to include on the To: line.

Applies To

SendMailTask Object

Syntax

object.ToLine[= value]

Part	Description
object	Expression that evaluates to a SendMailTask object
value	E-mail addresses to which the mail message is sent
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetToLine(BSTR *pRetVal);

HRESULT SetToLine(BSTR NewValue);

Remarks

The e-mail addresses must be separated by semicolons.

See Also

CCLine Property

MessageText Property

Subject Property


TransactionIsolationLevel Property

The TransactionIsolationLevel property specifies the isolation level at which a Package2 object transaction executes if the UseTransaction property is set to TRUE.

Applies To

Package Object	Package2 Object
Syntax

object.TransactionIsolationLevel[= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	Isolation level at which a Package2 object transaction executes
Data Type

DTSIsolationLevel

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetTransactionIsolationLevel(DTSIsolationLevel *pRetVal);

HRESULT SetTransactionIsolationLevel(DTSIsolationLevel NewValue);

Remarks

The default is ReadCommitted.

See Also

AutoCommitTransaction Property

InTransaction Property

JoinTransactionIfPresent Property

UseTransaction Property


TransformationSetOptions Property

The TransformationSetOptions property returns or sets the mode in which a ParallelDataPumpTask object operates.

Applies To

ParallelDataPumpTask Object

Syntax

oParallelDP.TransformationSetOptions [= value]

Part	Description
oParallelDP	Expression that evaluates to a ParallelDataPumpTask object
value	DTSTransformationSetOptions constant that specifies the ParallelDataPumpTask operating mode
Data Type

DTSTransformationSetOptions Constants

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetTransformationSetOptions(DTSTransformationSetOptions* pRetVal);

HRESULT SetTransformationSetOptions(DTSTransformationSetOptions NewValue);

Remarks

The property must be set to one of the DTSTransformationSetOptions values. The default is DTSTranSetOpt_Flattened.

See Also

TransformationSet Object


TransformFailureFunctionEntry Property

The TransformFailureFunctionEntry property specifies or returns the name of the script function that is to be called for the OnTransformFailure transformation phase.

Applies To

DTSTransformScriptProperties2 Object

Syntax

object.TransformFailureFunctionEntry [= name]

Part	Description
object	Expression that evaluates to a DTSTransformScriptProperties2 object
name	Name of the script function that supports the OnTransformFailure phase
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT TransformFailureFunctionEntry(BSTR* pRetVal);

HRESULT TransformFailureFunctionEntry(BSTR pRetVal);

Remarks

The OnTransformFailure phase occurs after the Transform phase returns DTSTransformStat_Error or DTSTransformStat_ExceptionRow, in the DataPumpTask2, DataDrivenQueryTask2 or ParallelDataPumpTask objects.

The OnTransformFailure script function has read access to the columns of the DTSSource collection and write access to the columns of the DTSDestination collection. Any return values that are valid during the Transform phase can be returned.

The property also can be referenced through the TransformServerProperties collection with the following code:

Set transprops = transform.TransformServerProperties
transprops("TransformFailureFunctionEntry") [= string]

See Also

BatchCompleteFunctionEntry Property

DataDrivenQueryTask2 Object

DataPumpTask2 Object

DTSTransformStatus

FunctionEntry Property

InsertFailureFunctionEntry Property

InsertSuccessFunctionEntry Property

ParallelDataPumpTask Object

PostSourceDataFunctionEntry Property

PreSourceDataFunctionEntry Property

PumpCompleteFunctionEntry Property


TransformFlags Property

The TransformFlags property specifies transformation flags that indicate characteristics of a transformation.

Applies To

Transformation Object	Transformation2 Object
Syntax

object.TransformFlags [= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	Flags that indicate characteristics of the transformation. Use a sum of codes from the DTSTransformFlags constants.
Data Type

Long

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetTransformFlags(LONG *pRetVal);

HRESULT SetTransformFlags(LONG NewValue);

Remarks

The TransformFlags property controls the types of conversions that are considered either valid or invalid (for example, possible overflow, possible loss of sign when converting signed to unsigned, possible string truncation). The test is made at the beginning of the transformation, not row by row.

See Also

DTSTransformFlags


TransformPhases Property

The TransformPhases property returns or sets the transform phases that this transformation supports.

Applies To

Transformation2 Object

Syntax

object.TransformPhases [= value]

Part	Description
object	Expression that evaluates to a Transformation2 object
value	Codes that indicate the phases this transformation supports. Must be a sum of values from the DTSTransformPhaseEnum constants.
Data Type

Long

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetTransformPhases(LONG *pRetVal);

HRESULT SetTransformPhases(LONG NewValue);

Remarks

These are the transformation phases that a transformation can support.

Phase	Description
PreSourceData	Occurs before the first row is fetched from source connection.
Transform	Occurs after each source row is fetched, before the destination row is written.
OnTransformFailure	Occurs after a failure in the Transform phase, indicated by the return of DTSTransformStat_Error or DTSTransformStat_ExceptionRow. Typically, this phase is caused by conversion errors.
OnInsertSuccess	Occurs after each data row is written successfully to the destination connection.
OnInsertFailure	Occurs after each attempt to write a data row to the destination connection failed (for example, by attempting to write a duplicate value to a primary key field, or a NULL to a NOT NULL field).
OnBatchComplete	Occurs in DataPumpTask2 if you select the FastLoad check box after each batch is written, successfully or unsuccessfully.
PostSourceData	Occurs after the last row is written to the destination connection.
OnPumpComplete	Occurs at the end of the execution of the task.
See Also

CurrentPhase Property

DTSTransformPhaseEnum


TransformServer Property

The TransformServer property returns a reference to the transform server object (the class-specific transformation object) through which the properties of that object can be directly accessed.

Applies To

Transformation Object	Transformation2 Object
Syntax

[Set transform =] object.TransformServer

Part	Description
object	Expression that evaluates to an object in the Applies To list
transform	Reference to the transform server object
Data Type

Object

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetTransformServer(IDispatch **pRetVal);

Remarks

You can access the properties of the class-specific transformation object directly or through the TransformServerProperties collection of the Transformation2 object.

Example

The following code creates a DataPumpTransformMidString transformation, and then references the transform server object and uses it to set the CharacterStart property:

    Dim objDataPump   As DTS.DataPumpTask

    Dim objTransform  As DTS.Transformation

    Dim objMidString  As DTSPump.DataPumpTransformMidString

    . . .

    Set objTransform = objDataPump.Transformations. _

            New("DTSPump.DataPumpTransformMidString")

    Set objMidString = objTransform.TransformServer

    objMidString.CharacterStart = 5

See Also

TransformServerID Property

TransformServerParameter Property

TransformServerProperties Property


TransformServerID Property

The TransformServerID property returns the programmatic identifier (ProgID) or class identifier (CLSID) of the transform server object (the class-specific transformation object).

Applies To

Transformation Object	Transformation2 Object
Syntax

object.TransformServerID

Part	Description
object	Expression that evaluates to an object in the Applies To list
Data Type

String

Modifiable

Read-only

Prototype (C/C++)

HRESULT GetTransformServerID(BSTR *pRetVal);

Remarks

The ProgID or CLSID returned by the TransformServerID property is the identifier that was used with the New method of the Transformations collection to create the Transformation2 object.

See Also

New (ID) Method

Transformations Collection

TransformServer Property

TransformServerParameter Property

TransformServerProperties Property


TransformServerParameter Property

The TransformServerParameter property specifies an initialization parameter for the transform server object (class-specific transformation object), if required.

Applies To

Transformation Object	Transformation2 Object
Syntax

object.TransformServerParameter [= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	Transform server's initialization parameter
Data Type

Variant

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetTransformServerParameter(VARIANT *pRetVal);

HRESULT SetTransformServerParameter(VARIANT NewValue) ;

Remarks

Because the TransformServerParameter property has a variant data type, it may be either a scalar value or an array. Some custom transformation servers may expose an alternate interface on their IDispatch transformation server objects to specify complex parameters.

See Also

TransformServer Property

TransformServerID Property

TransformServerProperties Property


TransformServerProperties Property

The TransformServerProperties property returns a reference to a Properties collection containing the properties of the transform server object (the class-specific transformation object).

Applies To

Transformation Object	Transformation2 Object
Syntax

object.TransformServerProperties

Part	Description
object	Expression that evaluates to an object in the Applies To list
Data Type

Properties

Modifiable

Read-only

Prototype (C/C++)

HRESULT GetTransformServerProperties(IDTSProperties **pRetVal);

Remarks

You can use the TransformServerProperties property to access the properties of the class-specific transformation object without creating a reference to that object.

Example

The following code creates a DataPumpTransformMidString transformation, and then references the CharacterStart property through the TransformServerProperties property:

    Dim objDataPump   As DTS.DataPumpTask

    Dim objTransform  As DTS.Transformation

    . . .

    Set objTransform = objDataPump.Transformations. _

            New("DTSPump.DataPumpTransformMidString")

    objTransform.TransformServerProperties("CharacterStart").Value = 5

See Also

Properties Collection

TransformServer Property

TransformServerID Property

TransformServerParameter Property


TrimEmbeddedWhiteSpace Property

The TrimEmbeddedWhiteSpace property specifies or returns a value indicating whether embedded white-space characters are removed from the source column string copied by custom transformations.

Applies To

DataPumpTransformMidString Object	DataPumpTransformTrimString Object
Syntax

transerver.TrimEmbeddedWhiteSpace [= boolean]

Part	Description
transerver	Expression that evaluates to an object from the Applies To list.
boolean	If TRUE, embedded white-space characters are removed from the source string. Default is FALSE.
Data Type

Boolean

Modifiable

Read/write

Prototype (C/C++)

HRESULT TrimEmbeddedWhiteSpace(VARIANT_BOOL* pRetVal);

HRESULT TrimEmbeddedWhiteSpace(VARIANT_BOOL pRetVal);

Remarks

White-space characters are spaces, tabs, carriage returns and linefeeds. Embedded white-space characters are those that appear between the first and last character that is not a white-space character.

The property also can be referenced through the TransformServerProperties collection with the following code:

Set transprops = transform.TransformServerProperties
transprops("TrimEmbeddedWhiteSpace") [= boolean]

See Also

TrimLeadingWhiteSpace Property

TrimTrailingWhiteSpace Property


TrimLeadingWhiteSpace Property

The TrimLeadingWhiteSpace property specifies or returns a value indicating whether leading white-space characters are removed from the source column string copied by custom transformations.

Applies To

DataPumpTransformMidString Object	DataPumpTransformTrimString Object
Syntax

transerver.TrimLeadingWhiteSpace [= boolean]

Part	Description
transerver	Expression that evaluates to an object from the Applies To list.
boolean	If TRUE, leading white-space characters are removed from the source string. Default is FALSE.
Data Type

Boolean

Modifiable

Read/write

Prototype (C/C++)

HRESULT TrimLeadingWhiteSpace(VARIANT_BOOL* pRetVal);

HRESULT TrimLeadingWhiteSpace(VARIANT_BOOL pRetVal);

Remarks

White-space characters are spaces, tabs, carriage returns and linefeeds. Leading white-space characters are those that appear ahead of the first character that is not a white-space character.

The property also can be referenced through the TransformServerProperties collection with the following code:

Set transprops = transform.TransformServerProperties
transprops("TrimLeadingWhiteSpace") [= boolean]

See Also

TrimEmbeddedWhiteSpace Property

TrimTrailingWhiteSpace Property


TrimTrailingWhiteSpace Property

The TrimTrailingWhiteSpace property specifies or returns a value indicating whether trailing white-space characters are removed from the source column string copied by custom transformations.

Applies To

DataPumpTransformMidString Object	DataPumpTransformTrimString Object
Syntax

transerver.TrimTrailingWhiteSpace [= boolean]

Part	Description
transerver	Expression that evaluates to an object from the Applies To list.
boolean	If TRUE, trailing white-space characters are removed from the source string. Default is FALSE.
Data Type

Boolean

Modifiable

Read/write

Prototype (C/C++)

HRESULT TrimTrailingWhiteSpace(VARIANT_BOOL* pRetVal);

HRESULT TrimTrailingWhiteSpace(VARIANT_BOOL pRetVal);

Remarks

White-space characters are spaces, tabs, carriage returns and linefeeds. Trailing white-space characters are those that appear after the last character that is not a white-space character.

The property also can be referenced through the TransformServerProperties collection with the following code:

Set transprops = transform.TransformServerProperties
transprops("TrimTrailingWhiteSpace") [= boolean]

See Also

TrimEmbeddedWhiteSpace Property

TrimLeadingWhiteSpace Property


Type Property

The Type property specifies the data type of the value of a Property object.

Applies To

Property Object

Syntax

object.Type

Part	Description
object	Expression that evaluates to a Property object
Data Type

Long

Modifiable

Read-only

Prototype (C/C++)

HRESULT GetType(long *pRetVal);

See Also

Get Property

Set Property

Value Property


UDLPath Property

The UDLPath property specifies the name and path of a Microsoft® Data Link file used to create a connection.

Applies To

Connection Object	Connection2 Object
Syntax

object.UDLPath [= path]

Part	Description
object	Expression that evaluates to an object in the Applies To list
path	Name and path of the data link file
Data Type

String

Modifiable

Read/write for the Connection2 object. Read-only for the Connection object.

Prototype (C/C++)

HRESULT GetUDLPath(BSTR *pRetVal);

Remarks

When a data link file is used, the ConnectionProperties collection is not available.

See Also

ConnectionProperties Property


UnicodeFile Property

The UnicodeFile property specifies or returns a value indicating whether the data read from or written to files by transformations is translated from or to Unicode.

Applies To

DataPumpTransformReadFile Object	DataPumpTransformWriteFile Object
Syntax

transerver.UnicodeFile [= boolean]

Part	Description
transerver	Expression that evaluates to an object from the Applies To list.
boolean	If TRUE, the file data is translated from or to Unicode. Default is FALSE.
Data Type

Boolean

Modifiable

Read/write

Prototype (C/C++)

HRESULT UnicodeFile(VARIANT_BOOL* pRetVal);

HRESULT UnicodeFile(VARIANT_BOOL pRetVal);

Remarks

For the DataPumpTransformReadFile object, the file is translated from Unicode to ANSI if the destination column is not Unicode and the UnicodeFile property is TRUE.

For the DataPumpTransformWriteFile object, the source column data has already been translated to from ANSI to Unicode, if necessary. If the UnicodeFile property is TRUE, the Unicode header bytes 0xFFFE are written to the file, unless the AppendIfFileExists property is TRUE and the header is already in the file.

If the UnicodeFile property is TRUE, the OEMFile property is ignored.

The property also can be referenced through the TransformServerProperties collection with the following code:

Set transprops = transform.TransformServerProperties
transprops("UnicodeFile") [= boolean]

See Also

AppendIfFileExists Property

OEMFile Property


UpdateQuery Property

The UpdateQuery property specifies a string of one or more parameterized SQL statements to execute at the destination as the Update query.

Applies To

DataDrivenQueryTask Object	TransformationSet Object
DataDrivenQueryTask2 Object
Syntax

object.UpdateQuery [= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	Parameterized string of SQL statements
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetUpdateQuery(BSTR *pRetVal);

HRESULT SetUpdateQuery(BSTR NewValue);

Remarks

Although the name of a data driven query property is preset, its content is not enforced. Any of the queries may be used for any desired operation. The nomenclature is provided as a convenient means of identification. The UpdateQuery property does not need to contain a Transact-SQL UPDATE statement.

The values of the columns specified by the UpdateQueryColumns property replace the parameters placeholders in the UpdateQuery in the order in which the columns were added to the collection.

See Also

Adding DTS Query Strings

DeleteQuery Property

InsertQuery Property

UpdateQueryColumns Property

UserQuery Property


UpdateQueryColumns Property

The UpdateQueryColumns property returns a reference to a collection of Column objects that serve as parameters for the query specified by the UpdateQuery property.

Applies To

DataDrivenQueryTask Object	TransformationSet Object
DataDrivenQueryTask2 Object
Syntax

object.UpdateQueryColumns

Part	Description
object	Expression that evaluates to an object in the Applies To list
Data Type

Columns Collection

Modifiable

Read-only

Prototype (C/C++)

HRESULT GetUpdateQueryColumns(IDTSColumns **pRetVal);

Remarks

The values of the columns specified by the UpdateQueryColumns property are substituted for the parameters in the UpdateQuery in the order in which the columns were added to the collection.

See Also

Adding DTS Query Strings

Column Object

DeleteQueryColumns Property

InsertQueryColumns Property

UpdateQuery Property

UserQueryColumns Property


UpperCaseString Property

The UpperCaseString property specifies or returns a value indicating whether the alphabetical characters in the source column string copied by transformations are all converted to uppercase characters.

Applies To

DataPumpTransformMidString Object	DataPumpTransformTrimString Object
Syntax

transerver.UpperCaseString [= boolean]

Part	Description
transerver	Expression that evaluates to an object from the Applies To list.
boolean	Boolean that specifies whether the alpha characters in the source string are converted to uppercase. Default is FALSE.
Data Type

Boolean

Modifiable

Read/write

Prototype (C/C++)

HRESULT UpperCaseString(VARIANT_BOOL* pRetVal);

HRESULT UpperCaseString(VARIANT_BOOL pRetVal);

Remarks

The property also can be referenced through the TransformServerProperties collection with the following code:

Set transprops = transform.TransformServerProperties
transprops("UpperCaseString") [= boolean]

See Also

LowerCaseString Property


UseCache Property

The UseCache property returns or sets whether cached information is used when enumerating the associated collection.

Applies To

OLEDBProviderInfos Collection	TaskInfos Collection
ScriptingLanguageInfos Collection	TransformationInfos Collection
Syntax

object.UseCache [= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list.
value	Determines whether cached information is used to enumerate the associated collection.
Data Type

Boolean

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetUseCache(VARIANT_BOOL *pRetVal);

HRESULT SetUseCache(VARIANT_BOOL NewValue);

Remarks

When UseCache is FALSE, the information about the components of the associated collection is obtained from the operating system registry. This requires all registered classes to be examined and may take a significant amount of time, depending on the amount of software installed on the computer.

Data Transformation Services (DTS) maintains a cache in the system registry of the components of each collection in the Applies To list and examines the appropriate cache, rather than all registered classes, when UseCache is TRUE. Use the Refresh method to refresh the appropriate cache from the system registry.

See Also

Refresh Method


UseCollation Property

The UseCollation property specifies whether column-level collation settings on the source table are used when transferring data between computers running instances of Microsoft® SQL Server™ 2000.

Applies To

TransferObjectsTask2 Object

Syntax

transfobj.UseCollation [= value]

Part	Description
transfobj	Expression that evaluates to a TransferObjectsTask2 object.
value	Determines whether column-level collation settings are used when transferring data.
Data Type

Boolean

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetUseCollation(VARIANT_BOOL *pRetVal);

HRESULT SetUseCollation(VARIANT_BOOL NewValue);

Remarks

The default for this property is TRUE. The UseCollation property of the TransferObjectsTask2 object exposes the UseCollation property of the SQL-DMO Transfer2 object.

If UseCollation is set to TRUE and the destination table is dropped during transfer, the new destination table will be created with column-level collations identical to those of the source table.

If UseCollation is set to FALSE and the destination table is dropped during transfer, the new destination table will be created with column-level collations identical to those of the destination server default code page. Note that if the column-level collation of the source data does not match the source server default code page, mistranslation will occur.

See Also

DestTranslateChar Property

SourceTranslateChar Property

Transfer2 Object

UseCollation Property


UseFastLoad Property

The UseFastLoad property specifies whether to use the FastLoad option, where rows are processed in batches under a single transaction commit.

Applies To

DataPumpTask Object	DataPumpTask2 Object
Syntax

object.UseFastLoad [= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list.
value	Boolean that specifies whether to use the FastLoad option, if available.
Data Type

Boolean

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetUseFastLoad(VARIANT_BOOL *pRetVal);

HRESULT SetUseFastLoad(VARIANT_BOOL NewValue);

Remarks

The batch size is controlled by the InsertCommitSize property.

The FastLoad option is available if the OLE DB provider supports the IRowsetFastLoad interface.

See Also

InsertCommitSize Property


UseOLEDBServiceComponents Property

The UseOLEDBServiceComponents property specifies whether to use OLE DB service components when initializing data sources.

Applies To

Package Object	Package2 Object
Syntax

object.UseOLEDBServiceComponents[= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	Boolean that specifies whether to use OLE DB service components
Data Type

Boolean

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetUseOLEDBServiceComponents(VARIANT_BOOL *pRetVal);

HRESULT SetUseOLEDBServiceComponents(VARIANT_BOOL NewValue);

Remarks

The default is TRUE.

See Also

ConnectionProperties Property


UseRepository Property

The UseRepository property sets or returns a value indicating whether Microsoft® SQL Server™ 2000 Meta Data Services should be used as the source of the Data Transformation Services (DTS) package to be run by an ExecutePackageTask object.

Applies To

ExecutePackageTask

Syntax

object.UseRepository [= boolean]

Part	Description
object	Expression that evaluates to an ExecutePackageTask object.
boolean	If TRUE, Meta Data Services is searched for the DTS package to be run.
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT UseRepository(VARIANT_BOOL* pRetVal);

HRESULT UseRepository(VARIANT_BOOL pRetVal);

Remarks

If UseRepository is FALSE, the DTS package is sought in the SQL Server msdb database, unless a storage file specification is provided in the FileName property.

This property also can be referenced through the Properties collection of the Task object with the following code:

Set taskprops = task.Properties
taskprops("UseRepository") [= boolean]

See Also

FileName Property

RepositoryDatabaseName Property


UserID Property

The UserID property specifies a user ID or name to use when making a connection.

Applies To

Connection Object	Connection2 Object
Syntax

object.UserID [= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	User ID or name to use
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetUserID(BSTR *pRetVal);

HRESULT SetUserID(BSTR NewValue);

Remarks

You need to specify values for the UserID and Password properties if UseTrustedConnection is FALSE.

Note   It is recommended that you connect to an instance of Microsoft® SQL Server™ using Windows Authentication instead of SQL Server Authentication. To use Windows Authentication, set UseTrustedConnection to TRUE.

See Also

Password Property

UseTrustedConnection Property


UserQuery Property

The UserQuery property specifies a string of one or more parameterized SQL statements to execute at the destination as the user query.

Applies To

DataDrivenQueryTask Object	TransformationSet Object
DataDrivenQueryTask2 Object
Syntax

object.UserQuery [= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	Parameterized string of SQL statements
Data Type

String

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetUserQuery(BSTR *pRetVal);

HRESULT SetUserQuery(BSTR NewValue);

Remarks

Although the name of a data driven query property is preset, its content is not enforced. Any of the queries may be used for any desired operation. The nomenclature is provided as a convenient means of identification. Typically, the UserQuery property contains a stored procedure reference.

The values of the columns specified by the UserQueryColumns property replace the parameter placeholders in the UserQuery in the order in which the columns were added to the collection.

See Also

Adding DTS Query Strings

DeleteQuery Property

InsertQuery Property

UpdateQuery Property

UserQueryColumns Property


UserQueryColumns Property

The UserQueryColumns property returns a reference to a collection of Column objects that serve as parameters for the query specified by the UserQuery property.

Applies To

DataDrivenQueryTask Object	TransformationSet Object
DataDrivenQueryTask2 Object
Syntax

object.UserQueryColumns

Part	Description
object	Expression that evaluates to an object in the Applies To list
Data Type

Columns Collection

Modifiable

Read-only

Prototype (C/C++)

HRESULT GetUserQueryColumns(IDTSColumns **pRetVal);

Remarks

The values of the columns specified by the UserQueryColumns property replace the parameter placeholders in the UserQuery in the order in which the columns were added to the collection.

See Also

Adding DTS Query Strings

Column Object

DeleteQueryColumns Property

InsertQueryColumns Property

UpdateQueryColumns Property

UserQuery Property


UseTransaction Property

The UseTransaction property specifies whether the Package2 object creates a transaction for supporting Data Transformation Services (DTS) tasks.

Applies To

Package Object	Package2 Object
Syntax

object.UseTransaction[= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list.
value	Determines whether the Package2 object creates a transaction.
Data Type

Boolean

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetUseTransaction(VARIANT_BOOL *pRetVal);

HRESULT SetUseTransaction(VARIANT_BOOL NewValue);

See Also

InTransaction Property

JoinTransactionIfPresent Property

TransactionIsolationLevel Property


UseTransaction (DTSMQMessage) Property

The UseTransaction property sets or returns a value indicating whether a transaction is used to send the message defined by the DTSMQMessage object.

Applies To

DTSMQMessage Object

Syntax

object.UseTransaction [= boolean]

Part	Description
object	Expression that evaluates to a DTSMQMessage object
boolean	Boolean that specifies whether the message is sent as part of a transaction
Data Type

Boolean

Modifiable

Read/write

Prototype (C/C++)

HRESULT UseTransaction(VARIANT_BOOL* pVal);

HRESULT UseTransaction(VARIANT_BOOL pVal);

Remarks

All the transacted messages sent by a DTSMessageQueueTask object use the same transaction.

See Also

WaitForAcknowledgement Property


UseTrustedConnection Property

The UseTrustedConnection property specifies whether the connection connects to the data source using Windows Authentication security mode.

Applies To

Connection Object	ExecutePackageTask Object
Connection2 Object
Syntax

object.UseTrustedConnection [= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	Value indicating whether to connect using Windows Authentication
Data Type

Boolean

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetUseTrustedConnection(VARIANT_BOOL *pRetVal);

HRESULT SetUseTrustedConnection(VARIANT_BOOL NewValue);

Remarks

You need to specify values for the UserID and Password properties if UseTrustedConnection is FALSE.

Note   It is recommended that you connect to an instance of Microsoft® SQL Server™ using Windows Authentication instead of SQL Server Authentication. To use Windows Authentication, set UseTrustedConnection to TRUE.

See Also

Password Property

UserID Property


Value Property

The Value property specifies the value of a GlobalVariable, OLEDBProperty, or PrecedenceConstraint object.

Applies To

GlobalVariable Object	OLEDBProperty2 Object
GlobalVariable2 Object	PrecedenceConstraint Object
OLEDBProperty Object	Property Object
Syntax

object.Value

Part	Description
object	Expression that evaluates to an object in the Applies To list
Data Type

Variant

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetValue(VARIANT *pRetVal);

HRESULT SetValue(VARIANT NewValue);

Remarks

For the PrecedenceConstraint object, the Value property must be from either the DTSStepExecResult or DTSStepExecStatus constants. For the other objects, the Value property can be any Variant, including references to COM objects, such as a Data Transformation Services (DTS) Package2 object or a Microsoft® ActiveX® Data Objects (ADO) disconnected recordset.

See Also

DTSStepExecResult

DTSStepExecStatus


VersionID Property

The VersionID property specifies the globally unique identifier (GUID) of this version of the Data Transformation Services (DTS) package.

Applies To

ExecutePackageTask Object	PackageLineage Object
Package Object	PackageLogRecord Object
Package2 Object	SavedPackageInfo Object
PackageInfo Object
Syntax

object.VersionID

Part	Description
object	Expression that evaluates to an object in the Applies To list
Data Type

String

Modifiable

Read-write for the ExecutePackageTask object. Read-only for the other objects.

Prototype (C/C++)

HRESULT GetVersionID(BSTR *pRetVal);

Remarks

For the ExecutePackageTask object, if the VersionID is not specified, the most recent version of the package is run. The PackageID does not need to be specified if the VersionID is specified because VersionID uniquely identifies both package and version.

To determine the version ID of a package, open the package in DTS Designer, and then in the Package/Properties dialog box, click the General tab.

The syntax of GUIDs is:

{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}

where X represents hexadecimal digits. The groupings are 8, 4, 4, 4, and 12 digits. The curly brackets are required. Spaces cannot be embedded.

See Also

PackageID Property


VersionSaveDate Property

The VersionSaveDate property specifies the date and time a version of a Data Transformation Services (DTS) package was saved.

Applies To

SavedPackageInfo Object

Syntax

object.VersionSaveDate

Part	Description
object	Expression that evaluates to a SavedPackageInfo object
Data Type

Date

Modifiable

Read-only

Prototype (C/C++)

HRESULT GetVersionSaveDate(*pRetVal);

See Also

PackageCreationDate Property


WaitForAcknowledgement Property

The WaitForAcknowledgement property returns or sets a value indicating whether a DTSMessageQueueTask waits for an acknowledgement after sending the message defined by the DTSMQMessage object.

Applies To

DTSMQMessage Object

Syntax

object.WaitForAcknowledgement [= boolean]

Part	Description
object	Expression that evaluates to a DTSMQMessage object
boolean	Boolean that specifies whether the task sending the message waits for an acknowledgement
Data Type

Boolean

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetWaitForAcknowledgement(VARIANT_BOOL *pVal);

HRESULT SetWaitForAcknowledgement(VARIANT_BOOL pVal);

Remarks

The sending task does not complete until the acknowledgement is received. If a transaction is used, it is not committed until the acknowledgement is received.

All the transacted messages sent by a DTSMessageQueueTask object use the same transaction.

See Also

UseTransaction Property


WriteCompletionStatusToNTEventLog Property

The WriteCompletionStatusToNTEventLog property specifies whether the completion status of the Data Transformation Services (DTS) package is written to the Microsoft® Windows® application log.

Applies To

Package Object	Package2 Object
Syntax

object.WriteCompletionStatusToNTEventLog [= value]

Part	Description
object	Expression that evaluates to an object in the Applies To list
value	Boolean that specifies whether package status is written to the Windows application log
Data Type

Boolean

Modifiable

Read/write

Prototype (C/C++)

HRESULT GetWriteCompletionStatusToNTEventLog(VARIANT_BOOL *pRetVal);

HRESULT SetWriteCompletionStatusToNTEventLog(VARIANT_BOOL NewValue);

Remarks

The default is TRUE.

See Also

FailOnError Property

FailPackageOnLogFailure Property


Methods

This section defines the methods of the Microsoft® SQL Server™ 2000 Data Transformation Services (DTS) objects and collections. The methods control the operation of the DTS packages and other objects.


AcquireConnection Method

The AcquireConnection method allows a task to acquire exclusive ownership of a connection to an OLE DB service provider.

Applies To

Connection Object	Connection2 Object
Syntax

[Value =] Connection.AcquireConnection(TaskName)

Part	Description
Connection	Expression that evaluates to an object in the Applies To list
TaskName	Name of the task that is to acquire the connection
Value	Boolean that indicates whether the connection was acquired
Remarks

When an application calls Connection.AcquireConnection, the InUse property is set to TRUE. The call fails if another task owns the connection. A task releases a connection by calling the ReleaseConnection method. This method is required only if you are creating a custom task.

All tasks must include calls to AcquireConnection and ReleaseConnection. The tasks supplied with Microsoft® SQL Server™ 2000 already include them.

Prototype (C/C++)

HRESULT AcquireConnection(
BSTR TaskName,
LPUNKNOWN *pRetVal);

See Also

Creating DTS Package Objects and Connections

InUse Property

ReleaseConnection Method


Add Method

The Add method adds an object to a collection.

Applies To

Columns Collection	PrecedenceConstraints Collection
Connections Collection	Steps Collection
DTSMQMessages Collection	Tasks Collection
DynamicPropertiesTaskAssignments Collection	Transformations Collection
GlobalVariables Collection	TransformationSets Collection
Lookups Collection
Syntax

Collection.Add Object

Part	Description
Collection	Expression that evaluates to an object in the Applies To list
Object	Object to add to the collection
Remarks

The required type of Object depends on the collection to which it is being added.

Collection	Object
Columns	Column Object
Connections	Connection Object Connection2 Object
DTSMQMessages	DTSMQMessage Object
DynamicPropertiesTaskAssignments	DynamicPropertiesTaskAssignment Object
GlobalVariables	GlobalVariable Object
Lookups	Lookup Object
PrecedenceConstraints	PrecedenceConstraint Object
Steps	Step Object Step2 Object
Tasks	Task Object
Transformations	Transformation Object Transformation2 Object
TransformationSets	TransformationSet Object
The Add method does not create an object; it adds an existing object to its collection. Typically, you create the object with the New method of the collection.

Prototype (C/C++)

HRESULT Add(ObjectInterface *Object);

See Also

New Method

New (Columns) Method

New (ID) Method

New (Name) Method


AddColumn Method

The AddColumn method creates a Column object by name and ordinal position and adds it to the collection.

Applies To

Columns Collection

Syntax

Columns.AddColumn Name,Ordinal

Part	Description
Columns	Expression that evaluates to a Columns collection
Name	String that is the name of the column
Ordinal	Long that is the ordinal position of the column
Remarks

The AddColumn method does not return a reference to the column object it creates. If you need to set Column properties other than Name and Ordinal, you can create the Column object with the New method, set the properties, and then add it to the collection with the Add method. Or, you can access the Column object from the collection after creating it with AddColumn.

Prototype (C/C++)

HRESULT AddColumn(
BSTR Name,
long Ordinal);

Example

This Microsoft® Visual Basic® sample accesses a Column object from the collection after creating it with AddColumn. The expression objTransform.SourceColumns evaluates to a Columns collection:

Dim objTransForm      As DTS.Transformation2

Dim objColumn         As DTS.Column

. . .

objTransForm.SourceColumns.AddColumn "LastName", 2

Set objColumn = objTransForm.SourceColumns( "LastName" )

See Also

Add Method

Adding DTS Column Objects

New (Columns) Method


AddConstraint Method

The AddConstraint method adds a PrecedenceConstraint object to a Step2 object.

Applies To

PrecedenceConstraints Collection

Syntax

Constraints.AddConstraint StepName

Part	Description
Constraints	Expression that evaluates to a PrecedenceConstraints collection
StepName	Name of the step referenced by the precedence constraint
Remarks

StepName is not the name of the Step2 object to which the PrecedenceConstraint object is being added. It is the name of the step whose status or result determines when the Step2 object can be released for execution.

The AddConstraint method does not return a reference to the PrecedenceConstraint object it creates. You may need to set PrecedenceConstraint properties, PrecedenceBasis, or Value to other than their defaults.  In this case, you can create the PrecedenceConstraint object with the New method, set the properties, and then add it to the collection with the Add method. Or, you can access the PrecedenceConstraint object from the collection after creating it with AddConstraint.

Prototype (C/C++)

HRESULT AddConstraint(BSTR StepName);

Example

This Microsoft® Visual Basic® sample accesses a PrecedenceConstraint object from the collection after creating it with AddConstraint:

objStep.PrecedenceConstraints.AddConstraint "StartStep"

Set objConstraint = objStep.PrecedenceConstraints( "StartStep" )

See Also

Add Method

Creating DTS Package Workflow and Tasks

PrecedenceBasis Property

PrecedenceConstraint Object

New (Name) Method

Value Property


AddGlobalVariable Method

The AddGlobalVariable method adds a GlobalVariable object to the collection by name.

Applies To

GlobalVariables Collection

Syntax

GlobalVariables.AddGlobalVariable Name, Value

Part	Description
GlobalVariables	Expression that evaluates to a GlobalVariables collection
Name	String that is the name of the global variable
Value	Variant that is the initial value of the global variable
Remarks

The AddGlobalVariable method does not return a reference to the GlobalVariable object it creates. You also can create the GlobalVariable object with the New method and then add it to the collection with the Add method.

Prototype (C/C++)

HRESULT AddGlobalVariable(
BSTR Name,
VARIANT Value);

See Also

Add Method

Adding DTS Lookups and Global Variables

GlobalVariable Object

New (Name) Method


AddLookup Method

The AddLookup method adds a parameterized query to the Lookups collection.

Applies To

Lookups Collection

Syntax

object.AddLookup Name, Query, ConnectionID, [MaxCacheRows]

Part	Description
object	Expression that evaluates to a Lookups collection
Name	String that is the lookup query name
Query	String that is the SQL query
ConnectionID	Long that is the connection ID
MaxCacheRows	Long that is the maximum number of rows to cache for reuse
Remarks

Typically, a Lookup object is referenced in a Microsoft® ActiveX® script. The Query is executed against the data source specified by the ConnectionID. The first row of the returned rowset is used. MaxCacheRows specifies the number of rows cached locally so that subsequent lookups that target that row do not need to reissue the query against the data source.

The AddLookup method does not return a reference to the Lookup object it creates. You also can create the Lookup object with the New method, set its properties, and then add it to the collection with the Add method.

Prototype (C/C++)

HRESULT AddLookup(BSTR Name,
BSTR Query,
long ConnectionID,
long MaxCacheRows);

Example

This Microsoft Visual Basic® sample creates and adds a Lookup object to the collection:

objDataPump.Lookups.AddLookup "ExpandState", _

"SELECT StateName FROM StateInfo WHERE POCode = ?", _

2, 50

See Also

Add Method

Adding DTS Lookups and Global Variables

Lookup Object

New (Name) Method


AddObjectForTransfer Method

The AddObjectForTransfer method adds an object to the list of Microsoft® SQL Server™ objects to be transferred.

Applies To

TransferObjectsTask Object	TransferObjectsTask2 Object
Syntax

object.AddObjectForTransfer ObjectName, OwnerName, Type

Part	Description
object	Expression that evaluates to an object in the Applies To list
ObjectName	Name of the object to transfer
OwnerName	Object owner name
Type	Type of object to transfer, from the DTSSQLObjectType constants
Prototype (C/C++)

HRESULT AddObjectForTransfer(
BSTR ObjectName,
BSTR OwnerName,
DTSSQLObjectType Type);

See Also

DTSSQLObjectType

GetObjectForTransfer Method

ResetObjectsList Method


BeginAcquireMultipleConnections Method

The BeginAcquireMultipleConnections method acquires ownership of the Connections collection's synchronization object. This is to serialize the acquisition of multiple connections by a Data Transformation Services (DTS) task.

Applies To

Connections Collection

Syntax

Connections.BeginAcquireMultipleConnections

Part	Description
Connections	Expression that evaluates to a Connections collection
Remarks

When implementing a custom task that needs to acquire more than one connection, do the following to avoid deadlocks:

1.	Call BeginAcquireMultipleConnections.

2.	For each connection to be acquired:

•	Verify that connection.InUse is FALSE.

•	Call connection.AcquireConnection.

3.	Call EndAcquireMultipleConnections.

Prototype (C/C++)

HRESULT BeginAcquireMultipleConnections();

See Also

AcquireConnection Method

Connection Object

Creating DTS Package Objects and Connections

EndAcquireMultipleConnections Method

InUse Property


CancelExecution Method

The CancelExecution method cancels execution of the task.

Applies To

TransferObjectsTask Object	TransferObjectsTask2 Object
Syntax

object.CancelExecution

Part	Description
object	Expression that evaluates to an object in the Applies To list
Remarks

CancelExecution must be called on a thread different from the execution thread.

Prototype (C/C++)

HRESULT CancelExecution();


CheckSyntax Method

The CheckSyntax method evaluates the script specified by the ActiveXScript property for correct syntax.

Applies To

ActiveScriptTask Object

Syntax

object.CheckSyntax()

Part	Description
Object	Expression that evaluates to an object in the Applies To list
Prototype (C/C++)

HRESULT CheckSyntax();

See Also

ActiveXScript Property

Adding DTS ActiveX Scripts

ScriptLanguage Property


CreateCustomToolTip Method

The CreateCustomToolTip method creates a ToolTip window for a Data Transformation Services (DTS) custom task.

Applies To

CustomTaskUI Object

Syntax (Visual Basic)

Sub CustomTaskUI_CreateCustomToolTip(
ByVal hwndParent As Long,
ByVal x As Long,
ByVal y As Long,
plTipWindow As Long )

Part	Description
CustomTaskUI	Expression that evaluates to a CustomTaskUI interface
HwndParent	Handle of window in which ToolTip is to be displayed
X	Horizontal coordinate of ToolTip window
Y	Vertical coordinate of ToolTip window
PlTipWindow	Handle of ToolTip window generated by method
Remarks

The CreateCustomToolTip method must be implemented by a custom task that is to show custom ToolTips in its user interface. It is called by DTS at the time the ToolTip is to be displayed. CreateCustomToolTip draws the ToolTip window and returns its window handle to DTS in the plTipWindow parameter.

Prototype (C/C++)

HRESULT CreateCustomToolTip(
long hwndParent,
long x,
long y,
long *plTipWindow);

See Also

Edit Method

Delete Method

New (CustomTaskUI) Method


Delete Method

The Delete method of the CustomTaskUI interface must be supplied by the implementer of a Data Transformation Services (DTS) custom task that has a user interface. It is called by DTS when an instance of the custom task is to be deleted.

Applies To

CustomTaskUI Object

Syntax (Visual Basic)

Sub CustomTaskUI_Delete(ByVal hwndParent As Long )

Part	Description
hwndParent	Handle to the window to be the parent of the custom task user interface
Remarks

The window that is parent to the custom task's user interface window typically would be the DTS Designer design sheet or the Microsoft® Visual Studio® development environment desktop.

Prototype (C/C++)

HRESULT Delete(long hwndParent);

See Also

CreateCustomToolTip Method

Edit Method

New (CustomTaskUI) Method


Edit Method

The Edit method of the CustomTaskUI interface must be supplied by the implementer of a Data Transformation Services (DTS) custom task that has a user interface. It is called by DTS when a user wants to edit properties of the CustomTask object.

Applies To

CustomTaskUI Object

Syntax (Visual Basic)

Sub CustomTaskUI_Edit(ByVal hwndParent As Long )

Part	Description
hwndParent	Handle to the window to be the parent of the custom task user interface
Remarks

The Edit method should display the user interface for the custom task, typically a dialog box or property sheet.

The window that is parent to the custom task's user interface window typically is the DTS Designer design sheet or the Microsoft® Visual Studio® development environment desktop.

Prototype (C/C++)

HRESULT Edit(long hwndParent);

See Also

CreateCustomToolTip Method

Delete Method

New (CustomTaskUI) Method


EndAcquireMultipleConnections Method

The EndAcquireMultipleConnections method releases ownership of the Connections collection's synchronization object. This is after serializing the acquisition of multiple connections by a Data Transformation Services (DTS) task.

Applies To

Connections Collection

Syntax

Connections.EndAcquireMultipleConnections

Part	Description
Connections	Expression that evaluates to a Connections collection
Remarks

When implementing a custom task that needs to acquire more than one connection, do the following to avoid deadlocks:

1.	Call BeginAcquireMultipleConnections.

2.	For each connection to be acquired:

•	Verify that connection.InUse is FALSE.

•	Call connection.AcquireConnection.

3.	Call EndAcquireMultipleConnections.

Prototype (C/C++)

HRESULT EndAcquireMultipleConnections();

See Also

AcquireConnection Method

BeginAcquireMultipleConnections Method

Connection Object

Creating DTS Package Objects and Connections

InUse Property


EnumPackageInfos Method

The EnumPackageInfos method returns a PackageInfos collection containing information about all the packages stored in Microsoft® SQL Server™ 2000 Meta Data Services or in SQL Server storage that satisfy the criteria of the input parameters.

Applies To

PackageRepository Object	PackageSQLServer Object
Syntax

Set collection = object.EnumPackageInfos(
PackageName,
ReturnLatest,
PackageID )

Part	Description
collection	Expression that evaluates to a PackageInfos collection
object	Expression that evaluates to an object in the Applies To list
PackageName	A string specifying the package name to which the collection is to be limited
ReturnLatest	A Boolean specifying whether only the latest version of each package is to be included in the collection
PackageID	A globally unique identifier (GUID) string specifying the package ID to which the collection is to be limited
Remarks

All parameters are required. To return information on all packages in Meta Data Services or in SQL Server storage, code the empty string "" for PackageName and PackageID, and FALSE for ReturnLatest.

The syntax of GUIDs is:

{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}

Where the X's are hexadecimal digits. The groupings are 8, 4, 4, 4, and 12 digits. The curly brackets are required. Spaces cannot be embedded for readability.

Prototype (C/C++)

HRESULT EnumPackageInfos(
BSTR PackageName,
VARIANT_BOOL ReturnLatest,
BSTR PackageID,
IDTSPackageInfos **pRetVal );

See Also

PackageID Property

PackageInfos Collection

PackageName Property

Retrieving DTS System, Package, and Log Data


EnumPackageLineages Method

The EnumPackageLineages method returns a PackageLineages collection containing data from the package lineage records stored in Microsoft® SQL Server™ 2000 Meta Data Services that satisfy the criteria of the input parameters.

Applies To

PackageRepository Object

Syntax

Set collection = object.EnumPackageLineages(
PackageVersionID,
LineageFullID,
LineageShortID )

Part	Description
collection	Expression that evaluates to a PackageLineages collection
object	Expression that evaluates to a PackageRepository object
PackageVersionID	A globally unique identifier (GUID) string specifying the version ID of the package version to which the collection is to be limited
LineageFullID	A GUID string specifying the lineage full ID to which the collection is to be limited
LineageShortID	A long specifying the lineage short ID to which the collection is to be limited
Remarks

A package lineage record is written each time a package stored in Meta Data Services is executed, if the package LineageOptions property specifies this to be done. Each such record has a unique lineage full ID and lineage short ID.

A package ID or the empty string cannot be specified for PackageVersionID. An error will be raised if there is no package lineage record in Meta Data Services with the specified version ID.

All parameters are required. To return all package lineage records for a particular package version, code the empty string "" for LineageFullID and 0 for LineageShortID. To return all package lineage records in Meta Data Services, iterate through the Meta Data Services packages with the EnumPackageInfos method, and then call EnumPackageLineages for each package version.

The syntax of GUIDs is:

{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}

where the X's are hexadecimal digits. The groupings are 8, 4, 4, 4, and 12 digits. The curly brackets are required. Spaces cannot be embedded.

Prototype (C/C++)

HRESULT EnumPackageLineages(
BSTR PackageVersionID,
BSTR LineageFullID,
long LineageShortID,
IDTSPackageLineages **pRetVal );

See Also

EnumPackageInfos Method

LineageFullID Property

LineageOptions Property

LineageShortID Property

PackageID Property

PackageLineages Collection

RemovePackageLineages Method

Retrieving DTS System, Package, and Log Data

VersionID Property


EnumPackageLogRecords Method

The EnumPackageLogRecords method returns a PackageLogRecords collection containing data from the package log records in the database. These package log records satisfy the criteria of the input parameters.

Applies To

PackageSQLServer Object

Syntax

Set collection = object.EnumPackageLogRecords(
PackageName,
ReturnLatest,
PackageID,
VersionID,
LineageFullID )

Part	Description
collection	Expression that evaluates to a PackageLogRecords collection.
object	Expression that evaluates to a PackageSQLServer object.
PackageName	A string specifying the package name to which log records in the collection are to be limited.
ReturnLatest	A Boolean specifying whether log records for only the latest version of each package are to be included in the collection.
PackageID	A globally unique identifier (GUID) string specifying the package ID to which log records in the collection are to be limited.
VersionID	A GUID string specifying the version ID of the package version to which log records in the collection are to be limited.
LineageFullID	A GUID string specifying the lineage full ID to which the collection is to be limited.
Remarks

A package log record is written to the msdb database on the server specified by the package LogServerName property each time a Data Transformation Services (DTS) package is executed, if the package LogToSQLServer property has been set. For Microsoft® SQL Server™ 2000 Meta Data Services packages, the log record's lineage full ID links to the package lineage record. For other packages, a GUID is created.

All parameters are required. To prevent a parameter from participating in the filter process, code the empty string "" for PackageName, PackageID, VersionID and LineageFullID, and FALSE for ReturnLatest. Coding all parameters this way will cause all package log records in the database to be returned, which may result in an unmanageably large collection.

The syntax of GUIDs is:

{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}

where the X's are hexadecimal digits. The groupings are 8, 4, 4, 4, and 12 digits. The curly brackets are required. Spaces cannot be embedded.

Prototype (C/C++)

HRESULT EnumPackageLogRecords(
BSTR PackageName,
VARIANT_BOOL ReturnLatest,
BSTR PackageID,
BSTR VersionID,
BSTR LineageFullID,
IDTSPackageLogRecords **pRetVal );

See Also

LineageFullID Property

LogServerName Property

LogToSQLServer Property

PackageID Property

PackageLineages Collection

PackageLogRecords Collection

PackageName Property

RemovePackageLogRecords Method

Retrieving DTS System, Package, and Log Data

VersionID Property


EnumStepLineages Method

The EnumStepLineages method returns a StepLineages collection containing information about all the step lineage records stored in Microsoft® SQL Server™ 2000 Meta Data Services that satisfy the criteria of the input parameter.

Applies To

PackageRepository Object

Syntax

Set collection = object.EnumStepLineages( LineageFullID )

Part	Description
collection	Expression that evaluates to a StepLineages collection.
object	Expression that evaluates to a PackageRepository object.
LineageFullID	A globally unique identifier (GUID) string specifying the lineage full ID to which the collection is to be limited.
Remarks

A step lineage record is written each time a step in a package stored in Meta Data Services is executed, if the package LineageOptions property specifies this to be done. A unique lineage full ID is created each time the package is executed (not for each step).

The parameter is required. You cannot code the empty string "" for LineageFullID. If there is no lineage record in Meta Data Services with the specified LineageFullID, an error occurs. To return all step lineage records in Meta Data Services, iterate through the Meta Data Services packages with the EnumPackageInfos method, then call EnumPackageLineages for each package version, and finally call EnumStepLineages for each package lineage. There may be many step lineage records in Meta Data Services.

The syntax of GUIDs is:

{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}

where the X's are hexadecimal digits. The groupings are 8, 4, 4, 4, and 12 digits.  The curly brackets are required. Spaces cannot be embedded for readability.

Prototype (C/C++)

HRESULT EnumPackageInfos(
BSTR LineageFullID,
IDTSStepLineages **pRetVal);

See Also

EnumPackageInfos Method

EnumPackageLineages Method

LineageFullID Property

LineageOptions Property

RemovePackageLineages Method

Retrieving DTS System, Package, and Log Data

StepLineages Collection


EnumStepLogRecords Method

The EnumStepLogRecords method returns a StepLogRecords collection containing data from the step log records in the database that satisfy the criteria of the input parameters.

Applies To

PackageSQLServer Object

Syntax

Set collection = object.EnumStepLogRecords(
LineageFullID,
StepExecutionID )

Part	Description
collection	Expression that evaluates to a StepLogRecords collection.
object	Expression that evaluates to a PackageSQLServer object.
LineageFullID	A globally unique identifier (GUID) string specifying the lineage full ID to which the collection is to be limited.
StepExecutionID	A variant specifying the step execution ID to which the collection is to be limited.
Remarks

A step log record is written to the Microsoft® SQL Server™ msdb database on the server specified by the package LogServerName property each time a step in a Data Transformation Services (DTS) package is executed, if the package LogToSQLServer property has been set. For SQL Server 2000 Meta Data Services packages, the log record's lineage full ID links to the package lineage record. For other packages, a GUID is created.

Both parameters are required. To prevent a parameter from participating in the filter process, code the empty string "" for LineageFullID, and NULL for StepExecutionID. Coding all parameters this way will cause all step log records in the database to be returned, which may result in an unmanageably large collection.

The syntax of GUIDs is:

{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}

where the X's are hexadecimal digits. The groupings are 8, 4, 4, 4, and 12 digits. The curly brackets are required. Spaces cannot be embedded for readability.

Prototype (C/C++)

HRESULT EnumStepLogRecords(
BSTR LineageFullID,
VARIANT StepExecutionID,
IDTSStepLogRecords **pRetVal );

See Also

LineageFullID Property

LogServerName Property

LogToSQLServer Property

PackageLineages Collection

RemoveStepLogRecords Method

Retrieving DTS System, Package, and Log Data

StepExecutionID Property

StepLogRecords Collection


EnumTaskLogRecords Method

The EnumTaskLogRecords method returns a TaskLogRecords collection containing data from the task log records in the database that satisfy the criteria of the input parameters.

Applies To

PackageSQLServer Object

Syntax

Set collection = object.EnumTaskLogRecords(
StepExecutionID,
SequenceID )

Part	Description
collection	Expression that evaluates to a TaskLogRecords collection
object	Expression that evaluates to a PackageSQLServer object
StepExecutionID	A variant specifying the step execution ID to which the collection is to be limited
SequenceID	A long specifying the sequence number of the desired task log record
Remarks

Task log records are not automatically written by the task classes supplied with Microsoft® SQL Server™ 2000, but the PackageLog interface is available so that a custom task or the script of an ActiveScriptTask object can write them. They are written to the msdb database in the instance of SQL Server specified by the package LogServerName property each time a task in a Data Transformation Services (DTS) package that has been implemented to write them is executed, if the package LogToSQLServer property has been set. SequenceID is a unique sequence number for each task log record.

Both parameters are required. To prevent a parameter from participating in the filter process, code NULL for StepExecutionID and 0 for SequenceID. Coding all parameters this way will cause all task log records in the database to be returned, which could result in an unmanageably large collection.

Prototype (C/C++)

HRESULT EnumTaskLogRecords(
VARIANT StepExecutionID,
long SequenceID,
IDTSTaskLogRecords **pRetVal );

See Also

ActiveScriptTask Object

LogServerName Property

LogToSQLServer Property

PackageLog Object

RemoveTaskLogRecords Method

Retrieving DTS System, Package, and Log Data

SequenceID Property

StepExecutionID Property

TaskLogRecords Collection


Execute Method

The Execute method executes a Data Transformation Services (DTS) task object.

Applies To

ActiveScriptTask Object	DynamicPropertiesTask Object
BulkInsertTask Object	ExecutePackageTask Object
CreateProcessTask Object	ExecuteSQLTask Object
CreateProcessTask2 Object	ExecuteSQLTask2 Object
CustomTask Object	ParallelDataPumpTask Object
DataDrivenQueryTask Object	SendMailTask Object
DataPumpTask Object	Task Object
DTSFTPTask Object	TransferObjectsTask Object
DTSMessageQueueTask Object
Syntax

object.Execute pPackage, pPackageEvents, pPackageLog, pTaskResult

Part	Description
object	Expression that evaluates to an object in the Applies To list
pPackage	Reference to the Package2 object
pPackageEvents	Reference to the events of the Package2 object
pPackageLog	Reference to a PackageLog object
pTaskResult	Return code from the DTSTaskExecResult constants
Remarks

An application does not have to call the Execute method for each step or task. Instead the Package2 object calls the Execute method to launch each step or task after the application calls Package2.Execute.

A reference to the Package2 object is passed as a parameter to allow access to the objects in the hierarchy for the package. But pPackage and all objects in its hierarchy must not be saved or referenced after the Execute method returns. Check pPackageEvents and pPackageLog for NULL/Nothing before using them.

Prototype (C/C++)

HRESULT Execute(
IDispatch.*pPackage,
IDispatch.*pPackageEvents,
IDispatch.*pPackageLog,
long.*pTaskResult);

See Also

DTSTaskExecResult

Execute (Package) Method


Execute (Package) Method

The Execute method executes a Data Transformation Services (DTS) package or step.

Applies To

Package Object	Step Object
Package2 Object
Syntax

object.Execute

Part	Description
object	Expression that evaluates to an object in the Applies To list
Remarks

When used with the Package2 and Step2 objects, the Execute method takes no parameters. An application need not call the Execute method for each step or task. Instead the Package2 object calls the Execute method to launch each step or task after the application calls Package2.Execute.

Prototype (C/C++)

HRESULT Execute( );

See Also

Execute Method

Managing DTS Package Programs


GetDayLongName Method

The GetDayLongName method returns the long (full) name for the specified day of the week.

Applies To

DataPumpTransformDateTimeString Object

Syntax

[string =] object.GetDayLongName(daynumber)

Part	Description
string	Long (full) name of the specified day of week
object	Expression that evaluates to a DataPumpTransformDateTimeString object
daynumber	Number of the day of the week
Remarks

The valid day numbers are from 1 through 7.

Prototype (C/C++)

HRESULT GetDayLongName(
long DayNumber,
BSTR* pRetVal);

See Also

Adding DTS Transformations

Day?LongName Property

GetDayShortName Method

SetDayLongName Method


GetDayShortName Method

The GetDayShortName method returns the short name (3-character abbreviation) for the specified day of the week.

Applies To

DataPumpTransformDateTimeString Object

Syntax

[string =] object.GetDayShortName(daynumber)

Part	Description
string	Short name (3-character abbreviation) of the specified day of week
object	Expression that evaluates to a DataPumpTransformDateTimeString object
daynumber	Number of the day of the week
Remarks

The valid day numbers are from 1 through 7.

Prototype (C/C++)

HRESULT GetDayShortName(
long DayNumber,
BSTR* pRetVal);

See Also

Adding DTS Transformations

Day?ShortName Property

GetDayLongName Method

SetDayShortName Method


GetDefaultProfileName Method

The GetDefaultProfileName method returns the default profile name.

Applies To

SendMailTask Object

Syntax

[string =] object.GetDefaultProfileName

Part	Description
object	Expression that evaluates to a SendMailTask object
string	String to receive the default profile name
Prototype (C/C++)

HRESULT GetDefaultProfileName(BSTR *DefaultProfile);

See Also

Profile Property


GetDTSVersionInfo Method

The GetDTSVersionInfo method retrieves version information for Data Transformation Services (DTS).

Applies To

Package Object	Package2 Object
Syntax

object.GetDTSVersionInfo [VersionMajor], [VersionMinor], _
[VersionBuild], [VersionComments])

Part	Description
object	Expression that evaluates to an object in the Applies To list
VersionMajor	Major version number of Microsoft® SQL Server™
VersionMinor	Incremental version number of SQL Server
VersionBuild	SQL Server build number
VersionComments	SQL Server product name including version number
Prototype (C/C++)

HRESULT GetDTSVersionInfo(long *VersionMajor,
long *VersionMinor,
long *VersionBuild,
BSTR *VersionComments);


GetExecutionErrorInfo Method

The GetExecutionErrorInfo method returns details about step execution failure.

Applies To

Step Object	Step2 Object
Syntax

object.GetExecutionErrorInfo pErrorCode, [pbstrSource], [pbstrDescription], _
[pbstrHelpFile], [pHelpContext], [pbstrIDofInterfaceWithError]

Part	Description
Step	Expression that evaluates to an object in the Applies To list
pErrorCode	Error code of the failure
pbstrSource	Source of error
pbstrDescription	Description property of the error
pbstrHelpFile	Help file name
pHelpContext	Help context ID
pbstrIDOfInterface WithError	ID of the interface returning the error
Remarks

Step2 object failure is separate from Package2 object failure. Therefore, error information for each step is unavailable from the COM IErrorInfo object or the Microsoft® Visual Basic® Err object.

When a step fails, the package will not fail unless the package FailOnError property or the step FailPackageOnError property is set. The error that is raised will only specify the step that failed, not the error that occurred. Use GetExecutionErrorInfo on the step that failed to get information about the error.

If you do not set either FailOnError or FailPackageOnError for any step, you can use GetExecutionErrorInfo on all steps in the Steps collection when package execution completes. GetExecutionErrorInfo returns meaningful information only when the step ExecutionStatus is DTSStepExecStat_Completed and ExecutionResult is DTSStepExecResult_Failure.

Prototype (C/C++)

HRESULT GetExecutionErrorInfo(
long *pErrorCode,
BSTR *pbstrSource,
BSTR *pbstrDescription,
BSTR *pbstrHelpFile,
long *pHelpContext,
BSTR *pbstrIDofInterfaceWithError);

See Also

ExecutionResult Property

ExecutionStatus Property

FailOnError Property

FailPackageOnError Property

Handling DTS Events and Errors

Steps Collection


GetExpandedProcessCommandLine Method

The GetExpandedProcessCommandLine method returns the process command line parameter string with the environment variables expanded.

Applies To

CreateProcessTask2 Object

Syntax

[string =] object.GetExpandedProcessCommandLine

Part	Description
object	Expression that evaluates to a CreateProcessTask2 object
string	String to receive the expanded command line
Prototype (C/C++)

HRESULT GetExpandedProcessCommandLine(BSTR* pRetVal)

See Also

ProcessCommandLine Property


GetLastExecutionLineage Method

The GetLastExecutionLineage method retrieves lineage information written to Microsoft® SQL Server™ 2000 Meta Data Services during the last execution of the Data Transformation Services (DTS) package.

Applies To

Package Object	Package2 Object
Syntax

[string =] object.GetLastExecutionLineage([LineageShort])

Part	Description
object	Expression that evaluates to an object in the Applies To list
LineageShort	Package version checksum value
string	String to receive the lineage data
Prototype (C/C++)

HRESULT GetLastExecutionLineage(
long *LineageShort,
BSTR *pRetVal);

See Also

EnumPackageLineages Method

EnumStepLineages Method

LineageShortID Property

PackageLineages Collection

Recording Data Lineage in DTS

Retrieving DTS System, Package, and Log Data

StepLineages Collection


GetMonthLongName Method

The GetMonthLongName method returns the long (full) name for the specified month.

Applies To

DataPumpTransformDateTimeString Object

Syntax

[string =] object.GetMonthLongName(monthnumber)

Part	Description
string	Long (full) name of the specified month
object	Expression that evaluates to a DataPumpTransformDateTimeString object
monthnumber	Number of the month
Remarks

The valid month numbers are from 1 through 12.

Prototype (C/C++)

HRESULT GetMonthLongName(
long MonthNumber,
BSTR* pRetVal);

See Also

Adding DTS Transformations

GetMonthShortName Method

Month??LongName Property

SetMonthLongName Method


GetMonthShortName Method

The GetMonthShortName method returns the short name (3-character abbreviation) for the specified month.

Applies To

DataPumpTransformDateTimeString Object

Syntax

[string =] object.GetMonthShortName(monthnumber)

Part	Description
string	Short name (3-character abbreviation) of the specified month
object	Expression that evaluates to a DataPumpTransformDateTimeString object
monthnumber	Number of the month
Remarks

The valid month numbers are from 1 through 12.

Prototype (C/C++)

HRESULT GetMonthShortName(
long MonthNumber,
BSTR* pRetVal);

See Also

Adding DTS Transformations

GetMonthLongName Method

Month??ShortName Property

SetMonthShortName Method


GetObjectForTransfer Method

The GetObjectForTransfer method iterates objects on the list of objects to be transferred.

Applies To

TransferObjectsTask Object	TransferObjectsTask2 Object
Syntax

object.GetObjectForTransfer Index, ObjectName, OwnerName, Type

Part	Description
object	Expression that evaluates to an object in the Applies To list.
Index	Index into the list of objects to be transferred.
ObjectName	Object name.
OwnerName	Object owner name.
Type	Object type, from the DTSSQLObjectType constants.
Remarks

The index of the first object in the list of objects to be transferred is 0.

Prototype (C/C++)

HRESULT GetObjectForTransfer(LONG Index,
BSTR *ObjectName,
BSTR *OwnerName,
DTSSQLObjectType *Type);

See Also

AddObjectForTransfer Method

DTSSQLObjectType

ResetObjectsList Method


GetPackageRepository Method

The GetPackageRepository method returns a PackageRepository object for the server and database specified by the input parameters.

Applies To

Application Object

Syntax

Set object = appobject.GetPackageRepository(
ServerName,
DatabaseName,
UserName ,
Password ,
ConnectionFlags )

Part	Description
object	Expression that evaluates to a PackageRepository object
appobject	Expression that evaluates to an Application object
ServerName	A string specifying the name of the server on which the Microsoft® SQL Server™ 2000 Meta Data Services instance is hosted
DatabaseName	A string specifying the name of the database in which the instance of Meta Data Services is located
UserName	A string specifying the logon name used to access the server specified by ServerName
Password	A string specifying the password used to access the server specified by ServerName
ConnectionFlags	A value from the DTSRepositoryStorageFlags constants that specifies the type of user authentication used to access the server specified by ServerName
Remarks

The PackageRepository object provides access to the Data Transformation Services (DTS) packages and lineage data stored on the associated instance of Meta Data Services.

UserName and Password need be specified (nonempty string) only if ConnectionFlags has the value DTSReposFlag_Default, which implies database authentication.

Prototype (C/C++)

HRESULT GetPackageRepository(
BSTR ServerName,
BSTR DatabaseName,
BSTR Username,
BSTR Password,
DTSRepositoryStorageFlags ConnectionFlags,
IDTSPackageRepository **pRetVal );

See Also

DTSRepositoryStorageFlags

GetPackageSQLServer Method

PackageRepository Object

Retrieving DTS System, Package, and Log Data


GetPackageSQLServer Method

The GetPackageSQLServer method returns a PackageSQLServer object for the server specified by the input parameters.

Applies To

Application Object

Syntax

Set object = appobject.GetPackageSQLServer(
ServerName,
UserName ,
Password ,
ConnectionFlags )

Part	Description
object	Expression that evaluates to a PackageSQLServer object.
appobject	Expression that evaluates to an Application object.
ServerName	A string specifying the name of the server to which to connect.
UserName	A string specifying the logon name used to access the server specified by ServerName.
Password	A string specifying the password used to access the server specified by ServerName.
ConnectionFlags	A value from the DTSSQLServerStorageFlags constants that specifies the type of user authentication used to access the server specified by ServerName.
Remarks

The PackageSQLServer object provides access to the Data Transformation Services (DTS) packages and log data stored on the associated server, which must be running an instance of Microsoft® SQL Server™.

UserName and Password need be specified (nonempty string) only if ConnectionFlags has the value DTSSQLStgFlag_Default, which implies database authentication.

Prototype (C/C++)

HRESULT GetPackageSQLServer(
BSTR ServerName,
BSTR Username,
BSTR Password,
DTSSQLServerStorageFlags ConnectionFlags,
IDTSPackageSQLServer **pRetVal );

See Also

DTSSQLServerStorageFlags

GetPackageRepository Method

PackageSQLServer Object

Retrieving DTS System, Package, and Log Data


GetPropertiesForObject Method

The GetPropertiesForObject method returns a Data Transformation Services (DTS) Properties collection from an object implementing a custom task.

Applies To

PropertiesProvider Object

Syntax

[Set colProperties =] object.GetPropertiesForObject( pObject)

Part	Description
object	Expression that evaluates to a PropertiesProvider object
pObject	Expression that evaluates to an object for which a Properties collection is to be retrieved
colProperties	Object variable of type Properties
Remarks

Use GetPropertiesForObject and the Properties collection it returns to determine, without causing an error, if an object supports a property.

Prototype (C/C++)

HRESULT GetPropertiesForObject(
IDispatch *pObject,
IDTSProperties **pRetVal);

See Also

Properties Collection


GetSavedPackageInfos Method

The GetSavedPackageInfos method retrieves a list of versions in this storage location.

Applies To

Package Object	Package2 Object
Syntax

[Set colSavedInfos =] Package.GetSavedPackageInfos(UNCFile)

Part	Description
Package	Expression that evaluates to an object in the Applies To list
UNCFile	Data Transformation Services (DTS) package storage file from which a list of versions is to be retrieved
colSavedInfos	Object variable of type SavedPackageInfos
Prototype (C/C++)

HRESULT GetSavedPackageInfos(
BSTR UNCFile,
IDTSSavedPackageInfos **pRetVal);

See Also

Retrieving DTS System, Package, and Log Data

SavedPackageInfos Collection


GetUIInfo Method

The GetUIInfo method returns top-level user interface information for a Data Transformation Services (DTS) custom task user interface element to its caller. It must be supplied by the implementer of a custom task that has a user interface.

Applies To

CustomTaskUI Object

Syntax (Visual Basic)

Sub CustomTaskUI_GetUIInfo( pbstrToolTip As String, pbstrDescription As String, _
plVersion As Long, pFlags As DTSCustomTaskUIFlags)

Part	Description
pbstrToolTip	ToolTip text
PbstrDescription	Description of user interface element
PlVersion	Reserved for future use
PFlags	Value from the DTSCustomTaskUIFlags constants that indicates whether the user interface element has a custom ToolTip
Prototype (C/C++)

HRESULT GetUIInfo(
BSTR *pbstrToolTip,
BSTR *pbstrDescription,
long *plVersion,
DTSCustomTaskUIFlags *pFlags);

See Also

CreateCustomToolTip Method

DTSCustomTaskUIFlags


Help Method

The Help method of the CustomTaskUI interface must be supplied by the implementer of a Data Transformation Services (DTS) custom task that has a user interface. It is called by DTS when Help has been invoked for the custom task.

Applies To

CustomTaskUI Object

Syntax (Visual Basic)

Sub CustomTaskUI_Help(ByVal hwndParent As Long )

Part	Description
hwndParent	Handle to the window to be the parent of the custom task user interface
Remarks

The window that is parent to the custom task's user interface window typically would be the DTS Designer design sheet or the Microsoft® Visual Studio® development environment desktop.

Prototype (C/C++)

HRESULT Help(long hwndParent);

See Also

CustomTask Object

GetUIInfo Method


Initialize Method

The Initialize method of the CustomTaskUI interface must be supplied by the implementer of a Data Transformation Services (DTS) custom task that has a user interface. It is called by DTS whenever the custom task is opened in the design environment.

Applies To

CustomTaskUI Object

Syntax (Visual Basic)

Sub CustomTaskUI_Initialize(ByVal pTask As Task )

Part	Description
pTask	Task object for the custom task
Remarks

Typically, the Initialize method provides initial values for user interface elements.

Prototype (C/C++)

HRESULT Initialize(IDTSTask *pTask);

See Also

Edit Method

GetUIInfo Method

New (CustomTaskUI) Method


InitializeMAPI Method

The InitializeMAPI method initializes the MAPI provider.

Applies To

SendMailTask Object

Syntax

object.InitializeMAPI

Part	Description
object	Expression that evaluates to a SendMailTask object
Prototype (C/C++)

HRESULT InitializeMAPI();

See Also

UnitializeMAPI Method


Insert Method

The Insert method inserts an object in an ordinal position in a collection.

Applies To

Columns Collection	Steps Collection
Connections Collection	Tasks Collection
GlobalVariables Collection	Transformations Collection
Lookups Collection	TransformationSets Collection
PrecedenceConstraints Collection
Syntax

collection.Insert Position, Object

Part	Description
collection	Expression that evaluates to an collection in the Applies To list
Position	Ordinal position of the object to insert
Object	Object to be inserted
Remarks

The required type of Object depends on the collection to which it is being inserted.

Collection	Object
Columns	Column Object
Connections	Connection Object Connection2 Object
GlobalVariables	GlobalVariable Object
Lookups	Lookup Object
PrecedenceConstraints	PrecedenceConstraint Object
Steps	Step Object Step2 Object
Tasks	Task Object
Transformations	Transformation Object Transformation2 Object
TransformationSets	TransformationSet Object
The Insert method does not create an object. It adds an existing object to its collection. Typically, you create the object with the New method of the collection.

Prototype (C/C++)

HRESULT Insert(
VARIANT Position,
Interface *Object);

See Also

Add Method

New Method

New (Columns) Method

New (ID) Method

New (Name) Method


Item Method

The Item method retrieves an object from a collection.

Applies To

Columns Collection	Properties Collection
Connections Collection	SavedPackageInfos Collection
DTSMQMessages Collection	ScriptingLanguageInfos Collection
DynamicPropertiesTaskAssignments Collection	Steps Collection
GlobalVariables Collection	TaskInfos Collection
Lookups Collection	Tasks Collection
OLEDBProperties Collection	TransformationInfos Collection
OLEDBProviderInfos Collection	Transformations Collection
PrecedenceConstraints Collection
Syntax

[Set object =] collection.Item(Index)

Part	Description
object	Object to be retrieved from collection
collection	Expression that evaluates to an collection in the Applies To list
Index	Object name or ordinal position
Remarks

Index is the object name or the numeric position within the collection.

The required type of Object depends on the collection from which it is being retrieved.

Collection	Object
Columns	Column Object
Connections	Connection Object Connection2 Object
DTSMQMessages	DTSMQMessage Object
DynamicPropertiesTaskAssignments	DynamicPropertiesTaskAssignment Object
GlobalVariables	GlobalVariable Object
Lookups	Lookup Object
OLEDBProperties	OLEDBProperty Object
OLEDBProviderInfos	OLEDBProviderInfo Object
PrecedenceConstraints	PrecedenceConstraint Object
Properties	Property Object
SavedPackageInfos	SavedPackageInfo Object
ScriptingLanguageInfos	ScriptingLanguageInfo Object
Steps	Step Object Step2 Object
TaskInfos	TaskInfo Object
Tasks	Task Object
TransformationInfos	TransformationInfo Object
Transformations	Transformation Object Transformation2 Object
TransformationSets	TransformationSet Object
You can iterate through these collection using the Item method and Count property. In Microsoft® Visual Basic® this looks like:

For Index = 1 To collection.Count

Set object = collection.Item(Index)

. . .

Next Index

However, it is faster to iterate through these collections using For Each ... Next in Visual Basic:

For Each object In collection

. . .

Next object

Prototype (C/C++)

HRESULT Item(
VARIANT Index,
interface **pRetVal);

See Also

Add Method

Count Property

Insert Method


Load Method

The Load method fills the container object using persisted property values. The Load method is called by Data Transformation Services (DTS) when a DTS package is loaded.

Applies To

PersistPropertyBag Object

Syntax

object.Load PropertyBag

Part	Description
object	Expression that evaluates to a PersistPropertyBag object
PropertyBag	PropertyBag object to be loaded
Remarks

Generic binary large objects (BLOBs) or objects are not supported as property values.

Prototype (C/C++)

HRESULT Load(IDTSPropertyBag *IDTSPropertyBag);

See Also

PropertyBag Object

Save Method


LoadFromRepository Method

The LoadFromRepository method loads the Data Transformation Services (DTS) package from the specified instance of Microsoft® SQL Server™ 2000 Meta Data Services. This includes information held in the objects and collections that belong to the Package2 object.

Applies To

Package Object	Package2 Object
Syntax

Package.LoadFromRepository RepositoryServerName, RepositoryDatabaseName, _
RepositoryUserName, RepositoryUserPassword, PackageID, [VersionID], _
[PackageName], [Flags], [pVarPersistStgOfHost]

Part	Description
Package	Expression that evaluates to an object in the Applies To list.
RepositoryServerName	Meta Data Services server name.
RepositoryDatabaseName	Meta Data Services database name or data source name (DSN).
RepositoryUserName	Meta Data Services user name.
RepositoryUserPassword	Meta Data Services user password.
PackageID	Package identifier, which is a string representation of a globally unique identifier (GUID).
VersionID	Version identifier, which is a string representation of a GUID.
PackageName	Name of package to be loaded.
Flags	Value from the DTSRepositoryStorageFlags constants indicating user authentication type.
pVarPersistStgOfHost	Screen layout information associated with a package (for internal use only).
Remarks

RepositoryDatabaseName is evaluated as an ODBC DSN if RepositoryServerName is empty or NULL. Otherwise, RepositoryServerName and RepositoryDatabaseName are used to create a connection without a DSN.

If VersionID is not specified or is blank, the most recent version of the package is retrieved.

Prototype (C/C++)

HRESULT LoadFromRepository(
BSTR RepositoryServerName,
BSTR RepositoryDatabaseName
BSTR RepositoryUserName,
BSTR RepositoryUserPassword,
BSTR PackageID,
BSTR VersionID CPPDEFAULT(= NULL)
BSTR PackageName CPPDEFAULT(= NULL)
DTSRepositoryStorageFlags Flags CPPDEFAULT(= DTSReposFlag_Default),
VARIANT *pUnkPersistStgOfHost CPPDEFAULT(= NULL));

See Also

DTSRepositoryStorageFlags

LoadFromSQLServer Method

LoadFromStorageFile Method

Managing DTS Package Programs

RemoveFromRepository Method

SaveToRepository Method

SaveToRepositoryAs Method


LoadFromSQLServer Method

The LoadFromSQLServer method loads the Data Transformation Services (DTS) package from the specified server running an instance of Microsoft® SQL Server™. This includes information held in the objects and collections that belong to the Package2 object.

Applies To

Package Object	Package2 Object
Syntax

Package.LoadFromSQLServer ServerName, [ServerUserName], [ServerPassword], _
[Flags], [PackagePassword], [PackageGuid], [PackageVersionGuid], _
[PackageName], [pVarPersistStgOfHost]

Part	Description
Package	Expression that evaluates to an object in the Applies To list.
ServerName	Server name.
ServerUserName	Server user name.
ServerPassword	Server user password.
Flags	Value from the DTSSQLServerStorageFlags constants indicating user authentication type.
PackagePassword	Package password if the package is encrypted.
PackageGuid	Package identifier, which is a string representation of a globally unique identifier (GUID).
PackageVersionGuid	Version identifier which is a string representation of a GUID.
PackageName	Package name.
pVarPersistStgOfHost	Screen layout information associated with a package (for internal use only).
Remarks

If PackageVersionGUID is not specified or is blank, the most recent version of the package is retrieved.

Prototype (C/C++)

HRESULT LoadFromSQLServer(
BSTR ServerName,
BSTR ServerUserName,
BSTR ServerPassword,
DTSSQLServerStorageFlags Flags CPPDEFAULT(= DTSSQLStgFlag_Default),
BSTR PackagePassword CPPDEFAULT(= NULL),
BSTR PackageGuid CPPDEFAULT(= NULL),
BSTR PackageVersionGuid CPPDEFAULT(= NULL),
BSTR PackageName CPPDEFAULT(= NULL),
VARIANT *pUnkPersistStgOfHost CPPDEFAULT(= NULL) );

See Also

DTSSQLServerStorageFlags

LoadFromRepository Method

LoadFromStorageFile Method

Managing DTS Package Programs

RemoveFromSQLServer Method

SaveToSQLServer Method

SaveToSQLServerAs Method


LoadFromStorageFile Method

The LoadFromStorageFile method loads the Data Transformation Services (DTS) package from the specified structured storage file. This includes information held in the objects and collections that belong to the Package object.

Applies To

Package Object	Package2 Object
Syntax

object.LoadFromStorageFile UNCFile, Password, [PackageID], _
[VersionID], [Name], [pVarPersistStgOfHost]

Part	Description
object	Expression that evaluates to an object in the Applies To list.
UNCFile	File specification of DTS package storage file.
Password	Package password if the package is encrypted.
PackageID	Package identifier, which is a string representation of a globally unique identifier (GUID).
VersionID	Version identifier, which is a string representation of a GUID.
Name	Package name.
pVarPersistStgOfHost	Screen layout information associated with a package (for internal use only).
Remarks

If VersionID is not specified or is blank, the most recent version of the package is retrieved.

Prototype (C/C++)

HRESULT LoadFromStorageFile(
BSTR UNCFile,
BSTR Password,
BSTR PackageID,
BSTR VersionID CPPDEFAULT(= NULL),
BSTR Name CPPDEFAULT(= NULL),
VARIANT *pUnkPersistStgOfHost CPPDEFAULT(= NULL));

See Also

LoadFromRepository Method

LoadFromSQLServer Method

Managing DTS Package Programs

SaveToStorageFile Method

SaveToStorageFileAs Method


Lock Method

The Lock method locks a GlobalVariable2 object for exclusive use.

Applies To

GlobalVariable2 Object

Syntax

globalvar.Lock timeout

Part	Description
globalvar	Expression that evaluates to a GlobalVariable2 object
timeout	Time-out value, in milliseconds
Remarks

If the global variable is already locked, the Lock method waits until the holder of the lock unlocks the global variable, or until the time-out occurs. When the time-out period elapses, an error occurs.

If 0 is specified for the time-out value, an error occurs immediately if the global variable is already locked.

Prototype (C/C++)

HRESULT Lock( long TimeOut );

See Also

Adding DTS Lookups and Global Variables

Unlock Method


Logoff Method

The Logoff method ends a MAPI session.

Applies To

SendMailTask Object

Syntax

object.Logoff()

Part	Description
Object	Expression that evaluates to a SendMailTask object
Prototype (C/C++)

HRESULT Logoff();

See Also

Logon Method


Logon Method

The Logon method creates a MAPI session.

Applies To

SendMailTask Object

Syntax

[errorstring =] object.Logon()

Part	Description
object	Expression that evaluates to a SendMailTask object
errorstring	String describing error if Logon fails
Prototype (C/C++)

HRESULT Logon(BSTR *ErrorString);

See Also

Logoff Method


Messages Method

The Messages method returns a reference to the DTSMQMessages collection.

Applies To

DTSMessageQueueTask Object

Syntax

[Set oMsgColl =] object.Messages

Part	Description
object	Expression that evaluates to a DTSMessageQueueTask object
oMsgColl	Object variable to receive a reference to a DTSMQMessages collection
Prototype (C/C++)

HRESULT Messages(DTSMQMessages **pVal)

See Also

DTSMQMessages Collection


New Method

The New method creates a new, unnamed object for a collection.

Applies To

DTSMQMessages Collection	Steps Collection
DynamicPropertiesTaskAssignments Collection
Syntax

[Set object =] Collection.New

Part	Description
Collection	Expression that evaluates to an object in the Applies To list
object	Object variable to receive reference to created object
Remarks

The required type of object depends on the collection to which it is being added:

Collection	Object
DTSMQMessages	DTSMQMessage Object
DynamicPropertiesTaskAssignments	DynamicPropertiesTaskAssignment Object
Steps	Step Object Step2 Object
The New method for the collections in the Applies To list creates a new object based on the collection type. The New methods for other collections use different parameters and syntax.

Prototype (C/C++)

HRESULT New(
ObjectInterface **RetVal);

Example

To create a new Step object using Microsoft® Visual Basic®, use:

Set objStep = objPackage.Steps.New

See Also

Add Method

New (Columns) Method

New (ID) Method

New (Name) Method


New (Columns) Method

The New method creates a new Column object with a specified name and ordinal position.

Applies To

Columns Collection

Syntax

[Set object =] Collection.New( Name, Ordinal )

Part	Description
Columns	Expression that evaluates to a Columns collection
object	Expression that evaluates to a Column object
Name	String that is the name of the column
Ordinal	Long that is the ordinal position of the column
Remarks

The New method for the Columns collection creates a new object based on the specified Name and Ordinal. The New methods for other collections use different parameters and syntax.

Prototype (C/C++)

HRESULT New(
BSTR Name,
long Ordinal,
IDTSColumn **RetVal);

Examples

This Microsoft® Visual Basic® example creates a new Column object named LastName that is to be the third column in the source columns collection:

Set objColumn = objTransform.SourceColumns.New( "LastName", 3 )

See Also

Add Method

Adding DTS Column Objects

New Method

New (ID) Method

New (Name) Method


New (CustomTaskUI) Method

The New method of the CustomTaskUI interface must be supplied by the implementer of a Data Transformation Services (DTS) custom task that has a user interface. It is called by DTS when a new instance of the custom task is to be created.

Applies To

CustomTaskUI Object

Syntax (Visual Basic)

Sub CustomTaskUI_New(ByVal hwndParent As Long )

Part	Description
hwndParent	Handle to the window to be the parent of the custom task user interface
Remarks

The window that is parent to the custom task's user interface window typically would be the DTS Designer design sheet or the Microsoft® Visual Studio® development environment desktop.

The New methods for various collections use different parameters and syntax than the New method of the CustomTaskUI interface.

Prototype (C/C++)

HRESULT New(
long hwndParent );

See Also

CreateCustomToolTip Method

Delete Method

Edit Method

New Method

New (Columns) Method

New (ID) Method

New (Name) Method


New (ID) Method

The New method creates a new object for a collection from a ProgID or CLSID.

Applies To

Connections Collection	Transformations Collection
Tasks Collection
Syntax

[Set object =] Collection.New( ID )

Part	Description
Collection	Expression that evaluates to an object in the Applies To list
object	Object variable to receive reference to created object
ID	ProgID or CLSID of object to be created
Remarks

The required type of object depends on the collection to which it is being added:

Collection	Object
Connections	Connection Object Connection2 Object
Tasks	Task Object
Transformations	Transformation Object Transformation2 Object
The New method for the collections in the Applies To list creates a new object based on the ProgID or CLSID of the corresponding class. The New methods for other collections use different parameters and syntax.

There are version-dependent and version-independent forms of a ProgID. Typically, the version-dependent form looks like name.version. The version-independent form typically has name only, without the .version, although that form is not required. The version-independent form should be used unless you need a feature of a particular version.

Prototype (C/C++)

HRESULT New(
BSTR bstrID,
ObjectInterface **RetVal);

Examples

To create a new connection using the Microsoft® OLE DB Provider for ODBC drivers in Microsoft Visual Basic®, use one of the following forms.

By version-independent ProgID:

Set objConnection = objPackage.Connections.New( "MSDASQL" )

By version-dependent ProgID:

Set objConnection = objPackage.Connections.New( "MSDASQL.1" )

By CLSID:

Set objConnection = _

objPackage.Connections.New( "{C8B522CB-5CF3-11CE-ADE5-00AA0044773D}" )

See Also

Add Method

New Method

New (Columns) Method

New (Name) Method


New (Name) Method

The New method creates a new object for a collection with a specified name.

Applies To

GlobalVariables Collection	PrecedenceConstraints Collection
Lookups Collection
Syntax

[Set object =] Collection.New( Name )

Part	Description
Collection	Expression that evaluates to an object in the Applies To list
object	Object variable to receive reference to created object
Name	String that is to be the name of the created object
Remarks

The required type of object depends on the collection to which it is being added:

Collection	Object
GlobalVariables	GlobalVariable Object
Lookups	Lookup Object
PrecedenceConstraints	PrecedenceConstraint Object
TransformationSets	TransformationSet Object
The New method for the collections in the Applies To list creates a new object with the specified name. The New methods for other collections use different parameters and syntax.

Prototype (C/C++)

HRESULT New(
BSTR Name,
ObjectInterface **RetVal);

Examples

This sample statement creates a new TransformationSet object named Customers, in Microsoft® Visual Basic®:

Set objTransSet = objParPumpTask.TransformationSets.New( "Customers" )

See Also

Add Method

New Method

New (Columns) Method

New (ID) Method


NewDataLink Method

The NewDataLink method gets a new Connection object using Microsoft® Data Link files.

Applies To

Connections Collection

Syntax

[Set object =] collection.NewDataLink(UDLPath)

Part	Description
collection	Expression that evaluates to a Connections collection
UDLPath	File specification of the UDL file
object	Object Variable of type Connection
Remarks

NewDataLink is similar to New, except you supply a UDL path instead of a provider ID.

Prototype (C/C++)

HRESULT NewDataLink (
BSTR UDLPath,
IDTSConnection **pRetVal);

See Also

Connection Object

New (ID) Method


Next Method

The Next method fetches the next object while iterating through the associated collection.

Applies To

PackageInfos Collection	StepLineages Collection
PackageLineages Collection	StepLogRecords Collection
PackageLogRecords Collection
Syntax

Set object = collection.Next

Part	Description
collection	Expression that evaluates to a collection in the Applies To list
object	Reference to next object in collection
Remarks

The object associated with each collection type is specified in this table.

Collection	Associated object	C/C++ interface
PackageInfos Collection	PackageInfo Object	IDTSPackageInfo
PackageLineages Collection	PackageLineage Object	IDTSPackageLineage
PackageLogRecords	PackageLogRecord Object	IDTSPackageLogRecord
StepLineages Collection	StepLineage Object	IDTSStepLineage
StepLogRecords Collection	StepLogRecord Object	IDTSStepLogRecord
TaskLogRecords Collection	TaskLogRecord Object	IDTSTaskLogRecord
Iterate through a collection by checking the EOF property after calling the Next method. If EOF is True, Next will have returned Nothing and all of the elements will have been fetched. In Microsoft® Visual Basic® this looks like:

Set object = collection.Next

Do Until collection.EOF

. . .

Set object = collection.Next

Loop

The collections in the Applies To list can also be processed using For Each ... Next in Visual Basic:

For Each object In collection

. . .

Next object

Prototype (C/C++)

HRESULT Next(interface **pRetVal);

interface is as defined in the above table.

See Also

EOF Property

Retrieving DTS System, Package, and Log Data


Read Method

The Read method retrieves a property value.

Applies To

PropertyBag Object

Syntax

[value =] object.Read( bstrPropertyName )

Part	Description
Object	Expression that evaluates to a PropertyBag object
BstrPropertyName	String identifying an exposed property by name
Value	Variant that receives the property value
Remarks

Generic BLOBs or objects are not supported as property values.

Prototype (C/C++)

HRESULT Read(
BSTR bstrPropertyName,
VARIANT *pValue);

See Also

PersistPropertyBag Object

Write Method


Refresh Method

The Refresh method updates the cached information for the associated collection by scanning the registered classes in the operating system registry.

Applies To

OLEDBProviderInfos Collection	TaskInfos Collection
ScriptingLanguageInfos Collection
Syntax

collection.Refresh

Part	Description
collection	Expression that evaluates to a collection in the Applies To list
Remarks

Data Transformation Services (DTS) maintains a cache (in the registry) of the components of each collection in the Applies To list. When iterating through any of the collections the appropriate cache is examined, rather than all registered classes, when the UseCache property is True. Use the Refresh method to refresh the appropriate cache from the system registry.

Prototype (C/C++)

HRESULT Refresh( );

See Also

Retrieving DTS System, Package, and Log Data

UseCache Property


ReleaseConnection Method

The ReleaseConnection method releases ownership of the connection and makes it available to other tasks.

Applies To

Connection Object	Connection2 Object
Syntax

Connection.ReleaseConnection()

Part	Description
Connection	Expression that evaluates to an object in the Applies To list
Remarks

The InUse property is set to False. This method is required only if you are creating a custom task. All tasks must include calls to AcquireConnection and ReleaseConnection. The tasks supplied with Microsoft® SQL Server™ 2000 already include them.

Rowsets are always released at the Task object level.

Prototype (C/C++)

HRESULT ReleaseConnection();

See Also

AcquireConnection Method

Creating DTS Package Objects and Connections

InUse Property


Remove Method

The Remove method removes an object from a collection.

Applies To

Columns Collection	PrecedenceConstraints Collection
Connections Collection	Steps Collection
DTSMQMessages Collection	Tasks Collection
DynamicPropertiesTaskAssignments Collection	Transformations Collection
GlobalVariables Collection	TransformationSets Collection
Lookups Collection
Syntax

collection.Remove Index

Part	Description
collection	Expression that evaluates to a collection in the Applies To list
Index	Object name or ordinal position
Remarks

Index is the object name or the numeric position within the collection.

The types of object contained in each collection type is as follows.

Collection	Object
Columns	Column Object
Connections	Connection Object Connection2 Object
DTSMQMessages	DTSMQMessage Object
DynamicPropertiesTaskAssignments	DynamicPropertiesTaskAssignment Object
GlobalVariables	GlobalVariable Object
Lookups	Lookup Object
PrecedenceConstraints	PrecedenceConstraint Object
Steps	Step Object Step2 Object
Tasks	Task Object
Transformations	Transformation Object Transformation2 Object
TransformationSets	TransformationSet Object
Prototype (C/C++)

HRESULT Remove(VARIANT Index);

See Also

Add Method

Insert Method

Item Method


RemoveAllLogRecords Method

The RemoveAllLogRecords method removes all package, step, and task log records from the database associated with the PackageSQLServer object.

Applies To

PackageSQLServer Object

Syntax

object.RemoveAllLogRecords( )

Part	Description
object	Expression that evaluates to a PackageSQLServer object
Remarks

Log records are written to the msdb database on the instance of Microsoft® SQL Server™ specified by the package LogServerName property each time a Data Transformation Services (DTS) package is executed, if the package LogToSQLServer property has been set. The RemoveAllLogRecords method removes these records for all packages from the database.

Prototype (C/C++)

HRESULT RemovePackageLogRecords( );

See Also

LogServerName Property

LogToSQLServer Property

PackageLogRecords Collection

RemovePackageLogRecords Method

RemoveStepLogRecords Method

RemoveTaskLogRecords Method

Retrieving DTS System, Package, and Log Data

StepLogRecords Collection

TaskLogRecords Collection


RemoveFromRepository Method

The RemoveFromRepository method removes the package from the specified instance of Microsoft® SQL Server™ 2000 Meta Data Services.

Applies To

Package Object	Package2 Object
Syntax

Package.RemoveFromRepository RepositoryServerName, _
RepositoryDatabaseName, RepositoryUserName, RepositoryUserPassword, _
PackageID, [VersionID], [PackageName], [Flags]

Part	Description
Package	Expression that evaluates to an object in the Applies To list.
RepositoryServerName	Meta Data Services server name.
RepositoryDatabaseName	Meta Data Services database name or datasource name (DSN).
RepositoryUsername	Meta Data Services user name.
RepositoryUserPassword	Meta Data Services user password.
PackageID	Package identifier, which is a string representation of a globally unique identifier (GUID).
VersionID	Version identifier, which is a string representation of a GUID.
PackageName	Package name.
Flags	Value from the DTSRepositoryStorageFlags constants, which specified the user authentication type.
Remarks

RepositoryDatabaseName is evaluated as an ODBC DSN if RepositoryServerName is empty or NULL. Otherwise, RepositoryServerName and RepositoryDatabaseName are used to create a connection without a DSN.

If VersionID is not specified or is blank, the most recent version of the package is removed.

Prototype (C/C++)

HRESULT RemoveFromRepository(
BSTR RepositoryServerName,
BSTR RepositoryDatabaseName,
BSTR RepositoryUserName,
BSTR RepositoryUserPassword,
BSTR PackageID,
BSTR VersionID CPPDEFAULT(= NULL)
BSTR PackageName CPPDEFAULT(= NULL)
DTSRepositoryStorageFlags Flags CPPDEFAULT(= DTSReposFlag_Default) );

See Also

DTSRepositoryStorageFlags

LoadFromRepository Method

Managing DTS Package Programs

SaveToRepository Method

SaveToRepositoryAs Method


RemoveFromSQLServer Method

The RemoveFromSQLServer method removes the package from the specified server running an instance of Microsoft® SQL Server™.

Applies To

Package Object	Package2 Object
Syntax

Package.RemoveFromSQLServer ServerName, [ServerUserName], _
[ServerPassword], [Flags], [PackageGuid], _
[PackageVersionGuid], [PackageName]

Part	Description
Package	Expression that evaluates to an object in the Applies To list.
ServerName	Server name.
ServerUserName	Server user name.
ServerPassword	Server user password.
Flags	Value from the DTSSQLServerStorageFlags constants indicating user authentication type.
PackageGuid	Package identifier, which is a string representation of a globally unique identifier (GUID).
PackageVersionGuid	Version identifier, which is a string representation of a GUID.
PackageName	Package name.
Remarks

If PackageVersionGUID is not specified or is blank, the most recent version of the package is removed.

Prototype (C/C++)

HRESULT RemoveFromSQLServer(
BSTR ServerName,
BSTR ServerUserName,
BSTR ServerPassword,
DTSSQLServerStorageFlags Flags CPPDEFAULT(= DTSSQLStgFlag_Default),
BSTR PackageGuid CPPDEFAULT(= NULL),
BSTR PackageVersionGuid CPPDEFAULT(= NULL),
BSTR PackageName CPPDEFAULT(= NULL) );

See Also

DTSSQLServerStorageFlags

LoadFromSQLServer Method

Managing DTS Package Programs

SaveToSQLServer Method

SaveToSQLServerAs Method


RemovePackageLineages Method

The RemovePackageLineages method removes the package and step lineage records from Microsoft® SQL Server™ 2000 Meta Data Services that satisfy the criteria of the input parameters.

Applies To

PackageRepository Object

Syntax

object.RemovePackageLineages( PackageVersionID, KeepLatest,
LineageFullID, LineageShortID )

Part	Description
Object	Expression that evaluates to a PackageRepository object.
PackageVersionID	A globally unique identifier (GUID) string specifying the version ID of the package version for which lineage records are to be removed.
KeepLatest	A Boolean which specifies whether the lineage records for the most recent execution are to be retained.
LineageFullID	A GUID string specifying the lineage full ID of the lineage records to be removed.
LineageShortID	A long specifying the lineage short ID of the lineage records to be removed.
Remarks

A package lineage record and step lineage records are written each time a package stored in Meta Data Services is executed, if the package LineageOptions property specifies this to be done. RemovePackageLineages removes these records from Meta Data Services.

A package ID or the empty string cannot be specified for PackageVersionID. An error will be raised if there is no package lineage record in Meta Data Services with the specified version ID.

All parameters are required. To remove all package lineage records for a particular package version, code False for KeepLatest, the empty string "" for LineageFullID and 0 for LineageShortID. To remove all package lineage records in Meta Data Services, iterate through the Meta Data Services packages with the EnumPackageInfos method, then call RemovePackageLineages for each package version.

The syntax of GUIDs is:

{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}

where the X are hexadecimal digits. The groupings are 8, 4, 4, 4, and 12 digits. The curly brackets are required. Spaces cannot be embedded for readability.

Prototype (C/C++)

HRESULT RemovePackageLineages(
BSTR PackageVersionID,
VARIANT_BOOL KeepLatest,
BSTR LineageFullID,
long LineageShortID );

See Also

EnumPackageLineages Method

LineageFullID Property

LineageOptions Property

LineageShortID Property

PackageID Property

Retrieving DTS System, Package, and Log Data

VersionID Property


RemovePackageLogRecords Method

The RemovePackageLogRecords method removes the package log records that satisfy the criteria of the input parameters from the database.

Applies To

PackageSQLServer Object

Syntax

object.RemovePackageLogRecords(
PackageName,
KeepLatest,
PackageID,
VersionID,
LineageFullID )

Part	Description
object	Expression that evaluates to a PackageSQLServer object.
PackageName	A string specifying the package name for which log records are to be removed.
KeepLatest	A Boolean which specifies whether the log records for the most recent execution are to be retained.
PackageID	A globally unique identifier (GUID) string specifying the package ID for which log records are to be removed.
VersionID	A GUID string specifying the version ID of the package version for which log records are to be removed.
LineageFullID	A GUID string specifying the lineage full ID for which log records are to be removed.
Remarks

A package log record is written to the msdb database on the instance of Microsoft® SQL Server™ specified by the package LogServerName property each time a Data Transformation Services (DTS) package is executed, if the package LogToSQLServer property has been set. The RemovePackageLogRecords method removes these records from the database.

All parameters are required. To prevent a parameter from participating in the filter process, code the empty string "" for PackageName, PackageID, VersionID and LineageFullID, and False for KeepLatest. Coding all parameters this way will cause all package log records in the database to be removed.

The syntax of GUIDs is:

{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}

where the X are hexadecimal digits. The groupings are 8, 4, 4, 4, and 12 digits. The curly brackets are required. Spaces cannot be embedded for readability.

Prototype (C/C++)

HRESULT RemovePackageLogRecords(
BSTR PackageName,
VARIANT_BOOL KeepLatest,
BSTR PackageID,
BSTR VersionID,
BSTR LineageFullID );

See Also

EnumPackageLogRecords Method

LineageFullID Property

LogServerName Property

LogToSQLServer Property

PackageID Property

PackageLogRecords Collection

PackageName Property

RemoveAllLogRecords Method

Retrieving DTS System, Package, and Log Data

VersionID Property


RemoveStepLogRecords Method

The RemoveStepLogRecords method removes the step log records that satisfy the criteria of the input parameters from the database.

Applies To

PackageSQLServer Object

Syntax

object.RemoveStepLogRecords(
LineageFullID,
StepExecutionID )

Part	Description
object	Expression that evaluates to a PackageSQLServer object.
LineageFullID	A globally unique identifier (GUID) string specifying the lineage full ID for which log records are to be removed.
StepExecutionID	A variant specifying the step execution ID for which log records are to be removed.
Remarks

A step log record is written to the msdb database on the instance of Microsoft® SQL Server™ specified by the package LogServerName property each time a step in a Data Transformation Services (DTS) package is executed, if the package LogToSQLServer property has been set. The RemoveStepLogRecords method removes these records from the database.

Both parameters are required. To prevent a parameter from participating in the filter process, code the empty string "" for LineageFullID, and Null for StepExecutionID. Coding all parameters this way will cause all step log records to be removed.

The syntax of GUIDs is:

{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}

where the X are hexadecimal digits. The groupings are 8, 4, 4, 4, and 12 digits. The curly brackets are required. Spaces cannot be embedded for readability.

Prototype (C/C++)

HRESULT RemoveStepLogRecords(
BSTR LineageFullID,
VARIANT StepExecutionID );

See Also

EnumStepLogRecords Method

LineageFullID Property

LogServerName Property

LogToSQLServer Property

RemoveAllLogRecords Method

Retrieving DTS System, Package, and Log Data

StepExecutionID Property

StepLogRecords Collection


RemoveTaskLogRecords Method

The RemoveTaskLogRecords method removes the task log records that satisfy the criteria of the input parameters from the database.

Applies To

PackageSQLServer Object

Syntax

object.RemoveTaskLogRecords(
StepExecutionID,
SequenceID )

Part	Description
object	Expression that evaluates to a PackageSQLServer object
StepExecutionID	A variant specifying the step execution ID for which log records are to be removed
SequenceID	A long specifying the sequence number of the log record to be removed
Remarks

Task log records are not written by the task classes supplied with Microsoft® SQL Server™ 2000, but the PackageLog interface is available so that custom tasks can write them. They are written to the msdb database on the server specified by the package LogServerName property, if the package LogToSQLServer property has been set. SequenceID is a unique sequence number for each task log record. The RemoveTaskLogRecords method removes these records from the database.

Both parameters are required. To prevent a parameter from participating in the filter process, code Null for StepExecutionID and 0 for SequenceID. Coding all parameters this way will cause all task log records in the database to be removed.

Prototype (C/C++)

HRESULT RemoveTaskLogRecords(
VARIANT StepExecutionID,
long SequenceID );

See Also

EnumTaskLogRecords Method

LogServerName Property

LogToSQLServer Property

PackageLog Object

RemoveAllLogRecords Method

Retrieving DTS System, Package, and Log Data

SequenceID Property

StepExecutionID Property

TaskLogRecords Collection


Reset Method

The Reset method resets all values in the target object to their defaults.

Applies To

DTSMQMessage Object	DynamicPropertiesTaskAssignment Object
Syntax

object.Reset

Part	Description
object	Expression that evaluates to an object in the Applies To list
Prototype (C/C++)

HRESULT Reset()


ResetObjectsList Method

The ResetObjectsList method clears the list of objects to be transferred.

Applies To

TransferObjectsTask Object	TransferObjectsTask2 Object
Syntax

object.ResetObjectsList

Part	Description
object	Expression that evaluates to an object in the Applies To list
Prototype (C/C++)

HRESULT ResetObjectsList();

See Also

AddObjectForTransfer Method

GetObjectForTransfer Method


ResolveName Method

The ResolveName method resolves an e-mail address.

Applies To

SendMailTask Object

Syntax

[string =] object.ResolveName(Address)

Part	Description
object	Expression that evaluates to a SendMailTask object
Address	E-mail addresses to be resolved
string	String to receive the list of resolved names
Remarks

E-mail addresses are separated by semicolons.

Prototype (C/C++)

HRESULT ResolveName(
BSTR Address,
BSTR *ErrorString);


Save Method

The Save method instructs an object implementing a custom task to perform custom property storage into a PropertyBag object. The Save method is called by Data Transformation Services (DTS) when a DTS package is stored.

Applies To

PersistPropertyBag Object

Syntax

object.Save PropertyBag

Part	Description
object	Expression that evaluates to a PersistPropertyBag object
PropertyBag	PropertyBag object to receive the persisted properties
Remarks

Generic BLOBs or objects are not supported as property values.

Prototype (C/C++)

HRESULT Save(IDTSPropertyBag *IDTSPropertyBag);

See Also

Load Method

PropertyBag Object


SaveAs Method

The SaveAs method creates a new Data Transformation Services (DTS) package ID and assigns the new name while preserving all other properties.

Applies To

Package Object	Package2 Object
Syntax

object.SaveAs NewName

Part	Description
object	Expression that evaluates to an object in the Applies To list
NewName	New package name
Remarks

The package is given a new name and package ID, but nothing is saved to persistent storage.

Prototype (C/C++)

HRESULT SaveAs( BSTR NewName );

See Also

Managing DTS Package Programs

SaveToRepository Method

SaveToRepositoryAs Method

SaveToSQLServer Method

SaveToSQLServerAs Method

SaveToStorageFile Method

SaveToStorageFileAs Method


SaveToRepository Method

The SaveToRepository method saves information being held in the Package2 object and its subordinate objects and collections to the specified instance of Microsoft® SQL Server™ 2000 Meta Data Services.

Applies To

Package Object	Package2 Object
Syntax

object.SaveToRepository(
RepositoryServerName,
RepositoryDatabaseName,
RepositoryUserName,
RepositoryUserPassword,
[Flags],
[CategoryID],
[pVarPersistStgOfHost])

Part	Description
object	Expression that evaluates to an object in the Applies To list.
RepositoryServerName	A string specifying the name of the server on which the instance of Meta Data Services is hosted.
RepositoryDatabaseName	A string specifying the name of the database in which the instance of Meta Data Services is located.
RepositoryUsername	A string specifying the logon name used to access the server specified by ServerName.
RepositoryUserPassword	A string specifying the password used to access the server specified by ServerName.
Flags	A value from the DTSRepositoryStorageFlags constants that specifies the type of user authentication used to access the server specified by RepositoryServerName.
CategoryID	Reserved.
pVarPersistStgOfHost	Screen layout information associated with a package (for internal use).
Remarks

RepositoryDatabaseName is evaluated as an ODBC datasource name (DSN) if RepositoryServerName is empty or NULL. Otherwise, RepositoryServerName and RepositoryDatabaseName are used to create a DSN-less connection.

A new VersionID value is always generated when the package is saved.

Prototype (C/C++)

HRESULT SaveToRepository(
BSTR RepositoryServerName,
BSTR RepositoryDatabaseName,
BSTR RepositoryUserName,
BSTR RepositoryUserPassword,
DTSRepositoryStorageFlags Flags,
BSTR CategoryID,
VARIANT pVarPersistStgOfHost);

See Also

DTSRepositoryStorageFlags

Managing DTS Package Programs

SaveAs Method

SaveToRepositoryAs Method

SaveToSQLServer Method

SaveToStorageFile Method


SaveToRepositoryAs Method

The SaveToRepositoryAs method saves information being held in the Package object and its subordinate objects and collections to the specified instance of Microsoft® SQL Server™ 2000 Meta Data Services. The new name and a new Data Transformation Services (DTS) package ID are assigned.

Applies To

Package2 Object

Syntax

object.SaveToRepository(
NewName,
RepositoryServerName,
RepositoryDatabaseName,
RepositoryUserName,
RepositoryUserPassword,
[Flags],
[CategoryID],
[pVarPersistStgOfHost])

Part	Description
Object	Expression that evaluates to a Package2 object.
NewName	A string specifying the new name for the package.
RepositoryServerName	A string specifying the name of the server on which the instance of Meta Data Services is hosted.
RepositoryDatabaseName	A string specifying the name of the database in which the instance of Meta Data Services is located.
RepositoryUsername	A string specifying the logon name used to access the server specified by ServerName.
RepositoryUserPassword	A string specifying the password used to access the server specified by ServerNam.e
Flags	A value from the DTSRepositoryStorageFlags constants that specifies the type of user authentication used to access the server specified by RepositoryServerName.
CategoryID	Reserved.
pVarPersistStgOfHost	Screen layout information associated with a package (for internal use).
Remarks

RepositoryDatabaseName is evaluated as an ODBC data source name (DSN) if RepositoryServerName is empty or NULL. Otherwise, RepositoryServerName and RepositoryDatabaseName are used to create a connection without a DSN.

New package ID and version ID values are generated when the package is saved.

Prototype (C/C++)

HRESULT SaveToRepositoryAs(
BSTR NewName,
BSTR RepositoryServerName,
BSTR RepositoryDatabaseName,
BSTR RepositoryUserName,
BSTR RepositoryUserPassword,
DTSRepositoryStorageFlags Flags,
BSTR CategoryID,
VARIANT pVarPersistStgOfHost);

See Also

DTSRepositoryStorageFlags

Managing DTS Package Programs

SaveAs Method

SaveToRepository Method

SaveToSQLServerAs Method

SaveToStorageFileAs Method


SaveToSQLServer Method

The SaveToSQLServer method saves information being held in the Package2 object and its subordinate objects and collections to the specified server running an instance of Microsoft® SQL Server™.

Applies To

Package Object	Package2 Object
Syntax

object.SaveToSQLServer(
ServerName,
[ServerUserName],
[ServerPassword],
[Flags],
[PackageOwnerPassword],
[PackageOperatorPassword],
[PackageCategoryID],
[pVarPersistStgOfHost],
[bReusePasswords])

Part	Description
object	Expression that evaluates to an object in the Applies To list.
ServerName	A string specifying the name of the server to which to connect.
ServerUserName	A string specifying the logon name used to access the server specified by ServerName.
ServerPassword	A string specifying the password used to access the server specified by ServerName.
Flags	A value from the DTSSQLServerStorageFlags constants that specifies the type of user authentication used to access the server specified by ServerName.
PackageOwnerPassword	A string specifying the package owner password if the package is encrypted.
PackageOperatorPassword	A string specifying the package user password if the package is encrypted.
PackageCategoryID	A string specifying the package category (reserved).
pVarPersistStgOfHost	Screen layout information associated with a package (for internal use).
bReusePasswords	A Boolean specifying whether to reuse package passwords.
Remarks

A new version ID value is always generated when the package is saved.

The default for bReusePasswords is True.

Prototype (C/C++)

HRESULT SaveToSQLServer(
BSTR ServerName,
BSTR ServerUserName,
BSTR ServerPassword,
DTSSQLServerStorageFlags Flags,
BSTR PackageOwnerPassword,
BSTR PackageOperatorPassword,
BSTR PackageCategoryID,
VARIANT pVarPersistStgOfHost),
VARIANT_BOOL bReusePasswords);

See Also

DTSSQLServerStorageFlags

Managing DTS Package Programs

SaveAs Method

SaveToRepository Method

SaveToSQLServerAs Method

SaveToStorageFile Method


SaveToSQLServerAs Method

The SaveToSQLServer method saves information being held in the Package2 object and its subordinate objects and collections to the specified server running an instance of Microsoft® SQL Server™. The new name and a new package ID are assigned.

Applies To

Package2 Object

Syntax

object.SaveToSQLServerAs(
NewName,
ServerName,
[ServerUserName],
[ServerPassword],
[Flags],
[PackageOwnerPassword],
[PackageOperatorPassword],
[PackageCategoryID],
[pVarPersistStgOfHost],
[bReusePasswords])

Part	Description
object	Expression that evaluates to a Package2 object.
NewName	A string specifying the new name for the package.
ServerName	A string specifying the name of the server to which to connect.
ServerUserName	A string specifying the logon name used to access the server specified by ServerName.
ServerPassword	A string specifying the password used to access the server specified by ServerName.
Flags	A value from the DTSSQLServerStorageFlags constants that specifies the type of user authentication used to access the server specified by ServerName.
PackageOwnerPassword	A string specifying the package owner password if the package is encrypted.
PackageOperatorPassword	A string specifying the package user password if the package is encrypted.
PackageCategoryID	A string specifying the package category (reserved.
pVarPersistStgOfHost	Screen layout information associated with a package (for internal use).
bReusePasswords	A Boolean specifying whether to reuse package passwords.
Remarks

New package ID and version ID values are generated when the package is saved, and the new name is assigned.

The default for bReusePasswords is True.

Prototype (C/C++)

HRESULT SaveToSQLServerAs(
BSTR NewName,
BSTR ServerName,
BSTR ServerUserName,
BSTR ServerPassword,
DTSSQLServerStorageFlags Flags,
BSTR PackageOwnerPassword,
BSTR PackageOperatorPassword,
BSTR PackageCategoryID,
VARIANT pVarPersistStgOfHost),
VARIANT_BOOL bReusePasswords);

See Also

DTSSQLServerStorageFlags

Managing DTS Package Programs

SaveAs Method

SaveToRepositoryAs Method

SaveToSQLServer Method

SaveToStorageFileAs Method


SaveToStorageFile Method

The SaveToStorageFile method saves the information being held in the Package2 object and its subordinate objects and collections to a structured storage file.

Applies To

Package Object	Package2 Object
Syntax

object.SaveToStorageFile(
[UNCFile],
[OwnerPassword],
[OperatorPassword],
[pVarPersistStgOfHost],
[bReusePasswords])

Part	Description
object	Expression that evaluates to an object in the Applies To list
UNCFile	File specification to which package is to be written
OwnerPassword	A string specifying the package owner password if the package is encrypted
OperatorPassword	A string specifying the package user password if the package is encrypted
pVarPersistStgOfHost	Screen layout information associated with a package (for internal use)
bReusePasswords	A Boolean specifying whether to reuse package passwords
Remarks

A new version ID value is always generated when the package is saved.

The default for bReusePasswords is True.

Prototype (C/C++)

HRESULT SaveToStorageFile(
BSTR UNCFile,
BSTR OwnerPassword
BSTR OperatorPassword
VARIANT *pVarPersistStgOfHost
VARIANT_BOOL bReusePasswords );

See Also

Managing DTS Package Programs

SaveAs Method

SaveToRepository Method

SaveToSQLServer Method

SaveToStorageFileAs Method


SaveToStorageFileAs Method

The SaveToStorageFileAs method saves the information being held in the Package2 object and its subordinate objects and collections to a structured storage file. The new name and a new package ID are assigned.

Applies To

Package2 Object

Syntax

object.SaveToStorageFileAs(
NewName,
[UNCFile],
[OwnerPassword],
[OperatorPassword],
[pVarPersistStgOfHost],
[bReusePasswords])

Part	Description
object	Expression that evaluates to a Package2 object
NewName	A string specifying the new name for the package
UNCFile	File specification to which package is to be written
OwnerPassword	A string specifying the package owner password if the package is encrypted
OperatorPassword	A string specifying the package user password if the package is encrypted
pVarPersistStgOfHost	Screen layout information associated with a package (for internal use)
bReusePasswords	A Boolean specifying whether to reuse package passwords
Remarks

New package ID and version ID values are generated when the package is saved, and the new name is assigned.

The default for bReusePasswords is True.

Prototype (C/C++)

HRESULT SaveToStorageFileAs(
BSTR UNCFile,
BSTR OwnerPassword
BSTR OperatorPassword
VARIANT *pVarPersistStgOfHost
VARIANT_BOOL bReusePasswords );

See Also

Managing DTS Package Programs

SaveAs Method

SaveToRepositoryAs Method

SaveToSQLServerAs Method

SaveToStorageFile Method


SetDayLongName Method

The SetDayLongName method sets the long (full) name for the specified day of the week.

Applies To

DataPumpTransformDateTimeString Object

Syntax

object.SetDayLongName(daynumber) = string

Part	Description
object	Expression that evaluates to a DataPumpTransformDateTimeString object
daynumber	Number of the day of the week
string	Long (full) name of the specified day of week
Remarks

The valid day numbers are from 1 through 7.

Prototype (C/C++)

HRESULT SetDayLongName(
long DayNumber,
BSTR NewValue);

See Also

Adding DTS Transformations

Day?LongName Property

GetDayLongName Method

SetDayShortName Method


SetDayShortName Method

The SetDayShortName method sets the short name (3-character abbreviation) for the specified day of the week.

Applies To

DataPumpTransformDateTimeString Object

Syntax

object.SetDayShortName(daynumber) = string

Part	Description
object	Expression that evaluates to a DataPumpTransformDateTimeString object
daynumber	Number of the day of the week
string	Short name (3-character abbreviation) of the specified day of week
Remarks

The valid day numbers are from 1 through 7.

Prototype (C/C++)

HRESULT SetDayShortName(
long DayNumber,
BSTR NewValue);

See Also

Adding DTS Transformations

Day?ShortName Property

GetDayShortName Method

SetDayLongName Method


SetMonthLongName Method

The SetMonthLongName method sets the long (full) name for the specified month.

Applies To

DataPumpTransformDateTimeString Object

Syntax

object.SetMonthLongName(monthnumber) = string

Part	Description
object	Expression that evaluates to a DataPumpTransformDateTimeString object
monthnumber	Number of the month
string	Long (full) name of the specified month
Remarks

The valid month numbers are from 1 through 12.

Prototype (C/C++)

HRESULT SetMonthLongName(
long MonthNumber,
BSTR NewValue);

See Also

Adding DTS Transformations

GetMonthLongName Method

Month??LongName Property

SetMonthShortName Method


SetMonthShortName Method

The SetMonthShortName method sets the short name (3-character abbreviation) for the specified month.

Applies To

DataPumpTransformDateTimeString Object

Syntax

object.SetMonthShortName(monthnumber) = string

Part	Description
object	Expression that evaluates to a DataPumpTransformDateTimeString object
monthnumber	Number of the month
string	Short name (3-character abbreviation) of the specified month
Remarks

The valid month numbers are from 1 through 12.

Prototype (C/C++)

HRESULT SetMonthShortName(
long MonthNumber,
BSTR NewValue);

See Also

Adding DTS Transformations

GetMonthShortName Method

Month??ShortName Property

SetMonthLongName Method


ShowAddressBook Method

The ShowAddressBook method displays the address book user interface.

Applies To

SendMailTask Object

Syntax

[Address =] object.ShowAddressBook(hwndParent)

Part	Description
object	Expression that evaluates to a SendMailTask object
hwndParent	Window handle of the parent window
Address	String to receive the address selected by the user
Remarks

hwndParent is the handle of the window on which the address book is to be displayed.

Prototype (C/C++)

HRESULT ShowAddressBook(
long hwndParent,
 	BSTR *Address);


Uninitialize Method

The Uninitialize method clears all state information and releases all related objects, allowing the Package object to be reused.

Applies To

Package Object	Package2 Object
Syntax

Package.Uninitialize()

Part	Description
Package	Expression that evaluates to an object in the Applies To list
Remarks

The Uninitialize method clears the execution-related state of the Package2 object, including any event handlers registered or any active sessions made by a Connection object. You must call Uninitialize before the Package2 object is final-released because event handlers may contain a circular reference. All child objects of the Package2 object must be released before you call Uninitialize.

In Microsoft® Visual Basic®, release object references by setting the corresponding object variables to Nothing or allow the variables to go out of scope. If you have multiple Package or Package2 object variables, release all but one of them and execute the Uninitialize method against the one remaining reference.

This method does not affect the presence of any structural elements of the package, such as removing items that have been added to collections. To implement a new Package object, simply release all references to a prior one or its children, and then create a new one.

Prototype (C/C++)

HRESULT UnInitialize();

See Also

Managing DTS Package Programs


UninitializeMAPI Method

The UninitializeMAPI method uninitializes the MAPI provider.

Applies To

SendMailTask Object

Syntax

object.UninitializeMAPI

Part	Description
object	Expression that evaluates to a SendMailTask object
Prototype (C/C++)

HRESULT UnInitializeMAPI();

See Also

InitializeMAPI Method


Unlock Method

The Unlock method unlocks a GlobalVariable2 object that had been previously locked with the Lock method.

Applies To

GlobalVariable2 Object

Syntax

globalvar.Unlock

Part	Description
globalvar	Expression that evaluates to a GlobalVariable2 object
Remarks

If the global variable is not already locked, the Unlock method does nothing, and no error occurs.

If the global variable was locked from a different thread than that which issued the Unlock method, an error occurs and the global variable is not unlocked.

Prototype (C/C++)

HRESULT Unlock( void );

See Also

Adding DTS Lookups and Global Variables

Lock Method


Write Method

The Write method updates a value in a PropertyBag collection.

Applies To

PropertyBag Object

Syntax

object.Write bstrPropertyName, Value

Part	Description
object	Expression that evaluates to a PropertyBag object
bstrPropertyName	String identifying an exposed property by name
Value	Value of the property to be saved
Remarks

Generic BLOBs or objects are not supported as property values.

Prototype (C/C++)

HRESULT Write(
BSTR bstrPropertyName,
VARIANT Value);

See Also

PersistPropertyBag Object

Read Method


WriteStringToLog Method

The WriteStringToLog adds a string to the log record that is being written for the step.

Applies To

PackageLog Object

Syntax

object.WriteStringToLog LogString

Part	Description
object	Expression that evaluates to a PackageLog object reference
LogString	String containing the log message that is to be appended to the log message for the step
Remarks

A log string is accumulated for each step. WriteStringToLog adds a new string to the log message, separated by a Newline character from the previously accumulated message. WriteStringToLog can be called any number of times during task execution.

The WriteStringToLog method is available to custom tasks, where the reference to the PackageLog object is a parameter of the task Execute method, which in a custom task, you must implement. It is also available in the Data Transformation Services (DTS) Microsoft® ActiveX® Script task, through the DTSPackageLog object.

Prototype (C/C++)

HRESULT WriteStringToLog( BSTR LogString );

See Also

Retrieving DTS System, Package, and Log Data

WriteTaskRecord Method


WriteTaskRecord Method

The WriteTaskRecord adds a record to the server log table for the current task execution, and formats it for WriteStringToLog to write it to the log file.

Applies To

PackageLog Object

Syntax

object.WriteTaskRecord ErrorCode, Description

Part	Description
object	Expression that evaluates to a PackageLog object reference
ErrorCode	A long integer that can be an error code or other numeric information to be logged
Description	A string that can be an error description or other textual information to be logged
Remarks

The WriteTaskRecord method is available to custom tasks, where the reference to the PackageLog object is a parameter of the task Execute method, which in a custom task, you must implement. It is also available in the Data Transformation Services (DTS) Microsoft® ActiveX® Script task, through the DTSPackageLog object.

Prototype (C/C++)

HRESULT WriteTaskRecord(
long ErrorCode,
BSTR Description );

See Also

Retrieving DTS System, Package, and Log Data

WriteStringToLog Method


Events

This section describes package events, which return information about the status of a Data Transformation Services (DTS) package execution.


OnError Event

The OnError event indicates and provides information about an error. It allows the event handler to cancel task execution.

Applies To

Package Object	Package2 Object
Syntax (Visual Basic)

Sub objPackage_OnError(ByVal EventSource As String, ByVal ErrorCode As Long, _
ByVal Source As String, ByVal Description As String, ByVal HelpFile As String, _
ByVal HelpContext As Long, ByVal IDOfInterfaceWithError As String, _
ByVal pbCancel As Boolean)

Part	Description
objPackage	Object variable of a type specified in the Applies To list.
EventSource	Source of event being executed (for example, a step name).
ErrorCode	Error code of the failure.
Source	Source of error message (for example, an OLE DB provider description).
Description	Description of the error.
HelpFile	Help file name.
HelpContext	Help context ID.
IDOfInterfaceWithError	ID of the user interface returning the error, a globally unique identifier (GUID).
pbCancel	Boolean that specifies whether to cancel task execution.
Remarks

The OnError event occurs during the Package2 object Execute method. An error can be raised by a Data Transformation Services (DTS) component or by a custom task. When an error occurs in execution, the OnError event is raised before return from the Execute method.

Use the pbCancel argument to direct package execution on error. When the OnError handler sets Cancel to TRUE, execution of the package is terminated on return from the error handler. When Cancel is FALSE, DTS package execution continues.

The OnError event is raised on each error occurring in a task or step. A step does not necessarily terminate after an error. For example, the MaximumErrorCount property of the DataPumpTask2 object specifies the number of errors that can occur before the task is terminated.

For task types defined by DTS, the EventSource argument specifies a step name. Custom tasks choose what to return for EventSource. When an error is not caused by or associated with a step, the EventSource argument is empty.

If you need to raise this event from a custom task implemented in Microsoft® Visual Basic®, use this syntax:

pPackageEvents.OnError EventSource, ErrorCode, Source, Description, _
HelpFile, HelpContext, IDOfInterfaceWithError, pbCancel

pPackageEvents is a reference to the package events object, passed in as a parameter of the custom task Execute method that you have implemented. When the event returns, terminate task execution if pbCancel is TRUE.

Prototype (C/C++)

HRESULT OnError(
BSTR EventSource,
long ErrorCode,
BSTR Source,
BSTR Description,
BSTR HelpFile,
long HelpContext,
BSTR IDOfInterfaceWithError,
BOOL *pbCancel);

See Also

Execute Method

Handling DTS Events and Errors


OnFinish Event

The OnFinish event indicates completion of a Data Transformation Services (DTS) task or step.

Applies To

Package Object	Package2 Object
Syntax (Visual Basic)

Sub objPackage_OnFinish(ByVal EventSource As String)

Part	Description
objPackage	Object variable of a type specified in the Applies To list.
EventSource	Source of event being executed (for example, a step name).
Remarks

For task types defined by DTS, the EventSource argument specifies a step name. Custom tasks choose what to return for EventSource. When an event is not caused by or associated with a step, the EventSource argument is empty.

If you need to raise this event from a custom task implemented in Microsoft® Visual Basic®, use this syntax:

pPackageEvents.OnFinish EventSource

pPackageEvents is a reference to the package events object, passed in as a parameter of the custom task Execute method that you have implemented.

Prototype (C/C++)

HRESULT OnFinish(BSTR EventSource);

See Also

Execute Method

Handling DTS Events and Errors


OnProgress Event

The OnProgress event provides information about the progress of a Data Transformation Services (DTS) task.

Applies To

Package Object	Package2 Object
Syntax (Visual Basic)

Sub objPackage_OnProgress(ByVal EventSource As String, _
ByVal ProgressDescription As String, ByVal PercentComplete As Long, _
ByVal ProgressCountLow As Long, ByVal ProgressCountHigh As Long)

Part	Description
objPackage	Object variable of a type specified in the Applies To list.
EventSource	Source of event being executed (for example, a step name).
ProgressDescription	Description of task progress.
PercentComplete	Percent of task completed.
ProgressCountLow	Low 32 bits of units (for example, rows) completed.
ProgressCountHigh	High 32 bits of units (for example, rows) completed.
Remarks

If the percent completed cannot be reported, 0 is returned.

For task types defined by DTS, the EventSource argument specifies a step name. Custom tasks choose what to return for EventSource. When an event is not caused by or associated with a step, the EventSource argument is empty.

If you need to raise this event from a custom task implemented in Microsoft® Visual Basic®, use this syntax:

pPackageEvents.OnProgress EventSource, ProgressDescription, _
PercentComplete, ProgressCountLow, ProgressCountHigh

pPackageEvents is a reference to the package events object, passed in as a parameter of the custom task Execute method that you have implemented.

Prototype (C/C++)

HRESULT OnProgress(
BSTR EventSource,
BSTR ProgressDescription,
long PercentComplete,
long ProgressCountLow,
long ProgressCountHigh);

See Also

Execute Method

Handling DTS Events and Errors


OnQueryCancel Event

The OnQueryCancel event terminates tasks. A Data Transformation Services (DTS) package raises this event only when it is safe to stop execution of the task. The event handler determines whether task execution should be terminated.

Applies To

Package Object	Package2 Object
Syntax (Visual Basic)

Sub objPackage_OnQueryCancel(ByVal EventSource As String, _
ByVal pbCancel As Boolean)

Part	Description
objPackage	Object variable of a type specified in the Applies To list.
EventSource	Source of event being executed (for example, a step name).
pbCancel	Boolean that specifies whether to cancel task execution.
Remarks

If pbCancel is set to TRUE by the event handler, DTS stops task execution and fails with error. This event may not occur if execution of the step or task completes quickly.

For task types defined by DTS, the EventSource argument specifies a step name. Custom tasks choose what to return for EventSource. When an event is not caused by or associated with a step, the EventSource argument is empty.

If you need to raise this event from a custom task implemented in Microsoft® Visual Basic®, use this syntax:

pPackageEvents.OnQueryCancel EventSource, pbCancel

pPackageEvents is a reference to the package events object, passed in as a parameter of the custom task Execute method that you have implemented. When the event returns, terminate task execution if pbCancel is TRUE.

Prototype (C/C++)

HRESULT OnQueryCancel(BSTR EventSource,
BOOL *pbCancel);

See Also

Execute Method

Handling DTS Events and Errors

KILL


OnStart Event

The OnStart event indicates the start of a Data Transformation Services (DTS) task or step.

Applies To

Package Object	Package2 Object
Syntax (Visual Basic)

Sub objPackage_OnStart(ByVal EventSource As String)

Part	Description
objPackage	Object variable of a type specified in the Applies To list.
EventSource	Source of event being executed (for example, a step name).
Remarks

For task types defined by DTS, the EventSource argument specifies a step name. Custom tasks choose what to return for EventSource. When an event is not caused by or associated with a step, the EventSource argument is empty.

If you need to raise this event from a custom task implemented in Microsoft® Visual Basic®, use this syntax:

pPackageEvents.OnStart EventSource

pPackageEvents is a reference to the package events object, passed in as a parameter of the custom task Execute method that you have implemented.

Prototype (C/C++)

HRESULT OnStart(BSTR EventSource);

See Also

Execute Method

Handling DTS Events and Errors


Constants

This section describes a Data Transformation Services (DTS) package constants, which are enumerated data types. These constants are used as parameters and return values in DTS package properties and methods.


DTSBulkInsert_DataFileType

The DTSBulkInsert_DataFileType constants specify the type of data file used in Bulk Insert operations.

Constant	Value	Description
DTSBulkInsert_DataFileType_Char	0	Char data file type
DTSBulkInsert_DataFileType_Native	1	Native data file type
DTSBulkInsert_DataFileType_WideChar	2	WideChar data file type
DTSBulkInsert_   DataFileType_WideNative	3	WideNative data file type
See Also

BulkInsertTask Object

DataFileType Property


DTSCustomTaskUIFlags

The DTSCustomTaskUIFlags constants specify flags indicating the type of user interface supported by the database custom task.

Constant	Value	Description
DTSCustomTaskUIFlags_Default	0	Default
DTSCustomTaskUIFlags_   DoesCustomToolTip	1	Custom task supports custom tooltips
See Also

GetUIInfo Method

CustomTaskUI Object


DTSDataPumpError

The DTSDataPumpError constants specify error ranges for Data Transformation Services (DTS) data pump execution.

Constant	Value	Description
DTSDataPump_E_   AutoBufferInterfaceNotSupported	8273 (x2051)	A transform definition required buffering for the specified source column, but the requested interface is not ISequentialStream or ILockBytes.
DTSDataPump_E_   AxScript_AbortPumpReturned	8502 (x2136)	A transformation phase returned by DTSTransformStat_AbortPump.
DTSDataPump_E_   AxScript_BadTransformFunction	8259 (x2043)	Microsoft® ActiveX® scripting transform function was not found.
DTSDataPump_E_   AxScript_CantChangeSrcCols	8260 (x2044)	ActiveX scripting transform does not allow a script to change source columns.
DTSDataPump_E_   AxScript_CantInitializeEngine	8262 (x2046)	ActiveX scripting transform was not able to initialize the script execution engine.
DTSDataPump_E_   AxScript_CantResetAfterInitialize	8261 (x2045)	The scripting engine properties cannot be changed after the scripting engine has been instantiated.
DTSDataPump_E_ AxScript_InvalidPhaseColumnAccess	8500 (x2134)	The script attempted to write source columns or the column access code is undefined.
DTSDataPump_E_   AxScript_NoPhaseFunc	8503 (x2137)	A script function for a phase the transformation is to support was not found.
DTSDataPump_E_   AxScript_ParseError	8258 (x2042)	ActiveX script parsing fails when called by ValidateSchema method.
DTSDataPump_E_   AxScript_RequiredParams	8256 (x2040)	ActiveX scripting transform requires script Text, Language, and FunctionEntry parameters to be specified in IDTSDataPumpTransformScriptProperties.
DTSDataPump_E_   AxScript_RunTimeError	8263 (x2047)	ActiveX scripting transform encountered a run-time error during the execution of the script.
DTSDataPump_E_    AxScript_ValidateSchemaError	8257 (x2041)	A transformation relied on a bad data type. User-defined data types, arrays, and vectors of types are not supported.
DTSDataPump_E_   BadTransformFlag	8210 (x2012)	Invalid or incompatible DTSTransformFlag value(s).
DTSDataPump_E_   BadTransformPhase	8496 (x2130)	An invalid transformation phase was specified, via the TransformPhases property.
DTSDataPump_E_ BadTransformStatusReturned	8211 (x2013)	Transform server returned an invalid DTSTransformStatus value, or an ActiveX script did not return an integral type. The data pump task will be terminated.
DTSDataPump_E_   CannotRebindColumn	8213 (x2015)	Binding information for one or more columns has been specified in a prior transform and cannot be respecified.
DTSDataPump_E_    CannotTransformChapterColumns	8219 (x201B)	A column in a hierarchical rowset that contains chapters (child rowsets) cannot itself be transformed.
DTSDataPump_E_   ColCountButNoCols	8198 (x2006)	A nonzero column count was specified with no column specification pointer.
DTSDataPump_E_   ColumnNameNotFound	8200 (x2008)	Column name not found.
DTSDataPump_E_   ColumnOutOfRange	8201 (x2009)	Column ordinal was out of range.
DTSDataPump_E_   Convert_BadBindInfo	8231 (x2027)	Incorrect binding information on column pair.
DTSDataPump_E_ Convert_BlobStorageNoInterface	8238 (x202E)	The required source BLOB storage object interface does not exist.
DTSDataPump_E_   Convert_ConversionFailed	8236 (x202C)	General conversion failure on column pair.
DTSDataPump_E_   Convert_ConversionInvalid	8235 (x202B)	Conversion invalid for data types on column pair.
DTSDataPump_E_   Convert_DestNotNull	8230 (x2026)	Destination does not allow NULL on column pair.
DTSDataPump_E_   Convert_DestOverflow	8232 (x2028)	Destination overflowed on column pair.
DTSDataPump_E_ Convert_ProviderOwnedTypeMismatch	8237 (x202D)	DBMEMOWNER_PROVIDEROWNED type mismatch for an allocatable type on column pair.
DTSDataPump_E_   Convert_SourceInvalidLength	8234 (x202A)	Source data length invalid for its type or for conversion to destination type on column pair.
DTSDataPump_E_   Convert_SourceInvalidVariant	8233 (x2029)	Source variant invalid on column pair.
DTSDataPump_E_    Copy_NeedSrcAndDestColumns	8228 (x2024)	A DTSTransformCopy operation must specify no columns or the same number of source and destination columns.
DTSDataPump_E_   Copy_ValidateSchemaError	8229 (x2025)	ValidateSchema method failed. See extended error information appended to error description. For more information, see OnError Event and GetExecutionErrorInfo Method.
DTSDataPump_E_   DataPumpNotReentrant	8207 (x200F)	Data pump implements a single execution operation and is therefore not reentrant.
DTSDataPump_E_ DDQ_BadTransformStatusContext	8293 (x2065)	Transform status returned a DataDrivenQueryTask value, but no DataDrivenQueryTask object was specified.
DTSDataPump_E_   DDQ_DestColumnNeedsLength	8295 (x2067)	One or more destination column definitions is variable-length and requires a maximum column size to be specified.
DTSDataPump_E_ DDQ_DestColumnNotTransformed	8294 (x2066)	One or more destination parameter columns had no transform specified.
DTSDataPump_E_ DDQ_DestDoesNotSupportSQL	8296 (x2068)	The destination OLE DB provider does not implement the IDBCreateCommand interface, which is needed to support SQL.
DTSDataPump_E_ DDQ_InformationNotSet	8293 (x2065)	Attempted to get data driven query destination information when data pump instance is not a DataDrivenQueryTask (internal error).
DTSDataPump_E_   DDQ_NeedDeleteQuery	8291 (x2063)	Transform status returned DeleteQuery value, but no DeleteQuery property was specified.
DTSDataPump_E_   DDQ_NeedInsertQuery	8289 (x2061)	Transform status returned InsertQuery value, but no InsertQuery property was specified.
DTSDataPump_E_   DDQ_NeedTransformStatus	8288 (x2060)	No query specification returned by transform status.
DTSDataPump_E_   DDQ_NeedUpdateQuery	8290 (x2062)	Transform status returned UpdateQuery value, but no UpdateQuery property was specified.
DTSDataPump_E_   DDQ_NeedUserQuery	8292 (x2064)	Transform status returned UserQuery value, but no UserQuery property was specified.
DTSDataPump_E_    DDQ_TransformStatusForced	8297 (x2069)	Transformation improperly tried to set query type.
DTSDataPump_E_   DestColumnAlreadySpecified	8202 (x200A)	One or more destination columns have been specified already in this or a prior transformation.
DTSDataPump_E_   DestColumnReadOnly	8208 (x2010)	One or more destination columns are read-only; you must define a mapping which does not include them.
DTSDataPump_E_   DestinationBlobBinding	8224 (x2020)	In-memory destination BLOB (DBCOLUMNFLAGS_ISLONG) columns must specify a nonzero cbInMemoryBlobSize.
DTSDataPump_E_   DestRowsetNotSupplied	8195 (x2003)	Destination columns or other information specified, but no destination rowset was supplied.
DTSDataPump_E_   IDataConvertRequired	8203 (x200B)	Transform requires an IDataConvert interface to be available on the destination rowset or from an OLE DB installation (Msdadc.dll).
DTSDataPump_E_   InvalidDataPumpOption	8499 (x2133)	DataPumpOptions property was set to an invalid value.
DTSDataPump_E_   InvalidDTSBindMode	8215 (x2017)	Invalid or incompatible DTSBindMode value(s), or DTSBindMode value incompatible with column type.
DTSDataPump_E_   InvalidFetchBufferSize	8214 (x2016)	FetchBufferSize property value must be nonzero.
DTSDataPump_E_   InvalidSpecifyBlobDefaults	8273 (x2051)	Invalid DTSSpecifyBlobDefaults enumeration value(s).
DTSDataPump_E_   InvalidStatusForPhase	8497 (x2131)	The transformation phase returned a status value that is invalid for that phase.
DTSDataPump_E_ LastRowCantBeLessThanFirst	8275 (x2053)	The LastRow property cannot be less than the FirstRow property.
DTSDataPump_E_   LineageVariableNotFound	8274 (x2052)	A global variable or lineage variable was not found.
DTSDataPump_E_   LookupDupName	8218 (x201A)	A lookup name duplicates one that already exists.
DTSDataPump_E_   MismatchColOrdAndName	8199 (x2007)	A column ordinal referenced the wrong column name. Ordinals are used only to distinguish between multiple columns with the same name.
DTSDataPump_E_ MustSpecifyDestOrTransform	8209 (x2011)	A destination or one or more transformations must be specified.
DTSDataPump_E_   NonBlobStorageBind	8217 (x2019)	Non-BLOB (DBCOLUMNFLAGS_ISLONG) columns cannot be bound to storage objects.
DTSDataPump_E_   NotImplemented	8192 (x2000)	Method or property not yet implemented.
DTSDataPump_E_   NotReentrant	8205 (x200D)	Data pump implements a single execution operation and is therefore not reentrant.
DTSDataPump_E_   NullVariantIUnknown	8206 (x200C)	Passed variant is of type IUnknown, but contains a NULL pointer.
DTSDataPump_E_   RowFailuresExceedLimit	8298 (x206A)	The number of error rows exceeded the MaximumErrorCount property.
DTSDataPump_E_   RowsetChangeMustInsert	8206 (x200E)	Destination IRowsetChange must support InsertRow (DBPROPVAL_UP_INSERT).
DTSDataPump_E_   RowsetsAlreadySet	8193 (x2001)	Can be set only before Rowsets or DataDrivenQueryTask have been initialized.
DTSDataPump_E_   RowsetsNotSupplied	8196 (x2004)	NonNULL source rowset and an optional destination rowset must be specified.
DTSDataPump_E_   SourceBlobBinding	8216 (x2018)	In-Memory Source BLOB (DBCOLUMNFLAGS_ISLONG) columns cannot be bound with DTSBindMode_Byref, and must specify a nonzero cbInMemoryBlobSize.
DTSDataPump_E_   SourceColumnsRequired	8197 (x2005)	Source columns are required for nondefault transformations.
DTSDataPump_E_   TransformDateTimeString_ ErrorParsingInputData	8342 (x2096)	Error parsing the input datetime string.
DTSDataPump_E_   TransformDateTimeString_ ErrorParsingInputFormat	8340 (x2094)	Error parsing the value of the InputFormat property.
DTSDataPump_E_   TransformDateTimeString_ ErrorParsingOutputFormat	8341 (x2095)	Error parsing the value of the OutputFormat property.
DTSDataPump_E_   TransformDateTimeString_ IndexOutOfRange	8337 (x2091)	The index used to access the array of day names or month names is out of range.
DTSDataPump_E_   TransformDateTimeString_ InvalidFormatString	8343 (x2097)	A string did not have a valid datetime format.
DTSDataPump_E_   TransformDateTimeString_ InvalidNameOrFormat	8338 (x2092)	A required property or internal name was set to an empty string.
DTSDataPump_E_   TransformDateTimeString_ InvalidY2KCutoff	8339 (x2093)	The ShortYear2000Cutoff property was set to a value outside of 0…99.
DTSDataPump_E_   TransformDateTimeString_ NeedSrcAndDestColumns	8336 (x2090)	Something other than exactly one source column and exactly one destination column was specified.
DTSDataPump_E_   TransformReadFile_ FileNotFound	8480 (x2120)	The file from which column data was to be read could not be opened.
DTSDataPump_E_   TransformReadFile_ InvalidDestSchema	8482 (x2122)	The destination column had type other than DBTYPE_STR, DBTYPE_WSTR or DBTYPE_BYTES.
DTSDataPump_E_   TransformReadFile_ InvalidSourceSchema	8481 (x2121)	The source column had type other than DBTYPE_STR, DBTYPE_WSTR or DBTYPE_BSTR.
DTSDataPump_E_   TransformReadFile_ NeedSrcAndDestColumns	8322 (x2082)	Something other than exactly one source column and exactly one destination column were specified.
DTSDataPump_E_   TransformsAlreadySet	8194 (x2002)	Reserved.
DTSDataPump_E_   TransformServerException	8212 (x2014)	Transform server generated an exception.
DTSDataPump_E_   TransformString_ ColumnCount	8321 (x2081)	A Trim String or Middle of String transformation specified other than one source column.
DTSDataPump_E_   TransformString_ DestStringTrunc	8324 (x2084)	Destination truncation occurred in a Lowercase String, Uppercase String, Trim String or Middle of String transformation when DTSTransformFlag_AllowStringTruncation was not set.
DTSDataPump_E_   TransformString_ NeedSrcAndDestColumns	8320 (x2080)	The number of source columns differs from the number of destination columns in a Lowercase String, Uppercase String, Trim String or Middle of String transformation.
DTSDataPump_E_   TransformString_ ValidateSchemaError	8323 (x2083)	The conversion from source to destination column cannot be performed without error, within the parameters of the TransformFlags property, in a Lowercase String, Uppercase String, Trim String or Middle of String transformation.
DTSDataPump_E_   TransformWriteFile_ FetchedNullFileName	8454 (x2106)	The source column that is to contain the file specification is NULL or empty.
DTSDataPump_E_   TransformWriteFile_ FileAlreadyExists	8449 (x2101)	The file that is to be written already exists, and ErrorIfFileExists has been set.
DTSDataPump_E_   TransformWriteFile_ FileColumnNameNotFound	8450 (x2102)	The column named by the FileColumnName property could not be found.
DTSDataPump_E_   TransformWriteFile_ InvalidDestSchema	8452 (x2104)	The source column that contains the file data has type other than DBTYPE_STR, DBTYPE_WSTR or DBTYPE_BSTR.
DTSDataPump_E_   TransformWriteFile_ InvalidFileColumnName	8453 (x2105)	The FileColumnName property was set to NULL or an empty string or was not set.
DTSDataPump_E_   TransformWriteFile_ InvalidSourceSchema	8451 (x2103)	The source column that contains the file specification has type other than DBTYPE_STR, DBTYPE_WSTR, DBTYPE_BYTES or DBTYPE_BSTR.
DTSDataPump_E_   TransformWriteFile_ NeedSrcAndDestColumns	8448 (x2100)	Something other than exactly two source columns and no destination columns were specified for a Write File transformation.
DTSDataPump_E_   UnsupportedPhase	8498 (x2132)	A Copy, Uppercase String, Lowercase String, Trim String, Middle of String, Datetime String, Read File or Write File transformation had a phase other than Transform specified.
See Also

Handling DTS Events and Errors


DTSDesignerSettings

The DTSDesignerSettings constants specify settings that control whether features are visible or hidden for Data Transformation Services (DTS).

Constant	Value	Description
DTSDesigner_Default	0	Multiphase transformation features are not shown in DTS Designer.
DTSDesigner_   ShowMultiPhaseTransforms	1	Multiphase transformation features are visible in DTS Designer.
See Also

DesignerSettings Property


DTSExceptionFileOptions

The DTSExceptionFileOptions constants specify how Data Transformation Services (DTS) DataPump errors and exception rows are to be written to files.

Constant	Value	Description
DTSExceptionFile_   AbortOnRowLogFailure	8192 (x2000)	Terminate the data pump if execution logging fails.
DTSExceptionFile_Ansi	256 (x0100)	File type is ANSI (uses ANSI code page).
DTSExceptionFile_DestRowFile	8	Destination exception rows are written to the destination exception file.
DTSExceptionFile_ErrorFile	2	Error rows are written to the error file.
DTSExceptionFile_OEM	512 (x0200)	File type is OEM (uses OEM code page).
DTSExceptionFile_Overwrite	4096 (x1000)	Data is overwritten, rather than appended, to file.
DTSExceptionFile_SingleFile70	1	Errors, source, and destination exception rows are all written to a single ANSI file.
DTSExceptionFile_SourceRowFile	4	Source exception rows are written to the source exception file.
DTSExceptionFile_Unicode	1024 (x0400)	File type is Unicode.
See Also

ExceptionFileOptions Property


DTSExecuteStatus

The DTSExecuteStatus constants return values (int or long) from data pump execution.

Constant	Value	Description
DTSTransformExec_AbortPump	4100 (x1004)	Pump terminated due to transform request or ErrorSink return.
DTSTransformExec_Error	4096 (x1000)	Indicates the status code is an error. Added to other items in this table.
DTSTransformExec_   ErrorCountExceeded	4098 (x1002)	Pump terminated because too many rows had errors.
DTSTransformExec_OK	0	All rows copied (or skipped) without error.
DTSTransformExec_OKErrors	4097 (x1001)	Pump continued to completion, but encountered errors.
See Also

IDTSDataPumpErrorSink


DTSFastLoadOptions

The DTSFastLoadOptions constants specify FastLoad options for the DataPumpTask FastLoadOptions property.

Constant	Value	Description
DTSFastLoad_CheckConstraints	2	Check constraints (default).
DTSFastLoad_Default	2	Specifies the default, same as check constraints
DTSFastLoad_KeepNulls	1	Keep NULLs.
DTSFastLoad_NoOptions	0	No options.
DTSFastLoad_TableLock	4	Lock table.
See Also

DataPumpTask2 Object

FastLoadOptions Property


DTSForceMode

The DTSForceMode constants override the default handling of associated properties.

Constant	Value	Description
DTSForceMode_Always	1	Data Transformation Services (DTS) always overrides default handling of property.
DTSForceMode_Default	0	DTS can choose to override default handling of property.
DTSForceMode_Never	2	DTS never overrides default handling of property.
See Also

ForceSourceBlobsBuffered Property


DTSFTPError

The DTSFTPError constants specify codes used to report errors in DTSFTPTask object execution.

Constant	Value	Description
DTSFTP_E_CancelExecution	1007 (x03EF)	A cancel execution request was received from the OnQueryCancel event.
DTSFTP_E_CopyFileError	1011 (x03F3)	An error occurred copying one of the specified files.
DTSFTP_E_   ExceedeMaximumStringSize	1001 (x03E9)	A string property value exceeded the maximum allowed size (usually 256 characters).
DTSFTP_E_FTPExecutionError	1006 (x03EE)	A reference to the IDTSPackageEvents interface could not be obtained.
DTSFTP_E_   IncorrectOverwriteCBSelect	1003 (x03EB)	An invalid value for the NonOverwritable property was specified.
DTSFTP_E_IncorrectRetryTimes	1004 (x03EC)	An invalid value for the NumRetriesOnSource property was specified.
DTSFTP_E_   InternetConnectionError	1008 (x03F0)	Connection to the internet using Microsoft® Internet Explorer as agent failed.
DTSFTP_E_   InvalidFileNameProperty	1012 (x03F4)	An error occurred parsing the SourceFilename property.
DTSFTP_E_   InvalidSourceLocation	1005 (x03ED0	An invalid value for the SourceLocation property was specified.
DTSFTP_E_OutOfMemory	1010 (x03F2)	A memory allocation for character string data failed.
DTSFTP_E_SiteConnectionError	1009 (x03F1)	Connection to the destination site failed, after connection to the internet succeeded.
DTSFTP_E_   TooManyFilesSelected	1002 (x03EA)	The value used to set the SourceFilename property exceeded the allowed maximum (2000 characters).
See Also

DTSFTPTask Object


DTSFTPSourceLocation

The DTSFTPSourceLocation constants are used with the SourceLocation property to specify the source location type for a DTSFTPTask object.

Symbol	Value	Description
DTSFTPSourceLocation_Directory	1	Source is a network directory.
DTSFTPSourceLocation_   InternetSite	0	Source is an Internet site (default).
See Also

SourceLocation Property


DTSIsolationLevel

The DTSIsolationLevel constants specify isolation levels for the Package TransactionIsolationLevel property.

Constant	Value	Description
DTSIsoLevel_Browse	256 (x0100)	Browse level
DTSIsoLevel_Chaos	16 (x0010)	Chaos level
DTSIsoLevel_CursorStability	4096 (x1000)	Cursor stability level
DTSIsoLevel_Isolated	1048576 (x00100000)	Isolated level
DTSIsoLevel_ReadCommitted	4096 (x1000)	Read committed level
DTSIsoLevel_ReadUncommitted	256 (x0100)	Read uncommitted level
DTSIsoLevel_RepeatableRead	65536 (x00010000)	Repeatable read level
DTSIsoLevel_Serializable	1048576 (x00100000)	Serializable level
See Also

Package2 Object

TransactionIsolationLevel Property


DTSLineageOptions

The DTSLineageOptions constants specify Microsoft® SQL Server™ 2000 Meta Data Services lineage options for the Package LineageOptions property.

Constant	Value	Description
DTSLineage_AddLineageVariables	1	Add lineage variables.
DTSLineage_None	0	Provide no lineage (default).
DTSLineage_   WriteToReposIfAvailable	2	Write to Meta Data Services if available.
DTSLineage_   WriteToReposRequired	3	Write to Meta Data Services (required).
See Also

LineageOptions Property

Package2 Object


DTSMQMessageType

The DTSMQMessageType constants are used with the MessageType property to specify the type of message defined by a DTSMQMessage object.

Symbol	Value	Description
DTSMQMessageType_DataFile	1	Message consists of the contents of a data file.
DTSMQMessageType_   GlobalVariables	2	Message consists of the names and values of one or more Data Transformation Services (DTS) package global variables.
DTSMQMessageType_String	0	Message is a text string.
See Also

MessageType Property


DTSMQStringMessageCompare

The DTSMQStringMessageCompare constants are used with the StringCompareType property to specify the type of comparison to be performed on a received string message by a DTSMessageQueueTask object. The Description column in the table below specifies the condition for successful comparison.

Symbol	Value	Description
DTSMQStringMessageCompare_   Contains	3	Received message contains the comparison string.
DTSMQStringMessageCompare_   Exact	1	Received message matches comparison string exactly, including case of letters.
DTSMQStringMessageCompare_   IgnoreCase	2	Received message matches comparison string, ignoring case of letters.
DTSMQStringMessageCompare_   None	0	No comparison is performed (default).
See Also

StringCompareType Property


DTSMQType

The DTSMQType constants are used with the TaskType property to specify the type of the DTSMessageQueueTask object.

Symbol	Value	Description
DTSMQType_Receiver	1	Task object is to receive a single message.
DTSMQType_Sender	0	Task object is to send one or more messages.
See Also

DTSMessageQueueTask Object

TaskType Property


DTSMSMQError

The DTSMSMQError constants specify codes used to report errors in DTSMessageQueueTask object execution.

Constant	Value	Description
DTSMSMQ_E_   AssignmentIndexOutOfRange	1006 (x03EE)	The index for the Item or Remove method of the DTSMQMessages collection was out of range.
DTSMSMQ_E_CancelExecution	1023 (x03FF)	A cancel execution request was received from the OnQueryCancel event.
DTSMSMQ_E_   CanNotGetMessageQueueInfo	1015 (x03F7)	An error occurred setting the label or the body of an Message Queuing message.
DTSMSMQ_E_   CanNotGetPackageInfo	1019 (x03FB)	An error occurred retrieving the package ID or version ID of the Data Transformation Services (DTS) package.
DTSMSMQ_E_   CanNotOpenMessageQueue	1014 (x03F6)	The queue specified by the QueuePath property could not be opened.
DTSMSMQ_E_   CanNotSendMessage	1017 (x03F9)	An error occurred sending a message to the queue after it was successfully opened.
DTSMSMQ_E_DataFileSizeError	1009 (x03F1)	A data file message exceeds the maximum allowed size, 4 megabytes (MB).
DTSMSMQ_E_   ErrorAccessMessageCollections	1016 (x03F8)	An error occurred accessing the data of a message to be sent.
DTSMSMQ_E_   ErrorOpeningDataFile	1008 (x03F0)	An error occurred opening the file that is the source of a data file message.
DTSMSMQ_E_   ErrorReadingDataFile	1010 (x03F2)	An error occurred reading the file that is the source of a data file message.
DTSMSMQ_E_   ErrorSavingToDataFile	1027 (x0403)	An error occurred creating the file that is to receive a data file message.
DTSMSMQ_E_   ErrorWritingDataFile	1021 (x03FD)	An error occurred writing a data file message to the receiving file.
DTSMSMQ_E_   ExceededMaximumStringSize	1001 (x03E9)	A string property value exceeds the maximum allowed size (usually 256 characters).
DTSMSMQ_E_   IncorrectDataFileMessageRead	1020 (x03FC)	The length of a data file message differs from the expected length.
DTSMSMQ_E_   IncorrectGlobalVariablesMessageRead	1025 (x0401)	An error occurred creating the global variable that is to receive a global variables message.
DTSMSMQ_E_   IncorrectMSMQMessageType	1007 (x03EF)	The message type specified by the MessageType or ReceiveMessageType properties is not valid.
DTSMSMQ_E_   IncorrectStringCompareType	1003 (x03EB)	The comparison type specified by the StringCompareType property is not valid.
DTSMSMQ_E_   IncorrectTaskType	1002 (x03EA)	The task type specified by the TaskType property is not valid.
DTSMSMQ_E_   IncorrectTimeoutValue	1004 (x03EC)	The timeout value specified by the ReceiveMessageTimeout property is not valid (negative).
DTSMSMQ_E_   InvalidAssignmentIndexVariantType	1005 (x03ED)	The index specified by the Item or Remove method of the DTSMQMessages collection is not valid.
DTSMSMQ_E_   InvalidGlobalVariablesProperties	1024 (x0400)	An error occurred formatting the global variables message to be sent.
DTSMSMQ_E_   InvalidTaskProperties	1022 (x03FE)	A property required for the type of message to be received was not specified.
DTSMSMQ_E_   MessageQueueObjectsNotSupported	1012 (x03F4)	An error occurred creating a Message Queuing object. Message Queuing was probably not properly installed.
DTSMSMQ_E_   NoMessageCollectionsFound	1011 (x03F3)	The DTSMQMessages collection does not exist or contains zero elements.
DTSMSMQ_E_   NoMessageQueuePathSpecified	1013 (x03F5)	The required QueuePath property was not specified.
DTSMSMQ_E_OutOfMemory	1018 (x03FA)	A memory allocation for character string data failed.
DTSMSMQ_E_   ReceiveMessageTimeout	1026 (x0402)	The timeout value specified by the ReceiveMessageTimeout property has elapsed, the task is being failed.
See Also

DTSMessageQueueTask Object


DTSPackageError

The DTSPackageError constants specify codes used to report errors in Data Transformation Services (DTS) package creation and execution.

Constant	Value	Description
DTSPackage_E_   AbandonedRowQueueDest	1076 (x0434)	This Step2 object has a DataPumpTask2 RowQueue destination. A corresponding Step2 object with a DataPumpTask2 RowQueue source was not found or was skipped.
DTSPackage_E_   AxScript_BadFunctionName	1020 (x03FC)	Microsoft® ActiveX® scripting: Function not found.
DTSPackage_E_   AxScript_CantAddGlobals	1021	ActiveX scripting: Cannot add global variables to ActiveX script.
DTSPackage_E_   AxScript_CantInitializeEngine	1017	ActiveX scripting: Not able to initialize the script execution engine.
DTSPackage_E_   AxScript_ParseError	1019	ActiveX scripting: Error parsing script.
DTSPackage_E_   AxScript_RequiredParams	1018	ActiveX scripting:  Language, and FunctionEntry names are required to be specified.
DTSPackage_E_   AxScript_RunTimeError	1022	ActiveX scripting: Encountered a run-time error during the execution of the script.
DTSPackage_E_BadForceMode	1065	Invalid DTSForceMode value.
DTSPackage_E_BadGUIDValue	1038	Invalid globally unique identifier (GUID) value specified.
DTSPackage_E_   BadPackageDSORowsetTask	1075	PackageDSORowset Step2 object must have a DataPumpTask2.
DTSPackage_E_   BadPrecedenceBasis	1026	Precedence basis should be step status or result.
DTSPackage_E_   BadPrecedenceStep	1036	Step specified in a precedence constraint was not found.
DTSPackage_E_BadPriorityClass	1042	Invalid priority class specified for the package.
DTSPackage_E_   BadRelativePriority	1043	Invalid relative priority specified for a step.
DTSPackage_E_   BadStepResultValue	1024	Invalid step result value.
DTSPackage_E_   BadStepStatusValue	1023	Invalid step status value.
DTSPackage_E_BadStepTask	1027	Cannot find task associated with step.
DTSPackage_E_   BadTaskResultValue	1025	Invalid task result value.
DTSPackage_E_   CannotFindConnection	1031	Connection specified in a task was not found.
DTSPackage_E_   CannotPersistProperty	1062	Cannot store property values in file or repository if they are empty, null, arrays, or objects.
DTSPackage_E_   CantChangeLoadedPkgName	1060	Cannot change name of a package that has been loaded from a storage file or Microsoft SQL Server™ 2000 Meta Data Services.
DTSPackage_E_   CantFindPackageInStg	1044	Cannot find specified package in the storage location specified.
DTSPackage_E_   CantFindVersionInStg	1040	Cannot find specified version of package in the storage location specified.
DTSPackage_E_   CantSetCommandProps	1041	Cannot set command properties specified.
DTSPackage_E_   ColumnNeedsNameOrOrdinal	1007	Columns collection can be indexed only by name or ordinal.
DTSPackage_E_   ColumnsNotDescribed	1014	Unable to fetch column meta data.
DTSPackage_E_ConnectionInUse	1030	Connection is currently being used by a task. The connection cannot be closed or reused.
DTSPackage_E_   ConnectionRequiresValidTaskName	1029	Acquiring a connection requires a valid task name.
DTSPackage_E_   CreateProcTask_Timeout	1037	Process created by a task did not terminate within the time specified.
DTSPackage_E_   DataDrivenQueryTask_   RequireXforms	1077	DataDrivenQueryTask2 object requires transformations to be specified.
DTSPackage_E_   DatatypeNotFound	1009	Invalid column data type.
DTSPackage_E_   DescribeNeedsQuery	1013	Custom implementation object's query property must be set before the columns can be described.
DTSPackage_E_   DSO_CantRelaunchPackage	1073	Package associated with this OLE DB provider cannot be relaunched.
DTSPackage_E_   DSO_OnlyOneCommand	1074	This OLE DB provider supports only a single active command.
DTSPackage_E_   DSO_OnlyOneRowset	1071	This OLE DB provider supports only a single active rowset.
DTSPackage_E_   DSO_OnlyOneSession	1070	This OLE DB provider supports only a single active session.
DTSPackage_E_   DSO_ProviderStringRequired	1072	This OLE DB provider requires a PROVIDERSTRING or DATASOURCE initialization property to be set.
DTSPackage_E_   EncryptStg_CantCreateOrWrite	1045	Cannot create storage elements or write to streams while loading encrypted package.
DTSPackage_E_   EncryptStg_CantOpenOrRead	1046	Cannot open storage elements or read from streams while saving encrypted package.
DTSPackage_E_   EncryptStg_HandsOnStg	1047	Encrypted storage cannot be released, committed, or reverted when elements in storage have not been released.
DTSPackage_E_   EncryptStg_   PasswordNotMatching	1049	Password specified does not match the owner or operator password.
DTSPackage_E_   EncryptStg_RequirePassword	1050	Cannot load encrypted package without a password.
DTSPackage_E_   EncryptStg_StreamTooLarge	1051	Encrypted streams cannot exceed a size of 128 KB.
DTSPackage_E_   EncryptStg_UnsupportedFlags	1048	Encrypted storage does not support the flags specified to open or create a storage element.
DTSPackage_E_   ExecutionCanceled	1063	Execution was canceled by user.
DTSPackage_E_   FailedOnStepError	1064	Package failed because a step failed.
DTSPackage_E_   MultiPackageStgNeedsID	1066	Specified storage file contains multiple packages; loading requires a name or package ID.
DTSPackage_E_NameDup	1004	Object of the specified name already exists in this object collection so a new object of the same name cannot be added.
DTSPackage_E_   NameMustBeUniqueInStgFile	1067	Specified storage file already contains a package of this name with a different package ID.
DTSPackage_E_NameNotFound	1003	Object of specified name was not found in this object collection.
DTSPackage_E_   NeedConnectionInfo	1010	Connection information was not specified in the custom implementation child of this object.
DTSPackage_E_   NeedDataDrivenQueries	1078	DataDrivenQueryTask2 object requires at least one query (and associated columns) to be specified.
DTSPackage_E_   NeedDataDrivenQueryAndColumns	1079	Data-driven queries must specify the text of the parameterized query and identify any columns (in the associated columns collection) needed to fill in the parameters.
DTSPackage_E_   NeedDestinationColumnDefinitions	1069	Required column definitions were not supplied by the application.
DTSPackage_E_   NoPackageDataFromServer	1068	No data for the specified package was retrieved from the specified server running an instance of SQL Server.
DTSPackage_E_NoStepsDefined	1005	No steps have been defined for the transformation package.
DTSPackage_E_   NoStepsToExecute	1012	No steps have been added.
DTSPackage_E_   NotImplemented	1001	Method or property not yet implemented.
DTSPackage_E_NoXformDispatch	1061	Transformation server does not support setting properties through automation interfaces.
DTSPackage_E_   ODBC_NeedConnectionInfo	1011	ODBC connection requires either a data source name or a server and driver name.
DTSPackage_E_OrdOutofRange	1002	Index value is out of range for this object collection.
DTSPackage_E_   PropertyStringTooLong	1059	This property cannot hold a string longer than 255 characters.
DTSPackage_E_PumpTask_   RequireRowsetDataSrcInfo	1034	Data source object name or SQL statement is required to obtain a rowset.
DTSPackage_E_PumpTask_   RequireSrcAndDestColumns	1033	Source and destination columns are required for a Transformation2 object.
DTSPackage_E_PumpTask_   RequireXformServer	1035	Transform server ID or transform server needs to be provided for a data pump task transformation.
DTSPackage_E_PumpTask_   RequireXforms	1032	Data pump task requires transformations to be specified.
DTSPackage_E_   RequireColumnNameAndOrdinal	1058	Specify a valid name and ordinal value for the column.
DTSPackage_E_   RequireConnectionProperties	1028	Required Connection object properties have not been specified in a Connection object.
DTSPackage_E_   RequireConnectionID	1057	Specify a valid ID for the connection.
DTSPackage_E_   RequireNameForExecOr\Stg	1039	Cannot load, save, or execute the package if some objects do not have a name. Specify names for these objects.
DTSPackage_E_   Security_InvalidPassword	1052	Password specified is invalid. Specify a password that is at least 8 characters in length.
DTSPackage_E_   Security_OperatorNotPrivileged	1054	Operator is privileged only to load the package and execute it.
DTSPackage_E_   Security_RequireBothPasswords	1053	Specify both owner and operator passwords to save a package to encrypted storage.
DTSPackage_E_   SQLTask_RequireSQL	1055	ExecuteSQLTask2 object requires SQL statements to be specified.
DTSPackage_E_   Step_CyclicDependency	1015	Step cannot be a predecessor of itself.
DTSPackage_E_   UnknownOleDBProperty	1056	OLE DB property specified is not supported by this OLE DB provider.
DTSPackage_E_   UsageBeforeDescribeOnly	1016	Reserved.
DTSPackage_E_WrongCollection	1008	Collection member may only be added or inserted under the same parent from which it was acquired.
See Also

Handling DTS Events and Errors

Package2 Object


DTSPackagePriorityClass

The DTSPackagePriorityClass constants specify the Microsoft® Win32® process priority class to be used when the Data Transformation Services (DTS) package is executed.

Constant	Value	Description
DTSPackagePriorityClass_High	3	High package priority
DTSPackagePriorityClass_Low	1	Low package priority
DTSPackagePriorityClass_Normal	2	Normal package priority
See Also

PackagePriorityClass Property


DTSPackageType

The DTSPackageType constants are used with the PackageType property to identify the tool that created the database package.

Name	Value	Package Created By
DTSPkgType_ActiveDirectory	4	Microsoft® Active Directory™, the directory service included with Microsoft Windows® 2000.
DTSPkgType_Default	0	Custom program (or not set).
DTSPkgType_DTSDesigner	2	Data Transformation Services (DTS) Designer.
DTSPkgType_DTSWizard	1	The DTS Import/Export Wizard.
DTSPkgType_SQLReplication	3	Microsoft SQL Server™ 2000 replication function.
See Also

PackageType Property


DTSRepositoryMetadataOptions

The DTSRepositoryMetadataOptions constants specify scanning and resolution options to use when storing a Data Transformation Services (DTS) package to Microsoft® SQL Server™ 2000 Meta Data Services.

Constant	Value	Description
DTSReposMetadata_Default	0	Package performs no scanner resolution.
DTSReposMetadata_   RequireScannedCatalog	1	Package requires that any database objects must have been scanned into Meta Data Services.
DTSReposMetadata_   ScanCatalogAlways	8	Package will scan all catalogs referenced, rescanning if already scanned.
DTSReposMetadata_   ScanCatalogIfNotFound	4	Package will issue a scan on all catalogs that are not found already scanned.
DTSReposMetadata_   UseScannedCatalogIfPresent	2	Package will use any scanned objects found; nonscanned references will create local objects.
See Also

RepositoryMetadataOptions Property


DTSRepositoryStorageFlags

The DTSRepositoryStorageFlags constants specify Microsoft® SQL Server™ 2000 Meta Data Services options to use when saving or loading a Data Transformation Services (DTS) package.

Constant	Value	Description
DTSReposFlag_Default	0	Use database authentication to connect to Meta Data Services on an instance of SQL Server.
DTSReposFlag_   UseTrustedConnection	256	Use Windows Authentication to connect to Meta Data Services on an instance of SQL Server.
See Also

LoadFromRepository Method

RemoveFromRepository Method

SaveToRepository Method

SaveToRepositoryAs Method


DTSSQLObjectType

The DTSSQLObjectType constants specify object copying options for the TransferObjectsTask, AddObjectForTransfer, and GetObjectForTransfer methods.

Constant	Value	Description
DTSSQLObj_AllDatabaseObjects	4607 (x11FF)	System and database objects
DTSSQLObj_   AllDatabaseUserObjects	4605 (x11FD)	User database objects
DTSSQLObj_Default	64 (x0040)	Defaults
DTSSQLObj_Rule	128 (x0080)	Rules
DTSSQLObj_StoredProcedure	16 (x0010)	Stored procedures
DTSSQLObj_SystemTable	2	System tables
DTSSQLObj_Trigger	256 (x0100)	Triggers
DTSSQLObj_UserDefinedDatatype	1	User-defined data types
DTSSQLObj_UserDefinedFunction	4096 (x1000)	User-defined functions
DTSSQLObj_UserTable	8	User tables
DTSSQLObj_View	4	Views
See Also

AddObjectForTransfer Method

GetObjectForTransfer Method


DTSSQLServerStorageFlags

The DTSSQLServerStorageFlags constants specify Microsoft® SQL Server™ 2000 options to use when saving or loading a Data Transformation Services (DTS) package.

Constant	Value	Description
DTSSQLStgFlag_Default	0	Use SQL Server Authentication to connect to an instance of SQL Server.
DTSSQLStgFlag_   UseTrustedConnection	256	Use Windows Authentication to connect to an instance of SQL Server.
See Also

LoadFromSQLServer Method

LogServerFlags Property

RemoveFromSQLServer Method

SaveToSQLServer Method


DTSStepExecResult

The DTSStepExecResult constants specify the results from the execution of a step.

Constant	Value	Description
DTSStepExecResult_Failure	1	Step execution failed.
DTSStepExecResult_Success	0	Step execution succeeded.
See Also

ExecutionResult Property


DTSStepExecStatus

The DTSStepExecStatus constants specify status codes that indicates the current step status.

Constant	Value	Description
DTSStepExecStat_Completed	4	Step execution is completed.
DTSStepExecStat_Inactive	3	Step execution is inactive.
DTSStepExecStat_InProgress	2	Step execution is in progress.
DTSStepExecStat_Waiting	1	Step is waiting to execute.
See Also

ExecutionStatus Property


DTSStepPrecedenceBasis

Steps can be executed after the precedence constraint is satisfied. The precedence constraint is based on either the execution status or execution result of another step. The PrecedenceBasis property indicates whether to use the step result or step status.

Constant	Value	Description
DTSStepPrecedenceBasis_   ExecResult	1	PrecedenceBasis based on execution result
DTSStepPrecedenceBasis_   ExecStatus	0	PrecedenceBasis based on execution status
See Also

PrecedenceBasis Property


DTSStepRelativePriority

The DTSStepRelativePriority constants specify the Microsoft® Win32® thread priority to be used when a step is executed.

Constant	Value	Description
DTSStepRelativePriority_   AboveNormal	4	Above normal thread priority
DTSStepRelativePriority_   BelowNormal	2	Below normal thread priority
DTSStepRelativePriority_Highest	5	Highest thread priority
DTSStepRelativePriority_Lowest	1	Lowest thread priority
DTSStepRelativePriority_Normal	3	Normal thread priority
See Also

RelativePriority Property


DTSStepScriptResult

The DTSStepScriptResult constants specify return codes to be used from the Microsoft® ActiveX® scripts associated with package steps. They should not be returned from the scripts associated with an ActiveXScriptTask object or DataPumpTransformScript or DTSTransformScriptProperties2 transformations.

Constant	Value	Description
DTSStepScriptResult_   DontExecuteTask	1	Do not execute task.
DTSStepScriptResult_ExecuteTask	0	Execute task.
DTSStepScriptResult_RetryLater	2	Retry execution later.
See Also

ActiveXScript Property

Step2 Object


DTSTaskExecResult

The DTSTaskExecResult constants specify the result from the execution of a task.

Constant	Value	Description
DTSTaskExecResult_Failure	1	Task execution failed.
DTSTaskExecResult_RetryStep	2	Task execution is to be repeated.
DTSTaskExecResult_Success	0	Task execution succeeded.
See Also

Execute Method


DTSTransfer_CopyDataOption

The DTSTransfer_CopyDataOption constants specify data copying options for the TransferObjectsTask CopyData property.

Constant	Value	Description
DTSTransfer_AppendData	2	Data that is copied is appended to existing tables.
DTSTransfer_DontCopyData	0	Schema only is copied.
DTSTransfer_ReplaceData	1	Data that is copied replaces existing data.
See Also

CopyData Property


DTSTransfer_ScriptOption

The DTSSQLServerStorageFlags constants specify extended scripting options. They are equivalent to SQLDMO_SCRIPT2_TYPE constants used by SQL-DMO.

The DTSTransfer_ScriptOption constants specify scripting options for the TransferObjectsTask ScriptOption property.

Constant	Value	Description
DTSTransfer_Script_Aliases	16384	For users, script aliases.
DTSTransfer_Script_   AppendToFile	256	Append to output file if it already exists.
DTSTransfer_Script_Bindings	128	Include rule/default bindings (table only).
DTSTransfer_Script_   ClusteredIndexes	8	Include clustered index creation (table only).
DTSTransfer_Script_   DatabasePermissions	32	Database (statement) permissions.
DTSTransfer_Script_Default	4	Object creation only.
DTSTransfer_Script_DRI_All	532676608	All the foregoing (specifying this and not PrimaryObject gets just DRI output).
DTSTransfer_Script_   DRI_AllConstraints	520093696	Bitmask of all constraint types (primary key, foreign key, unique, check, default).
DTSTransfer_Script_DRI_   AllKeys	469762048	Bitmask of all key types (primary key, foreign key, unique).
DTSTransfer_Script_DRI_   Checks	16777216	Generated script creates column-specified CHECK constraints. Directs scripting when declarative referential integrity establishes dependency relationships. Applies only when scripting references a Microsoft SQL Server™ table.
DTSTransfer_Script_   DRI_Clustered	8388608	Generated script creates clustered indexes. Directs scripting when declarative referential integrity establishes dependency relationships. Applies only when scripting references a SQL Server table.
DTSTransfer_Script_   DRI_Defaults	33554432	Generated script includes column-specified defaults. Directs scripting when declarative referential integrity establishes dependency relationships. Applies only when scripting references a SQL Server table.
DTSTransfer_Script_   DRI_ForeignKeys	134217728	Generated script creates FOREIGN KEY constraints. Directs scripting when declarative referential integrity establishes dependency relationships. Applies only when scripting references a SQL Server table.
DTSTransfer_Script_   DRI_NonClustered	4194304	Generated script creates nonclustered indexes. Directs scripting when declarative referential integrity establishes dependency relationships. Applies only when scripting references a SQL Server table.
DTSTransfer_Script_   DRI_PrimaryKey	268435456	Generated script creates PRIMARY KEY constraints. Directs scripting when declarative referential integrity establishes dependency relationships. Applies only when scripting references a SQL Server table.
DTSTransfer_Script_   DRI_UniqueKeys	67108864	Generated script creates candidate keys defined using a unique index. Directs scripting when declarative referential integrity establishes dependency relationships. Applies only when scripting references a SQL Server table.
DTSTransfer_Script_   DRIIndexes	65536	Script DRI-generated indexes as indexes if NoDRI is specified.
DTSTransfer_Script_   DRIWithNoCheck	536870912	Script DRI with nocheck (not included in _DRI_All).
DTSTransfer_Script_Drops	1	Include object drops.
DTSTransfer_Script_   IncludeHeaders	131072	Include descriptive header in individual object script output.
DTSTransfer_Script_   IncludeIfNotExists	4096	Include "if not exists" on object creation.
DTSTransfer_Script_Indexes	73736	Include all index creation (table only).
DTSTransfer_Script_   NoCommandTerm	32768	Do not append "GO" to commands.
DTSTransfer_Script_NoDRI	512	Do not include DRI (use only if you are targeting a Microsoft SQL Server version 6.0 or earlier installation with scripts).
DTSTransfer_Script_NoIdentity	1073741824	Script with no IDENTITY attribute (such as for replication).
DTSTransfer_Script_   NonClusteredIndexes	8192	Includes nonclustered index creation (table only).
DTSTransfer_Script_   ObjectPermissions	2	Includes object creation.
DTSTransfer_Script_   OwnerQualify	262144	Owner-qualify DROP statements (and CREATE where possible).
DTSTransfer_Script_   Permissions	34	Both database and object permissions (for scripting users).
DTSTransfer_Script_   PrimaryObject	4	Generate Transact-SQL creating the referenced component.
DTSTransfer_Script_SortedData	1048576	If the index or constraint was clustered, append sorted_data.
DTSTransfer_Script_   SortedDataReorg	2097152	Same as DTSTransfer_Script_SortedData, but DTSTransfer_Script_Sorted Data Reorg is used to preserve fillfactor.
DTSTransfer_Script_   TimestampToBinary	524288	Converts timestamp columns to binary(8) (for replication, and so on).
DTSTransfer_Script_ToFileOnly	64	If not set, a string is returned (if file is nonnull, both are done).
DTSTransfer_Script_   TransferDefault	2147061505	The default script type for a transfer. This is combination of following flags DTSTransfer_Script_PrimaryObject DTSTransfer_Script_Bindings DTSTransfer_Script_ClusteredIndexes DTSTransfer_Script_NonClusteredIndexes                                                          DTSTransfer_Script_Triggers DTSTransfer_Script_ToFileOnly DTSTransfer_Script_Permissions DTSTransfer_Script_IncludeHeaders DTSTransfer_Script_Aliases DTSTransfer_Script_IncludeIfNotExists DTSTransfer_Script_OwnerQualify DRI-restrictive flags. These may be combined with PrimaryObject as desired. These are used to include or exclude specific DRI components.
DTSTransfer_Script_Triggers	16	Include trigger creation (table only).
DTSTransfer_Script_   UDDTsToBaseType	1024	Converts user-defined data types to base type when creating columns (table only).
DTSTransfer_Script_   UseQuotedIdentifiers	2147483648	Scripts with quoted identifiers. Also will cause the Transfer object to SET QUOTED_IDENTIFIER ON on the destination.
See Also

ScriptOption Property


DTSTransfer_ScriptOptionEx

The DTSTransfer_ScriptOptionEx constants specify extended scripting options. They are equivalent to SQLDMO_SCRIPT2_TYPE constants used by SQL-DMO.

Constant	Value	Description
DTSTransfer_ScriptEx_70Only	16777216 (x01000000)	Script the transfer of Microsoft® SQL Server™ 7.0 objects only.
DTSTransfer_ScriptEx_   AgentAlertJob	2048 (x0800)	Include job in alert scripting.
DTSTransfer_ScriptEx_   AgentNotify	1024 (x0400)	Script notification for SQLServerAgent alert object.
DTSTransfer_ScriptEx_AnsiFile	2	Generate ANSI output file.
DTSTransfer_ScriptEx_   AnsiPadding	1	Explicitly SET ANSI PADDING on or off before the CREATE TABLE statement.
DTSTransfer_ScriptEx_   EncryptPWD	128 (x0080)	Script encrypted password for logins.
DTSTransfer_ScriptEx_   ExtendedProperty	4194304 (x00400000)	Include extended property scripting as part of object scripting
DTSTransfer_ScriptEx_   FullTextCat	2097152 (x00200000)	Include full-text catalog scripting.
DTSTransfer_ScriptEx_   FullTextIndex	524288 (x00080000)	Include full-text index scripting (table only).
DTSTransfer_ScriptEx_   JobDisable	33554432 (x02000000)	Script Transact-SQL to disable the job at the end of job creation.
DTSTransfer_ScriptEx_   LoginSID	1048576 (x00100000)	Include the security identification number (SID) for standard SQL Server logins.
DTSTransfer_ScriptEx_   MarkTriggers	32 (x0020)	Mark system triggers. For replication, single table script only.
DTSTransfer_ScriptEx_   NoCollatin	8388608 (x00800000)	Do not script the collation clause if source is an instance of SQL Server 2000.
DTSTransfer_ScriptEx_NoFG	16 (x0010)	Do not generate ON <filegroup>. For replication.
DTSTransfer_ScriptEx_   NonStop	8	When error occurs during script file generation, log error and continue.
DTSTransfer_ScriptEx_   NoWhatIfIndexes	512 (x0200)	Do not script What-If indexes (default: script out).
DTSTransfer_ScriptEx_   OnlyUserTriggers	64 (x0040)	Only script user triggers. For replication, single table script only.
DTSTransfer_ScriptEx_   SeparateXPs	256 (x0100)	Script XP to a separate file (Convert).
DTSTransfer_ScriptEx_   TransferDefault	4112 (x1010)	Default.
DTSTransfer_ScriptEx_   UnicodeFile	4	Generate UNICODE output file.
See Also

ScriptOptionEx Property


DTSTransformationSetOptions

The DTSTransformationSetOptions constants specify the operating mode of a Parallel Data Pump Task object.

Constant	Value	Description
DTSTranSetOpt_Flattened	0	Transforms component rowsets independently without reference to chapter subsets (default).
DTSTranSetOpt_Hierarchical	1	Transforms component rowsets row at a time, using chapter subsets to transform child rowsets.
DTSTranSetOpt_   DataDrivenQueries	4	Transforms component rowset as in flattened-mode, user queries to save data.
See Also

Parallel Data Pump Task

TransformationSetOptions Property


DTSTransformFlags

The DTSTransformFlags constants specify the flags controlling transformation. They are used to set the TransformFlags property of the Transformation object. These values are used during schema validation, which occurs before any rows are transformed.

Constant	Value	Description
DTSTransformFlag_   AllowDemotion	1	Allows the transfer to proceed even if there are potential overflows. Overflows that actually occur during transformation cause the row to be exceptioned. This value can be specified when the source values are all (or mostly) within the range of the destination column.
DTSTransformFlag_   AllowLosslessConversion	512 (x0200)	Allows all conversions for which a lossless conversion is possible (for example, Promotion, non-NULLable -> NULLable, unsigned -> signed with field size increase).
DTSTransformFlag_   AllowNullChange	16 (x0010)	Allows the transfer to proceed even if the source column allows NULL values and the destination column does not. Any row actually containing NULL is exceptioned, however.
DTSTransformFlag_   AllowNumericTruncation	8	Allows the transfer to proceed even when numeric truncation is possible, such as when the source is a floating-point or numeric/decimal type and the destination is an integral type. Loss of significance occurs without error, but integer overflow still causes an error.
DTSTransformFlag_   AllowPromotion	2	Allows 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.
DTSTransformFlag_   AllowSignChange	32 (x0020)	Allows the transfer to proceed even in the event that the source and destination have a signed versus unsigned mismatch. As with DTSTransformFlag_AllowDemotion, errors may occur during a transform.
DTSTransformFlag_   AllowStringTruncation	4	Allows column (w)char or byte data to be truncated silently (for example, when moving data from a char(60) to a char(40) column).
DTSTransformFlag_Default	63 (x003F)	Includes the default flag combination of DTSTransformFlag_AllowDemotion, DTSTransformFlag_AllowNullChange, DTSTransformFlag_AllowNumericTruncation, DTSTransformFlag_AllowPromotion, DTSTransformFlag_AllowSignChange and DTSTransformFlag_AllowStringTruncation.
DTSTransformFlag_   ForceConvert	128 (x0080)	Allows the conversion to proceed at all times, even when the source and destination types are fundamentally different. Does a bitwise copy when no other conversion is appropriate.
DTSTransformFlag_   PreserveDestRows	256 (x0100)	Causes the data pump to not clear the destination row storage at the end of row processing. This allows the destination row values to be reused by the next transformation.
DTSTransformFlag_   RequireExactType	64 (x0040)	Requires that the data type of the destination column be exactly the same as the data type of the source column (including length or precision and scale, fixed versus variable length, sign, and nullability).
DTSTransformFlag_Strict	0	Specifies no flags; the conversion must be between exact types, although conversions between string and nonstring datatypes is allowed and may cause errors. This value may be overridden by DTSTransformFlag_RequireExactType, which is even stricter.
See Also

Transformation2 Object

TransformFlags Property


DTSTransformPhaseEnum

The DTSTransformPhaseEnum constants specify the available Data Transformation Services (DTS) data pump transformation phases.

Constant	Value	Description
DTSTransformPhase_All	255 (x00FF)	Bitmask for all transform phases.
DTSTransformPhase_None	0	Specifies no phases.
DTSTransformPhase_   OnBatchComplete	64 (x0040)	Occurs after a fast load batch completes, on success or failure.
DTSTransformPhase_   OnInsertFailure	32 (x0020)	Occurs after an Insert operation or a data driven query fails.
DTSTransformPhase_   OnInsertSuccess	16 (x0010)	Occurs after an Insert operation or a data driven query succeeds.
DTSTransformPhase_   OnPumpComplete	128 (x0080)	Occurs once at end of Data Transformation Services (DTS) data pump operation.
DTSTransformPhase_   OnTransformFailure	8	Occurs after transformation fails (for example, a conversion error).
DTSTransformPhase_   PostSourceData	2	Occurs after all source rows processed.
DTSTransformPhase_   PreSourceData	1	Occurs before first source row processed.
DTSTransformPhase_Transform	4	Occurs after source row is fetched, performs the primary transformation processing.
See Also

CurrentPhase Property

TransformPhases Property


DTSTransformStatus

The DTSTransformStatus constants return values (int or long) from the ActiveXScriptTask object transformation.

Constant	Value	Description
DTSTransformStat_AbortPump	16384 (x4000)	Processing is terminated with the current row and DTSTransformExec_AbortPump is returned from IDTSDataPump::Execute.
DTSTransformStat_DeleteQuery	64 (x0040)	The executed DELETE statement is passed to the SetRowsetAndQueries property on the destination, with values from the currently transformed destination row.
DTSTransformStat_   DestDataNotSet	512 (x0200)	The current row is not written to the destination only if all transformations return this value. If present in the returned status of a transformation, it is removed before being passed to the next transformation through DTSTransformPhaseInfo.TransformStatus.
DTSTransformStat_Error	8192 (x2000)	Indicates the transformation encountered an error.
DTSTransformStat_ErrorSkipRow	8194 (x2002)	Terminate further processing of this row due to error and call the error sink, but do not write to exception file.
DTSTransformStat_ExceptionRow	8448 (x2100)	Terminate further processing of this row as an exception and call the error sink, and write this row to exception file.
DTSTransformStat_Info	4096 (x1000)	Success with additional information, which the application can process further by reading its pvTransformUserData value (if it shares that knowledge with the transform server) or through OLE DB error records.
DTSTransformStat_InsertQuery	16 (x0010)	Executes the INSERT statement passed to the SetRowsetAndQueries property on the destination, with values from the currently transformed destination row.
DTSTransformStat_NoMoreRows	32768 (x8000)	The current row is the last to be processed. The current row is processed as specified by other transformation status values. This value differs from DTSTransformStat_AbortPump in that no error is raised.
DTSTransformStat_OK	1	Default conversions (if any) succeeded. Write the row to destination if specified, without calling any error handlers.
DTSTransformStat_OKInfo	4097 (x1001)	Write row if destination specified; also call ErrorSink with information.
DTSTransformStat_SkipFetch	4	Do not fetch the next row; reexecute all transforms against the current source and destination rows.
DTSTransformStat_SkipInsert	8	Do not write the current row to the destination.
DTSTransformStat_SkipRow	2	Terminate further processing of this row, for nonerror reasons.
DTSTransformStat_SkipRowInfo	4098 (x1002)	Terminate further processing of this row, and call ErrorSink with information.
DTSTransformStat_UpdateQuery	32 (x0020)	Executes the UPDATE statement passed to the SetRowsetAndQueries property on the destination, with values from the currently transformed destination row.
DTSTransformStat_UserQuery	128 (x0080)	Executes the user query statement passed to SetRowsetAndQueries on the destination, with values from the currently transformed destination row.
See Also

IDTSDataPumpErrorSink


DynamicPropertiesTaskError

The DynamicPropertiesTaskError constants specify codes used to report errors in DynamicPropertiesTask object execution.

Constant	Value	Description
DTSDynamicProperties_E_   AssignmentIndexOutOfRange	1005 (x03ED)	An index for the Assignments collection is out of range.
DTSDynamicProperties_E_   ConnectionIdNotFoundInPackage	1009 (x03F1)	No Connection2 object with the specified ConnectionID was found.
DTSDynamicProperties_E_   CouldNotOpenFileForReading	1012 (x03F4)	The data file specified as the property value source could not be opened for reading.
DTSDynamicProperties_E_   EnvironmentVariableNotFound	1015 (x03F7)	The environment variable specified as the property value source could not be found.
DTSDynamicProperties_E_   ExceededMaximumPropertySize	1016 (x03F8)	The length of a string property value exceeds the maximum (256 characters).
DTSDynamicProperties_E_   GlobalVariableNotFoundInPackage	1013 (x03F5)	The global variable specified as the property value source does not exist in the package.
DTSDynamicProperties_E_   InvalidAssignmentIndexVariantType	1018 (x03FA)	The Variant specified for an Assignments collection index does not have a type valid for that purpose.
DTSDynamicProperties_E_   InvalidSourceType	1002 (x03EA)	The value specified for the SourceType property is not defined.
DTSDynamicProperties_E_   KeyNotFound	1006 (x03EE)	The key specified as the property value source could not be found in the .ini file.
DTSDynamicProperties_E_   NoEnvironmentVariableProvided	1014 (x03F6)	No environment variable was specified as the property value source, although one was required.
DTSDynamicProperties_E_   NoFileNameProvided	1003 (x03EB)	No data file name was specified as the property value source, although one was required.
DTSDynamicProperties_E_   NoGlobalVariableProvided	1008 (x03F0)	No global variable was specified as the property value source, although one was required.
DTSDynamicProperties_E_   NoKeyProvided	1007 (x03EF)	No .ini file key was specified as the property value source, although one was required.
DTSDynamicProperties_E_   NoPropertyValueProvided	1011 (x03F3)	No property value could be retrieved from the .ini file.
DTSDynamicProperties_E_   NoRowsReturnedFromQuery	1010 (x03F2)	No rows were returned from the query that was the property value source.
DTSDynamicProperties_E_   NoSectionProvided	1004 (x03EC)	No .ini file section was specified, although one was required.
DTSDynamicProperties_E_   PackagePropertyNotFound	1001 (x03E9)	The specified package property whose value was to be changed is not defined.
DTSDynamicProperties_E_   SectionNotFound	1005 (x03ED)	The specified section could not be found in the .ini file.
See Also

DynamicPropertiesTask Object


DynamicPropertiesTaskSourceType

The DynamicPropertiesTaskSourceType constants are used with the SourceType property to specify the type of source object that provides the value to which a Data Transformation Services (DTS) package object property will be set by the DynamicPropertiesTask object.

Symbol	Value	Description
DTSDynamicPropertiesSource   Type_Constant	4	Source is a constant.
DTSDynamicPropertiesSource   Type_DataFile	5	Source is the contents of a data file.
DTSDynamicPropertiesSource   Type_EnvironmentVariable	3	Source is the value of a system environment variable.
DTSDynamicPropertiesSource   Type_GlobalVariable	2	Source is the value of a Data Transformation Services (DTS) global variable within the package.
DTSDynamicPropertiesSource   Type_IniFile	0	Source is the value of a key within an .ini file.
DTSDynamicPropertiesSource   Type_Query	1	Source is a value returned by an SQL query.
See Also

SourceType Property


Data Pump Interfaces

The Microsoft® SQL Server™ 2000 Data Transformation Services (DTS) data pump is an OLE DB provider that provides the interfaces and methods to import, export, and transform data from an OLE DB data source to an OLE DB destination. The DTS data pump is the engine of the Transform Data task, Data Driven Query task, and Parallel Data Pump task, which is accessed through the ParallelDataPumpTask object.

These tasks create rowsets on the source and destination connections, then create an instance of the data pump to move rows between the source and destination rowsets. They also add instances of transformations to the data pump instance, transforming individual row data as it is moved from source to destination.

The data pump provides an extensible COM-based architecture that allows custom applications to perform complex data validations and transformations as data moves from source to destination. Third-party applications can also extend the data pump by creating custom COM objects that implement the IDTSDataPumpTransform interface to make use of the full power of Microsoft Win32® and COM. This allows an application to avoid the overhead of converting native data types to OLE DB variant data types and then converting them back again.

Data pump interfaces are implemented using Microsoft Visual C++® applications that include Dtspump.h.

Using the Data Pump Interfaces

An application must call IDTSDataPump interface methods in order. For example, these methods must be called in the following order:

1.	SetRowsets

2.	AddTransform

3.	Execute

Other methods on the interface may be called in any order prior to a call to the Execute method. Because the data pump represents a single execute operation, the data pump is not reentrant within calls. It returns an error if it is called as though it were reentrant.

Calls to IDTSDataPump result in calls to the IDTSDataPumpTransform interfaces in the following sequence:

1.	Create an instance of the transformation server object and associated properties, if necessary.

2.	Call IDTSDataPump::AddTransform.

3.	Call IPersistPropertyBag::Load, if IPropertyBag is specified.

4.	Call IDTSDataPumpTransform::Initialize.

5.	Call IDTSDataPumpTransform::AddVariable ("DTSErrorRecords").

6.	Call IDTSDataPumpTransform::ValidateSchema.

7.	Call IDTSDataPump::Execute.

8.	Call IDTSDataPumpTransform::AddVariable, including any object except DTSErrorRecords.

9.	Call IDTSDataPumpTransform::Execute.


IDTSDataPump

The IDTSDataPump interface is used to specify OLE DB source and destination rowsets to be used, add transformations to the data pump, and execute the transfer of data by the data pump.

The AddTransform method returns an error if IDTSDataPump::SetRowsets has not been called, and IDTSDataPump::SetRowsets returns an error if any transformations have been added due to the IDTSDataPumpTransform::ValidateSchema method having been executed against them previously. IDTSDataPump::InitNew reinitializes the IDTSDataPump object.


IDTSDataPump::AddTransform

The AddTransform method adds a transformation to the data pump.

Syntax

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.
Remarks

The data pump calls CoCreateInstance on the transformation object specified by ServerClsid. The transformation 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 QueryInterface. 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 CLSID of the transformation server as a CLSID, ProgID, or as an existing IUnknown object implementing the IDTSDataPumpTransform interface.

pIStorage is used to set the properties of the transformation server, 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.

See Also

DTSTransformFlags


IDTSDataPump::AddTransformVariable

The AddTransformVariable method allows the data pump consumer to pass its global variables through to the executing transformation server.

Syntax

HRESULT AddTransformVariable(
LPCOLESTR pwzName,
BOOL bGlobal,
VARIANT Variable );

Argument	Description
pwzName [in]	Variable name
bGlobal [in]	For Microsoft® ActiveX® scripts, indicates whether this variable's methods must be qualified by the object name
Variable [in]	Variable value, passed to and updatable by the transformation
Remarks

This method results in a call to IDTSDataPumpTransform::AddVariable during IDTSDataPump::Execute initialization, before transformations are actually executed. The data pump itself does not operate on these variables, but simply passes them through. If bGlobal is TRUE for an ActiveX script, then the methods of this variable are considered global and can be called directly, without qualifying by object name.


IDTSDataPump::Execute

The Execute method executes the data pump and any transformations that have been defined.

Syntax

HRESULT Execute (
LPBYTE pvUserData,
ULARGE_INTEGER *puliRowsComplete,
ULONG *pulErrorRows,
LPDTSExecuteStatus pExecStatus );

Argument	Description
pvUserData [in]	User data passed back to event and error sinks
*puliRowsComplete [out]	Total number of source rows processed, including those skipped
*pulErrorRows [out]	Total number of error rows encountered
pExecStatus [out]	Pump return status
Remarks

Control is not returned to the caller until the last row has been processed or the data pump fails. Calls to the Execute method of each transformation server are made for each row in the order in which the transformations were added. Structured exception handling is placed around each call. If the called server returns an exception (for example, an access violation), an error is reported. The data pump reports all errors through the IDTSDataPumpErrorSink::OnTransformError event.

The Execute method returns DTSExecuteStatus constant values. Execute returns E_FAIL if it is terminated; DB_E_ERRORSOCURRED if the maximum error count is exceeded; DB_S_ERRORSOCCURRED if errors occurred, but the maximum error count is not exceeded; and NOERROR if it completes with no errors.

See Also

DTSExecuteStatus

IDTSDataPumpErrorSink::OnTransformError


IDTSDataPump::GetRowsets

The GetRowsets method is used to return interface pointers to the current source rowset and destination rowsetchange object.

Syntax

HRESULT GetRowsets (
IRowset **ppSrcRowset,
IRowsetChange **ppDestRowsetChange );

Argument	Description
**ppSrcRowset [out]	Variable to receive a pointer to the source rowset
**ppDestRowsetChange [out]	Variable to receive a pointer to the destination rowsetchange object
Remarks

GetRowsets allows a consumer application to reuse an instance of the data pump.


IDTSDataPump::InitNew

The InitNew method is used to reset the data pump between successive executions.

Syntax

HRESULT InitNew();


IDTSDataPump::SetFetchBufferSize

The SetFetchBufferSize method specifies the size of the buffer that the data pump uses to hold rows fetched from the source using the OLE DB IRowset::GetNextRows method.

Syntax

HRESULT SetFetchBufferSize (
ULONG cIn );

Argument	Description
cIn [in]	Size of the GetNextRows HROW buffer
Remarks

The default buffer size is 1.


IDTSDataPump::SetInsertCommitSize

The SetInsertCommitSize method specifies the number of rows inserted at a data destination between commit operations.

Syntax

HRESULT SetInsertCommitSize (
ULONG cIn );

Argument	Description
cIn [in]	Number of successful rows inserted between commit operations, if supported by the OLE DB provider.
Remarks

The SetInsertCommitSize default setting is 0.


IDTSDataPump::SetMaximumErrorRowCount

The SetMaximumErrorRowCount method specifies the maximum number of errors that can occur before the data pump fails.

Syntax

HRESULT SetMaximumErrorRowCount (
ULONG cIn );

Argument	Description
cIn [in]	Maximum number of allowable error rows
Remarks

By default, the data pump fails on the first error.


IDTSDataPump::SetProgressRowCount

The SetProgressRowCount method specifies how often notifications should be sent using the connection point.

Syntax

HRESULT SetProgressRowCount (
ULONG cIn );

Argument	Description
cIn [in]	Number of rows inserted between progress notifications
Remarks

If no event sink has been created, then no notifications are sent. If an event sink exists and SetProgressRowCount is not called, progress notifications are sent every 1000 rows.


IDTSDataPump::SetRowsets

The SetRowsets method specifies the source and destination rowsets to be used by the data pump.

Syntax

HRESULT SetRowsets (
IRowset *pSrcRowset,
IRowsetChange *pDestRowsetChange );

Argument	Description
*pSrcRowset [in]	Pointer to the source rowset
*pDestRowsetChange [in]	Pointer to the destination rowset
Remarks

The consumer application must open the rowsets before the data pump can use them.

The OLE DB provider must support DBPROP_UPDATABILITY: DPBROP_UP_INSERT.


IDTSDataPump2

The IDTSDataPump2 interface extends the IDTSDataPump interface and supports features added to the Data Transformation Services (DTS) data pump for Microsoft® SQL Server™ 2000. The new features supported by IDTSDataPump2 are:

•	Support for execution of a single row or set of rows.

•	Support for processing rows on a different thread from which previous rows in the rowset were processed.

•	Support for multiphased operation of transformation servers


IDTSDataPump2::AddTransform2

The AddTransform method adds a new Transform with extended multiphase capability to the data pump.

Syntax

HRESULT AddTransform2(
LPCOLESTR pwzName,
LPBYTE pvUserData,
LPCDTSTransformColumnsSpecification pColumns,
DTSGuid ServerClsid,
VARIANT ServerParameters,
DTSTransformFlags dwFlags,
DTSTransformPhaseEnum ePhases,
IStorage *pIStorage );

Argument	Description
pwzName [in]	Transformation name
pvUserData [in]	Data that is passed to the event sink if an event occurs during a transformation
pColumns [in]	Structure specifying source and destination columns
ServerClsid [in]	ProgID or CLSID of transformation, which can be Iunknown
ServerParameters [in]	Server parameters for the current transformation
dwFlags [in]	Transformation column-validation flags
ePhases [in]	Phases for which the transformation will be called
pIStorage [in]	Pointer to persistent storage of transformation properties
Remarks

The data pump calls CoCreateInstance on the transformation object specified by ServerClsid. The transformation specified must support the IDTSDataPumpTransform2 interface and, by inheritance, IDTSDataPumpTransform. It must respond to QueryInterface for both IDTSDataPumpTransform2 and IDTSDataPumpTransform.

See Also

IDTSDataPump::AddTransform

IDTSDataPumpTransform2 Interface


IDTSDataPump2::ExecuteComplete

The ExecuteComplete method terminates a sequence of single-row data pump executions.

Syntax

HRESULT ExecuteComplete (
LPDTSExecuteInfo pExecInfo );

Argument	Description
pExecInfo [in/out]	Execution info to be passed into and returned from the data pump
Remarks

To execute one or more rows of the source rowset, the data pump caller first calls ExecuteInit, calls ExecuteRow for each row to be processed, and then calls ExecuteComplete. If ExecuteComplete is not called, Insert batches may not be completed successfully and transformation server processing may not be correctly cleaned up.

See Also

IDTSDataPump2::ExecuteInit

IDTSDataPump2::ExecuteRow

IDTSDataPump2::GetExecuteInfo


IDTSDataPump2::ExecuteInit

The ExecuteInit method initiates a sequence of single-row data pump executions.

Syntax

HRESULT ExecuteInit (
LPBYTE pvUserData,
BOOL *pbEndOfRowset,
LPDTSExecuteInfo pExecInfo );

Argument	Description
pvUserData [in]	Data that is passed to an event sink if an event occurs
pbEndOfRowset [out]	TRUE if at end of source rowset
pExecInfo [in/out]	Execution info to be passed into and returned from the data pump
Remarks

To execute one or more rows of the source rowset, the data pump caller first calls ExecuteInit, calls ExecuteRow one or more times, and then calls ExecuteComplete. ExecuteInit returns TRUE in pbEndOfRowset if the end of the rowset has already been reached.

See Also

IDTSDataPump2::ExecuteComplete

IDTSDataPump2::ExecuteRow

IDTSDataPump2::GetExecuteInfo


IDTSDataPump2::ExecuteRow

The ExecuteRow method causes the data pump to process a single-row of the source rowset.

Syntax

HRESULT ExecuteRow (
BOOL *pbEndOfRowset,
LPDTSExecuteInfo pExecInfo );

Argument	Description
pbEndOfRowset [out]	TRUE if at end of source rowset
pExecInfo [in/out]	Execution information to be passed into and returned from the data pump
Remarks

To execute one or more rows of the source rowset, the data pump caller calls ExecuteInit, calls ExecuteRow for each row to be processed, and then calls ExecuteComplete. ExecuteRow returns TRUE in pbEndOfRowset if the end of the rowset has been reached.

If MaximumErrorRowCount is greater than 0, ExecuteRow continues until a row is successfully processed or MaximumErrorRowCount is exceeded.

See Also

IDTSDataPump2::ExecuteComplete

IDTSDataPump2::ExecuteInit

IDTSDataPump2::GetExecuteInfo


IDTSDataPump2::GetExecuteInfo

The GetExecuteInfo returns information about data pump execution.

Syntax

HRESULT GetExecuteInfo(
LPDTSExecuteInfo pExecInfo );

Argument	Description
pExecInfo [in/out]	Execution information to be passed into and returned from the data pump
Remarks

GetExecuteInfo may be called at any point after ExecuteInit.

pExecInfo is a pointer to a DTSExecuteInfo structure. This structure is used to pass the following information to and from the data pump:

•	Total number of source rows processed.

•	Total number of error rows encountered.

•	Data pump execution status.

•	Transform status, used to select the data driven query to be executed.

•	Handles to input source and destination chapters, used to specify the chapters where hierarchical rowset processing occurs.

•	Handles to output source and destination rows, returned by the data pump to enable caller to specify where rowset processing should resume at next ExecuteRow call.

See Also

IDTSDataPump2::ExecuteRow


IDTSDataPump2::GetOptions

The GetOptions method returns extended data pump processing options.

Syntax

HRESULT GetOptions(
LPDTSDataPumpOptions peOptions );

Argument	Description
peOptions [out]	Extended data pump processing options
Remarks

For more information about the extended data pump processing options, see IDTSDataPump2::SetOptions.


IDTSDataPump2::SetExecuteThreadComplete

The SetExecuteThreadComplete method completes processing that must be done on the current thread, prior to the data pump being called on another thread.

Syntax

HRESULT SetExecuteThreadComplete( );

Remarks

Some transformations may generate a thread-specific state that requires cleanup to be executed on that thread. For example, if ExecuteInit or ExecuteRow is called on a worker thread that is not the same as that on which ExecuteComplete is called, SetExecuteThreadComplete must be called on the worker thread when it has completed its operation (prior to ExecuteComplete being called).

Currently this is specific to the Microsoft® ActiveX® Script transformation, due to the requirement that IActiveScript execution state cannot be transferred across threads. In ActiveX Script transformations, any variables in the script, including global variables outside function scope, will be independent across multiple threads calling ExecuteRow. Calling this method causes IDTSDataPumpTransform2::SetExecuteThreadComplete to be called for all transformations supporting the IDTSDataPumpTransform2 interface.

See Also

IDTSDataPump2::ExecuteComplete

IDTSDataPump2::ExecuteInit

IDTSDataPump2::ExecuteRow


IDTSDataPump2::SetOptions

The SetOptions method sets extended data pump processing options.

Syntax

HRESULT SetOptions(
DTSDataPumpOptions eOptions );

Argument	Description
eOptions [in]	Extended data pump processing options
Remarks

The extended data pump processing options are:

Symbol	Value	Description
DTSDataPumpOpt_Default	0	Normal processing occurs.
DTSDataPumpOpt_AlwaysCommitFinalBatch	1	The final batch is committed even if the data pump fails. This is to support restartability.
See Also

IDTSDataPump2::GetOptions


IDTSDataPumpErrorSink

The IDTSDataPumpErrorSink interface provides optional error sinks for the source, transformations, or destination to data pump consumers. Only one of the error sink methods is called for each row, and the method called indicates where the error was encountered.

The error sinks determine the appropriate response to the error. The response is one of the following:

•	Terminate the data pump.

•	Increment an error count and continue if the error count does not exceed the value of the MaximumErrorCount property.

•	Continue the data pump operation.

The error information is written to the exception file and the package OnError event is raised if a handler has been provided.

See Also

Handling DTS Events and Errors

MaximumErrorCount Property

OnError Event


IDTSDataPumpErrorSink::OnBindingError

The OnBindingError method indicates that a binding error occurred in a call to the OLE DB IAccessor::CreateAccessor method.

Syntax

HRESULT OnBindingError (
LPBYTE pvExecUserData,
HRESULT hrError,
LPCDTSTransformColumnInfo pSourceRow,
const DBBINDSTATUS *pSourceDBBindStatus,
LPCDTSTransformColumnInfo pDestinationRow,
const DBBINDSTATUS *pDestinationDBBindStatus );

Argument	Description
pvExecUserData [in]	User data pointer passed to IDTSDataPump::Execute.
hrError [in]	Error code from CreateAccessor: specifies the destination if pDestinationRow, the source if pSourceRow.
pSourceRow [in]	Pointer to the source row and binding information.
pSourceDBBindStatus [in]	Pointer to source binding status returns.
pDestinationRow [in]	Pointer to the destination row and binding information; NULL if from a source binding error.
pDestinationDBBindStatus [in]	Pointer to destination binding status returns; NULL if from a source binding error.
Remarks

OnBindingError can be useful when designing custom transformation servers. It is primarily used to diagnose binary large object (BLOB)-related problems.


IDTSDataPumpErrorSink::OnDestinationError

The OnDestinationError method indicates that an error occurred during InsertRow.

Syntax

HRESULT OnDestinationError (
LPBYTE pvExecUserData,
LPDTSTransformColumnInfo pSourceRow,
LPDTSTransformColumnInfo pDestinationRow,
HRESULT hrError,
ULARGE_INTEGER uliRow,
ULONG cErrors,
BOOL *pbAbort );

Argument	Description
pvExecUserData [in]	User data pointer passed to IDTSDataPump::Execute.
pSourceRow [in]	Pointer to the source row and binding information; NULL if GetNextRows or GetData failed.
PDestinationRow [in]	Pointer to the destination row and binding information; NULL if prior to the execution of the transformation.
hrError [in]	Error code from the OLE DB or system call.
uliRow [in]	Number of the row that failed.
cErrors [in]	Number of error rows encountered during the transformation, including the current row.
pbAbort [out]	Set to TRUE by the error sink if this error should terminate IDTSDataPump::Execute. Otherwise, Execute continues until MaximumErrorRowCount is exceeded.
Remarks

OnDestinationError is called when an error is encountered sending a row to the destination using IRowsetChange::InsertRow. Operation of the data pump continues unless the pbAbort flag is set to TRUE or the maximum allowable error count is exceeded.


IDTSDataPumpErrorSink::OnSourceError

The OnSourceError method indicates that an error occurred during a GetNextRows or GetData operation.

Syntax

HRESULT OnSourceError (
LPBYTE pvExecUserData,
LPDTSTransformColumnInfo pSourceRow,
HRESULT hrError,
ULARGE_INTEGER uliRow,
ULONG cErrors,
BOOL *pbAbort );

Argument	Description
pvExecUserData [in]	User data pointer passed to IDTSDataPump::Execute.
pSourceRow [in]	Pointer to the source row and binding information; NULL if GetNextRows or GetData failed.
hrError [in]	Error code from the OLE DB or system call.
uliRow [in]	Number of the row that failed.
cErrors [in]	Number of error rows encountered during the transformation, including the current row.
pbAbort [out]	Set to TRUE by the error sink if this error should terminate IDTSDataPump::Execute. Otherwise, Execute continues until MaximumErrorRowCount is exceeded.
Remarks

OnSourceError is called when an error is encountered acquiring a source row. This is generally considered to be a fatal data pump error, and the pbAbort flag is set to TRUE.


IDTSDataPumpErrorSink::OnTransformError

The OnTransformError method indicates that an error occurred during one or more transformations.

Syntax

HRESULT OnTransformError (
LPBYTE pvExecUserData,
LPBYTE pvTransformUserData,
IDTSDataPumpTransform *pTransformServer,
LPDTSTransformColumnInfo pSourceRow,
DTSTransformStatus TransformStatus,
HRESULT hrTransform,
ULARGE_INTEGER uliRow,
ULONG cErrors,
BOOL *pbAbort );

Argument	Description
pvExecUserData [in]	User data pointer passed to IDTSDataPump::Execute.
pvTransformUserData [in]	User data pointer passed to IDTSDataPump::AddTransform in DTSTransformColumnsSpecification parameter.
pTransformServer [in]	Pointer to the transformation server returning the error.
pSourceRow [in]	Pointer to the source row and binding information.
TransformStatus [in]	Transformation returned status code.
hrTransform [in]	DTSDataPumpTransform::Execute or DTSDataPumpTransform2::ProcessPhase HRESULT return code.
uliRow [in]	Number of the row that failed.
cErrors [in]	Number of error rows encountered during the transformation, including the current row.
pbAbort [out]	Set to TRUE by the error sink if this error should terminate IDTSDataPump::Execute. Otherwise, Execute continues until MaximumErrorRowCount is exceeded.
Remarks

OnTransformError is called when an error is encountered transforming a row. Such an error may be encountered in one of the following ways:

•	The transformation server encounters data that cannot be transformed. It reports this by returning an error transform status. This is considered normal and operation of the data pump continues unless the pbAbort flag is set to TRUE or the maximum allowable error count is exceeded.

•	The transformation server returns an error in the HRESULT from DTSDataPumpTransform::Execute. This is considered a fatal data pump error.

•	The transformation server returns an exception. Any such exception is reported by the data pump as a normal row error, and operation continues.


IDTSDataPumpProgressSink

The IDTSDataPumpProgressSink interface exposes the OnIntervalComplete method, which is a progress indicator event sink.


IDTSDataPumpProgressSink::OnIntervalComplete

The OnIntervalComplete method is a progress indicator event sink that a custom application can use to indicate progress during a transformation.

Syntax

HRESULT OnIntervalComplete (
LPBYTE pvExecUserData,
ULARGE_INTEGER uliRowsComplete,
BOOL *pbAbort );

Argument	Description
pvExecUserData [in]	User data pointer passed to IDTSDataPump::Execute.
uliRowsComplete [in]	Total source rows processed during the current transformation, including those skipped.
*pbAbort [out]	Indicates whether to terminate transformation execution; set to TRUE by the event sink to terminate IDTSDataPump::Execute.


IDTSDataPumpTransform

The IDTSDataPumpTransform interface is retrieved and its methods are called by the data pump to perform individual transformations. All custom transformation COM objects must support the IDTSDataPumpTransform interface.

An instance of the IDTSDataPumpTransform interface is created by the ServerClsid being passed to IDTSDataPump::AddTransform. ServerParameters allows the data pump consumer to create a single instance of an IDTSDataPumpTransform implementation and pass it to multiple IDTSDataPump::AddTransform calls. This is used by custom transformation servers and can be used for internal operations as performing aggregations. The custom transformation server should track this using the pvTransformServerData parameter to optimize operations such as AddVariable, OnRowComplete, and so on.


IDTSDataPumpTransform::AddVariable

The AddVariable method adds a variable to the execution context of a transformation server. AddVariable is always called one time before ValidateSchema to add the IDTSErrorRecords object.

Syntax

HRESULT AddVariable (
LPBYTE pvTransformServerData,
LPCOLESTR pwzName,
BOOL bGlobal,
VARIANT Variable );

Argument	Description
pvTransformServerData [in]	Transform server state data
pwzName [in]	Variable name
bGlobal [in]	For Microsoft® ActiveX® scripts, indicates whether the methods of this variable must be qualified by the object name
Variable [in]	Variable value; passed to and updatable by the transformation server
Remarks

AddVariable allows an application variable to be passed through to the transformation process. The data pump always calls this method to add the DTSErrorRecords object immediately after a call to IDTSDataPumpTransform::Initialize and before a call to ValidateSchema. This allows ValidateSchema to add errors to the OLE DB error records collection for the thread if columns are found to be in error.

For objects to be used in ActiveX scripts, the variable should be ignored if the variant is not of type VT_DISPATCH. This allows all variables to be passed to all transformation servers. The bGlobal parameter indicates whether the properties and methods of the variable are to be added to the global namespace of the script; if so, the method can be called directly, instead of requiring qualification using the object name. Data pump-generated variables (for example, DTSErrorInfo, and the DTSSource and DTSDestination column collections) are always added with this flag set to FALSE to minimize the likelihood of name conflict.


IDTSDataPumpTransform::Execute

The Execute method executes the transformation for a single row.

Syntax

HRESULT Execute (
LPBYTE pvTransformServerData,
LPCDTSTransformColumnInfo pSrcColumnInfo,
LPDTSTransformColumnInfo pDestColumnInfo,
IDTSDataConvert *pIDTSDataConvert,
LPDTSTransformStatus peTransformStatus );

Argument	Description
pvTransformServerData [in]	Transformation server state data
pSrcColumnInfo [in]	Source column and row data
pDestColumnInfo [in/out]	Destination column and row data
pIDTSDataConvert [in]	Pointer to the data conversion interface
peTransformStatus [out]	Result of the transformation
Remarks

This function is called by the data pump and executes the specified transformation. The IDTSDataConvert interface is supplied to provide a DTS-compatible conversion utility. For more information, search include file dtspump.h for IDTSDataConvert. dtspump.h is installed by default to X:\Program Files\Microsoft SQL Server\80\Tools\DevTools\include\.

Execute returns NO_ERROR except when a fatal failure occurs. When Execute returns an error, the data pump terminates. Normal errors such as data violations should be handled as a returned peTransformStatus, which results in a call to IDTSDataPumpErrorSink::OnTransformError. Because some OLE DB providers may have restrictions on the number of storage objects that may be open, Execute should release any BLOB storage objects that do not need to be held during the destination insert upon completion, instead of waiting for OnRowComplete.

Column data should be written in the buffer referenced by DTSColumnData.pvData of the element for the destination column, at the offset specified by DBBINDING.obValue. You can instead store a pointer to the data at this location if you add the DBTYPE_BYREF flag to DBBINDING.wType. For more information and a description of these fields, see Column Information Structures in DTS Transformations.

Transformations that implement both IDTSDataPumpTransform and IDTSDataPumpTransform2 typically implement Execute by calling IDTSDataPumpTransform2::ProcessPhase with NULL for the pPhaseInfo parameter.

See Also

IDTSDataPumpTransform2::ProcessPhase


IDTSDataPumpTransform::Initialize

The Initialize method allows the transformation server to initialize its state for the current transformation.

Syntax

HRESULT Initialize (
LPCOLESTR pwzName,
VARIANT ServerParameters,
LPBYTE *ppvTransformServerData);

Argument	Description
pwzName [in]	Transformation name
ServerParameters [in]	Parameters to server for this transformation
ppvTransformServerData [out]	Transformation server state data
Remarks

An instance of the transformation server object is created by ServerClsid and is passed to IDTSDataPump::AddTransform, unless this is an IUnknown object.

ServerParameters allows the Data Transformation Services (DTS) data pump to create an instance of an IDTSDataPumpTransform implementation and pass it to multiple IDTSDataPump::AddTransform calls. This is only used by custom transformation servers and can be helpful for internal operations such as aggregations. The transformation server should track this in the pvTransformServerData parameter to optimize operations such as AddVariable, OnRowComplete, and so on.

The output ppvTransformServerData is passed to all subsequent methods, so a single instance of a transformation server can be used to implement multiple separate transformations. Generally, you will need to allocate the storage whose reference you return in ppvTransformServerData. You need to release the storage in OnTransformComplete, or in ValidateSchema, if ValidateSchema returns an error.

See Also

IDTSDataPump::AddTransform

IDTSDataPumpTransform::AddVariable

IDTSDataPumpTransform::OnRowComplete

IDTSDataPumpTransform::OnTransformComplete

IDTSDataPumpTransform::ValidateSchema


IDTSDataPumpTransform::OnRowComplete

The OnRowComplete method is called after every successful fetch operation, allowing the transformation server to free per-row allocations and client-owned data in both source and destination rows.

Syntax

HRESULT OnRowComplete (
LPBYTE pvTransformServerData,
LPDTSTransformColumnInfo pSrcColumnInfo,
LPDTSTransformColumnInfo pDestColumnInfo,
IDTSDataConvert *pIDTSDataConvert,
DTSTransformStatus eTransformStatus,
HRESULT hrInsert );

Argument	Description
pvTransformServerData [in]	Transform server state data
pSrcColumnInfo [in/out]	Source column and row data
pDestColumnInfo [in/out]	Destination column and row data
pIDTSDataConvert [in]	Pointer to the data conversion interface
eTransformStatus [in]	Result of Execute
hrInsert [in]	Result of IRowsetChange::InsertRow
Remarks

After a successful fetch operation, the data pump calls Execute and attempts to insert the row into the destination using IRowsetChange::InsertRow, if specified. OnRowComplete is called for every successful fetch operation, regardless of whether Execute or InsertRow succeeded or failed. If OnRowComplete returns FAILED, the data pump terminates.

hrInsert indicates whether IRowsetChange::InsertRow succeeded.

eTransformStatus indicates whether errors occurred that resulted in no call to InsertRow. OLE DB requires that IRowsetChange::InsertRow release any storage objects contained in the row; therefore, the transformation server must be careful not to call pIDTSDataConvert->ClearBindingData on a storage object that has already been released.


IDTSDataPumpTransform::OnTransformComplete

After all rows have been transformed or the data pump has been terminated due to errors, the OnTransformComplete method is called to allow the transformation server to release all allocations made for the transformation.

Syntax

HRESULT OnTransformComplete (
LPBYTE pvTransformServerData,
LPDTSTransformColumnInfo pSrcColumnInfo,
LPDTSTransformColumnInfo pDestColumnInfo,
IDTSDataConvert *pIDTSDataConvert );

Argument	Description
pvTransformServerData [in]	Transform server state data
pSrcColumnInfo [in/out]	Source column and row data
pDestColumnInfo [in/out]	Destination column and row data
*pIDTSDataConvert [in]	Pointer to the data conversion interface
Remarks

OnTransformComplete is called only if ValidateSchema completes successfully. OnTransformComplete is not called if the transformation implements IDTSDataPumpTransform2 and IDTSDataPumpTransform2::GetTransformServerInfo indicates the transformation supports DTSTransformPhase_OnPumpComplete phase.

See Also

IDTSDataPumpTransform2::GetTransformServerInfo

IDTSDataPumpTransform2::ProcessPhase


IDTSDataPumpTransform::ValidateSchema

The ValidateSchema method validates the schema of the source and destination columns to be transformed.

Syntax

HRESULT ValidateSchema (
LPBYTE pvTransformServerData,
LPCDTSTransformColumnInfo pSrcColumnInfo,
LPCDTSTransformColumnInfo pDestColumnInfo,
IDTSDataConvert *pIDTSDataConvert,
DTSTransformFlags eTransformFlags );

Argument	Description
pvTransformServerData [in]	Transform server state data
pSrcColumnInfo [in/out]	Source column and row data
pDestColumnInfo [in/out]	Destination column and row data
*pIDTSDataConvert [in]	Pointer to the data conversion interface
eTransformFlags [in]	Input flags for transformation validation and execution
Remarks

Pointers to source and destination column information structures are passed to ValidateSchema. The transformation can then validate data types, preventing unintended row transfers if the types are incompatible. If the transformation does not validate at this time (for example, due to a complex conversion performed on the row data), then it simply returns NO_ERROR. A validation failure should return an appropriate failure code, such as DB_E_SCHEMAVIOLATION, or one defined by the transformation server because the data pump cannot proceed.

The pointer to the IDTSDataConvert interface is passed in to allow the destination to verify that conversion between the source and destination data types is possible and to indicate any special conditions that may be encountered.

The transformation flags define the data type promotion, demotion, and conversions that are allowed. Additional custom properties may be defined through a custom interface, in which case the object (such as an IUnknown object) must be created and edited prior to the object being passed to IDTSDataPump::AddTransform.


IDTSDataPumpTransform2

The IDTSDataPumpTransform2 interface must be implemented by all transformations that are to run with Microsoft® SQL Server™ 2000. It supports multi-phase transform operations. Transformations that implement IDTSDataPumpTransform2 must still implement IDTSDataPumpTransform.


IDTSDataPumpTransform2::GetTransformServerInfo

The GetTransformServerInfo method returns information that describes the functionality of the transformation.

Syntax

HRESULT GetTransformServerInfo (
BSTR *pbstrHelpString,
LPDTSTransformPhaseEnum peSupportedPhases );

Argument	Description
pbstrHelpString [out]	Description of the transformation implementation
peSupportedPhases [out]	Phases supported by this transformation
Remarks

This method is called before IDTSDataPumpTransform::Initialize. It returns a textual description that can be used as a help string and a bitmask that contains flags for the supported phases. These flags are values from DTSTransformPhaseEnum.

Any output parameter can be NULL if that information is not desired by the caller. GetTransformServerInfo must be prepared to handle these.

IDTSDataPumpTransform2::ProcessPhase is not called for a phase specified by GetTransformServerInfo unless the value specified for the TransformPhases property of the Transformation2 object also specifies the phase. For packages built in Data Transformation Services (DTS) Designer, specify phases on the Phases tab of the Transformation Options dialog box.

See Also

IDTSDataPumpTransform::Initialize

IDTSDataPumpTransform::OnTransformComplete

IDTSDataPumpTransform2::ProcessPhase

TransformPhases Property


IDTSDataPumpTransform2::PreValidateSchema

The PreValidateSchema method validates the schema of the source and destination columns to be transformed. It is called from Data Transformation Services (DTS) Designer at the time the transformation is being configured.

Syntax

HRESULT PreValidateSchema (
LPCDTSTransformColumnMetadata pSrcMetadata,
LPCDTSTransformColumnMetadata pDestMetaData,
DTSTransformFlags eTransformFlags,
DTSTransformPhaseEnum ePhases );

Argument	Description
pSrcMetadata [in]	Source column meta data
pDestMetaData [in]	Destination column meta data
eTransformFlags [in]	Input flags for transformation validation and execution
ePhases [in]	Phases this transformation is expected to support
Remarks

PreValidateSchema provides validation at the time the package is built, rather than when it is executed. It is called from DTS Designer when the user selects the Only Show Valid Transformations check box in the Create New Transformation dialog box and when the Transformation Options dialog box is closed. It is passed the meta data for the source and destination columns, the transformation flags and a bitmask defining the phases the transformation is expected (by the caller) to support.

Any level of validation can be provided, up to and including that done by IDTSDataPumpTransform::ValidateSchema. However, Only Show Valid Transformations simply removes the transformation name from the Create New Transformation dialog box, so complex validations may leave the user wondering why the transformation is not valid.

The transformation flags, which use values from DTSTransformFlags, define the data type promotion, demotion and conversions that are allowed. However, PreValidateSchema is not called when they are changed from the Transformation Flags dialog box, so you may want to defer validation involving the flags to ValidateSchema.

The source and destination column meta data structure DTSTransformColumnMetadata has these fields.

Field	Description
cColumns	Count of source or destination columns.
rgDBColumnInfo	Pointer to an array of OLE DB DBCOLUMNINFO structures. There is one array element for each column.
For more information about the DBCOLUMNINFO structure, see Column Information Structures in DTS Transformations.

See Also

DTSTransformFlags

IDTSDataPumpTransform::ValidateSchema


IDTSDataPumpTransform2::ProcessPhase

The ProcessPhase method executes a phase of the transformation for a single row.

Syntax

HRESULT ProcessPhase (
LPBYTE pvTransformServerData,
LPCDTSTransformColumnInfo pSrcColumnInfo,
LPDTSTransformColumnInfo pDestColumnInfo,
IDTSDataConvert *pIDTSDataConvert,
LPCDTSTransformPhaseInfo pPhaseInfo,
LPDTSTransformStatus peTransformStatus );

Argument	Description
pvTransformServerData [in]	Transformation server state data
pSrcColumnInfo [in]	Source column and row data
pDestColumnInfo [in/out]	Destination column and row data
pIDTSDataConvert [in]	Pointer to the data conversion interface
pPhaseInfo [in]	Transform phase information structure
peTransformStatus [out]	Result of the transformation
Remarks

This function is called by the data pump and executes a phase of the transformation. The phase is identified by a code from DTSTransformPhaseEnum in a field of pPhaseInfo, a DTSTransformPhaseInfo structure. The following table lists the transformation phases that are available.

Phase	Description
DTSTransformPhase_PreSourceData	Called before first fetch of source data. Valid destination codes can be returned in peTransformStatus to write a destination row. DTSTransformStat_SkipFetch can be returned to loop and write multiple rows.
DTSTransformPhase_Transform	Transforms source columns to destination columns. Performs same function as IDTSDataPumpTransform::Execute.
DTSTransformPhase_OnTransformFailure	Called when DTSTransformPhase_Transform phase returns DTSTransformStat_Error or DTSTransformStat_ExceptionRow. The returned peTransformStatus overrides that from DTSTransformPhase_Transform. The insert operation and data driven queries (DDQs) will be attempted if the peTransformStatus so directs.
DTSTransformPhase_OnInsertSuccess	Called on success of the insert/DDQ. Destination operations cannot be specified in peTransformStatus as the destination row has already been written.
DTSTransformPhase_OnInsertFailure	Called on failure of the insert operation or data driven query. Destination operations cannot be specified in peTransformStatus (for example, the insert operation and data driven query cannot be retried).
DTSTransformPhase_OnBatchComplete	Called after the success or failure of a data pump batch. The batch size is defined by the InsertCommitSize property.
DTSTransformPhase_PostSourceData	Called after last row of source data has been fetched and transformed. Valid destination codes can be returned in peTransformStatus to write a destination row, but no source data is available. DTSTransformStat_SkipFetch can be returned to loop and write multiple rows.
DTSTransformPhase_OnPumpComplete	Called when data pump operation completes as a success or failure, if the transformation supports this phase. It is called in place of IDTSDataPumpTransform::OnTransformComplete. The pPhaseInfo structure is available.
ProcessPhase is only called for the phases that are returned in the peSupportedPhases parameter of IDTSDataPumpTransform2::GetTransformServerInfo. When there are multiple transformations, each phase is executed for all the transformations, in the order in which they were created, before moving on to the next phase.

Note   ProcessPhase is not called for a phase specified by GetTransformServerInfo unless the value specified for the TransformPhases property of the Transformation2 object also specifies the phase. For packages built in Data Transformation Services (DTS) Designer, specify phases on the Phases tab of the Transformation Options dialog box. The one exception is DTSTransformPhase_OnPumpComplete, for which ProcessPhase called (in place of OnTransformComplete) whenever GetTransformServerInfo specifies the phase is supported.

The source and destination column data is described by the DTSTransformColumnInfo structures referenced by pSrcColumnInfo and pDestColumnInfo. Column data should be written in the buffer referenced by DTSColumnData.pvData of the element for the destination column, at the offset specified by DBBINDING.obValue. You can instead store a pointer to the data at this location if you add the DBTYPE_BYREF flag to DBBINDING.wType. For more information and a description of these fields, see Column Information Structures in DTS Transformations.

Transformations that implement both IDTSDataPumpTransform and IDTSDataPumpTransform2 typically implement Execute by calling IDTSDataPumpTransform2::ProcessPhase with NULL for the pPhaseInfo parameter.

The IDTSDataConvert interface provides a DTS-compatible conversion utility. For more information, search include file dtspump.h for IDTSDataConvert. dtspump.h is installed by default to c:\Program Files\Microsoft SQL Server\80\Tools\DevTools\include\.

See Also

DTSTransformPhaseEnum

DTSTransformPhaseInfo Object

IDTSDataPumpTransform::Execute

IDTSDataPumpTransform::OnTransformComplete

IDTSDataPumpTransform2::GetTransformServerInfo

InsertCommitSize Property

TransformPhases Property


IDTSDataPumpTransform2::SetExecuteThreadComplete

The SetExecuteThreadComplete method performs any deallocations and cleanup that might be necessary because the Data Transformation Services (DTS) data pump instance (and thus the transformation) is going to continue execution on another thread. It is called when IDTSDataPump2::SetExecuteThreadComplete is called.

Syntax

HRESULT SetExecuteThreadComplete( );

The method has no parameters.

Remarks

Data pump execution can be segmented so that it processes one or more rows on a thread when IDTSDataPump2::ExecuteRow is called, then processes additional rows when ExecuteRow is called on another thread. The DTS tasks supplied with Microsoft® SQL Server™ 2000 do not cross threads like this, but custom tasks can do so. Custom tasks doing this must call IDTSDataPump2::SetExecuteThreadComplete on the original thread before calling ExecuteRow on the new thread. IDTSDataPump2::SetExecuteThreadComplete calls IDTSDataPumpTransform2::SetExecuteThreadComplete for each transformation.

In most cases, the transformation does not need to do anything. Only when the transformation has invoked a thread-affinitive process, it may need to close that process before re-opening it on the new thread. For example, if the transformation uses the ActiveScripting engine, it needs to make a separate copy of the scripting engine instance, then call IActiveScript::Close on the old thread, then initialize the scripting engine instance copy on the new thread.


IDTSDataPumpTransform2::SetExtendedInfo

The SetExtendedInfo method is reserved for future use.

Syntax

HRESULT SetExtendedInfo (
IUnknown *pUnkExtendedInfo );

Argument	Description
pUnkExtendedInfo [in]	Object supplying extended information
Remarks

If you implement IDTSDataPumpTransform2, you must implement SetExtendedInfo even though it is not called. Simply return NO_ERROR.

When implemented, SetExtendedInfo will be called prior to IDTSDataPumpTransform::ValidateSchema. pUnkExtendedInfo will be a pointer to an object that will QueryInterface to one or more interfaces that supply extended information. These will need to be released in or prior to IDTSDataPumpTransform::OnTransformComplete.

See Also

IDTSDataPumpTransform::OnTransformComplete

IDTSDataPumpTransform::ValidateSchema


Transform Status Enumerations

Dtspump.h and Dtspump.dll expose these constant enumerations.

Enumeration	Description
DTSDataPumpError	Error codes generated by the data pump.
DTSExecuteStatus	Return values from data pump execution.
DTSTransformFlags	Flags that control the conversions performed by transformations.
DTSTransformPhaseEnum	Codes that denote the transformation phases.
DTSTransformStatus	Return codes that Microsoft® ActiveX® Script Transformations can generate.


Object, Property, or Method Reserved

This DTS object, property, or method is reserved for future use.


See SQL Server Books Online to review this topic.