NAME

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

SYNOPSIS

  use Win32::SqlServer::DTS::Package;

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

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

DESCRIPTION

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

EXPORT

Nothing.

METHODS

execute

Execute all the steps available in the package.

Requires that the _sibling attribute exists and is defined correctly, otherwise method call will abort program execution.get_connections

Returns a array reference with Win32::SqlServer::DTS::Package::Step::Result objects for error checking.

get_steps

Returns an iterator to get all steps defined inside the DTS package. Each call to the iterator (that is a code reference) will return a Win32::SqlServer::DTS::Package::Step object until all steps are returned.

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 Win32::SqlServer::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 iterator (code reference) that will return a Win32::SqlServer::DTS::Connection object at each invocation until there are no more objects available.

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

Returns 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 iterator. At each iterator (which is a code reference) call, one subclass object of Win32::SqlServer::DTS::Task will be returned.

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 Win32::SqlServer::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.

_get_tasks_by_type

_get_tasks_by_type is a "private method". It will return an iterator (which is a code reference) that will return Win32::SqlServer::DTS::Task subclasses objects at each call depending on the type passed as a parameter. It will not return and will complete ignore any Task class that is not returned by Win32::SqlServer::DTS::TaskTypes::get_types().

This method creates a cache after first call, so don't expect it will find new tasks after first invocation.

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 a iterator (code reference) that will return, at each invocation, a 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 a iterator (code reference) that will return a Win32::SqlServer::DTS::Task::DynamicProperty object at each invocation until there is no more tasks to return.

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 a iterator (code reference) that will return a Win32::SqlServer::DTS::Task::ExecutePackage object at each invocation until there is no more tasks to return.

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 iterator (code reference) that will return a Win32::SqlServer::DTS::Task::SendEmail at each invocation until there is no more tasks available.

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 Win32::SqlServer::DTS::Package was modified (or it's inner object were).

Expectes a Win32::SqlServer::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 Win32::SqlServer::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

• Win32::SqlServer::DTS::Application at perldoc.

• Win32::OLE at perldoc.

• Win32::SqlServer::DTS::DateTime, 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.

cpanm Win32::SqlServer::DTS

perl -MCPAN -e shell
install Win32::SqlServer::DTS