TSM Using the API
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 For UNIX Using the
Hierarchical Storage Management Clients. 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 Tivoli Space
Manager For UNIX Using the 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.
For support for this or any Tivoli product, you can contact Tivoli
Customer Support in one of the following ways:
- Visit the Tivoli Storage Manager technical support Web site at
http://www.tivoli.com/support/storage_mgr/tivolimain.html.
- Submit a problem management record (PMR) electronically at
IBMSERV/IBMLINK. You can access the IBMLINK from Web site at
http://www2.ibmlink.ibm.com.
- Submit a problem management record (PMR) electronically from our Web site
at http://www.tivoli.com/support.
- Send e-mail to support@tivoli.com.
Customers in the United States can call 1-800-TIVOLI8
(1-800-848-6548). For product numbers 5697-TS9, 5697-DRS or 5697-DPM,
call 1-800-237-5511.
International customers should consult the Web site for customer support
telephone numbers.
Or, you can review the Customer Support Handbook that is
available on our Web site at
http://www.tivoli.com/support/handbook/.
When you contact Tivoli Customer Support, be ready to provide
identification information for your company so that support personnel can
assist you. Company identification information also might be needed to
access various online services available on the Web site.
The support Web site offers extensive information, including a guide to
support services (the Customer Support Handbook); frequently asked
questions (FAQs); and documentation for all Tivoli products, including
Release Notes, Redbooks, and Whitepapers. The documentation for some
product releases is available in both PDF and HTML formats. Translated
documents are also available for some product releases.
You can order documentation by sending e-mail to
swdist@tivoli.com. Please provide the publication
number, part number, or order number of the document that you want.
Alternatively, you can provide the document title, version number, and date of
publication.
We are very interested in hearing about your experience with Tivoli
products and documentation. We also welcome your suggestions for
improvements. If you have comments or suggestions about our
documentation, please contact us in one of the following ways:
- Send e-mail to pubs@tivoli.com.
- Complete our customer feedback survey at
http://www.tivoli.com/support/feedback.
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-4119
- Tivoli Storage Manager for UNIX Using the Backup-Archive Clients,
SH26-4122
- Tivoli Storage Manager for Windows Using the Backup-Archive Client,
SH26-4117
- Tivoli Storage Manager Messages, GC35-0405
The Tivoli Storage Manager publications are available on the following
CD-ROM:
Tivoli Storage Manager Publications Version 4.1,
SK3T-1417.
The following sections contain a summary of changes for
each release.
Version 4.1 no longer supports OS/2. Please ignore any
references to OS/2.
- dsmRenameObj
- Renames the high-level or low-level object name.
The dsmDeleteObj now supports the new delType,
-delBackID. This delType deletes a backup object based
on object ID rather than the object name and copy group.
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 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 ]