ptg 2134 CHAPTER 52 SQL Server Integration Services 10. To execute the package, double-click the .dtsx file, 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. ptg 2135 The Package Execution Utility 52 NOTE You could also execute this new package by using the dtexec utility at a command prompt: C:> dtexec /FILE “C:\HotCustomerPlus.dtsx” The Package Execution Utility The dtsrun utility in SQL Server 2000 is no longer used within SQL Server 2008. It has been taken over by the dtexec utility, 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 dtexec utility, 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 dtsrun command-line options have direct dtexec equivalents, such as the options for providing a server name or package name or for setting the value of a variable. Other dtsrun command-line options don’t have direct dtexec equivalents. In addition, some dtexec command-line options support features in SSIS, such as the options to pass in connection strings and manage checkpoints. You can create new command-line dtexec executions 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, .dtsx file), you are always placed in this dtexecui environment (just as you automatically start up Microsoft Word when you double-click a Word document). The dtexec Utility You use the dtexec command-line utility to configure and execute 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 (package store) ptg 2136 CHAPTER 52 SQL Server Integration Services 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 The dtexec utility 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. ptg 2137 The Package Execution Utility 52 2. Package-loading phase—The package specified by the /SQL, /FILE, or /DTS option 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 /VALIDATE option was specified. 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 an operating system batch file. The dtexec utility can set the following exit code values: Running Packages The dtexec options 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. The dtexec package execution options include the following: . /~CheckF[ile] filespec—This option sets the CheckpointFileName property on the package to the path and file specified in filespec. This file is used when the package restarts. . /~CheckP[ointing]{on\off}—The value on specifies 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 on if the option is declared without a value. Package execution fails 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. 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. ptg 2138 CHAPTER 52 SQL Server Integration Services NOTE Using 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—This option specifies that during the command sourc- ing phase of the utility, the file specified in filespec is opened, and options from the file are read until the EOF is found in the file. filespec is a text file that contains additional dtexec command options. The filespec argument 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. The displayoptions values are N (name), C (computer), O (operator), S (source name), G (source GUID), X (execution GUID), M (message), and T (time start and end). One list_options value is I, which specifies the inclusion list. With this value set, only the source names or GUIDs that are specified are logged. The value E specifies the exclusion list. With this value set, 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, 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_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. The /DTS option cannot be used together with the /File or /SQL option. . /~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 filespec argument 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_orprogid parameter specifies the log provider and can be specified as a class GUID. configstring is the string used to configure the log provider. Following are the available log providers: ptg 2139 The Package Execution Utility 52 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 /User option to retrieve the package from SQL Server. If the /Password option is omitted and the /User option 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 are N (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 /Reporting option 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 CheckpointUsage property on the package. The possible values are Deny (sets the CheckpointUsage property to DTSCU_NEVER), Force (sets the CheckpointUsage property to DTSCU_ALWAYS), and ifPossible (sets the CheckpointUsage property to DTSCU_IFEXISTS). . /~Set propertyPath;value—This option 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. You can specify more than one /SET option at a time. ptg 2140 CHAPTER 52 SQL Server Integration Services . /~Ser[ver] server—This option identifies the name of the server from which to retrieve the package. If you do not specify the /Server option, 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 msdb database). . /~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 the package_id argument. . /~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 /Validate option 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 ptg 2141 The Package Execution Utility 52 Figure 52.43 shows the command prompt and subsequent execution of the HotCustomersPlus.dtsx SSIS 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 dtutil command-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. The dtutil options 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. ptg 2142 CHAPTER 52 SQL Server Integration Services 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. The dtutil options include the following: . /~C[opy][StorageLocation];[PackageName]—This option identifies where the package is to be stored ( StorageLocation value of DTS, FILE, or SQL) and the full destination path and filename of the package ( PackageName). When the Copy action encounters an existing package at the destination, dtutil prompts you to confirm package deletion. Y overwrites the package, and N aborts 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 the SQL, DTS,orFILE option. . /~DestP[assword] Password—This option specifies the password used with the SQL option 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 PackagePath argument 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. StorageLocation types are DTS, FILE, and SQL. ProtectionLevel determines whether a password is required. The possible ProtectionLevel values 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), and 5 (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. StorageLocation is SQL or DTS only. The location of the new folder is indicated by FolderPath. ptg 2143 The Package Execution Utility 52 . /~FDe[lete] [StorageLocation] ExistingFolderPath;ExistingFolderName—This option deletes the folder specified by the name in ExistingFolderName from SQL Server ( SQL) or SSIS (DTS). StorageLocation is SQL or DTS only. 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 ExistingFolderPath parameter specifies the folder whose contents you want to view. StorageLocation is SQL or DTS only. The optional S parameter 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 ExistingFolderPath parameter is the path and name of the folder for which you need to verify its existence. StorageLocation is SQL or DTS only. . /~FR[ename] [StorageLocation]; ExistingFolderPath; ExistingFolderName; NewFolderName—This option renames a folder on the SSIS (DTS) or SQL Server (SQL). StorageLocation is SQL or DTS only. ExistingFolderPath is the location (path) of the folder to rename. ExistingFolderName is the name of the folder to be renamed, and NewFolderName is 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 PathName value 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. StorageLocation may be DTS, FILE, or SQL. PathandName indi- cates the package path (location) and/or package name: SQL uses the package path and package name, FILE uses a UNC or local path, and DTS uses a location relative to the root of the SSIS package store. If an existing package at the destination has the same name, dtutil prompts you to answer Y to 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/N prompts 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. StorageLocation may be DTS, FILE, or SQL. ExistingPath specifies the path . {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. specified by the SQL, DTS,orFILE option. . /~DestP[assword] Password—This option specifies the password used with the SQL option to connect to a destination SQL Server instance using SQL Server authentication. . /~DestS[erver]. “C:HotCustomerPlus.dtsx” The Package Execution Utility The dtsrun utility in SQL Server 2000 is no longer used within SQL Server 2008. It has been taken over by the dtexec utility, which is bigger and