The Tivoli Storage Manager API Sample

Program
Setup and Use
By Ron McCracken
Version 1.0
iii
Copyright Notice
Copyright IBM Corporation 2008. All rights reserved. May only be used pursuant
to a Tivoli Systems Software License Agreement, an IBM Software License
Agreement, or Addendum for Tivoli Products to IBM Customer or License
Agreement. No part of this publication may be reproduced, transmitted,
transcribed, stored in a retrieval system, or translated into any computer
language, in any form or by any means, electronic, mechanical, magnetic,
optical, chemical, manual, or otherwise, without prior written permission of
IBM Corporation. IBM Corporation grants you limited permission to make hardcopy
or other reproductions of any machine -readable documentation for your own use,
provided that each such reproduction shall carry the IBM Corporation copyright
notice. No other rights under copyright are granted without prior written
permission of IBM Corporation. The document is not intended for prod uction and
is furnished as is without warranty of any kind. All warranties on this
document are hereby disclaimed, including the warranties of merchantability and
fitness for a particular purpose.
U.S. Government Users Restricted Rights -- Use, duplication or disclosure
restricted by GSA ADP Schedule Contract with IBM Corporation.
Trademarks
IBM, the IBM logo, Tivoli, the Tivoli logo, AIX, Cross -Site, NetView, OS/2,
Planet Tivoli, RS/6000, Tivoli Certified, Tivoli Enterprise, Tivoli Enterprise
Console, Tivoli Ready, and TME are trademarks or registered trademarks of
International Business Machines Corporation or Tivoli Systems Inc. in the
United States, other countries, or both.
Lotus is a registered trademark of Lotus Development Corporation.
Microsoft, Windows, Windows NT, and the Windows logo are trademarks of
Microsoft Corporation in the United States, other countries, or both.
UNIX is a registered trademark of The Open Group in the United States and other
countries.
C-bus is a trademark of Corollary, Inc. in the United States, other countries,
or both.
PC Direct is a trademark of Ziff Communications Company in the United States,
other countries, or both and is used by IBM Corporation under license.
ActionMedia, LANDesk, MMX, Pentium, and ProShare are t rademarks of Intel
Corporation in the United States, other countries, or both. For a complete list
of Intel trademarks, see http://www.intel.com/sites/corporate/trademarx.htm.
SET and the SET Logo are trademarks owned by SET Secure Electronic Transaction
LLC. For further information, see http://www.setco.org/aboutmark.html.
Java and all Java-based trademarks and logos are trademarks or registered
trademarks of Sun Microsystems, Inc. in the United States and other countries.
Other company, product, and service names may be trademarks or service marks of
others.
Notices
References in this publication to Tivoli Systems or IBM products, programs, or
services do not imply that they will be available in all countries in which
Tivoli Systems or IBM operates. Any r eference to these products, programs, or
services is not intended to imply that only Tivoli Systems or IBM products,
programs, or services can be used. Subject to valid intellectual property or
other legally protectable right of Tivoli Systems or IBM, any functionally
equivalent product, program, or service can be used instead of the referenced
product, program, or service. The evaluation and verification of operation in
conjunction with other products, except those expressly designated by Tivoli
Systems or IBM, are the responsibility of the user. Tivoli Systems or IBM may
have patents or pending patent applications covering subject matter in this
document. The furnishing of this document does not give you any license to
these patents. You can send license i nquiries, in writing, to the IBM Director
of Licensing, IBM Corporation, North Castle Drive, Armonk, New York 10504 -1785,
iv
U.S.A.
v
About the Tivoli Field Guides
Sponsor
Tivoli Customer Support sponsors the Tivoli Field Guide program.
Authors
Those who write field guides belong to one of these three groups:
Tivoli Support and Services Engineers who work directly with customers
Tivoli Customers and Business Partners who have experience using Tivoli software in a
production environment
Tivoli developers, testers, and architects
Audience
The field guides are written for all customers, both new and existing. They are applicable to
external audiences including executives, project leads, technical leads, team members, and to
internal audiences as well.
Types of FieId Guides
Two types of Tivoli Field Guides describe how Tivoli products work and how they are used in real
life situations:
Field Guides for technical issues are designed to address specific technical scenarios or
concepts that are often complex to implement or difficult to understand, for example:
endpoint mobility, migration, and heartbeat monitoring.
Field Guides for business issues are designed to address specific business practices that
have a high impact on the success or failure of an ESM project, for example: change
management, asset Management, and deployment phases.
Purposes
The Field Guide program has two major purposes:
To empower customers & business partners to succeed with Tivoli software by
documenting and sharing product information that provides accurate and timely
information on Tivoli products and the business issues that impact an enterprise systems
management project
To leverage the internal knowledge within Tivoli Customer Support and Services and the
external knowledge of Tivoli customers and Business Partners
AvaiIabiIity
All completed field guides are available free to registered customers and internal lBM employees
at the following Web site:
http://www.ibm.com/software/sysmgmt/products/support/Field_Guides.html
Authors can submit proposals and access papers by e -mail:
vi
mailto:Tivoli_eSupport_Feedback@us.ibm.com
vii
Table of Contents
SETUP AND USE ........................................................................................... I
Sponsor................................ ................................ ................................ ..... v
Authors ................................ ................................ ................................ ..... v
Audience ................................ ................................ ................................ ... v
Types of FieId Guides ................................ ................................ .............. v
Purposes................................ ................................ ................................ ... v
AvaiIabiIity ................................ ................................ ................................ v
SETUP AND USE .......................................................................................... 1
CLIENT CONFIGURATION ................................ ................................ ................................ . 1
Installation................................ ................................ ................................ ...... 1
Unix Systems................................ ................................ ............................ 1
Windows Systems................................ ................................ .................... 2
Compilation................................ ................................ ................................ ....2
Option File ................................ ................................ ................................ ..... 2
Registration................................ ................................ ................................ ....3
THE INTERACTIVE, SINGLE-THREADED APPLICATION PACKAGE (DAPISMP) ...................... 3
SUMMARY................................ ................................ ................................ ...................... 10
1
The Tivoli Storage Manager API Sample
Program
Setup and Use
The TSM APl includes a series of sample programs that illustrate the use of all the APl functions.
Source codes and make files are provided for the host platform under the
Tivoli/TSM/api/SAMPSRC subdirectory, and , in the case of Windows, a pre-compiled
dapismp.exe program is provided under the Tivoli/TSM/api/SAMPRUN subdirectory , as well. This
paper is a guide to the APl sample programs and a tutorial in the the use of the dapismp.exe
sample program. Application architects preparing to design an APl -based application will also
want to obtain a copy of the following field guide:
TivoIi FieId Guide - Meeting CompIiance Using IBM System Storage Archive
Manager
ln addition to providing a wealth of information about archive-specific design, Chapter 4 deals
with performance and scalability, which are equally applicable to backup applications.
Client Configuration
The APl sample program is furnished as part of the client APl component, which can be
downloaded from the following location:
ftp://service.boulder.ibm.com/storage/tivoli -storage-management/maintenance/client/
lnstallation
Unix Systems
For Unix operating systems, the APl is prov ided as a separate installation package tailored to the
requirements of the specific platform, e.g. a package file on Solaris or an rpm file for Linux .
Consult the appropriate platform's client user's guide for installation instructions. The actual
installation image is downloaded in the form of a zipped tar archive file. The installation process
will be similar to the following, taken from a Solaris installation:
1. Log in as root. (This is essential for a successful installation)
2. Copy the image labeled C97LKML.tar.gz into the /cdrom directory on the Solaris system,
unzip, and extract the contents.
3. Change directories to the location where the packages are stored. This should be
/cdrom/C97LKML/tsmcli/solaris
4. lnstall the APl client: # pgkadd a ./tsmadmin d ./TlVsmCapi.pkg TlVsmCapi
The standard backup/archive client is provided as a separate package. You may wish to install it
as well, in order to have local use of the administrative command line for TSM server
communication.
2
Windows Systems
For the Windows platform, the APl component is a subset of the client installation image , which is
supplied as a self-extracting executable file. Execution of the file results in extraction of the
installation program and files into a local system directory. The default location is a bit unwieldy to
use, and our recommendation is to create an easily accessible directory under the C: \ directory.
NOTE: Although the extraction process will display a message indicating successful installation of
the client, this is misleading. The installation image has actually been extracted to the target
directory mentioned above.
lnstallation of the APl is done by changing directories into the installation image directory, running
the extracted setup.exe program, and selecting Custom lnstallation to specify the installation of
the APl. You may also wish to select installation of the Administrative Command Line component,
as this provides a way to work with a remote TSM server from the local system.
Compilation
The sample program itself i s supplied as source code, so once the package installation is
completed it will be necessary to compile the sample program (s) desired using an appropriate
C++ compiler. A make file (makesmp.mak) is provided with the source code, and in its comments
it explains the options available to make each of the various sample programs.
There are eight different sample programs provided:
Tivoli Storage Manager buffer sample application (callbuff) -
Event-based retention policy sample application (callevnt) -
Deletion hold sample application (callhold) -
Multi-threaded applications (callmt*) -
Multi-threaded, Unicode applications (callmtu*) -
Data retention protection sample application (callret) -
lnteractive, single-threaded application package (dapismp) -
Logical object grouping application (dsmgrp) -
NOTE: On Windows, a pre-compiled version of the dapismp sample program is supplied.
Option File
Besides installing the APl component, the user needs to provide a basic dsm.opt file containing
connection information for an accessible TSM server.
The dsm.opt file is a plain ASCll text file, which, for the sample program, must contain at a
minimum the communication information required to contact the server. An example of minimum
file contents is listed below:
commmethod tcpip
tcpport 1500
TCPSERVERADDRESS 9.48.200.99
3
The TCPSERVERADDRESS may be specified either as an lP address, as in the example, or as
a fully qualified domain name if name services are available. This file may be pl aced in any
convenient location, but see the note below.
Also, if you are planning to run any of the sample programs other than dapismp, check the
comments at the beginning of the source file. ln some cases , additions to the dsm.opt file are
required.
NOTE: lf you have installed the Administrative Command Line and intend to use it, it is easiest to
locate your dsm.opt file in the same directory as the dsmadmc executable. Otherwise a number
of changes to your user environmental variables will be needed. Alt ernatively, two files may be
established: one for the Administrative Command Line, the other for use with the APl sample
program in a separate location.
Registration
Unless the target TSM server has been configured for open registration (an unusual setup, and
not the default), it is also necessary to register the node name(s) to be used during login on the
TSM server. This step establishes the security credentials for the client.
A test node can be registered on the target TSM server in one of two ways. lf the lntegrated
Solutions Console is in use, a wizard is provided for this purpose. Otherwise it can be done using
the administrative command line. The node name(s) is/are at the user's discretion in most cases;
however, check the comments at the head of each sample program source file for specific
directions concerning node setup requirements . For example:
TSM> REGISTER NODE APITEST apipswd
The above command registers a node named APlTEST, with an initial logon password of
apipswd, into the STANDARD domain.
NOTE: Node names are not case sensitive, but passwords are case sensitive.
With these minimum preparatory steps complete, the sample program is ready for use.
The Interactive, Single-Threaded Application
Package (dapismp)
This program starts as any other executable program. lt will initially display the following list of
options:
0. Signon
1. Backup
2. Restore
3. Archive
4. Retrieve
5. Queries
6. Change Password
7. Utilities: Deletes, Updates, Logevent, SetAccess, RetentionEvent
8. Set preferences, envSetUp
4
9. Exit to System
10. Restore/Retrieve without Offset Prompt
11. Extended Signon
Some of these functions require a prior sign -on to the server, others do not (server sign-on does
not occur at program start) . The functions that require a server sign-on will generate an error
message to that effect when executed, if a sign-on has not been previously accomplished. The
functions that will work without a previous sign -on are:
0. Signon
5. Queries (selected sub-options only)
8. Set preferences, envSetUp
9. Exit to System
11. Extended Signon
Most APl-based applications will be designed to check their environment setup, and that is
accomplished via queries, so let's start by looking at the query options. Selecting option 5 results
in the display of a submenu:
Choose one of the following items to query:
0. Access Query
1. Backup Query
2. Archive Query
3. Management Class Query
4. Filespace Query
5. Session lnfo Query
6. APl Version Query
7. Option File Query
8. Session Options Query
9. Quit
10. Proxy Node Authority
11. Proxy Node Peers
Since the first thing an APl -based application should do is check the installed version of the APl,
using the dsmQueryApiVersionEx call (this function is illustrated by option 6):
Enter selection ==> 6
APl Version = 5.4.0.2
When you are writing an application, dsmSetUp will usually be the next APl call used. Option 8 of
the top-level menu implements the dsmSetUp function, for example by setting the path to your
dsm.opt file (referred to as the configuration file).
Upon selecting option 8, another submenu is displayed. Sub-option 0 exercises the dsmSetUp
function. Sub-option 1 allows display of various configuration parameters, and the remaining
options allow you to change these parameters. Below is an illustration of the setup of the option
file location:
5
Having set up the environment, the next step is to complete a login to the server, using either
option 0 (zero), which is a basic logon or option 11 (eleven), which uses extended capabilities
such as encryption. Option 0 illustrates the use of th e dsmlnit function call, while option 11
illustrates the corresponding dsmlnitEx function.
NOTE: For new development the dsmlnitEx call should be used, so the option 11 dialog is
illustrated below.
Note that if the APl Config file location was previo usly set, it does not need to be reset during the
signon. The illustration shows the capability to reset it at session initiation.
The program prompts for certain identifying information. The node name input must match that of
a registered node on the target server. The Owner name (optional) specifies the local owner
6
name for data. The Password is the node password previously registered on the server. The APl
config file is the full path to the dsm.opt file previously created. lf the default location is use d, this
can be left blank, or it can be set in the setup option as discussed above. ln either of these cases,
it may be left blank here. Alternatively, a new value can be specified here and it will override any
previously set values. Session options, User Name, User pswd, and all subsequent entries can
also be left blank. Upon completion of a successful session initialization, a session handle will be
returned. For a full discussion of the significance of the values being set, refer to the APl manual
discussion of the dsmlnitEx function call.
Having started a session, all the remaining menu options become usable. Something else has
happened, as well, on the TSM server. Below is the output of a query node command run on a
TSM server immediately after the fi rst logon by the APl sample program:
Node Name Platform Policy Domain Days Since
Name Last Access
------------------- -------------- ----------
APITEST Sample-- STANDARD <1
API
DEMO6 WinNT STANDARD 417
VM1 Linux86 STANDARD 861
VM3 (?) STANDARD 889
Note that all but one Node Name has an associated Platform Name. This is assigned the first
time a node initiates a session with the server. (The last node in the list has not yet initiated a
session, so its platform type is unknown).
One of the things an APl -based application must do is specify its Platform Name. As you can see,
the APlTEST node has SampleAPl as its Platform Name. A recommended best practice is to
set up a Platform Name indicative of the application.
With a successful logon accomplished, we can query the server to ob tain our session-related
settings and the available management classes needed for subsequent backup/archive
operations. Returning to the Query menu, we exercise option 5:
7
The session information returned from the server includes information about the server as well as
the node (client). lt provides such useful information as the default management class for the
node. (This is the management class assigned to objects by the dsmBindMC function, in the
absence of other instructions). lt also shows the node type, filespace delimiter, and high-and-low
level delimiters that have been established for this node. This is good to know so as to avoid
using inappropriate settings in subsequent sessions.
Management class information is obtained via option 3:
lf you leave the management class search string blank, a list of all management classes in the
domain to which the node APlTEST is assigned will be generated. ln this case, only one
management class has been defined on the server. ln designing an APl-based application, it is a
good idea to check on the available management classes when initiating a session. Since
management class definitions are managed by the server, it is possible in some environments for
8
these to be changed without coordinating with the using nodes. Attempting to bind objects to a
non-existent management class will result in an error condition , which must be handled.
Now, let us return to the main menu (option 9 of the query menu) and turn our attention to use of
the backup function of the main menu, option 1. The example below shows the minimum input
required to backup a single object. (The filespace, highlevel, and lowlevel specifications in the
example are appropriate for a Windows system, Unix will differ)
There is one subtle element that needs further amplification. The sample program requires the
user to input a filespace name, and that name is used to create the object in server storage. The
sample program does not provide a separate menu item to accomplish this. However, in the
actual APl coding, it is necessary to first create the filespace before using it (a separate APl call).
This call is only needed the first time the filespace is used. Subsequent backup/archive
operations using the same filespace do not need to create the filesp ace. The most efficient
program will obtain a list of available filespaces at session start and refrain from repeated queries.
Option 4 of the Query submenu demonstrates the use of the dsmQueryFilespace function:
ln this example, the query pattern was left blank, resulting in the return of all filespaces previously
established for the test node. Note some curious behavior. Two objects have been backed up
previously, one using an upper case filespace designator and the other a lower case designator.
The Windows platform does not differentiate between upper and lower case, but the TSM or
SSAM server does (regardless of the host platform), so if you mix usage you will have two
filesystem specifications for each logical drive. Since an APl application does n ot have to restrain
itself to the use of actual file system mount points as filespace designators, this illustrates another
way to segregate data into manageable parts. But remember not to create more than about 100
filespaces for each node name.
9
Having backed up an object, let's see what the server has to show us. This is done via the
Administrative Command Line. Assuming that you chose to install the Administrative Command
Line on your test system, you can change directories to the client installation dir ectory and run the
dsmadmc executable program. You will be prompted for a user name and password
(admin/admin is the default on a new installation, but your setup may differ) after which you can
issue server commands. Depending on your installation charact eristics, you may need to reset
your user environment to point to your dsm.opt file for this to work.
To see what has been backed up, run the following query:
TSM> select * from backups where node_name=APITEST
NOTE: While the TSM/SSAM server is not case sensitive with regard to node names, the
database is case sensitive. All node names are converted to uppercase for storage, and queries
using a text match must also be in upper case.
select * from backups where node_name='APITEST'
ANR2963W This SQL query may produce a very large result table, or may
require a significant amount of time to compute.
NODE_NAME: APITEST
FILESPACE_NAME: C:
FILESPACE_ID: 1
STATE: ACTIVE_VERSION
TYPE: FILE
HL_NAME: \temp\
LL_NAME: setup.log
OBJECT_ID: 864938
BACKUP_DATE: 2008-10-20 09:49:07.000000
DEACTIVATE_DATE:
OWNER:
CLASS_NAME: STANDARD
From this we can see that an object has been backed up. Note the OBJECT_lD, which is server -
assigned. This is the information needed to actually restore or retrieve an object from the server,
or to send an event to that object.
Now let us look at the restore option, Option 2:
10
Option 2 allows for a partial object restore. This is made possible by specifying an offset and
object length. lf non-zero values are supplied, the server will restore only that portion of the
referenced object specified, rather than the entire object. Option 10 of the sample program allows
for a restore without using offset/length values.
Note the message showing the buffer length. This is the receive buffer that must be established in
an APl application, and the sample program provides an option to adjust its buffer sizes in the Set
Preferences submenu (option 8 of the main menu).
By selecting option 1 of the submenu, the current preferences can be displayed, and separate
menu items are provided to change each setting. Below is Option 1 output:
There is one other feature you may wish to test with the APl sample program : the tracing
capability of the APl. To do this you must add two lines to your dsm.opt file:
TRACEFLAGS API,api_detail,appl,config,timestamp,verbdetail
TRACEFILE 'C:\Program Files\Tivoli\TSM\api\SAMPRUN\trace.log'
Then restart the sample program and point it at the new dsm.op t file. Run any desired sample
program options to capture a trace of the APl calls used. This is similar to the process used to
capture trace information for use in obtaining Ready for Tivoli validation for your APl -based
application, should you choose to do so.
Summary
This Field Guide has explained the content of the sample programs provided as source code in
the TSM APl and reviewed the installation and compilation steps needed to use these programs
as a learning tool. lt has also provided a brief tutori al in use of one of the sample programs,
dapismp. By combining a review of the APl manual, titled Using the Application Programming
lnterface, and a study of the sample programs, a developer with C++ coding experience should
be able to successfully write an APl-based application.