TSM Using the API


About This Book

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:

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.


Contacting Customer Support

For support for this or any Tivoli product, you can contact Tivoli Customer Support in one of the following ways:

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:


Conventions Used in This Book

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.

Related Publications

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.


Summary of Code Changes

The following sections contain a summary of changes for each release.

Version 4 Release 1 Level 0 July 2000

Version 4.1 no longer supports OS/2. Please ignore any references to OS/2.

New Function Call

dsmRenameObj
Renames the high-level or low-level object name.

Changed Function Call

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.

Version 3 Release 7 Level 0 September 1999

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.

New Function Calls

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.

Updated Structures

The envSetUp structure has been updated to include the logName field. The structure version has been updated to a value of 2.

Version 3 Release 1 Level 7 May 1999

Functional Enhancements

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.

Updated Structures

The apiSessInfo structure has been updated to include the adsmServerName field. The structure version has been updated to a value of 2.

New Function Call

dsmUpdateObject
Supports update of archived objects.

Version 3 Release 1 Level 6 January 1999

Functional Enhancements

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.

Changed Function Calls

dsmSetUp
Permits a multithread flag.

Version 3 Release 1 Level 5 August 1998

New Function Calls

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.

Version 3 Release 1 Level 3 March 1998

New Function Calls

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.

Version 3 Release 1 Level 0 October 1997

The API is not supported at the Version 3 level for the following platforms:

Functional Enhancements

General

Interoperability

New Function Calls

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.

Changed Function Calls

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.

New Server Functions

Following is a description of new server functions in Version 3:

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 ]