Chapter 7. Package

Package

This chapter discusses many of the package-level properties and methods, including transactions, execution methods, properties, and storage locations. Some of these properties enable or change the implementation of properties in connections, tasks, or workflows.

You can use the properties of the package to affect package execution, package transactions, and package logging. The properties are package-specific in that they affect the entire package. Some of the properties of tasks and workflows are dependant on properties set up in the package (see “Transactions” later in this chapter). To access these properties, choose Properties from the Package menu, or right-click an unoccupied area of the workspace and choose Package Properties from the shortcut menu. Either action opens the Package Properties dialog box.

The Package Properties dialog box has four tabs: General, Global Variables, Logging, and Advanced (see Figure 7.1). Each of the options on these tabs will be discussed in detail the following sections.

The Package Properties dialog box.

Figure 7.1. The Package Properties dialog box.

General Properties

The General tab has three sections of properties. Most of the properties on this tab are read-only; some of them can be set in other areas of the package. The first section contains the descriptors for the package, including the Name, Description, Package GUID, and Version GUID. The name is set when you save the package (see “Package Storage Locations” later in this chapter). You can add or edit the description of the package in this tab. The two GUIDs are used to identify the package and its current version. (You can store multiple versions in SQL Server Local Packages, Meta Data Services Packages, and the Structured Storage file.) The version GUID will be the same as the package GUID if it is the first and only version.

The next section is the Creation area, where you can find the creator of the package. The creator is stored in Windows networking domainusername format. The next field is the Win32 computer name of the machine on which the package was created. After that, you can find the date and time the package was created.

The Execution Parameters section allows you to set the Windows process priority. The default is Normal, but you can set it for High or Low. You also can set the maximum number of tasks to be executed in parallel. The number you use here can increase or decrease the efficiency of the package, depending on how the steps are set up. If you set this number too high and have a high number of steps being executed in parallel, it will significantly slow the execution of the package. If you set the value too low, it will negatively impact a package that has a number of steps set up for simultaneous execution.

Global Variables

The Global Variables tab has a table that allows you to change the names, types, and initial values of these global variables. You can use these variables many places in the package. (See Chapter 4, “DTS Tasks,” specifically the section on the ActiveX task, for some of the types of usage available) The values that you set in this tab are saved with the package. This is also true if the value is changed during the execution of the package. If the value is changed, the new value will show up in this dialog box after the package has run.

You can use this attribute to set and recover values that have been used in the execution of the package. These variables are in scope for the duration of the execution of the package. This tab also allows you to enforce explicit declaration of all variables in all scripts in the package (similar to the Option Explicit declaration in Visual Basic).

Logging

You set package-logging properties in the Logging tab of the Package Properties dialog box. The DTS package log can be used to track down any problems or errors that occurred during the execution of a package. The log tracks the execution or lack of execution of individual steps in the package. You can see whether any given step succeeded, failed, or did not run. (Although steps that do not run are not listed in the log, their absence from the log shows that they did not run.) This information is stored in msdb tables in SQL Server (package information in the sysdtspackagelog table, step information in the sysdtssteplog table) or in SQL Server Meta Data Services (package information in Package Tab in the DTS Meta Data node of Enterprise Manager).

You can save the log in any instance of SQL Server 2000. You can use the properties to specify which server instance you will use and how you will access the server (Windows Authentication or SQL Server Authentication, username and password). In this frame you can also choose to fail the package on a log error. You might want to use this option if your process requires that the package be logged.

You can view the log by right-clicking the package in the detail of the Local Packages or Meta Data Services Packages in Enterprise Manager and choosing Package Logs from the shortcut menu. This brings up the DTS Packages Logs dialog box, which allows you to select and open any package log available in this location (see Figure 7.3). You can then view the log (see Figure 7.4), which displays the step details and allows you to view more information (if available) and the error information on steps that failed due to errors. Any step that is executed is displayed with a red cross for failure or a green check for success. Steps that are not run will not be included in the log.

List of available logs.

Figure 7.3. List of available logs.

The package log details with error details showing.

Figure 7.4. The package log details with error details showing.

Custom Task and ActiveX Script Task Logging

The PackageLog object allows you to log custom tasks in the sysdtstasklog table. (See Chapter 16, “Creating Your Own Custom Task,” for more information on creating a custom task.) When you create a custom task, the package log is included in CustomTask_Execute as a parameter, as follows:

Private Sub CustomTask_Execute(ByVal pPackage As Object, _ 
    ByVal pPackageEvents As Object, ByVal pPackageLog As Object, _ 
    pTaskResult As DTS.DTSTaskExecResult) 
... 
pPackageLog.WriteStringToLog "Task Successful" 
... 

The DTSPackageLog scripting object provides a way for ActiveX scripts to add log entries into the sysdtstasklog table by using script, as follows:

Dim objLog 
Set ObjLog = DTSPackageLog 
ObjLog.WriteStringToLog "Task Successful" 

In both cases, you can view the log data by clicking the More Info button in the Log Data dialog box.

Table 7.1 defines the values in the Run Status column. The remaining columns add further detail about the step as it was executed (times, step names, and error information).

Table 7.1. Run Status Codes in the Package Log

Run Status

Description

1

Step Waiting

2

Step In Progress

3

Step Inactive

4

Step Completed

Error Handling

The Error Handling properties are located in the Logging tab of the Package Properties dialog box. You can set three properties. First, you can set the location of the error file.

Sample of Error File

Notice in this example log file, the executed package wrote information to the package log about all steps in the package, whether or not an individual step ran. If a step ran, it will retain start and end times, and the step execution time. For steps that did not run, the log lists the steps and notes that the step was not executed.

The execution of the following DTS package succeeded:

Package Name: DTS Test 1 
Package Description: (null) 
Package ID: {805C300A-C3BC-4B5C-B068-F223E76C9B0C} 
Package Version: {A2E9689C-F3EC-4FD9-9CE3-48D912764D5F} 
Package Execution Lineage: {24890402-01BC-4F62-BEDC-CF8B3ACF667C} 
Executed On: STEVEHLAPTOP 
Executed By: SteveH 
Execution Started: 2/13/2001 11:14:18 AM 
Execution Completed: 2/13/2001 11:14:25 AM 
Total Execution Time: 7.03 seconds 

Package Steps execution information: 


Step 'DTSStep_DTSDataPumpTask_2' succeeded 
Step Execution Started: 2/13/2001 11:14:18 AM 
Step Execution Completed: 2/13/2001 11:14:24 AM 
Total Step Execution Time: 5.888 seconds 
Progress count in Step: 1 

Step 'DTSStep_DTSActiveScriptTask_1' succeeded 
Step Execution Started: 2/13/2001 11:14:18 AM 
Step Execution Completed: 2/13/2001 11:14:18 AM 
Total Step Execution Time: 0.631 seconds 
Progress count in Step: 0 

Step 'DTSStep_DTSSendMailTask_1' was not executed 

Step 'DTSStep_DTSExecuteSQLTask_1' failed 

Step Error Source: Microsoft JET Database Engine 
Step Error Description:The Microsoft Jet database engine could not find the object 
'test'. Make sure the object exists and that you spell its name and the path name 
correctly. 
Step Error code: 80040E37 
Step Error Help File: 
Step Error Help Context ID:5003011 

Step Execution Started: 2/13/2001 11:14:24 AM 
Step Execution Completed: 2/13/2001 11:14:25 AM 
Total Step Execution Time: 0.33 seconds 
Progress count in Step: 0 
******************************************************************************* 

Second, you can set the package to fail on the first error. When this option is selected, the package will result in failure if an error occurs in any step. This option is important if you are tracking the successful completion of the package for any reason. If you do not select this option, the package can have steps fail but will result in the successful completion of the package.

When this happens, a package that is using Execute Package tasks with precedence constraints may not work as expected. The Execute Package tasks will receive the success notice from the executed package even if steps in the package fail. This could also affect you if you are executing dependent steps that are running in parallel. To stop the parallel processes, you should fail the package when any step fails. You can also use this property to help manage transactions, as discussed in the following section.

Finally, you can set the package to write the completion status of the package to the application event log in Windows NT or Windows 2000 (see Figure 7.5).

Completion status written to the Windows application event log.

Figure 7.5. Completion status written to the Windows application event log.

Full Text in Event Log

Recording package execution status to the Windows application log can be beneficial if you want to leverage existing enterprise monitoring tools that use the Windows application log for their source data. To view the Windows application log, go to the Start menu and point to Programs/Administrative Tools, and then click Event Viewer. Click Application on the Log menu. Microsoft SQL Server events are identified by the entry MSSQLSERVER in the Source column. SQL Server Agent events are identified by the entry SQLSERVERAGENT. You can also create a filtered view on SQL Server events by pointing to the View menu, clicking Filter Events, and in the Source list, selecting MSSQLSERVER and or SQLSERVERAGENT. To view more information about a specific event, double-click the event. The code that follows is the full text in event log:

Event Type:   Information 
Event Source:   DataTransformationServices 
Event Category:   None 
Event ID:   80 
Date:   2/13/2001 
Time:   11:22:07 AM 
User:   N/A 
Computer:   STEVEHLAPTOP 
Description: 
The execution of the following DTS Package succeeded: 

Package Name: DTS Test 1 
Package Description: (null) 
Package ID: {805C300A-C3BC-4B5C-B068-F223E76C9B0C} 
Package Version: {A2E9689C-F3EC-4FD9-9CE3-48D912764D5F} 
Package Execution Lineage: {BB2E2B80-221F-40E6-B57A-8B4AC931698B} 
Executed On: STEVEHLAPTOP 
Executed By: SteveH 
Execution Started: 2/13/2001 11:22:04 AM 
Execution Completed: 2/13/2001 11:22:07 AM 
Total Execution Time: 3.365 seconds 

Package Steps execution information: 


Step 'DTSStep_DTSDataPumpTask_2' succeeded 
Step Execution Started: 2/13/2001 11:22:04 AM 
Step Execution Completed: 2/13/2001 11:22:07 AM 
Total Step Execution Time: 2.804 seconds 
Progress count in Step: 1 

Step 'DTSStep_DTSActiveScriptTask_1' succeeded 
Step Execution Started: 2/13/2001 11:22:04 AM 
Step Execution Completed: 2/13/2001 11:22:04 AM 
Total Step Execution Time: 0.391 seconds 
Progress count in Step: 0   
Step 'DTSStep_DTSSendMailTask_1' was not executed 

Step 'DTSStep_DTSExecuteSQLTask_1' failed 

Step Error Source: Microsoft JET Database Engine 
Step Error Description:The Microsoft Jet database engine could not find the object 
'test'. Make sure the object exists and that you spell its name and the path name 
correctly. 
Step Error code: 80040E37 
Step Error Help File: 
Step Error Help Context ID:5003011 

Step Execution Started: 2/13/2001 11:22:07 AM 
Step Execution Completed: 2/13/2001 11:22:07 AM 
Total Step Execution Time: 0.05 seconds 
Progress count in Step: 0 

Transactions

DTS has the capability to use transactions with the packages. You can use transactions to keep data in multiple servers consistent, to incorporate multiple tasks or steps into a single unit, to put multiple transactions in a single package, or to control errors in a asynchronous environment. Transactions are not available for all tasks or connection types (see the sidebar “Supported Connection and Task Types” in this section), and for transactions to work, MS DTC must be running on the computer on which the package is to be executed. Many reasons for using transactions exist, but several properties need to be set up in the workflows and in the package for them to work correctly. When you use transactions, carefully analyze how you are setting up your packages and transaction properties to prevent many of the anomalies that can occur.

Supported Connection and Task Types

The connection types are as follows:

  • Microsoft OLE DB Provider for SQL Server. This is the standard OLE DB provider for SQL Server, which implements transactions.

  • ODBC data source. The ODBC driver must support the attribute SQL_ATT_ENLIST_IN_DTC, and this attribute must be set. See the ODBC driver documentation for more information.

  • Microsoft Data Link. The data link can access any OLE DB driver. The driver must implement the ItransactionJoin interface if you want it to join a distributed transaction. See the OLE DB driver documentation for more information.

If you need to establish more than one transaction in the package, you need to establish a new connection for each transaction. A connection can participate in only one connection at a time.

Following are the task types. These tasks can join package transactions:

  • Bulk Insert task

  • Data Driven Query task

  • Transform Data task

  • Execute Package task

  • Execute SQL task

These tasks support their own local or distributed transactions but cannot join package transactions.

These transactions are created in code and not supported by DTS directly:

  • Microsoft ActiveX Script task

  • Execute Process task

These tasks do not support transactions because when they are completed, they cannot be rolled back:

  • File Transfer Protocol task

  • Dynamic Properties task

  • Send Mail task

  • Copy SQL Server Objects task

  • Message Queue task

All these tasks can commit or roll back transactions. At this time, however, custom tasks cannot participate in transactions.

Uses for DTS Transactions

The uses for DTS transactions are:

  • To collect data from multiple tasks and apply them to the data destination in a single transaction. This method is especially helpful for data that is related but handled in separate tasks, such as uploading shipments and new inventory counts.

  • To update different servers consistently. By setting up transactions for updates to each data destination, you will be able to keep the data on multiple servers consistent.

  • To control errors in an asynchronous environment by using Message Queue tasks. When you use transactions, you can resend the message if some portion of the task fails and roll back any database changes that depend on the Message Queue task. For more information on the Message Queue, see Chapter 15, “Managing Distributed Databases with DTS and Message Queues.”

Use Execute Package tasks to control multiple transactions. By setting up transactions in each of the packages, you will be able to control the sequence of transactions via the main package.

The Transactions section of the Advanced tab of the Package Properties dialog box has three properties that you need to set to use transactions in the package.

To activate transactions in the package, check the Use Transactions check box. Checking this option enables the other options in this section and enables the use of transactions in the workflows. If this option is not checked, any requests from the workflows to join a transaction will be ignored.

The next property to set is Commit on Successful Package Completion. When you choose this property, all open transactions will commit when the package completes if either of the following statements is true:

  • No steps have failed.

  • The Fail Package on First Error check box is cleared.

The last property to set on the Advanced tab is Transaction Isolation Level. This property determines the locking level used in the transactions to isolate the user from dirty reads, nonrepeatable reads, and phantom data. Table 7.2 shows the isolation levels with increasing degrees of protection, from Chaos to Serializable. The default in SQL Server including DTS is Read Committed. Refer to the isolation levels section of SQL Server Books On Line (BOL) for more information.

Table 7.2. Transaction Isolation Levels (from Least to Greatest)

Transaction Isolation Level

Description

Chaos

Anything goes; no protection.

Read Uncommitted

Updates can be lost. Only physically corrupt data will not be read.

Read Committed

Lowest level; does not lose updates. Does not accept dirty reads.

Repeatable Read

No dirty or nonrepeatable reads.

Serializable

Transactions are completely isolated. No dirty or nonrepeatable reads; no phantom data.

On the Advanced tab of the Package Properties dialog box, you should set the Fail Package on First Error option when you are using transactions. By selecting this option, you force a package to return an error on a failed step; therefore, it will correctly roll back the transaction. (Refer to “Error Handling” earlier in this chapter for more details.)

You also can set properties that affect transactions on workflows. By using the workflow properties, you can have steps join a transaction, roll back the transaction on step failure, and commit the transaction on successful completion of the step. See Chapter 6, “DTS Workflows,” for more information.

Transaction Scenarios

When you use transactions in DTS, you must be aware that different combinations of steps and workflows affect how the transaction will be initiated and committed. Sometimes, you need many steps participating in the same transactions; at other times, you need to use many transactions. Each situation has a different setup to keep you from getting anomalous data. Please understand that much care is necessary to set up transactions in DTS packages successfully.

Sequential Tasks

First, you should try to organize the package steps sequentially. This layout is the simplest one to use with transactions (see Figure 7.6). By using precedence constraints, you can establish that all tasks must succeed to commit the transaction. Set the package property to use transactions. Then set all the steps to join a transaction, if present, and to roll back the transaction on the step failure. In the final step, set the property to commit the transaction on the successful completion of the step.

Sequential tasks in a transaction.

Figure 7.6. Sequential tasks in a transaction.

Parallel Tasks

Sometimes, you may find it necessary to execute steps in parallel. If you need to have these steps be part of the same transaction, you need to plan the layout carefully to prevent anomalous results. First, use DTS package failure to roll back the transaction in the case of any step failure. Next, carefully consider whether you need more than one connection. If you need only one connection, SQL Server will serialize the execution of the steps in spite of the parallel configuration, which means that the precedence relationship will be enforced, but not the order of execution. If you need two connections, and these connections are on different data sources (in particular, different SQL Server instances), the tasks configured in parallel will execute as expected: in parallel. If the connections refer to the same data source—in this case, the same SQL Server instance—you can set the Execute on Main Package Thread workflow property or use precedence constraints to ensure that the package does not fail when the tasks try to join the transaction.

You need to manage the package carefully to prevent unexpected and undesirable results. Suppose that you have three tasks, A, B, and C. Two of these tasks execute from one connection, SQL1, and one executes from the second connection, SQL2 (see Figure 7.7).

Parallel tasks using transactions.

Figure 7.7. Parallel tasks using transactions.

If tasks A and C execute simultaneously and task C fails, task A continues to successful completion.Task C’s failure causes the transaction to roll back, so the work from A and C is rolled back. However, because task A completed successfully, task B will start, joining a new transaction, and then will commit the transaction if the package property Commit on Successful Package Completion is set. For this reason, you must set Fail Package on First Error for the package. This property causes all steps that haven’t started not to execute; then the rollback occurs as expected on all tasks currently participating in the transaction.

Branching Workflows

If you find it necessary to initiate certain tasks based on the success or failure of a series of parallel steps, you will want to branch your processes based on the success or failure of the transaction. In the previous example, we had three tasks that were part of a transaction in a package that would fail on the first error. To branch the process, use the Execute Package task and precedence to determine the next step (see Figure 7.8). For this package, clear the Fail Package on First Error check box so that the failure of the Execute Package step will be returned and precedence followed. You also need to check Use Transactions for the package.

Branching transactions using an Execute Package task.

Figure 7.8. Branching transactions using an Execute Package task.

In Figure 7.8, you see that if the ABC package fails, an email task is executed, but on success, task D will execute. Table 7.3 shows the various properties you can set to have the tasks use transactions in different ways.

Table 7.3. Branching Transactions: Step Properties to Be Set

 

Join Transaction

Commit Transaction

Rollback Transaction

Tasks A, B, C, D in same transaction

PackageABC Task D

PackageABC Task D

PackageABC Task D

Tasks A, B, C, in different transaction than task D

Task D

Task D

Task D

Checkpointing for Multiple Transactions

At times, you might be able to divide the work in a package logically into separate transactions. In that case, you would want to use a method of checkpointing to handle the transactions (see Figure 7.9). You set up the steps to participate in the first transaction and then, using precedence relationships, step to an ActiveX Script task. No code needs to be placed in this task, because it is only a placeholder. You set the workflow properties on the task to join the transaction and to commit the transaction upon the successful completion of this step. By doing so, you can insulate the transactions and have better control of the process. When the ActiveX Script task completes successfully, the next steps can continue, joining a new transaction if necessary.

Using ActiveX Script tasks as checkpoints.

Figure 7.9. Using ActiveX Script tasks as checkpoints.

Inheriting Transactions

In DTS, you can use the Execute Package task to inherit transactions. You do so by creating packages that use transactions and then running them in a parent package with the Execute Package task. By enabling the Join Transaction If Present feature in the Options tab of the Workflow Properties dialog box, a package can inherit the parent package’s transaction if the package is part of an Execute Package Task that has joined the transaction (Join Transaction If Present). When this situation occurs, all the steps in the subpackages that have joined the transactions are included in the transaction.

Using inherited transactions changes the way transactions are handled in the subpackages. Steps in the child package join the parent package transaction so that no new package transaction is created. The properties that call for committing the transaction on the successful completion of the step or package are ignored. No rollback will occur when the package completes even if an error occurs. However, if you set the workflow to rollback the transaction on step failure, it will rollback the parent transaction. Be sure to set the Fail Package on First Error property for the subpackages. This property prevents the Execute Package Task from returning success when a step in a subpackage fails.

For more information on DTS transactions, search for DTS transactions in Microsoft SQL Server BOL.

Miscellaneous Properties

The remaining properties in the Advanced tab of the Package Properties dialog box are Lineage, Scanning Options, and OLE DB. The Lineage and Scanning Options are closely related to the Meta Data Repository, which is covered in Chapter 18, “Data Lineage.”The OLE DB property determines how OLE DB data objects are instantiated.

Lineage

The first option is Show Lineage As a Source Column. This option adds global data-lineage variables to the package but does not write them to Meta Data Services until the Write Lineage to Repository option is selected. Just showing the lineage allows you to create a custom task that can work with the lineage tracking and auditing information. Only when the write option is selected will the lineage be saved to the repository each time the package is saved. The lineage data is used to implement row-and column-level logging, which is discussed in more detail in Chapter 18.

Scanning Options

The Scanning Options dialog box provides several properties related to how the DTS package’s meta data is scanned for the repository. These options are discussed in detail in Chapter 18 in the “Scanning Options” section.

OLE DB

The only option that you can implement here is Use OLE DB Service Components. When this option is selected (which is the default), the package instantiates the OLE DB data-source objects by using the OLE DB service components, which can increase both the functionality and the performance of the OLE DB data provider. (Refer to the OLE DB provider documentation for provider-specific information.)

Some data providers support only forward-only scrolling, for example. By using the service components, you can enable the consumer to scroll within the data set by using the client cursor engine. (The client cursor engine also supports the use of Find in the data set.)

You also can enable session pooling by using the service components, which can improve the performance of the package. (You can learn more about the OLE DB service components at http://msdn.microsoft.com/library/psdk/dasdk/oled0cs7.htm.) The DTS providers (PackageDSO, RowQueue, and FlatFile) and the Microsoft OLE DB Provider for SQL Server ignore this setting. If the check box is cleared, the data-source objects are instantiated directly with CoCreateInstance; thus, the services are not available.

Disconnected Edit

In DTS Designer, right-click the design sheet, and then click Disconnected Edit to bring up the Edit All Package Properties dialog box. The Edit All Properties dialog consists of two parts: The layout of the package appears in the left pane, and the properties related to the selected component in the component appear in the right pane (see Figure 7.10).

Edit All Properties.

Figure 7.10. Edit All Properties.

Some of the properties in this Edit All Properties dialog box (such as task, step, and connection names) are not available in the Properties dialog boxes of the objects themselves. You can use Disconnected Edit to change the properties of a package when the source or destination is not available. DTS tries to connect to the data sources or destinations to validate the connection information; Disconnected Edit allows you to bypass this protection feature.

Using Disconnected Edit is dangerous because you can edit many properties in the package without DTS validating the changes. If you edit them here, there is no guarantee that the changes will work when the package is executed. Use Disconnected Edit only if you are very comfortable with most of the components of DTS and if this tool is the only way to edit the properties you need to modify.

Package Storage Locations

You can save a package in a number of ways. Each storage location has certain advantages, which are discussed later in this chapter. When you save the package initially, or use the Save As option, the Save DTS Package dialog box allows you to save to different locations via the Location drop-down menu (see Figure 7.11). You need to understand that each time you choose Save As from the File menu, the package GUID will change, not just the version GUID.

Package storage locations.

Figure 7.11. Package storage locations.

SQL Server

You can use SQL Server to save the package to the sysdtspackages table (see the “Sample Record from sysdtspackages” sidebar in this section) in the msdb database on the selected server instance. When you save the package here, it will appear in the Enterprise Manager tree below the Data TransformationLocal Packages node.

When you save in SQL Server, versions are established each time the package is saved. The first time the package is saved, the package GUID and the version GUID (visible in the General tab of the Package Properties dialog box; refer to Figure 7.1) are the same GUID.When the package is edited and resaved, the version GUID changes. You will not be prompted to save the new version if the package has already been saved, because SQL Server will save the package as a new version by default. This allows you to keep a record of the changes made in a package and also allows you to specify which version to run so that you can continue development while allowing the production package (such as an earlier version) to execute. This location is by far the most convenient and simplest way to save and maintain versions.

Sample Record from sysdtspackages

The actual packages that are stored in SQL Server are located in the msdb database in SQL Server. Following is a sample package record from the sysdtspackages table in msdb:

name       DTS Test 1 
id        805C300A-C3BC-4B5C-B068-F223E76C9B0C 
versionid     2896CDE1-47C8-4FB0-9A93-965B119AE15A   
description    Test package 
categoryid    B8C30002-A282-11D1-B7D9-00C04FB6EFD5 
createdate    2000-12-05 01:11:05.003 
owner       MINNEAPOLISSteveH 
packagedata    {Image} 
owner_sid     0x01 
packagetype    0 

Meta Data Services

This option saves the package in the Meta Data Repository of any valid SQL Server 2000 instance (in SQL Server 7.0 this was called SQL Server Repository). For more detailed information on using Meta Data Services with DTS packages, see Chapter 18.You can open a package saved as meta data in the Data TransformationMeta Data Services Packages node of Enterprise Manager.

Structured Storage File

You can use this option to save the DTS package to a .dts file. The Structured Storage File is the most portable of the various storage options, because you can copy and transfer the file quite easily. The file is called a structured file because it uses COM-structured storage. If you are doing a great deal of package editing and then saving the package to the same file, the file can become quite large because each version is saved. When you save the package in a structured storage file, you are prompted for a filename. If you create a new file, the package has only one version: the current one. If you choose an existing filename, you will be prompted to add the current package to the existing file, creating a new version of the file. In the SQL Server Enterprise Manager console tree, right-click on the Data Transformation Services folder. Then click Open Package from the context menu. In the Select File dialog box, click the file you want, and then click Open. If multiple versions of the DTS Package were created, the Select Package dialog box appears where you can click the package or package version you want to open (see Figure 7.12).

Opening a package stored in a structured storage file

Figure 7.12. Opening a package stored in a structured storage file

Visual Basic File

SQL Server 2000 also allows you to save the package to a .bas file. You can open this file in Visual Basic and edit it in the Visual Studio development environment.When the package has been stored to Visual Basic, it cannot be edited with SQL Server. The package can be executed only programmatically through Visual Basic or its compiled program. By saving the package to this location, you are also able to see the syntax of the DTS objects that can be programmed.

Package Security

When you save a package to SQL Server or a structured storage file, you can secure it beyond the Windows authentication or SQL server authentication levels. When you save the package, you can assign owner and user passwords. When you assign an owner password, you need to use this password to edit or run the package. To assign a user password, you need to assign an owner password. Using both passwords allows a user to run the package, but the user will not have permission to edit or to open the package. Microsoft recommends that you apply this security option to further secure both the package and the database, especially if you are not using Windows authentication for data access.

Connection Security

Some security issues are specifically related to the connection objects in DTS. First, if you use Microsoft Data Link files (.udl), you should use Windows Authentication for database access. The reason is that Data Links require you to enter the SQL Server username and password when you use SQL Server Authentication. This information is stored in unsecured form in the file. The level of access that the SQL Server user has determines how much of a security breach exists. However, if you use Windows Authentication, it sets a flag in the UDL file, making the access information secure.

Second, when you use SQL Server connection objects, DTS persists the authentication details with the package. If you still need to prevent persisted security details, you can turn off the Persist Security Info option in the Advanced Connection Properties dialog box for the SQL Server connection. Please be aware that this option is available only for a SQL Server connection; setting it to False can cause other problems when you are working in secure environments. To prevent problems with persisted security information, you should use Windows NT Authentication, because no usernames or passwords are persisted with the package.

Package Execution

You can execute a package from three locations: Enterprise Manager, a DTS tool, and the command line. In Enterprise Manager, you can execute local and Meta Data Services packages by right-clicking on the selected package located in the details pane of the Enterprise Manager Console tree and selecting Execute from the context menu.

You can execute a package from the two primary DTS tools: the DTS Designer and DTS Import/Export Wizard. From an open package, you can execute the package from one of three locations in the DTS Designer. First, you can click the Execute button on the toolbar. Second, you can choose Execute from the Package menu. Third, you can execute the package by right-clicking a blank space on the DTS Designer window and choosing Execute from the shortcut menu. You also can execute a package at the end of the DTS Import/Export Wizard by selecting the Run Immediately option and clicking Finish.

Microsoft provides two utilities for executing the package from a command line. The DTS Run utility can be accessed by typing dtsrunui without any command switches. This will bring up the DTS Run dialog box (see Figure 7.13), which allows you to select the location of the package, the package name and version, and the location details. After the package has been selected you can Run or Select a scheduled task to run. (The Run and Schedule buttons remain disabled until a valid package version is selected.)

DTS Run dialog box.

Figure 7.13. DTS Run dialog box.

Clicking the Advanced button gives you access to global variables, logging information, and command-line information. You can edit the global variables temporarily by adding new ones or editing existing ones. These global-variable changes are valid only for the current DTS Run session and are not saved when the session is closed.

You also can select the log file and specify whether to write the completion status of the package to the event log. For the command line, you can choose to encrypt the command for use in the next utility, dtsrun.exe. In addition, you can have the line generated in SQL Server 7.0 format. When you click the Generate button, the utility will create a command line for dtsrun.exe that has the selected properties applied. You can use this generated command line in the next utility described by copying and pasting it into a command line.

Command-Line Formats Generated from DTS Run

When you generate a command line from the DTS Run utility (dtsrunui.exe) to execute a DTS package using dtsrun.exe, you are presented with different options that determine the format of the command line.

This command line is created when you select no options:

DTSRun /S "(local)" //N "DTS Test 1" //V "{A2E9689C-F3EC-4FD9-9CE3-48D912764D5F}" //W 
"0" //E 

This command line is created when you select SQL Server 7.0 Format only:

DTSRun /S "(local)" //N "DTS Test 1" //V "{A2E9689C-F3EC-4FD9-9CE3-48D912764D5F}" //E 

This command line is created when you select Encrypt the Command only:

DTSRun 
/∼Z0x4050833D40908D31188F436727E340111E360047CC10CBD59BC560636ABBED22B630673340E95 
049A1FC69CE0D3AD96854F2101F3C3C763B24F05A0E779B2C395BE7D572B60289D3ED997FF2B3ECD0F 
5EF0C89358B354DFF1B6A21189C3114774E283B4486379A18A06195C5FDB5C4E52E2C498359EF43DA4 
20D288956D4DC2FBA62214FC8696EDAC8B08F2E09E860768DA74C59A4210AC1CB09714F7194E7CC12D 
9C563C2536029F25662CD72DA508B5098CC8CA960FAA083CC96 

This command line is created when you select Encrypt the Command and SQL Server 7.0 Format together:

DTSRun /∼S 0xBD02B5BE90E2B90926828A12F24175AA /∼N 
0x64C9C49314125FB980EC63C075EACCD8FCBD1CF0E8A295B5 /∼V 
0xD751BE59BF32E3D7BB500A00CE73B349219F0597C886C9C9FFAD32B71BC6C02648EF197C56B976B2 
92871661BA8FA7A2089F804E9D9A58EB66C920CE6F82CC21008194D41AB757A2CF6A2662FFDB60E9 
/E 

The other utility is dtsrun.exe. This utility has no graphic components and several switches (see Table 7.4) that give you more control over the execution of the package. You can generate the command line with switches by using the dtsrun utility as mentioned in the previous paragraph. From this utility, you can execute packages stored in the SQL Server msdb, structured storage files, and SQL Server Meta Data Services.

Table 7.4. dtsrun Utility Command-Line Switches

Switch

Value to Enter

Description

/?

 

Displays the command-line options.

 

Specifies that the value following the switch is encrypted.Valid with /S, /U, /P, /N, /G, /V, /M, /F, and /R.

/S

server_name [instance_name]

Specifies the server to use. If you includeonly server_name, the default instance will be used. To use another instance, use this format: server_nameinstance_ name.

/U

user_name

SQL Server login used to connect to SQL Server.

/P

Password

SQL Server password used with the login to connect to SQL Server.

/E

 

Use trusted connection (Windows Authentication).

/N

package_name

Name of the package to be run.

/G

package_guid_string

Package ID assigned to the package when it was saved.

/V

package_version_guid_string

Version ID assigned to the package when it was saved.

/M

package_password

Either the owner or user password assigned to the package.

/F

Filename

Name of the structured storage file being executed. If a server_name is also given, the SQL Server package is executed and then added to the structured storage file.

/R

repository_database_name

Name of the repository database to use. If no name is given, the default database is used.

/A

global_variable_name: typeid=value

Use this option to create and set multiple global variables in the package if you have Owner permission. Refer to BOL for valid type identifiers.

/L

log_file_name

Name of the package log file if it is to be different from the one stored in the package.

/W

Windows_Event_Log

True = Use event log. False = Do not use event log.

/Z

 

Specifies that the command line has been encrypted with SQL Server 2000 encryption.

/!X

 

Prevents the package from being executed. You can use this option when you want to create an encrypted command line but do not want to execute the package.

/!D

 

Deletes a package from an instance of SQL Server.

/!Y

 

Displays the encrypted command line for executing the package without executing the package.

/!C

 

Copies the command line to Microsoft Windows Clipboard.

Notes on dtsrun Command-Line Switches

You can use encrypted options by adding a tilde (∼) after the slash and before the option switch.

The switch for global variables (/A) is the option that allows multiple values. For all other options, the last value will be the one used by the utility.

Any spaces between the switch and the values are optional and will be ignored. If the values contain embedded spaces, the values need to be embedded between double quotation marks.

All the execution methods described in this section return various levels of detail about the success or failure of the package that is being executed. When you are executing a package from the DTS tools, the Enterprise Manager, or the DTS Run utility (dtsrunui.exe, not dtsrun.exe), a dialog box opens when the package runs. The Executing DTS Package dialog box (see Figure 7.14) shows each step in the package and the status, start time, finish time, and execution time for each step. (The status text varies according to the task being executed.)

Executing DTS Package dialog box.

Figure 7.14. Executing DTS Package dialog box.

If the package has Execute Package Tasks, this dialog box does not display the steps from each Execute Package Task. Some information from the steps is displayed as the tasks execute in the status line above the progress bar. From this dialog box, you can cancel the package. The package does not quit running immediately, however; it waits until any steps that do not support canceling complete. To view this information later, you need to refer to the package log.

If an error is encountered when you use the dtsrun utility from the command line, the package will stop executing and display error information and usage instructions. No dialog box is displayed when you use this utility. This is very helpful when you are trying to execute the package by using batch files or scheduled tasks in Windows and do not want any graphical interfaces involved.

Package Scheduling

You can schedule packages to run at specific times and in specific patterns. If you need to run a package nightly, monthly, or even hourly, you can do so by setting up a SQL Server Job. The easiest way to do this is by right-clicking on the package in the detail pane of the Local Packages or Meta Data Services Packages folder in the SQL Server Enterprise Manager console tree. If the SQL Server Agent is not running when you try to schedule it, you will receive a warning; then you can proceed to set up the schedule (see Figure 7.15). You can set a Recurring Job Schedule the same way that you would set up a recurring job in SQL Server.

Scheduling a package.

Figure 7.15. Scheduling a package.

After you set up a job, you can edit it in the Management/SQL Server Agent/Jobs section of Enterprise Manager. You also can view the Job History here. However, editing the actual job step is difficult because the wizard uses the encrypted dtsrun command line. On the other hand, you can create the job manually in the Jobs section of the Enterprise Manager by creating an Operating System Command (CmdExec) step that uses the dtsrun utility. You can find details on the various formats and syntaxes used with dtsrun.exe in “Package Execution” earlier in this chapter. (Remember that you can use the DTS Run utility, dtsrunui.exe, to generate the command line.)

To create and execute this SQL Server job successfully, the SQL Server agent must have the security permissions to run operating-system commands from within SQL Server (via CmdExec or xp_cmdshell). If you need to schedule your package but cannot grant the necessary permissions to the agent, see the sidebar “Alternative to SQL Server Jobs for Scheduled Packages.”

SQL Server jobs also have logging available. The first level of job logging is displayed in the detail view of the job listing in the Jobs detail of the Enterprise Manager. You can see the details of the last job, run as well as details on the current and future status of the job, including whether the job is enabled, runnable, or scheduled and when it is scheduled to run again. The next level of logging allows you to view the job history, which contains the detailed history of the job. Here you can look for specifics about why a job fails. Checking the job history for errors before troubleshooting your package is important. If you were able to execute the package from Enterprise Manager but not through the scheduler, you are most likely to find the problem in the job history. For more information about SQL Server jobs, refer to the BOL topic “Creating Jobs.”

Alternative to SQL Server Jobs for Scheduled Packages

Sometimes, you need to secure the SQL Server Agent to the point that you will not be able to execute packages in scheduled jobs. A workaround is to create a Windows Scheduled Task and use the dtsrun command-line utility to execute the package. Launch the Scheduled Task wizard by double-clicking Scheduled Tasks in Control Panel, and then double-clicking Add Scheduled Tasks. You can schedule a task to run daily, weekly, or monthly, change the schedule for a task, and customize how a task runs at a scheduled time. The first step in the Scheduled Task wizard is to click on Browse and select the dtsrun executable using the following pathname: [SQL Server Folder]80ToolsBinndtsrun.exe).

Next, add a name, select the frequency of the task, choose the start time and date, and add the username and password to run the task. When these properties are entered, check the Advanced Properties check box, and click Finish. The Properties dialog box for the task opens. At this point, you need to edit the Run text to include all the appropriate command switches and parameters. Now that you have scheduled the package successfully, you can track its success or failure through the package logs in SQL Server Data Transformation Services.

Package Deletion

Deleting a package is fairly simple. To delete the entire package from SQL Server or Meta Data Services, right-click the package and choose Delete from the shortcut menu. You need to be the owner or a member of the sysadmin fixed server role to delete the package or a version of the package. You can delete any version of a package that has been saved to SQL Server. You can delete the most recent package only if it is stored in Meta Data Services. To delete versions, right-click the package and choose Versions from the shortcut menu. When the DTS Package Versions dialog box opens, select the package version and click Delete. You cannot delete individual versions from packages stored in a structured storage file or a Visual Basic file.

Summary

Using the information provided in this chapter, you should be able to make good decisions on which package properties are necessary to fulfill your needs. Whether the package needs to be portable (storage locations), needs to implement transactions, or needs to be executed on a schedule, you should be able to choose the options necessary to get the desired result. For information on advanced logging of packages, see Chapter 14, “Custom Error Logging with DTS,” and Chapter 18, “Data Lineage.”

..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset
18.119.112.160