Microsoft SQL Server 2000 Data Transformation Services- P9

Set cus = tsk.CustomTask With cus .Name = “tsk” & sBaseName .Description = sBaseName End With pkg.Tasks.Add tsk ‘Create step for task Set stp = pkg.Steps.New With stp .Name = “stp” & sBaseName .Description = sBaseName .TaskName = tsk.Name End With pkg.Steps.Add stp fctCreateDynamicPropertiesTask = stp.Name Set tsk = Nothing Set cus = Nothing Set stp = Nothing ProcExit: Exit Function ProcErr: MsgBox Err.Number & “ - “ & Err.Description fctCreateDynamicPropertiesTask = “” GoTo ProcExit End Function Conclusion The Dynamic Properties task improves the level of control within a DTS package. The next two chapters describe the two tasks that give you control between packages—the Execute Package task and the Message Queue task. Control Tasks P ART IV 376 L ISTING 17.1 Continued 22 0672320118 CH17 11/13/00 4:57 PM Page 376 Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark. CHAPTER 18 The Execute Package Task IN THIS CHAPTER • When to Use the Execute Package Task 378 •Creating the Task and Setting Its Properties 379 • Setting Values of Global Variables in the Child Package 380 • The NestedExecutionLevel Property of the Package 383 •Creating and Calling a Utility DTS Package 384 •Creating the Task in Visual Basic 387 23 0672320118 CH18 11/13/00 5:04 PM Page 377 Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark. Control Tasks P ART IV 378 The Execute Package task lets you execute one DTS package from another. When to Use the Execute Package Task Here are some reasons you might want to divide your DTS functionality between several packages: • The packages have become too complex. They will be easier to understand if the tasks are divided between several packages. •You have a task or group of tasks that performs a utility function. This functionality can be put into a separate package so that the same code can be used by several packages. • Some of the DTS functionality needs to have a higher level of security. You can put that functionality into a separate package where it can be executed but not viewed or edited. There are several ways to execute one package from another, in addition to using the Execute Package task. This task is the easiest way to execute another package, but some of the other ways have additional functionality. Here are the other possibilities: •Use DTSRun from an Execute Process task. If you use an encrypted command line, you can hide all the parameters used in the execution, including the name of the server, pack- age, and user. •Use the DTS object model from an ActiveX Script task. You can change the properties of the package and its tasks before executing the package. You can read the values of global variables after executing the package. •Use OpenRowset to query a package from an Execute SQL task. You can return a record- set from the child package when you use this strategy. •Use the OLE Automation stored procedures from an Execute SQL task. This strategy allows you to execute a package from the context of a remote server. You can also mod- ify the properties before executing and read the values of global variables after executing, as when you use the object model from an ActiveX Script task. You can set the values of global variables in the child package when you use the Execute Package task and in all but one of the other strategies. Using OpenRowset from an Execute SQL task is the only method that does not allow you to set the values of global variables in the package you are executing. You can only receive values back from a child package when you use the DTS object model in an ActiveX Script task or with the OLE Automation stored procedures in an Execute SQL task. You cannot receive values of global variables back from a child package when you use the Execute Package task. 23 0672320118 CH18 11/13/00 5:04 PM Page 378 Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark. One of the most important advantages of using the Execute Package task rather than one of the other methods is that you can include parent and child packages together in transactions. To enable transactions that span packages, you have to do the following: • Ensure that transactions are enabled for the package as a whole. The package transaction properties are set on the Advanced tab of the DTS Package Properties dialog. •In the Workflow Properties dialog for the step associated with the Execute Package task, select the Join Transaction If Present option. • The Microsoft Distributed Transaction Coordinator client must be running on all the computers that are executing one of the packages. There is more information about using transactions in DTS packages in Chapter 24, “Steps and Precedence Constraints.” Creating the Task and Setting Its Properties You can create the Execute Package task in the Package Designer or in code. The last section of this chapter shows how to create the task in code. The Package Designer’s Execute Package Task Properties dialog is shown in Figure 18.1. The Execute Package Task C HAPTER 18 18 T HE E XECUTE P ACKAGE T ASK 379 F IGURE 18.1 You choose package and connection information on the General tab of the Execute Package Task Properties dialog. 23 0672320118 CH18 11/13/00 5:04 PM Page 379 Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark. Most of the properties of the Execute Package task are concerned with package and connection information. You set these properties on the General tab of the Execute Package Task Properties dialog: • Description —The description of the task. • FileName —The file from which the DTS package is to be loaded. When the DTS pack- age is not stored in a file, this property should be an empty string. • UseRepository —If FileName is an empty string and this property is TRUE ,the package is loaded from the repository. If FileName is an empty string and this property is FALSE ,the package is loaded from SQL Server storage. • RepositoryDatabaseName — The database that contains the instance of Meta Data Services from which the package is to be retrieved. This property is only used for a pack- age loaded from the repository. If it is an empty string, the database that contains the default instance of Meta Data Services is used. • PackageName , PackageID , VersionID — You choose the package and version from those available in the storage location you have specified. When you choose a package, the Execute Package task will always use the most current version of that package. If you choose a particular version of a package, the task will always use the same version, whether or not new versions are created. The value of these three properties is displayed in the interface. To change the Package or Version ID, you have to pick a new item in the Select Package dialog. • PackagePassword — Either the owner password or the user password can be used to exe- cute the package. • ServerName — The server on which the DTS package is stored. • ServerUserName , ServerPassword , and UseTrustedConnection —Connection informa- tion for the server on which the DTS package is stored. Setting Values of Global Variables in the Child Package You can pass information from the parent package to the child package by setting the values of global variables. There are two ways you can do this: •With fixed values, where you set the values of the global variables at design time in the Execute Package task. •With dynamic values, where the child package is sent the current values assigned to the global variables as the parent package is being executed. Control Tasks P ART IV 380 23 0672320118 CH18 11/13/00 5:04 PM Page 380 Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark. You send global variables with the fixed values method by adding global variables on the Inner Package Global Variables tab of the Execute Package Task Properties dialog, as shown in Figure 18.2. You can choose the name, the datatype, and the value for the global variable. The Execute Package Task C HAPTER 18 18 T HE E XECUTE P ACKAGE T ASK 381 F IGURE 18.2 You set fixed values for global variables on the Inner Package Global Variables tab. The variables you set on this tab are not global variables in the parent package. They set the values of global variables in the child package. You send global variables with the dynamic values method by adding global variables on the Outer Package Global Variables tab, as shown in Figure 18.3. This tab allows you to choose from the existing global variables in the parent package. These parent package global variables set the values of global variables in the child package to the parent package values at the time the Execute Package task is executed. You can send global variables with both methods in the same Execute Package task. If you use the same name for both a fixed value and a dynamic value global variable, the global variable is sent with the fixed value. The two types of global variables are received the same way in the child package. If a global variable with the specified name exists in the child package, the value sent from the parent package is assigned to it. If that global variable doesn’t exist in the child package, a new global variable is created. This new global variable only persists during the execution of the child package. 23 0672320118 CH18 11/13/00 5:04 PM Page 381 Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark. F IGURE 18.3 You choose existing global variables on the Outer Package Global Variables tab when you want to use the dynamic values method. Control Tasks P ART IV 382 Global variable names are always case sensitive. If you are attempting to pass a vari- able and you do not match the case of all the letters in the name, a new variable will be created in the child package. Also, a global variable passed to a child package overrules the option for required explicit declaration of global variables. A new global variable will be created in the child package when a global variable with the same name doesn’t exist, even if explicit declaration of variables is required in that package. C AUTION The Execute Package task has a GlobalVariables collection that contains a collection of GlobalVariable objects. All of the fixed-value global variables that you pass to the child pack- age are members of this collection. The Execute Package task has an InputGlobalVariableNames property that contains a semi- colon-delimited list of global variable names. These are the names of the dynamic value global variables that are being sent to the child package: “GlobalVariableName1”;”GlobalVariableName2”;”GlobalVariablename3” 23 0672320118 CH18 11/13/00 5:04 PM Page 382 Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark. The NestedExecutionLevel Property of the Package The DTS Package2 object has a property called NestedExecutionLevel . This read-only prop- erty reports the level of nesting that has been reached through the use of the Execute Package task. This property returns a value of 0 for a package that is executed directly and a value of 1 for the first package called by the Execute Package task. If that called package calls another pack- age, the NestedExecutionLevel property will return a value of 2 for the innermost package. DTS has an absolute limit of 32 for the NestedExecutionLevel. If that level is reached and another Execute Package task is executed, the package will fail with the following error: “Nested package execution limit of 32 was exceeded.” If you are calling DTS packages recursively with the Execute Package task, you can query the NestedExecutionLevel property to break out of the recursion before this error occurs: Dim pkg, stp Set pkg = DTSGlobalVariables.Parent Set stp = pkg.Steps(“stpExecutePackage”) If pkg.NestedExecutionLevel = 32 Then stp.DisableStep = True End If The Execute Package Task C HAPTER 18 18 T HE E XECUTE P ACKAGE T ASK 383 It’s hard to find the right terminology to talk about these two kinds of global vari- ables. I am not satisfied with the Inner Package/Outer Package labeling that the inter- face gives to the two kinds of global variables, because both types become global variables in the inner package. I think it’s better to focus on the function of the global variables. If you have fixed values that you always want to send to the child package, you cre- ate global variables that use the fixed value method. You specify the fixed value, along with the global variable name, on the Inner Package Global Variables tab. If you have dynamic values that you want to set while your parent package is execut- ing, you create global variables with the dynamic value method. You create global variables in the parent package and send them to the child package on the Outer Package Global Variables tab. N OTE 23 0672320118 CH18 11/13/00 5:04 PM Page 383 Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark. Creating and Calling a Utility DTS Package In Chapter 12, “The Execute SQL Task,” I described how to use OLE Automation procedures in an Execute SQL task to force a DTS package to execute on a particular server. I have encap- sulated that somewhat complex code into a utility DTS package so that it can be called with the Execute Package task. The name of the utility package is the Remote Execution Utility. You call it from an Execute Package task, and it runs the selected DTS package on any server you choose. The utility writes execution information to an INI file. The whole process is shown in Figure 18.4. Control Tasks P ART IV 384 Books Online recommends against using the Execute Package task to call packages recursively because of the danger of a stack overflow shutting down the Enterprise Manager. C AUTION Calling Package Executes Locally Called Package Executes on Server of Your Choice Execute Package Task Remote Execution Utility Executes Locally Execute SQL Task F IGURE 18.4 The Remote Execution Utility contains the functionality to execute a Called Package on any server and report the results to the Calling Package. You can find the utility and a sample of a Calling Package and a Called Package in three files on the CD—CallingPackage.dts, RemoteExecutionUtility.dts, and CalledPackage.dts. To use these sample packages, you have to do the following: 1. Save the Remote Execution Utility and the Called Package to SQL Server. You can put them on any servers you like, as long as you reference those servers appropriately in the Execute Package task in the Calling Package. 2. The Calling Package has to be set to log to SQL Server. Check the logging settings in the Package Properties dialog. 3. In the Execute Package task of the Calling Package, you must choose the Remote Execution Utility as the package to be executed. 4. Set the global variables in the Execute Package task to appropriate values. 23 0672320118 CH18 11/13/00 5:04 PM Page 384 Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark. You are only required to send one value to the Remote Execution Utility—the PackageName . The utility will open the Called Package from SQL Server storage on the local computer using integrated security. The utility will execute the Called Package in the context of the local server, again using integrated security. You can override these default values by sending these global variables to the Remote Execution Utility: • PackageStorageServer —The name of the server where the Called Package is stored using SQL Server storage. • PackageStorageUserName and PackageStoragePassword . • PackageExecutionServer —The name of the server where the Called Package is to be executed. • PackageExecutionUserName and PackageExecutionPassword . • ConnectionServer —You can change all the connections in the executed package to ref- erence a particular server. If this parameter is an empty string, the connections will not be changed. • ConnectionUserName and ConnectionPassword . The Remote Execution Utility reports results in an INI file. The following global variables can be sent to the utility to set up the reporting: • CallingPackageID —Any identification value from the Calling Server. I recommend sending the short lineage value for the current execution of the Calling Server. You could also use the full lineage value, the package ID, the package version ID, or the package name. • ReportName —The name of the INI file used to report results. If not supplied, the name of the INI file will be set to RemoteExecutionReport.ini. • ReportDirectory —The directory where the INI file is to be written. The default value is set in the Remote Execution Utility to the user’s temporary directory. • StepName —The step associated with a Transform Data task for which you want a com- plete report. If this is not set, no step will be given special reporting. The Execute Package Task C HAPTER 18 18 T HE E XECUTE P ACKAGE T ASK 385 The initial version of SQL Server 2000 limits the headings used for INI files in the Dynamic Properties task to 255 characters. Because of this limitation, the Calling Package will not be able to read the values for the current package execution after 23 entries have been made into the INI file. C AUTION 23 0672320118 CH18 11/13/00 5:04 PM Page 385 Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark. [...]... sPackageName PackagePassword = sPackagePassword RepositoryDatabaseName = sRepositoryDatabaseName UseRepository = bUseRepository The Execute Package Task CHAPTER 18 LISTING 18.1 389 Continued ServerName = sServerName VersionID = sVersionID If sServerUserName = “” Then UseTrustedConnection = True Else ServerPassword = sServerPassword ServerUserName = sServerUserName UseTrustedConnection = False End If End... ReceiveMessageTimeout = lReceiveMessageTimeout 19 402 Control Tasks PART IV LISTING 19.1 Continued StringCompareValue = sStringCompareValue End If Case 1 Data file DataFileNonOverwritable = bDataFileNonOverwritable If sSaveDataFileName “” Then SaveDataFileName = sSaveDataFileName End If If sDTSMessageLineageID “” Then DTSMessageLineageID = sDTSMessageLineageID End If If sDTSMessagePackageID “” Then DTSMessagePackageID... have Microsoft s Messaging API (MAPI) installed and the user must have a valid user profile for the messaging system NOTE Send Mail is the task I have seen fail most frequently when I move a DTS package from a development machine to the database server Not all database servers have MAPI installed, and if they do, you still have to make sure that the user profile you are using is valid on the server. .. Task • Creating the Task in Visual Basic 408 408 406 Control Tasks PART IV The Send Mail task provides an interface between your DTS package and your email system This task is the same in SQL Server 2000 as it was in SQL Server 7.0 When to Use the Send Mail Task The primary role of the Send Mail task is to send a report regarding what has happened in the execution of a DTS package Using the workflow objects,... Message Queue Task Properties dialog opens when you click on the expand button by the Identifier box on the Message Queue Task Properties dialog This dialog allows you to choose a package from SQL Server, SQL Server Meta Data Services, or structured file storage After selecting one of those options, you can click on the expand button beside the Package name box In the Select Package dialog, shown in Figure... Optional sPackageID As String = “”, _ Optional sPackageName As String = “”, _ Optional sPackagePassword As String = “”, _ Optional sRepositoryDatabaseName As String = “”, _ Optional sServerName As String = “(local)”, _ Optional sServerPassword As String = “”, _ Optional sServerUserName As String = “”, _ Optional bUseRepository As Boolean = False, _ Optional sVersionID As String = “”) As String On Error GoTo... Task Properties dialog when receiving a data file message The filename is set with the SaveDataFileName property The overwriting choice is stored in the DataFileNonOverwritable property Receiving a Global Variables Message Figure 19.5 shows the choices when you are receiving a global variables message The sending package filtering, discussed in “Filtering a Data File or a Global Variables Message,”... DTSMQMessageType values: • 0—DTSMQMessageType_String • 1—DTSMQMessageType_DataFile • 2—DTSMQMessageType_GlobalVariables The DTSMQMessage object also has a set of properties, one of which is used for each of the message types: • MessageString—The • MessageDataFile—The • MessageGlobalVariables—A text of the string message being sent path and filename of the data file being sent semicolon-delimited list of the names... Receiving a Data File Message Figure 19.4 shows the choices you have when you are configuring the Message Queue task to receive a data file message You choose the filename and path where you want to save the file, and whether to overwrite an existing file with that name You can also filter messages based on the sending DTS package These filtering choices are discussed in the “Filtering a Data File or... with the code listings on the CD The project requires references to the Microsoft DTSPackage Object Library and the Microsoft DTS Custom Tasks Object Library LISTING 19.1 The Visual Basic Code to Create a Message Queue Task Option Explicit Public Function fctCreateMessageQueueTask( _ pkg As DTS.Package2, _ sBaseName As String, _ bDataFileNonOverwritable As Boolean, _ sDTSMessageLineageID As String, _ . .ServerName = sServerName .VersionID = sVersionID If sServerUserName = “” Then .UseTrustedConnection = True Else .ServerPassword = sServerPassword .ServerUserName. ,the package is loaded from SQL Server storage. • RepositoryDatabaseName — The database that contains the instance of Meta Data Services from which the