Partilhar via

dtexec Utility

  • Artigo

The dtexec command prompt utility is used to configure and execute SQL Server 2005 Integration Services (SSIS) packages. The dtexec utility provides access to all the package configuration and execution features, such as connections, properties, variables, logging, and progress indicators. The dtexec utility lets you load packages from three sources: a Microsoft SQL Server database, the SSIS service, and the file system.

Note

On a 64-bit computer, Integration Services installs both a 32-bit and a 64-bit version of the dtexec utility (dtexec.exe).

The utility has four phases that it proceeds through as it executes. The phases are as follows:

  1. Command sourcing phase: The command prompt reads the list of options and arguments that have been specified. All subsequent phases are skipped if a /? or /HELP option is encountered.
  2. Package load phase: The package specified by the /SQL, /FILE, or /DTS option is loaded.
  3. Configuration phase: Options are processed in this order:
    • Options that set package flags, variables, and properties.
    • Options that verify the package version and build.
    • Options that configure the run-time behavior of the utility, such as reporting.
  4. Validation and execution phase: The package is run, or validated without running if the /VALIDATE option was specified.

Exit codes returned from dtexec utility

When a package runs, dtexec can return an exit code. The exit code is used to populate the ERRORLEVEL variable, the value of which can then be tested in conditional statements or branching logic within a batch file. The following table lists the values that the dtexec utility can set when exiting.

Value Description

0

The package executed successfully.

1

The package failed.

3

The package was canceled by the user.

4

The utility was unable to locate the requested package. The package could not be found.

5

The utility was unable to load the requested package. The package could not be loaded.

6

The utility encountered an internal error of syntactic or semantic errors in the command line.

Utility syntax rules

All options must start with a slash (/) or a minus sign (-). The options that are shown here start with a slash (/), but the minus sign (-) can be substituted.

An argument must be enclosed in quotation marks if it contains a space. If the argument is not enclosed in quotation marks, the argument cannot contain white space.

Doubled quotation marks within quoted strings represent escaped single quotation marks.

Options and arguments are not case-sensitive, except for passwords.

Using dtexec from the xp_cmdshell

You can run dtexec from the xp_cmdshell prompt. The following example shows how to run a package called UpsertData.dtsx and ignore the return code:

EXEC xp_cmdshell 'dtexec /f "C:\UpsertData.dtsx"'

The following example shows how to run the same package and capture the return code:

DECLARE @returncode int
EXEC @returncode = xp_cmdshell 'dtexec /f "C:\UpsertData.dtsx"'

Important

In Microsoft SQL Server 2005, the xp_cmdshell option is disabled by default on new installations. The option can be enabled by using the Surface Area Configuration tool or by running the sp_configure system stored procedure. For more information, see xp_cmdshell Option.

Syntax

dtexec /option [value] [/option [value]]...

Parameters

To understand how the command prompt options used with the SQL Server 2000 dtsrun utility map to the command prompt options used with the SQL Server 2005 dtexec utility, see dtsrun to dtexec Command Option Mapping. For suggestions about how to upgrade these utilities, see Upgrading dtsrun Command Lines.

Option

Description

/? [option_name]

(Optional). Displays the command prompt options, or displays help for the specified option_name and then closes the utility.

If you specify an option_name argument, dtexec starts SQL Server Books Online and displays the dtexec Utility topic.

**/CheckF[ile]**filespec

(Optional). Sets the CheckpointFileName property on the package to the path and file specified in filespec. This file is used when the package restarts. If this option is specified and no value is supplied for the file name, the CheckpointFileName for the package is set to an empty string. If this option is not specified, the values in the package are retained.

/CheckP[ointing]{on\off}

(Optional). Sets a value that determines whether the package will use checkpoints during package execution. The value on specifies that a failed package is to be rerun. When the failed package is rerun, the run-time engine uses the checkpoint file to restart the package from the point of failure.

The default value is on if the option is declared without a value. Package execution will fail if the value is set to on and the checkpoint file cannot be found. If this option is not specified, the value set in the package is retained. For more information, see Using Checkpoints in Packages.

The /CheckPointing on option of dtexec is equivalent to setting the SaveCheckpoints property of the package to True, and the CheckpointUsage property to Always.

**/Com[mandFile]**filespec

(Optional). Specifies that during the command sourcing phase of the utility, the file specified in filespec is opened, options from the file are read until EOF is found in the file. filespec is a text file that contains additional dtexec command options. The filespec argument specifies the file name and path of the command file to associate with the execution of the package.

**/Conf[igFile]**filespec

(Optional). Specifies a configuration file to extract values from. Using this option, you can set a run-time configuration that differs from the configuration that was specified at design time for the package. You can store different configuration settings in an XML configuration file and then load the settings before package execution by using the /ConfigFile option.

ms162810.note(en-US,SQL.90).gifNote:

If the /ConfigFile option specifies a location for the configuration file that is different than the location that the package specifies, the dtexec utility might raise a warning. You can disregard this warning. As long as the /ConfigFile option specifies a valid file path, the dtexec utilty will find and use the configuration file that the /ConfigFile option specifies.

**/Conn[ection]**id_or_name;connection_string [[;id_or_name;connection_string]…]

(Optional). Specifies that the connection manager with the specified name or GUID is located in the package, and specifies a connection string.

This option requires that both parameters be specified: the connection manager name or GUID must be provided in the id_or_name argument, and a valid connection string must be specified in the connection_string argument. For more information, see Connection Managers.

/Cons[oleLog] [[displayoptions];[list_options;src_name_or_guid]...]

(Optional). Displays specified log entries to the console during package execution. If this option is omitted, no log entries are shown in the console. If the option is specified without parameters that limit the display, every log entry will display. To limit the entries that are displayed to the console, you can specify the columns to show by using the displayoptions parameter, and limit the log entry types by using the list_options parameter.

The displayoptions values are as follows:

  • N (Name)
  • C (Computer)
  • O (Operator)
  • S (Source Name)
  • G (Source GUID)
  • X (Execution GUID)
  • M (Message)
  • T (Time Start and End)

The list_options values are as follows:

  • I - Specifies the inclusion list. Only the source names or GUIDs that are specified are logged.
  • E - Specifies the exclusion list. The source names or GUIDs that are specified are not logged.
  • The src_name_or_guid parameter specified for inclusion or exclusion is an event name, source name, or source GUID.

If you use multiple /ConsoleLog options on the same command prompt, they interact as follows:

  • Their order of appearance has no effect.
  • If no inclusion lists are present on the command line, exclusion lists are applied against all kinds of log entries.
  • If any inclusion lists are present on the command line, exclusion lists are applied against the union of all inclusion lists.

For several examples of the /ConsoleLog option, see the Remarks section.

**/D[ts]**package_path

(Optional). Loads a package from the SSIS Package Store. The package_path argument specifies the relative path of the SSIS package, starting at the root of the SSIS Package Store, and includes the name of the SSIS package. If the path or file name specified in the package_path argument contains a space, you must put quotation marks around the package_path argument.

The /DTS option cannot be used together with the /File or /SQL option. If multiple options are specified, dtexec fails.

/De[crypt] password

(Optional). Sets the decryption password that is used when you load a package with password encryption.

**/F[ile]**filespec

(Optional). Loads a package that is saved in the file system. The filespec argument specifies the path and file name of the package. You can specify the path as either a Universal Naming Convention (UNC) path or a local path. If the path or file name specified in the filespec argument contains a space, you must put quotation marks around the filespec argument.

The /File option cannot be used together with the /DTS or /SQL option. If multiple options are specified, dtexec fails.

/H[elp] [option_name]

(Optional). Displays help for the options, or displays help for the specified option_name and closes the utility.

If you specify an option_name argument, dtexec starts SQL Server Books Online and displays the dtexec Utility topic.

**/L[ogger]**classid_orprogid;configstring

(Optional). Associates one or more log providers with the execution of an SSIS package. The classid_orprogid parameter specifies the log provider, and can be specified as a class GUID. The configstring is the string that is used to configure the log provider.

The following list shows the available log providers:

  • Text file:
    • ProgID: DTS.LogProviderTextFile.1
    • ClassID: {59B2C6A5-663F-4C20-8863-C83F9B72E2EB}
  • SQL Server Profiler:
    • ProgID: DTS.LogProviderSQLProfiler.1
    • ClassID: {5C0B8D21-E9AA-462E-BA34-30FF5F7A42A1}
  • SQL Server:
    • ProgID: DTS.LogProviderSQLServer.1
    • ClassID: {6AA833A1-E4B2-4431-831B-DE695049DC61}
  • Windows Event Log:
    • ProgID: DTS.LogProviderEventLog.1
    • ClassID: {97634F75-1DC7-4F1F-8A4C-DAF0E13AAA22}
  • XML File:
    • ProgID: DTS.LogProviderXMLFile.1
    • ClassID: {AFED6884-619C-484F-9A09-F42D56E1A7EA}

**/M[axConcurrent]**concurrent_executables

(Optional). Specifies the number of executable files that the package can run concurrently. The value specified must be either a non-negative integer, or -1. A value of -1 means that SSIS will allow a maximum number of concurrently running executables that is equal to the total number of processors on the computer executing the package, plus two.

**/P[assword]**password

(Optional). Allows the retrieval of a package that is protected by SQL Server Authentication. This option is used together with the /User option. If the /Password option is omitted and the /User option is used, a blank password is used. The password value may be quoted.

ms162810.security(en-US,SQL.90).gifSecurity Note:

When possible, use Windows Authentication.

/Remcomment

(Optional). Includes comments on the command prompt or in command files. The argument is optional. The value of comment is a string that must be enclosed in quotation marks, or contain no white space. If no argument is specified, a blank line is inserted. comment values are discarded during the command sourcing phase.

**/Rep[orting]**level [;event_guid_or_name[;event_guid_or_name[...]]

(Optional). Specifies what types of messages to report. The available reporting options for level are as follows:

N    No reporting.

E    Errors are reported.

W    Warnings are reported.

I    Informational messages are reported.

C    Custom events are reported.

D    Data Flow task events are reported.

P    Progress is reported.

V    Verbose reporting.

The arguments of V and N are mutually exclusive to all other arguments; they must be specified alone. If the /Reporting option is not specified then the default level is E (errors), W (warnings), and P (progress).

All events are preceded with a timestamp in the format "YY/MM/DD HH:MM:SS", and a GUID or friendly name if available.

The optional parameter event_guid_or_name is a list of exceptions to the log providers. The exception specifies the events that are not logged that otherwise might have been logged.

You do not have to exclude an event if the event is not ordinarily logged by default

/Res[tart] {deny | force | ifPossible}

(Optional). Specifies a new value for the CheckpointUsage property on the package. The meaning of the parameters are as follows:

Deny   Sets CheckpointUsage property to DTSCU_NEVER.

Force    Sets CheckpointUsage property to DTSCU_ALWAYS.

ifPossible    Sets CheckpointUsage property to DTSCU_IFEXISTS.

The default value of force is used if no value is specified.

/SetpropertyPath;value

(Optional). Overrides the configuration of a variable, property, container, log provider, Foreach enumerator, or connection within a package. When this option is used, /SET changes the propertyPath argument to the value specified. Multiple /SET options can be specified.

You can determine the value of propertyPath by running the Package Configuration Wizard. The paths for items that you select are displayed on the final Completing the Wizard page, and can be copied and pasted. If you have used the wizard only for this purpose, you can cancel the wizard after you copy the paths.

The following is an example of executing a package and providing a new value for a variable:

dtexec /f mypackage.dtsx /set \package.variables[myvariable].Value;myvalue

**/Ser[ver]**server

(Optional). When the /SQL or /DTS option is specified, this option specifies the name of the server from which to retrieve the package. If you omit the /Server option and the /SQL or /DTS option is specified, package execution is tried against the local server. The server_instance value may be quoted.

**/SQ[L]**package_path

Loads a package that is stored in SQL Server. The package_path argument specifies the name of the package to retrieve. If folders are included in the path, they are terminated with backslashes ("\"). The package_path value can be quoted. If the path or file name specified in the package_path argument contains a space, you must put quotation marks around the package_path argument.

You can use the /User, /Password, and /Server options together with the /SQL option.

If you omit the /User option, Windows Authentication is used to access the package. If you use the /User option, the /User login name specified is associated with SQL Server Authentication.

The /Password option is used only together with the /User option. If you use the /Password option, the package is accessed with the user name and password information provided. If you omit the /Password option, a blank password is used.

Security Note   When possible, use Windows Authentication.

If the /Server option is omitted, the default local instance of SQL Server is assumed.

The /SQL option cannot be used together with the /DTS or /File option. If multiple options are specified, dtexec fails.

/Su[m]

(Optional). Shows an incremental counter that contains the number of rows that will be received by the next component.

**/U[ser]**user_name

(Optional). Allows the retrieval of a package that is protected by SQL Server Authentication. This option is used only when the /SQL option is specified. The user_name value can be quoted.

Security Note   When possible, use Windows Authentication.

/Va[lidate]

(Optional). Stops the execution of the package after the validatation phase, without actually running the package. During validation, use of the /WarnAsError option causes dtexec to treat a warning as an error; therefore the package fails if a warning occurs during validation.

**/VerifyB[uild]**major[;minor[;build]]

(Optional). Verifies the build number of a package against the build numbers that were specified during the verification phase in the major, minor, and build arguments. If a mismatch occurs, the package will not execute.

The values are long integers. The argument can have one of three forms, with a value for major always required:

  • major
  • major;minor
  • major; minor; build

**/VerifyP[ackageID]**packageID

(Optional). Verifies the GUID of the package to be executed by comparing it to the value specified in the package_id argument.

/VerifyS[igned]

(Optional). If specified, this option causes the package to fail if the package is not signed.

**/VerifyV[ersionID]**versionID

(Optional). Verifies the version GUID of a package to be executed by comparing it to the value specified in the version_id argument during package Validation Phase.

/W[arnAsError]

(Optional). Causes the package to consider a warning as an error; therefore, the package will fail if a warning occurs during validation. If no warnings occur during validation and the /Validate option is not specified, the package is executed.

Remarks

The order in which you specify command options can influence the way in which the package executes:

  • Options are processed in the order they are encountered on the command line. Command files are read in as they are encountered on the command line. The commands in the command file are also processed in the order they are encountered.
  • If the same option, parameter, or variable appears in the same command line statement more than one time, the last instance of the option takes precedence.
  • /Set and /ConfigFile options are processed in the order they are encountered.

Examples

Running Packages

To execute an SSIS package saved to SQL Server using Windows authentication, use the following code:

dtexec /sq pkgOne /ser productionServer

To execute an SSIS package saved to the File System folder in the SSIS Package Store, use the following code:

dtexec /dts "\File System\MyPackage"

To validate a package that uses Windows Authentication and is saved in SQL Server without executing the package, use the following code:

dtexec /sq pkgOne /ser productionServer /va

To execute an SSIS package that is saved in the file system, use the following code:

dtexec /f "c:\pkgOne.dtsx"

To execute an SSIS package that is saved in the file system, and specify logging options, use the following code:

dtexec /f "c:\pkgOne.dtsx" /l "DTS.LogProviderTextFile;c:\log.txt"

To execute a package that uses Windows Authentication and is saved to the default local instance of SQL Server, and verify the version before it is executed, use the following code:

dtexec /sq pkgOne /verifyv {c200e360-38c5-11c5-11ce-ae62-08002b2b79ef}

To execute an SSIS package that is saved in the file system and configured externally, use the following code:

dtexec /f "c:\pkgOne.dtsx" /conf "c:\pkgOneConfig.cfg"

Note

The package_path or filespec arguments of the /SQL, /DTS, or /FILE options must be enclosed in quotation marks if the path or file name contains a space. If the argument is not enclosed in quotation marks, the argument cannot contain white space.

Logging Option

If there are three log entry types of A, B, and C, the following ConsoleLog option without a parameter displays all three log types with all fields:

/CONSOLELOG

The following option displays all log types, but with the Name and Message columns only:

/CONSOLELOG NM

The following option displays all columns, but only for log entry type A:

/CONSOLELOG I;LogEntryTypeA

The following option displays only log entry type A, with Name and Message columns:

/CONSOLELOG NM;I;LogEntryTypeA

The following option displays log entries for log entry types A and B:

/CONSOLELOG I;LogEntryTypeA;LogEntryTypeB

You can achieve the same results by using multiple ConsoleLog options:

/CONSOLELOG I;LogEntryTypeA /CONSOLELOG I;LogEntryTypeB

If the ConsoleLog option is used without parameters, all fields are displayed. The inclusion of a list_options parameter causes the following to displays only log entry type A, with all fields:

/CONSOLELOG NM;I;LogEntryTypeA /CONSOLELOG

The following displays all log entries except log entry type A: that is, it displays log entry types B and C:

/CONSOLELOG E;LogEntryTypeA

The following example achieves the same results by using multiple ConsoleLog options and a single exclusion:

/CONSOLELOG E;LogEntryTypeA /CONSOLELOG
/CONSOLELOG E;LogEntryTypeA /CONSOLELOG E;LogEntryTypeA
/CONSOLELOG E;LogEntryTypeA;LogEntryTypeA

The following example displays no log messages, because when a log file type is found in both the included and excluded lists, it will be excluded.

/CONSOLELOG E;LogEntryTypeA /CONSOLELOG I;LogEntryTypeA

SET Option

The following shows how to use the /SET option, which lets you change the value of any package property or variable when you start the package from the command line.

/SET \package\DataFlowTask.Variables[User::MyVariable].Value;newValue

See Also

Concepts

dtsrun to dtexec Command Option Mapping

Other Resources

How to: Run a Package in Business Intelligence Development Studio
Integration Services Considerations on 64-bit Computers

Help and Information

Getting SQL Server 2005 Assistance

Change History

Release History

17 November 2008
Changed content:
  • Added note about the warning that the dtexec utility raises if the /ConfigFile option specifies a configuration file that is different than the file that the package specifies.

17 July 2006
Changed content:
  • Explained error codes in more detail.
  • Added syntax example that shows error code capture.
  • Noted correspondence of CheckPointing on option and the UI property CheckpointUsage.

14 April 2006
Changed content:
  • Noted that parameters that includes spaces must be enclosed in quotation marks.
  • Added sample on how to execute an SSIS package saved to the file system.

5 December 2005
Changed content:
  • Added important notice that xp_cmdshell is disabled by default.