Microsoft SQL Server 2008 R2 Unleashed- P218 pdf

NOTE You could also execute this new package by using the dtexecutility at a command prompt: C:> dtexec /FILE “C:\HotCustomerPlus.dtsx” The Package Execution Utility Thedtsrunutility in

10 To execute the package, double-click the .dtsxfile, which automatically invokes the

package execution utility Choose Execute, and the package executes and shows all

results in the execution console, as shown in Figure 52.40 That’s it: you have

popu-lated the data mart and created data in an flat file for distribution to the sales team

FIGURE 52.39 Control of flow between the old data flow and new data flow tasks

FIGURE 52.40 Executing the SSIS package

NOTE

You could also execute this new package by using the dtexecutility at a command

prompt:

C:> dtexec /FILE “C:\HotCustomerPlus.dtsx”

The Package Execution Utility

Thedtsrunutility in SQL Server 2000 is no longer used within SQL Server 2008 It has

been taken over by the dtexecutility, which is bigger and better and has more options

and values to serve your every SSIS package execution need Before you begin to use the

dtexecutility, you should execute it at a command prompt with the help option set only

and pipe the results into a text file:

c:> dtexec /? > dtexec.txt

You will quickly see all the main options and how similar this is to dtsrun(in SQL Server

2000) Some dtsruncommand-line options have direct dtexecequivalents, such as the

options for providing a server name or package name or for setting the value of a variable

Otherdtsruncommand-line options don’t have direct dtexecequivalents In addition,

somedtexeccommand-line options support features in SSIS, such as the options to pass

in connection strings and manage checkpoints

You can create new command-line dtexecexecutions visually with the assistance of the

Package Execution utility, which you open through dtexecui This GUI displays all the

available options and ensures the use of the correct syntax (see Figure 52.41) You start it

up from the command prompt:

c:> dtexecui

Using this Package Execution utility is really the best way to create new command-line

executions for SSIS packages and to run them easily Figure 52.42 shows the Package

Execution Progress console during a package execution You can choose to stop the

execu-tion from here

When you double-click any filesystem-stored SSIS package (that is, .dtsxfile), you are

always placed in this dtexecuienvironment (just as you automatically start up Microsoft

Word when you double-click a Word document)

The dtexec Utility

You use the dtexeccommand-line utility to configure and execute SSIS packages The

dtexecutility provides access to all the package configuration and execution features, such

as connections, properties, variables, logging, and progress indicators The dtexecutility

lets you load packages from three sources:

A Microsoft SQL Server database

The SSIS service (package store)

ptg FIGURE 52.41 The user interface for executing and configuring SSIS packages

FIGURE 52.42 The Package Execution Progress console in the Execute Package utility

The filesystem itself

Thedtexecutility proceeds through four phases as it executes:

1 Command sourcing phase—The command prompt reads the list of options and

arguments specified All subsequent phases are skipped if a /?or/H[ELP]option is

encountered

2 Package-loading phase—The package specified by the /SQL,/FILE, or /DTSoption is

loaded

3 Configuration phase—These options are processed in the following order: process

options that set package flags, variables, and properties; process options that verify

the package version and build; and process options that configure the runtime

behavior of the utility, such as reporting

4 Validation and execution phase—The package is run or validated without running

if the /VALIDATEoption was specified

When a package runs, dtexeccan return an exit code The exit code is used to populate

theERRORLEVELvariable—the value of which can then be tested in conditional statements

or branching logic within an operating system batch file The dtexecutility can set the

following exit code values:

Running Packages

Thedtexecoptions are additive Depending on what you are trying to do, you are able to

string one or more options and their values together in the following form:

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

To show available options for dtexec, you use ’/?’or’/H’or’/Help’ Alternatively, you

can see the details for a particular option by using the available options indicator followed

by the option name (’/? [option name]) This invokes SQL Server Books online for that

particular option Note that a dash (-) may be substituted for / in this command

Thedtexecpackage execution options include the following:

/~CheckF[ile] filespec—This option sets the CheckpointFileNameproperty on the

package to the path and file specified infilespec This file is used when the

package restarts

/~CheckP[ointing]{on\off}—The value onspecifies that a failed package is to be

rerun When the failed package is rerun, the runtime engine uses the checkpoint file

to restart the package from the point of failure The default value is onif the option

is declared without a value Package execution fails if the value is set to onand the

checkpoint file cannot be found If this option is not specified, the value set in the

package is retained

Exit Code Value Description

0 Successful package execution

1 Package execution failure

3 User-canceled package execution

4 Package could not be found

5 Package could not be loaded

6 Utility encountered an internal error

NOTE

Using the/CheckPointing onoption ofdtexecis equivalent to setting the

SaveCheckpointsproperty of the package toTrueand theCheckpointUsage

property toAlways

/~Com[mandFile] filespec—This option specifies that during the command

sourc-ing phase of the utility, the file specified infilespecis opened, and options from

the file are read until the EOF is found in the file.filespecis a text file that contains

additionaldtexeccommand options Thefilespecargument specifies the filename

and path of the command file to associate with the execution of the package

/~Conf[igFile] filespec—This option specifies a configuration file to extract

values from Using this option, you can set a runtime configuration that differs from

the configuration specified for the package at design time

/~Conn[ection] id_or_name;connection_string [[;id_or_name;connection_

string] ]—This option specifies the specific connection manager name or GUID

and the specific connection string to use This option requires that both parameters

be specified

/~Cons[oleLog] [[displayoptions];[list_options ; src_name_or_guid] ]—This

option displays specified log entries to the console during package execution

name),G(source GUID), X(execution GUID), M(message), and T(time start and end)

only the source names or GUIDs that are specified are logged The value Especifies

the exclusion list With this value set, the source names or GUIDs that are specified

are not logged The src_name_or_guidparameter specified for inclusion or exclusion

is an event name, a source name, or a source GUID

/~D¥ package_path—This option is used to load a package from the SSIS package

store The package_pathargument 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 The /DTSoption cannot be used together with the /Fileor/SQLoption

/~De[crypt] password—This option provides the decryption password used when

you load a package with password encryption

/~F[ile]filespec—This option is used to load a package saved at the filesystem

level The filespecargument specifies the path and filename of the package

/~L[ogger]classid_orprogid;configstring—This option associates one or more log

providers with the execution of an SSIS package The classid_orprogidparameter

specifies the log provider and can be specified as a class GUID.configstringis the

string used to configure the log provider

Following are 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—This option is used to identify the

number of executable files the package can run concurrently The value specified

must be either a non-negative integer or –1 With a value of –1, SSIS allows a

maximum number of concurrently running executables equal to the total number of

processors on the computer executing the package, plus two

/~P[assword] password—This option is used together with the /Useroption to

retrieve the package from SQL Server If the /Passwordoption is omitted and the

/Useroption is used, a blank password is used

/~Rem comment—This option creates a comment on the command prompt or in

command files The comment is a string that must be enclosed in quotation marks,

and it must contain no whitespace

/~Rep[orting] level [;event_guid_or_name[;event_guid_or_name[ ]]—This

option identifies what types of messages to report Available reporting option levels

areN(no reporting), E(errors are reported), W(warnings are reported), I

(informa-tional messages are reported), C(custom events are reported), D(data flow task events

are reported), P(progress is reported), and V(verbose reporting; all details of each

type) If the /Reportingoption is not specified, the default level is E,W, and P

/~Res[tart] {deny | force | ifPossible}—This option enables you to set a new

value for the CheckpointUsageproperty on the package The possible values are Deny

(sets the CheckpointUsageproperty to DTSCU_NEVER),Force(sets the

CheckpointUsageproperty to DTSCU_ALWAYS), and ifPossible(sets the

CheckpointUsageproperty to DTSCU_IFEXISTS)

/~Set propertyPath;value—This option overrides the configuration of a variable,

property, container, log provider, Foreachenumerator, or connection within a

package When this option is used, /SETchanges the propertyPathargument to the

value specified You can specify more than one /SEToption at a time

/~Ser[ver] server—This option identifies the name of the server from which to

retrieve the package If you do not specify the /Serveroption, the package

execu-tion is attempted against the local server

/~SQ[L] package_path—This option is used to load a package stored in SQL Server

(in the msdbdatabase)

/~Su[m]—This option displays the incremental counter that contains the number of

rows that will be received by the next package component

/~U[ser] user_name—This option identifies the SQL Server user ID needed to

retrieve the package

/~Va[lidate]—This option is used to complete the validation phase of package

execution only The package is not executed

/~VerifyB[uild] major[;minor[;build]]—This option is a verification of the build

number of a package against the build numbers specified during the verification

phase in the major, minor, and build arguments If a mismatch occurs, the package

does not execute These values are long integers

/~VerifyP[ackageID] packageID—This option verifies the GUID of the package to

be executed by comparing it to the value specified in thepackage_idargument

/~VerifyS[igned]—If specified, this option causes the package to fail if the package

is not signed

/~VerifyV[ersionID] versioned—This option verifies the version GUID of a

package to be executed by comparing it to the value specified in the version_id

argument during the package validation phase

/~W[arnAsError]—This option cause the package to consider a warning as an error.

In other words, the package fails if a warning occurs during validation If no

warn-ings occur during validation and the /Validateoption is not specified, the package

is executed

Running Package Examples

To execute an SSIS package saved to SQL Server using Windows authentication, you use

the following code:

dtexec /SQL UnleashedPackage1SQL /SER DBARCH-LT2\SQL08DE01

To execute an SSIS package saved to the package store (on the filesystem), you use the

following code:

dtexec /DTS “\File System\UnleashedPackage99PS”

To execute an SSIS package saved in the filesystem, you use the following code:

C:> dtexec /FILE “C:\HotCustomerPlus.dtsx”

/MAXCONCURRENT “ -1 “ /CHECKPOINTING OFF /REPORTING EWCDI

Figure 52.43 shows the command prompt and subsequent execution of the

HotCustomersPlus.dtsxSSIS package Now, the package can be set up for regular batch

execution using SQL Agent or any scheduling software

To execute an SSIS package saved in the filesystem and specify logging options, you use

the following code:

C:> dtexec /FILE “C:\HotCustomerPlus.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 to verify the version before it is executed, you use the

following code:

dtexec /sq UnleashedPackage1 /verifyv {b399e360-38c5-11c5-99x1-ae62-08002b2b79ef}

The dtutil Utility

You use the dtutilcommand-line utility to copy, move, delete, or verify the existence of a

package These actions can be performed on any SSIS package, regardless of whether it is

stored in a Microsoft SQL Server database, the SSIS package store, or at the filesystem

Thedtutiloptions are additive Depending on what you are trying to do, you string one

or more options and their values together in the following form:

dtutil /option [value] [/option [value]]

To show available options for dtutil, you use ’/?’or’/H’or’/Help’, as follows:

c:> dtutil /?

Note that a dash (-) may be substituted for / in this command

FIGURE 52.43 Command-line execution of an SSIS package

Alternatively, you can see the details for a particular option by using the available options

indicator followed by the option name (’/?’[option name]) This invokes SQL Server

Books online for that particular option

Thedtutiloptions include the following:

/~C[opy][StorageLocation];[PackageName]—This option identifies where the

package is to be stored (StorageLocationvalue of DTS,FILE, or SQL) and the full

destination path and filename of the package (PackageName) When the Copyaction

encounters an existing package at the destination, dtutilprompts you to confirm

package deletion Yoverwrites the package, and Naborts the overwrite of the

destina-tion package If you include the /Q(quiet) option, no prompt appears, and the

exist-ing destination package is overwritten

/~Dec[rypt] Password—This option sets the decryption password used when

loading a package with password encryption

/~Del[ete]—This option deletes the package specified by theSQL,DTS, orFILEoption

/~DestP[assword] Password—This option specifies the password used with the

SQLoption to connect to a destination SQL Server instance using SQL Server

authentication

/~DestS[erver] Server—This option specifies the server name used with any action

that causes a destination to be saved to SQL Server or a nonlocal or nondefault

server when saving an SSIS package

/~DestU[ser] User name—This option specifies the SQL Server username at the

destination SQL Server instance

/~DT[S] PackagePath—This option specifies that the SSIS package referenced is

located in the SSIS package store, and the PackagePathargument is a relative path

that commences at the root of the SSIS package store

/~En[crypt] [StorageLocation];[;Path;ProtectionLevel[;Password]—This

option encrypts the loaded package with the specified protection level and password

and saves it to the location specified in Path.StorageLocationtypes are DTS,FILE,

andSQL.ProtectionLeveldetermines whether a password is required

The possible ProtectionLevelvalues are 0(strips sensitive information), 1(sensitive

information is encrypted using local user credentials), 2(sensitive information is

encrypted using the required password), 3(package is encrypted using the required

password),4(package is encrypted using local user credentials), and5(package uses

SQL Server storage encryption)

/~Ex[ists]—This option is used to determine whether a package exists.

/~FC[reate] [StorageLocation];FolderPath;NewFolderName—This option creates a

new folder with the name specified by NewFolderName.StorageLocationisSQLor

DTSonly The location of the new folder is indicated by FolderPath

/~FDe[lete] [StorageLocation] ExistingFolderPath;ExistingFolderName—This

option deletes the folder specified by the name in ExistingFolderNamefrom SQL

Server (SQL) or SSIS (DTS).StorageLocationisSQLorDTSonly The location of the

folder to delete is indicated by ExistingFolderPath

/~FDi[rectory] [StorageLocation] FolderPath[;S]]—This option lists the

contents, both folders and packages, in a folder on SSIS (DTS) or SQL Server (SQL)

The optional ExistingFolderPathparameter specifies the folder whose contents you

want to view StorageLocationisSQLorDTSonly The optional Sparameter specifies

that you want to view a listing of the contents of the subfolders for the folder

speci-fied in ExistingFolderPath

/~FE[xists] [StorageLocation] ExistingFolderPath—This option verifies

whether the specified folder exists on SSIS (DTS) or SQL Server (SQL) The

ExistingFolderPathparameter is the path and name of the folder for which you

need to verify its existence StorageLocationisSQLorDTSonly

/~FR[ename] [StorageLocation]; ExistingFolderPath; ExistingFolderName;

NewFolderName—This option renames a folder on the SSIS (DTS) or SQL Server (SQL)

StorageLocationisSQLorDTSonly ExistingFolderPathis the location (path) of

the folder to rename ExistingFolderNameis the name of the folder to be renamed,

andNewFolderNameis the new name to give the folder

/~Fi≤PathName—This option specifies that the SSIS package to be operated on is

located in the filesystem, and the PathNamevalue contains either a universal naming

convention (UNC) path or local path

/~I[DRegenerate]—This option creates a new GUID for the package and updates the

package ID property

/~M[ove] [StorageLocation]; PathandName—This option specifies a move action

for an SSIS package StorageLocationmay be DTS,FILE, or SQL.PathandName

indi-cates the package path (location) and/or package name: SQLuses the package path

and package name, FILEuses a UNC or local path, and DTSuses a location relative to

the root of the SSIS package store If an existing package at the destination has the

same name, dtutilprompts you to answer Yto overwrite this existing package or N

to not do the move If you specify the /Q(quiet) option, no prompt appears when

an existing package may exist at the move destination, and it is just overwritten

/~Q[uiet]—This option disables the Y/Nprompts when a package with the same

name as the specified package already exists at the destination location or if the

specified package is already signed

/~R[emark] [Text]—This option is a comment to the command line There can be

multiple remarks in a command line

/~Si[gn] [StorageLocation]; ExistingPath; Hash—This option signs an SSIS

package.StorageLocationmay be DTS,FILE, or SQL.ExistingPathspecifies the path