Using the Application Program Interface
Tivoli Storage Manager (TSM) is a client and server licensed program
product that provides storage management services to customers in a
multi-platform computer environment. In addition to the application
program interface (API), Tivoli Storage Manager includes the following
programs available on a variety of platforms:
- A backup-archive client program that permits users to back up and archive
files from their workstations or file servers to storage, or to restore and
retrieve backup versions and archived copies of files to their local file
systems.
- A server program that permits systems to perform as a backup and archive
server or migration server for distributed workstations and file
servers. The server program also supplies hierarchical storage
management (HSM) services.
- An administrative client program that you can access from a Web browser or
the command line. The program permits an administrator to control and
monitor server activities, to define storage management policies for backup,
archive, and space management services, and to set up schedules to perform
those services at regular intervals.
- A Web backup-archive client that permits an authorized administrator, help
desk person, or end user to perform backup, restore, archive and retrieve
services using a Web browser on a remote machine.
Associated with TSM is the Tivoli Space Manager Client Program that was previously a feature of ADSM known as Hierarchical Storage Manager
(HSM). Tivoli Space Manager automatically migrates eligible files to
storage to maintain specific levels of free space on local file systems, and
automatically recalls migrated files when they are accessed. It also
permits users to migrate and recall specific files. This client program
only runs on the operating systems that are specified in ADSTAR
Distributed Storage Manager Using the UNIX
Hierarchical Storage Management Clients.
This book provides information to help you add Tivoli Storage Manager
application program interface calls to an existing application, and documents
general-use program interface information that the TSM product
provides. General-use program interfaces permit you to write programs
that obtain the services of Tivoli Storage Manager. You should be
familiar with C programming language, and Tivoli Storage Manager
functions.
Tivoli Storage Manager books are translated into other languages.
Contact your Tivoli representative for a list of available
translations.
This book uses the following typographical
conventions:
Table 1. Typographical Conventions
Example
| Description
|
autoexec.ncf
| A series of lowercase letters with an extension indicates program file
names.
|
archive
| Boldface type indicates either an API function call, or a Tivoli Storage
Manager command.
|
dateformat
| Boldface italic type indicates either the name of a file, or a Tivoli
Storage Manager option.
|
filespec
| Italicized type indicates either the name of a parameter, a new term, or
a placeholder for information that you provide.
Italics are also used for emphasis in the text.
|
maxcmdretries
| Monospaced type indicates either fragments of a program, or information
as it would appear on a display screen.
|
plus sign (+)
| A plus sign (+) between two keys indicates that you should press both
keys at the same time.
|
Included here is a list of the publications that are referred to in
this manual.
- Tivoli Storage Manager Installing
the Clients, SH26-4102
- Tivoli Storage Manager for
UNIX Using the Backup-Archive Clients, SH26-4105
- Tivoli Storage Manager for
Windows Using the Backup-Archive Client, SH26-4101
- Tivoli Storage Manager Messages,
GC35-0382
All of the Tivoli Storage Manager publications are available on the
following CD-ROM:
- Tivoli Storage Manager For IBM MVS Online
Product Library, SK2T-8779
The following sections contain a summary of changes for
each release.
Note: | The Version 3.7 release of the API includes C++ code. If
your application uses this library, compile it with the appropriate C++
compiler on that platform. See the sample makefiles for the appropriate
compiler.
|
- dsmInitEx
- Starts an API session using the additional parameters that permit extended
verification.
- dsmLogEventEx
- Logs a user message to the server log file, to the local error log, or to
both with additional application-specific parameters.
- dsmQueryApiVersionEx
- Performs a query request for the API library version with an additional
sublevel field.
The envSetUp structure has been updated to include the
logName field. The structure version has been updated to a
value of 2.
The -fromowner option now supports
-fromowner=root on UNIX to permit non-root users access to
files owned by root if set access was performed.
The apiSessInfo structure has been updated to include the
adsmServerName field. The structure version has been updated
to a value of 2.
- dsmUpdateObject
- Supports update of archived objects.
The support of multi-threading in the API permits the application to
have multiple sessions with the TSM server in the same process. See "Using Multi-Threading" for more information.
- dsmSetUp
- Permits a multithread flag.
- dsmCleanUp
- Use dsmCleanUp if you use dsmSetUp.
- dsmSetUp
- An application can override the values of environment variables. At
this level, only single-thread mode is supported.
- dsmDeleteAccess
- An application can delete any defined access rule.
- dsmQueryAccess
- An application can query the current access rule that is defined for
objects on this node.
- dsmSetAccess
- An application can give access authority to other nodes or owners.
The API is not supported at the Version 3 level for the
following platforms:
- The API for OS/2 is now shipped with a 32-bit DLL. Rebuild
applications on OS/2 with this DLL.
- New typedefs are in dsmapitd.h. To pick up the
definitions, include this file before dsmapifp.h
and dsmrc.h. The Version 2 typedefs will continue to
work. If your application wants to update your code with our new
typedefs, comment out the backward compatibility section in
dsmapitd.h, and the compiler will mark any usage of the old
typedefs.
- The dsmapitd.h file includes a new header file,
dsmapips.h for platform-specific definitions.
- On UNIX platforms, the API library now uses the same Trusted
Communications Agent (TCA) module as the Backup-Archive client. The
Version 2 file was dsmapitca. The Version 3 file is
dsmtca.
- On platforms that have National Language Support (OS/2, NT, and AIX), we
support languages other than English for certain fields. The fields
that can have foreign language characters are: filespace, high level,
low level, and archive description. All other fields must contain
English characters.
- The default value for the compressalways option is now
Yes. In Version 2, the default was No.
- In Version 3, we now support some limited interoperability between the API
applications and the Backup-Archive command-line client. See Chapter 4, Interoperability for more information.
- dsmLogEvent
- An application can log an event message either on the client or the
server.
- dsmQueryCliOptions
- An application can query the client options before a dsmInit
call.
- dsmQuerySessOptions
- An application can query the client options after a dsmInit
call.
- dsmUpdateObj
-
An application can update meta data for an object.
- dsmBeginQuery
- Backup now has a point-in-time field, and archive now permits a Directory
objType.
- dsmGetNextQObj
- Backup response structure has a new restoreOrderExt field that you must
use instead of restoreOrder. Backup and Archive response structures now
have a sizeEstimate field. Only objects sent using the Version 3
library will have this value saved and returned on the query. Filespace
response structure now has backStartDate fields and backCompleteDate
fields.
- dsmRCMsg
- On platforms that have National Language Support and a choice of language
message files, the API returns a message string in the national
language.
- dsmRegisterFS
- Registers a new file space for the node with the server. The fsType
field includes the string, API: which displays at the
beginning of the fsType string. The maximum fsInfo area now available
to applications is DSM_MAX_USER_FSINFO_LENGTH (480).
- dsmSendObj
- Archive now permits a Directory objType.
- dsmUpdateFS
- Now has action bit maps for backStartDate and backCompleteDate.
Following is a description of new server functions in Version 3:
- Event logging and monitoring. You can set up event
logging of client and server events.
- SQL queries of the TSM database. You can use SQL queries
to obtain information about the server and clients.
- Storing data on another TSM server. You can store data
for one server (a source server) on another server (a target server).
Using another TSM server is especially useful for storing backups of the TSM
database and TSM storage pools.
- Server file aggregation. TSM can combine and store small
client files as larger aggregated files. Aggregation can improve
performance and reduce database overhead. See File Aggregation for more information.
- Device support. Device support has been enhanced on AIX,
Windows NT, and MVS.
- Administrative client web interface. You can access
server functions from any workstation using a web browser that supports HTML
2.0 or higher. It is not necessary for the workstation to have
an administrative client installed.
- Immediate processing of commands on a client. You can
use a TSM administrative command to run operations immediately on a client
workstation.
- Point-in-time restoration of client files. Clients can
restore files to a specific point in time if incremental backups were
performed and policy was set up appropriately.
- Restarting client restoration sessions. Clients can
restart restore sessions that were interrupted. Administrators can
request information about these sessions and cancel them.
- Defining client options at the server. You can define
sets of client options at the server, and assign a set to a client when
registering the client.
- Changing server options without stopping the server. You
can change some server options and have the changes take effect without
stopping and starting the server.
For more information about these new server functions, see the
administrator's guide for your operating system.
[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]