NAME

TSM - Perl extension for the Tivoli Storage Manager

SYNOPSIS

  use TSM;
  my $tsm->new();
  my $tsm->new(id => "user id");
  my $tsm->new(id => "user id", pa => "password");
  my $tsm->new(file => "rcfile");
  
  my $outputstring = $tsm->dsmadmc("options", "tsm_command");
  my @columns = $tsm->get_columns(TABLE_NAME);
  my $arrayref = select("select_string");
  my $entries_added = select_hash($hashref, "select_string");
  my $hashref = select_single("select_string"); 
  
  

DESCRIPTION

This module will give you a convenient access to the administrative console of the TSM server. It has been developed under AIX 4.3.3, TSM 4.1.2 and PERL 5.6.0. As of now, I can not guarantee that it will work on Win32 systems.

INSTALLATION

The installation works as usual:

        perl Makefile.PL
        make
        make test
        make install

USAGE

Before using the module, you have to specify its usage with

        use TSM;

The first step of connecting to the TSM server is to create a new TSM instance by one of the following ways:

1. my $tsm->new();

This is the default way, which will manage the ID and password handling for you. It will look for a file .tsmrc either in the current directory or in the HOME directory of the user who executs the command (in this order). See below for details about .tsmrc. If the files are missing, cannot be read. miss information, the user will be prompted for the ID (if missing) and the password.

If you don't like this mechanism, you can influence the behaviour as follows:

2. my $tsm->new(id => "user_id");

Specify the TSM user, whoc should be used for the command. The password can still be provided in the .tsmrc.

3. my $tsm->new(id => "user_id", pa => "password");

Specify user and password (not recommended, since the password is in clear text).

4. my $tsm->new(file => "rcfile");

Specify another file with a user id and the password.

After initiating an instance with the TSM server, you can use it to access the tsm server. The most common command is the regular administrative console:

        my @output=$tsm->dsmadmc("options", "tsm command");

Please be aware, that output is different of what you usually see at the console itself. I am currently using the UNIX pipe mechanism which will create an unformatted output stream. If anybody knows a better (without going through an outputfile), please let me know. The output itself will be an array of output lines.

I have implemented 3 select commands to query the database directly:

1. my $arrayref = $tsm->select("select_string");

This select command returns a reference to an array of hashes with the output. Each element of the array contains a reference to a hash with the column names as the keys and the corresponding values. In the following example, we print the volume name and the storage pool of all volumes:

        my $arrayref = $tsm->select("* from volumes");
        foreach my $element (@$arrayref)
        {
                print "$element->{VOLUME_NAME}:\t $element->{STGPOOL_NAME}\n";
        };

If you use the generic "*" for the columns, you can use the following function to get an array of the column names:

        my @columns = $tsm->get_columns(TABLE_NAME);

2. my $hashref = select_single("select_string");

This is a simpler form of the first one, which is more convenient if you know, that the query returns only one record, e.g.

        my $statusref = $tsm->select_single("* from status"};
        print "$statusref->{RESTART_DATE}\n";
        

instead of

        my $statusref = $tsm->select("* from status"};
        print "$statusref->[0]{RESTART_DATE}\n";
         

3. my $entries_added = select_hash($hashref, "select_string");

This select command can be used, if the values of the first column are unique. They will be used as the keys of the hash, that must be provided to the command. This hash will then contain the values of the first column as its keys, and a reference to a hash as the value, which contains the columns/value of the columns 2-n. This output is usefull, if you want to combine different queries to one output, e.g. libvolumes and volumes with the volume name as the key. Let's see how it works: In the following example, we are using an existing hash with a fake entity, and merging it with the result of the select_hash command.

        my %volumes = ('xxxxxx' => {FAKE_ENTRY => "TEST"});
        my $retval = $tsm->select_hash(\%volumes, "* from volumes where volume_name='xxxxxx'");
        
        print "I'm still there: 'xxxxxx' -> $volumes{'xxxxxx'}{FAKE_ENTRY}\n"; 
        print "$retval elements changed or new\n";
        foreach my $element (sort keys %volumes)
        {
                print "$element: $volumes{$element}{STGPOOL_NAME}\n";
        };

The file .tsmrc:

Since this file contains the password, it should not be readable for anybody but the owner. If you need more then one instance with different user ids, you can specify the file name with the "file => file_name" parameter.

The syntax of the .tsmrc is as follows:

        ID      user_id
        PA      password

COPYRIGHT

Copyright (c) 2001 Joerg Nouvertne. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

AUTHOR

For any issues, problems, or suggestions for further improvements, please do not hesitate to contact me.

        Joerg Nouvertne joerg.nouvertne@wtal.de

SEE ALSO

perl(1).