DTS Packages and Steps P ART V 526 You can extend the flexibility of DTS by managing packages programmatically. You can man- age packages with any programming language that supports COM. This chapter focuses on managing packages with Visual Basic and with the OLE Automation system stored procedures available in SQL Server. Much of the information in this chapter is also relevant to other programming languages. Many of the chapters in this book have examples that show how to use Visual Basic with DTS. Chapter 12, “The Execute SQL Task,” and Chapter 18, “The Execute Package Task,” have examples of using the OLE Automation stored procedures. Chapter 30, “Programming with the DTS Object Model,” has a summary of the programming objects available in DTS. Chapters 31, “Creating a Custom Task with VB,” and 32, “Creating a Custom Transformation with VC++,” show how to extend DTS functionality by programming custom tasks and custom transformations. Working with DTS Packages in Visual Basic You have many advantages when you use Visual Basic with DTS instead of using the DTS management tools built into SQL Server 2000: • The ability to integrate DTS functionality with the rest of your application. • More flexibility in responding to errors generated by DTS. •A more convenient development environment for writing programming code. There are also some disadvantages: • The DTS Designer and the DTS Wizard generate many DTS objects automatically. A good deal of programming is needed to re-create these structures using Visual Basic. • The DTS Designer gives a visual representation of the programmatic flow in the data transformation. This visual representation is missing when you work with DTS in Visual Basic. Because there are distinct advantages to working with DTS in Visual Basic and to working with the SQL Server 2000 DTS design tools, the best development strategy often uses both. Because you can save a package as Visual Basic code, you can quickly move from one envi- ronment to the other. Installation Requirements The earliest version of Visual Basic you can use with DTS in SQL Server 2000 is 5.0 with Service Pack 3. You also have to install the SQL Server client tools on both your development computer and all the computers that are going to be running the packages. 32 0672320118 CH26 11/13/00 4:59 PM Page 526 Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark. Saving a Package to Visual Basic It’s usually easiest to start the development of a DTS package with the DTS Wizard or the DTS Designer. When you want to work with the package’s objects from Visual Basic, you can save the package to Visual Basic code. You can do this from both the DTS Wizard and the DTS Designer. The Save DTS Package dialog from the DTS Designer is shown in Figure 26.1. Managing Packages with Visual Basic and Stored Procedures C HAPTER 26 26 M ANAGING P ACKAGES WITH V ISUAL B ASIC 527 F IGURE 26.1 The DTS Designer and the DTS Wizard both allow you to save a package as a Visual Basic code file. There are several reasons why you might want to save a package to Visual Basic: •To search for and replace variable names, DTS object names, data structure names, or server names throughout a package. •To verify or modify a particular setting for a property in all objects of a package. •To merge two or more packages (although you have to avoid conflicts with object names and connection ID values when you do this). • So that you can continue development of the package in the Visual Basic development environment. •To dynamically modify and execute the package as a part of a Visual Basic application. •To learn about programming with the DTS object model. There is one significant problem in saving a package to Visual Basic—you lose the package’s visual display if you open it up again with the Package Designer. The DTS Package Designer provides an excellent graphical user interface for displaying the flow of a data transformation application. You can place connection, task, and workflow icons in the places that most clearly illustrate what is happening in the data transformation. 32 0672320118 CH26 11/13/00 4:59 PM Page 527 Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark. This visual display is lost if you save a package to Visual Basic and then execute the Visual Basic code to save the package to one of the other three forms of storage. SaveToSQLServer , SaveToStorageFile , and SaveToRepository all have a parameter called pVarPersistStgOfHost , which is used to store a package’s screen layout information. Unfortunately, this parameter can only be referenced internally by the DTS Designer. It is not possible to use this parameter from Visual Basic to save or re-create the package’s visual dis- play in the designer. When a package is saved from Visual Basic using any of the DTS Save methods, the default layout is created. The wizards also use the default layout. This layout is fine for simple pack- ages, but it’s usually inadequate for more complex ones. Figure 26.2 shows a complex package in the DTS Designer before it’s saved to Visual Basic. Figure 26.3 shows the same package after it has been saved from Visual Basic and then opened again in the DTS Designer. DTS Packages and Steps P ART V 528 F IGURE 26.2 A complex DTS package before being saved to Visual Basic. (Sample package from Microsoft OLAP Unleashed.) 32 0672320118 CH26 11/13/00 4:59 PM Page 528 Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark. F IGURE 26.3 The same DTS package after being saved from Visual Basic with no changes. Managing Packages with Visual Basic and Stored Procedures C HAPTER 26 26 M ANAGING P ACKAGES WITH V ISUAL B ASIC 529 If I have a package with a complex layout and I want to make a global change of a name or a property, I often use an ActiveX Script inside the package to make the change. The loss of the package’s layout makes me avoid using the Visual Basic saving option for simple changes in complex packages. N OTE Setting Up the Visual Basic Design Environment You can create a package in Visual Basic using any one of these project types: •Standard EXE • ActiveX EXE • ActiveX Document EXE • ActiveX DLL • ActiveX Document DLL 32 0672320118 CH26 11/13/00 4:59 PM Page 529 Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark. Code Libraries Needed for DTS You will need to add references to some or all of the following libraries: •Microsoft DTSPackage Object Library (dtspkg.dll)—Required for all DTS packages. •Microsoft DTSDataPump Scripting Object Library (dtspump.dll)—Almost always required. It contains the built-in transformations and the DTS scripting object. •Microsoft DTS Custom Tasks Object Library (custtask.dll)—Contains the Message Queue task, the FTP task, and the Dynamic Properties task. • DTSOLAPProcess (msmdtsp.dll)—Contains the Analysis Services Processing task. • DTSPrediction (msmdtsm.dll)—Contains the Data Mining Prediction task. • OMWCustomTasks 1.0 Type Library (cdwtasks.dll)—Contains the Transfer Databases task and the four associated transfer tasks. Starting a Project with a Package Saved to Visual Basic When you save a package to Visual Basic, a code module (*.bas) is created. Here is one of the ways you can use that code module in Visual Basic: 1. Open Visual Basic and create a new Standard EXE project. 2. Select References from the Project menu. Add the object libraries that are needed for your package. 3. Add the saved DTS code module to the project. 4. You can remove the default form from the project, if you want. It’s not needed. 5. The code module contains code for both executing the package and saving it to SQL Server. When the code module is created, the line to save the package is commented out, so the package is executed but not saved. The Structure of the Generated DTS Visual Basic Code Module The book’s CD has a simple DTS package stored in a file called Save To VB Demo Package.dts. This package has been saved to a Visual Basic code module called Save To VB Demo Package.bas. All the sample code in this section comes from this code module. The code module that’s generated when you save a package to Visual Basic has the following elements: • Header information • Declaration of public variables • Main function DTS Packages and Steps P ART V 530 32 0672320118 CH26 11/13/00 4:59 PM Page 530 Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark. • One function to create each of the tasks • One function to create each of the transformations in the transformation tasks Header Information The Visual Basic code module for a DTS task starts with header information that describes the creation of the module. The header for the Save To VB Demo Package is shown in Listing 26.1. L ISTING 26.1 The Header for a DTS Visual Basic Code Module ‘**************************************************************** ‘Microsoft SQL Server 2000 ‘Visual Basic file generated for DTS Package ‘File Name: C:\Temp\Save To VB Demo Package.bas ‘Package Name: Save To VB Demo Package ‘Package Description: Save To VB Demo Package ‘Generated Date: 8/8/2000 ‘Generated Time: 8:25:24 AM ‘**************************************************************** Declaration of Public Variables The code module declares two public variables, one for a Package object and the other for a Package2 object. It’s necessary to have a Package2 object so that the extended features in SQL Server 2000 can be accessed. The Package object is needed to handle events in Visual Basic. Handling DTS events in Visual Basic is described in the “Executing a Package from Visual Basic” section later in this chapter. The public variable declarations are shown in Listing 26.2. L ISTING 26.2 The Declaration of Public Variables in a DTS Visual Basic Code Module Option Explicit Public goPackageOld As New DTS.Package Public goPackage As DTS.Package2 Main Function The Main function has five sections: • Set package properties •Create package connections Managing Packages with Visual Basic and Stored Procedures C HAPTER 26 26 M ANAGING P ACKAGES WITH V ISUAL B ASIC 531 32 0672320118 CH26 11/13/00 4:59 PM Page 531 Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark. •Create package steps •Create package tasks •Save or execute package The function begins by setting the properties of the DTS package as a whole, as shown in Listing 26.3. L ISTING 26.3 Setting the Package Properties at the Beginning of the Main Function Private Sub Main() set goPackage = goPackageOld goPackage.Name = “Save To VB Demo Package” goPackage.Description = “Save To VB Demo Package” goPackage.WriteCompletionStatusToNTEventLog = False goPackage.FailOnError = False goPackage.PackagePriorityClass = 2 goPackage.MaxConcurrentSteps = 4 goPackage.LineageOptions = 0 goPackage.UseTransaction = True goPackage.TransactionIsolationLevel = 4096 goPackage.AutoCommitTransaction = True goPackage.RepositoryMetadataOptions = 0 goPackage.UseOLEDBServiceComponents = True goPackage.LogToSQLServer = False goPackage.LogServerFlags = 0 goPackage.FailPackageOnLogFailure = False goPackage.ExplicitGlobalVariables = False goPackage.PackageType = 0 DTS Packages and Steps P ART V 532 The generated code sets many properties of DTS objects, which you don’t have to explicitly set when you’re creating a DTS package in Visual Basic. For example, to cre- ate, execute, and save this package, you only have to identify the Package2 object with the Package object and give the package a name: Set goPackage = goPackageOld goPackage.Name = “Save To VB Demo Package” N OTE The next section has the code that creates the DTS connections, as shown in Listing 26.4. 32 0672320118 CH26 11/13/00 4:59 PM Page 532 Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark. L ISTING 26.4 Code to Create the DTS Connections ‘----------------------------------------------------- ‘ create package connection information ‘----------------------------------------------------- Dim oConnection as DTS.Connection2 ‘------------- a new connection defined below. ‘For security purposes, the password is never scripted Set oConnection = goPackage.Connections.New(“SQLOLEDB”) oConnection.ConnectionProperties(“Integrated Security”) = “SSPI” oConnection.ConnectionProperties(“Persist Security Info”) = True oConnection.ConnectionProperties(“Initial Catalog”) = “pubs” oConnection.ConnectionProperties(“Data Source”) = “(local)” oConnection.ConnectionProperties(“Application Name”) = _ “DTS Designer” oConnection.Name = “Pubs Connection” oConnection.ID = 1 oConnection.Reusable = True oConnection.ConnectImmediate = False oConnection.DataSource = “(local)” oConnection.ConnectionTimeout = 60 oConnection.Catalog = “pubs” oConnection.UseTrustedConnection = True oConnection.UseDSL = False ‘If you have a password for this connection, ‘please uncomment and add your password below. ‘oConnection.Password = “<put the password here>” goPackage.Connections.Add oConnection Set oConnection = Nothing Managing Packages with Visual Basic and Stored Procedures C HAPTER 26 26 M ANAGING P ACKAGES WITH V ISUAL B ASIC 533 The generated code sets several properties twice—once as objects in the ConnectionProperties collection and once as properties of the Connection2 object. You can use either method when you create connections in Visual Basic. When you create a connection, you have to specify the properties that identify the data source and the security that is needed to access that data source. You usually don’t have to set the other properties— Reusable , ConnectionTimeOut , and UseDSL . One of the most important properties is ConnectionID because it is used to identify the connection when it is used with a particular text. N OTE 32 0672320118 CH26 11/13/00 4:59 PM Page 533 Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark. The next section, shown in Listing 26.5, creates the DTS steps. L ISTING 26.5 Code to Create the DTS Steps ‘------------------------------------------------------ ‘ create package steps information ‘------------------------------------------------------ Dim oStep as DTS.Step2 Dim oPrecConstraint as DTS.PrecedenceConstraint ‘------------- a new step defined below Set oStep = goPackage.Steps.New oStep.Name = “DTSStep_DTSExecuteSQLTask_1” oStep.Description = “Update Authors” oStep.ExecutionStatus = 1 oStep.TaskName = “DTSTask_DTSExecuteSQLTask_1” oStep.CommitSuccess = False oStep.RollbackFailure = False oStep.ScriptLanguage = “VBScript” oStep.AddGlobalVariables = True oStep.RelativePriority = 3 oStep.CloseConnection = False oStep.ExecuteInMainThread = False oStep.IsPackageDSORowset = False oStep.JoinTransactionIfPresent = False oStep.DisableStep = False oStep.FailPackageOnError = False goPackage.Steps.Add oStep Set oStep = Nothing DTS Packages and Steps P ART V 534 Most of the step properties can be set by default. Here’s the basic code needed to create this step: Set oStep = goPackage.Steps.New oStep.Name = “DTSStep_DTSExecuteSQLTask_1” oStep.TaskName = “DTSTask_DTSExecuteSQLTask_1” goPackage.Steps.Add oStep Set oStep = Nothing N OTE 32 0672320118 CH26 11/13/00 4:59 PM Page 534 Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark. The next section, shown in Listing 26.6, calls individual functions that create the tasks. These separate functions are located at the end of the code module. L ISTING 26.6 Code That Calls the Functions to Create the DTS Tasks ‘---------------------------------------------------- ‘ create package tasks information ‘---------------------------------------------------- ‘call Task_Sub1 for task DTSTask_DTSExecuteSQLTask_1 (Update Authors) Call Task_Sub1(goPackage) ‘---------------------------------------------------- ‘ Save or execute package ‘---------------------------------------------------- The Main function concludes with code to save the package to SQL Server and execute the package. (See Listing 26.7.) The command that saves the package is commented out when the file is generated. To save the package, you have to uncomment the command and change the server name, username, and password to the appropriate values. Of course, you could also replace the SaveToSQLServer method with SaveToFile or SaveToRepository . L ISTING 26.7 The Last Section of the Main Function Has Code to Save and/or Execute the Package ‘goPackage.SaveToSQLServer “(local)”, “sa”, “” goPackage.Execute goPackage.Uninitialize ‘to save a package instead of executing it, comment out the _ ‘executing package line above and uncomment the saving package line set goPackage = Nothing set goPackageOld = Nothing End Sub Functions to Create the Tasks The code module ends with individual functions that create the tasks for the package. The sam- ple module creates one simple Execute SQL task, as shown in Listing 26.8. Much more code is needed to create any of the transformation tasks. Separate individual functions are created for each of the transformations in a transformation task. Managing Packages with Visual Basic and Stored Procedures C HAPTER 26 26 M ANAGING P ACKAGES WITH V ISUAL B ASIC 535 32 0672320118 CH26 11/13/00 4:59 PM Page 535 Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark. [...]... “DTSExecuteSQLNamespace”, _ SQLNSRootType _Server, CStr(sConnection), hWnd ‘Get a reference to the root node (the Server) hServer = SQLNS.GetRootItem ‘Get a reference to the Data Transformation Services node hDTS = SQLNS.GetFirstChildItem( _ hServer, SQLNSOBJECTTYPE_DTSPKGS) ‘Get a reference either to the Local Packages ‘ or the Meta Data Services packages node If bSQLServerStorage = True Then hPackages = SQLNS.GetFirstChildItem(... DTSSQLStgFlag_UseTrustedConnection, , , , sPackageName Else pkg.LoadFromSQLServer sServer, sUserID, sPassword, _ DTSSQLStgFlag_Default, , , , sPackageName End If ‘Modify the package pkg.Description = “New description for package” ‘Save the package If sUserID = “” Then pkg.SaveToSQLServer sServer, , , _ DTSSQLStgFlag_UseTrustedConnection Else pkg.LoadFromSQLServer sServer, sUserID, sPassword, _ 26 MANAGING PACKAGES WITH... fctDTSExecuteSQLNamespace function You can find this code on the CD in a Visual Basic project with the files DTSExecuteSQLNS.vbp, DTSExecuteSQLNS.bas, and DTSExecuteSQLNS.frm LISTING 26.12 A Function That Executes a Package with SQL Namespace ‘Project must include a reference to the ‘ Microsoft SQLNamespace Object Library ‘This Object Library implemented in Mssql7\Binn\Sqlns.dll Public Function fctDTSExecuteSQLNamespace(... method The method’s parameters can be used either by name or by position The following code uses the LoadFromSQLServer method to load a DTS package: EXEC @hResult = sp_OAMethod @hPkg , ‘LoadFromSQLServer’ , NULL , @ServerName = @sServerName, @ServerUserName = @sServerUserName, @ServerPassword = @sServerPassword, @Flags = @lFlags, @PackageName = @sPackageName Using sp_OAGetProperty and sp_OASetProperty... string If sServer = “” Then sConnection = Server= .;” Else sConnection = Server= ” & End If If sUser = “” Then sConnection = sConnection Else sConnection = sConnection sConnection = sConnection End If ‘Local server sServer & “;” & “Trusted_Connection=Yes;” & “UID=” & sUser & “;” & “pwd=” & sPassword & “;” ‘Initialize the SQL Namespace, using the Server as the root node SQLNS.Initialize “DTSExecuteSQLNamespace”,... sPackageName As String, _ Optional sServer As String = “”, _ Optional sUser As String = “”, _ Optional sPassword As String = “”, _ 544 DTS Packages and Steps PART V LISTING 26.12 Continued Optional bSQLServerStorage As Boolean = True) As Long On Error GoTo ProcErr Dim sqlns As New SQLNamespace Dim sqlnsObject As SQLNamespaceObject Dim Dim Dim Dim Dim hWnd As Long hServer As Long hDTSPackages As Long... SQLNS.GetFirstChildItem( _ hDTS, SQLNSOBJECTTYPE_DTS_LOCALPKGS) Else Managing Packages with Visual Basic and Stored Procedures CHAPTER 26 LISTING 26.12 Continued ‘Get a reference to the particular package hPackage = SQLNS.GetFirstChildItem( _ hPackages, SQLNSOBJECTTYPE_DTSPKG, sPackageName) ‘Set the package to be a SQL Namespace object Set sqlnsObject = SQLNS.GetSQLNamespaceObject(hPackage) ‘Execute the package sqlnsObject.ExecuteCommandByID... fctDTSExecuteSQLNamespace that executes a DTS package using SQL Namespace You have to specify a package name You can also supply the name of the server where the package is stored, the username and password needed to access that server, and whether or not the package is stored in SQL Server storage The function defaults to the local server, integrated security, and SQL Server storage The function returns 0 if successful... DECLARE @sPackageName varchar(255) DECLARE @sServerName varchar(255) DECLARE @sServerUserName varchar(255) DECLARE @sServerPassword varchar(255) DECLARE @lFlags int Enter name of package and access information SET @sPackageName = ‘TestOA’ SET @sServerName = ‘(local)’ SET @sServerUserName = ‘’ SET @sServerPassword = ‘’ SET @lFlags = 256 256 For Trusted, 0 for SQL Server Security Integers used as object... OUT, @desc OUT SELECT Info = ‘Create Package’, Source= RTrim(@src), _ Description=@desc END Load package SET @sMethod = ‘LoadFromSQLServer’ EXEC @hResult = sp_OAMethod @hPkg , @sMethod , NULL , @ServerName = @sServerName, @ServerUserName = @sServerUserName, @ServerPassword = @sServerPassword, @Flags = @lFlags, @PackageName = @sPackageName IF @hResult 0 BEGIN EXEC sp_OAGetErrorInfo NULL, @src OUT, @desc . pkg.LoadFromSQLServer sServer, , , _ DTSSQLStgFlag_UseTrustedConnection, , , , sPackageName Else pkg.LoadFromSQLServer sServer, sUserID, sPassword, _ DTSSQLStgFlag_Default,. node (the Server) hServer = SQLNS.GetRootItem ‘Get a reference to the Data Transformation Services node hDTS = SQLNS.GetFirstChildItem( _ hServer, SQLNSOBJECTTYPE_DTSPKGS)