/ 
Win32-InstallShield-0.5
River stage zero No dependents
/ Win32::InstallShield

NAME

Win32::InstallShield - InstallShield data file interface

SYNOPSIS

use InstallShield;

# Constructors
$is = Win32::InstallShield->new();
$is = Win32::InstallShield->new( $ism_file );

ABSTRACT

An OO interface for manipulating InstallShield XML .ism files

DESCRIPTION

This module provides an interface to add, remove and modifify rows in an InstallShield .ism file. It only supports versions of InstallShield that save their data as XML.

EXAMPLES

This example updates the product version.

use Win32::InstallShield;

$is = Win32::InstallShield->new( $ism_file );
$is->UpdateProperty(
    { 
        Property => 'ProductVersion',
        Value    => '1.2.3.4',
    }
);

$is->savefile( $ism_file );

METHODS

new
$is = Win32::InstallShield->new();
$is = Win32::InstallShield->new( $installshield_filename );
$is = Win32::InstallShield->new( $io_file_handle );

The constructor. Can optionally be called with the same arguments as loadfile.

loadfile
$is->loadfile( $filename );
$is->loadfile( $io_file_handle );

Loads an InstallShield ism file. Can be called with either a filename or an IO::File object that is opened in read ("r") mode. Returns 1 on success, 0 on failure.

load
$is->load( $ism_text );

Loads the supplied text of an InstallShield ism file. Returns 1 on success, 0 on failure.

savefile
$is->savefile( );
$is->savefile( $filename );
$is->savefile( $io_file_handle );

Stores the ism data in a file. Can be called with either a filename or an IO::File object that is opened in write ("w") mode. If no argument is passed, and the last load was via a filename, savefile will default to the filename previously supplied. Returns 1 on success, 0 on failure.

save
$is->save();

Returns the ism data as a string.

tables
my $tables = $is->tables();

Returns an arrayref containing a list of all the tables that were found in the ISM file.

has_table
if($is->has_table( 'ModuleSignature' ) {
  print "This is a merge module\n";
}

Returns true if a table exists with the supplied name, false otherwise. Table names are case-insensitive.

column_is_key
my $is_key = $is->column_is_key( $table, $column_name );

Returns true if the column is a key column, false other wise. Returns undef if the column doesn't exist.

column_width
my $width = $is->column_width( $table, $column_name );

Returns the width of the named column. Returns undef if the column doesn't exist.

column_type
my $type = $is->column_type( $table, $column_name );

Returns the type of the named column. Returns undef if the column doesn't exist.

columns
my $columns = $is->columns( $table );

Returns an array ref containing the names of the columns in the given table.

key_columns
my $key_columns = $is->key_columns( $table );

Returns an array ref containing the names of the key columns in the given table.

property
my $version = $is->property('ProductVersion');
my $success = $is->property('ProductVersion', $version);

Gets or sets the value associated with a property. If a value is supplied, it will attempt to update the property and return 1 on success and 0 on failure. undef is returned if the property does not exist.

summary
my $summary_value = $is->summary( $summary_field );
my $success = $is->summary( $summary_field, $value );

my $summary_table = $is->summary;

Gets or sets the value associated with a field in the summary table. If no field name is provided, a reference to a hash containing all of the summary field/value pairs.

summary_fields
my @field_names = $is->summary_fields;

Returns a list of the valid fields for the summary table, as they appear in the DTD embedded in the ISM file.

valid_summary_field
my $is_valid = $is->valid_summary_field( $field_name );

Returns 1 if the field $field_name is valid according to the DTD in the ISM file, 0 otherwise.

featureComponents
my $components = $is->featureComponents( $feature );

Returns an arrayref of the components in the named feature. Returns undef if the feature does not exist.

COMPONENT ATTRIBUTES

All of the attribute methods can accept an attribute as either a name or a value. The name can be prefixed with msidbComponentAttributes as it is in the MSI documentation, but it is not required.

Valid attributes: LocalOnly 0 SourceOnly 1 Optional 2 RegistryKeyPath 4 SharedDllRefCount 8 Permanent 16 ODBCDataSource 32 Transitive 64 NeverOverwrite 128 64bit 256 DisableRegistryReflection 512 UninstallOnSupersedence 1024 AttributesShared 2048

set_component_attribute
my $success = $is->set_component_attribute( $component_name, '64bit', 1 );

Update the value of a single component attribute flag. Returns 1 on success, 0 on failure.

get_component_attribute
my $is_64bit = $is->get_component_attribute( $component_name, '64bit' );
my $is_shared = $is->get_component_attribute( $component_name, 8 );

Returns 1 if the named component has the given attribute set, 0 otherwise. Returns undef if the component does not exist, or the attribute is invalid. The attribute name or value can be used.

get_component_attribute_value
my $attr_number = $is->get_component_attribute_value( 'LocalOnly' );

Given a component attribute name, returns the bit value associated with the attribute. The msidbComponentAttributes prefix for attribute names is accepted, but not required. Given a valid attribute value, simply returns the value. Returns undef on invalid input.

get_component_attribute_name
my $attr_name = $is->get_component_attribute_name( 512 );

Given a component attribute value, returns the name associated with the value. Given a valid attribute name, simply returns the name. The msidbComponentAttributes prefix for attribute names is accepted, but not required. Returns undef on invalid input.

valid_component_attributes
my @attr_names = $is->valid_component_attributes;

Returns a list of valid attribute names.

ROW MANIPULATION METHOD SYNTAX

Row manipulation methods can be called in different ways. First, they are all case insensitve, and the '_' is optional, so for the 'Property' table, these are equivilent:

$is->add_row( 'Property', $rowdata );
$is->AddRow( 'Property', $rowdata );

Also, you can call each method using the table name in place of the word 'row', so these are equivilent to the two above:

$is->add_property( $rowdata );
$is->AddProperty( $rowdata );

All row manipulation methods are called with a set of data describing a row. In the methods below, it is represented by the variable $rowdata. It can be passed to the function in one of three formats: a list, an array ref or a hash ref.

List

You can simply put the columns in an array in the correct order (which you can get by looking at the ism or calling the columns method), and pass it to the method.

my @rowdata = ( 'Column_1_Value', 'Column_2_value' );
$success = $is->update_row( $table, @rowdata );

Array ref

You can do the same as above, but pass it as a single array reference.

$success = $is->update_row( $table, \@rowdata );

Hash ref

You can also pass a hash ref, using column names as keys.

my %rowdata = (
    Property   => 'ProductVersion',
    Value      => '1.2.3.4',
    ISComments => '',
);
$success = $is->update_row( $table, \%rowdata );

ROW MANIPULATION METHODS

getHash_row
my $row = $is->getHash_row( $table, $rowdata );

Returns a hash ref containing the data that matches the keys supplied in $rowdata. Returns undef if the row is not found.

getArray_row
my $row = $is->getArray_row( $table, $rowdata );

Returns an array ref containing the data that matches the keys supplied in $rowdata. Returns undef if the row is not found.

update_row
my $success = $is->update_row( $table, $rowdata );

Updates the row that matches the keys supplied in $rowdata. Any columns for which an undef is supplied will remain unchanged. An empty string will force the column to be empty. Returns 1 on success, 0 on failure.

add_row
my $success = $is->add_row( $table, $rowdata );

Adds a row containing the data in $rowdata. Returns 1 on success, 0 on failure.

del_row
my $success = $is->del_row( $table, $rowdata );

Deletes the row that matches the keys supplied in $rowdata. Returns 1 on success, 0 on failure.

purge_row
$is->purge_row( $table, $rowdata );
$is->purge_row( 'Component', 'Awesome.dll' );
$is->PurgeComponent( 'Awesome.dll' );

Removes the row that matches the key in $rowdata from the given table, and any rows in other tables with foreign keys that reference it. Key values are case sensitive. This only works for tables with a key column that has the same name as the table, which seems to be the only way you can use foreign keys in an ISM in any case. Returns 1 on success, 0 on failure.

add_or_update_row
my $success = $is->add_or_update_row( $table, $rowdata );

Adds a row if no row exists with the supplied keys, updates the matching row otherwise.

searchHash_row
my $rows = $is->searchHash_row( $table, $rowdata );

Returns any rows in the given table that match the supplied columns. The return value is an arrayref, where each entry is a hash as would be returned by getHash_row. Returns an empty arrayref if no matches are found. Returns the entire table if no $rowdata argument is provided.

Columns with undefined values will be ignored for matching purposes. Values used for matching can be either literal strings, in which case an exact match is required, or quoted regular expressions such as:

my $rows = $is->searchHash_row( 'Property', { Property=>qr/^_/ } );

This would search for all properties that begin with an underscore.

searchArray_row
my $rows = $is->searchArray_row( $table, $rowdata );

Works the same as searchHash_row, but returns an arrayref containing arrayrefs, like getArray_row instead of hashrefs.

AUTHOR

Kirk Baucom, <kbaucom@schizoid.com>

COPYRIGHT AND LICENSE

Copyright 2003 by Kirk Baucom

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.