/ 
DTS-0.04
/ DTS::Package

NAME

DTS::Package - a Perl class to access Microsoft SQL Server 2000 DTS Packages

SYNOPSIS

  use DTS::Package;

	# $OLE_package is an already instantied class using Win32::OLE
	my $package = DTS::Package->new( $OLE_package );

	# prints the custom task name
	print $custom_task->get_name, "\n";

DESCRIPTION

DTS::Package is an class created to be used as a layer that represent a package object in DTS packages.

EXPORT

Nothing.

METHODS

log_to_server

Returns true or false (in Perl terms, this means 1 or 0 respectivally) if the "Log package execution to SQL Server" is set.

auto_commit

Returns true or false (in Perl terms, this means 1 or 0 respectivally) if the "Auto Commit Transaction property" is set.

new

Expects a DTS.Package2 object as a parameter and returns a new DTS::Package object.

Not all properties from a DTS.Package2 will be available, specially the inner objects inside a DTS package will be available only at execution of the respective methods. These methods may depend on the _sibling attribute, so one should not remove it before invoking those methods. The documentation tells where the method depends or not on _sibling attribute.

use_explicit_global_vars

Returns true if the property "Explicit Global Variables" is set. Otherwise returns false.

use_event_log

Returns true if the property "Write completation status to event log" is set. Otherwise returns false.

fail_on_error

Returns true if the property "Fail package on first error" is set. Otherwise returns false.

add_lineage_vars

Returns true or false (1 or 0 respectivally) if the Add Lineage Variables property is set.

is_lineage_none

Returns true if provide no lineage (default) or false otherwise.

is_repository

Returns true or false if the package will write to Meta Data Services if available.

is_repository_required

Returns true or false if writing to Meta Data Services is required.

to_string

Returns a string will all properties from the package, separated with new line characters. Each property also has a text with a sort description of the property.

This method will not fetch automatically the properties from objects inside the package, line connections and tasks. Each object must be fetched first using the apropriated method and them invoking the to_string from each object.

get_connections

Returns an array reference with all connections objects available inside the package.

This method depends on having the _sibling attribute available, therefore is not possible to invoke this method after invoking the kill_sibling method.

count_connections

Return an integer that represents the total amount of connections available in the package object.

Besides the convenience, this method is uses less resources than invoking the respective get_ method and looping over the references in the array reference.

This method depends on having the _sibling attribute available, therefore is not possible to invoke this method after invoking the kill_sibling method.

get_tasks

Returns an array reference with all tasks available in the package.

This method depends on having the _sibling attribute available, therefore is not possible to invoke this method after invoking the kill_sibling method.

Warning: get_tasks method will abort with an error message if the DTS package has tasks that are not available as subclasses of DTS::Task class. In doubt, use the available methods to fetch only the supported tasks. This should be "fixed" in future releases with the implementation of the missing classes.

count_tasks

Returns a integer with the number of tasks available inside the package.

Besides the convenience, this method is uses less resources than invoking the respective get_ method and looping over the references in the array reference.

This method depends on having the _sibling attribute available, therefore is not possible to invoke this method after invoking the kill_sibling method.

count_datapumps

Returns an integer represents the total amount of DataPumpTask tasks available in the package.

Besides the convenience, this method is uses less resources than invoking the respective get_ method and looping over the references in the array reference.

This method depends on having the _sibling attribute available, therefore is not possible to invoke this method after invoking the kill_sibling method.

get_datapumps

Returns an array reference with all the DataPumpTasks tasks available in the package.

This method depends on having the _sibling attribute available, therefore is not possible to invoke this method after invoking the kill_sibling method.

count_dynamic_props

Returns an integer represents the total amount of DynamicPropertiesTask tasks available in the package.

Besides the convenience, this method is uses less resources than invoking the respective get_ method and looping over the references in the array reference.

This method depends on having the _sibling attribute available, therefore is not possible to invoke this method after invoking the kill_sibling method.

get_dynamic_props

Returns an array reference with all the DynamicPropertiesTask tasks available in the package.

This method depends on having the _sibling attribute available, therefore is not possible to invoke this method after invoking the kill_sibling method.

get_execute_pkgs

Returns an array reference with all the ExecutePackageTask tasks available in the package.

This method depends on having the _sibling attribute available, therefore is not possible to invoke this method after invoking the kill_sibling method.

count_execute_pkgs

Returns an integer with the total of ExecutePackageTask tasks available in the package.

Besides the convenience, this method is uses less resources than invoking the respective get_ method and looping over the references in the array reference.

This method depends on having the _sibling attribute available, therefore is not possible to invoke this method after invoking the kill_sibling method.

get_send_emails

Returns an array reference with all the SendMailTask tasks available in the package.

This method depends on having the _sibling attribute available, therefore is not possible to invoke this method after invoking the kill_sibling method.

count_send_emails

Returns an integer with the total of SendMailTask tasks available in the package.

Besides the convenience, this method is uses less resources than invoking the respective get_ method and looping over the references in the array reference.

This method depends on having the _sibling attribute available, therefore is not possible to invoke this method after invoking the kill_sibling method.

save_to_server

Saves the package to a SQL Server. This method must be called if the DTS::Package was modified (or it's inner object were).

Expectes a DTS::Credential object as a parameter. If the Package will be saved in the same server from where it was fetched it's useful to use the method get_credential from the DTS::Application object.

The optional parameters:

  • PackageOwnerPassword

  • PackageOperatorPassword

  • PackageCategoryID

  • pVarPersistStgOfHost

  • bReusePasswords

from the original DTS API are not implemented.

save_to_file

Saves the package to a structured file.

Expects a complete pathname as a parameter. If a DTS structure filename is not passed together with the path, the method will use the package name followed by a '.dts' extension.

The optional parameters:

  • OwnerPassword

  • OperatorPassword

  • pVarPersistStgOfHost

  • bReusePasswords

from the original DTS API are not implemented.

get_creation_date

Returns a DataTime object with the timestamp of the creation date of the package. When used the to_string method, it will be returned the equivalent result of the method datetime from DateTime class.

The timezone of the DateTime object is the float one. See DateTime for more information.

get_creator_computer

Returns a string with the machine name from where the package was created.

get_description

Returns a string with the description of the package.

get_log_file

Returns a string with the filename of the file used to store the log messages from the package execution.

get_max_steps

Returns a integer the maximum number of steps allowed to be executed simultaneously in the package.

get_name

Returns a string with the name of the package

get_id

Returns a string with the unique ID in the database of the package.

get_priority

Returns a string with the priority of the package ('High', 'Low' or 'Normal').

get_version_id

Returns a string with the version ID of the package.

CAVEATS

This API is incomplete. There are much more properties defined in the SQL Server API.

SEE ALSO

  • DTS::Application at perldoc.

  • Win32::OLE at perldoc.

  • DateTime and DateTime::TimeZone::Floating at perldoc for details about the implementation of creation_date attribute.

  • MSDN on Microsoft website and MS SQL Server 2000 Books Online are a reference about using DTS' object hierarchy, but you will need to convert examples written in VBScript to Perl code.

AUTHOR

Alceu Rodrigues de Freitas Junior, <arfreitas@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2006 by Alceu Rodrigues de Freitas Junior

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available.