Introducing the Tivoli Storage Manager API Client

The Tivoli Storage Manager application program interface (API) enables an application client to use its storage management functions. It is provided and documented to enable customers or ISVs to interface their own specialized applications to Tivoli Storage Manager. The API can be run in single or

multi-threaded mode, hence allowing applications to create multiple sessions with the Tivoli Storage Manager server within the same process. The API consists of a set of function calls that an application can use to perform the following

operations:

• Start or end a Tivoli Storage Manager session.

• Assign management classes to objects before storing them on a Tivoli Storage Manager server.

• Back up or archive objects to a Tivoli Storage Manager server.

• Restore or retrieve objects from a Tivoli Storage Manager server.

• Query the server for information on objects stored there.

• Manage file spaces.

When you, as an application developer, install the Tivoli Storage Manager API, you receive the following:

• The files that an end user of an application would need:

• API shared library and associated files

• Sample client options files

• Documentation

• The source code for the API header files that your application needs.

• The source code for a sample application and the makefile to build it.

Applications using ADSM V2 API may not work with Tivoli Storage Manager’s V3.7 API. Under such circumstance, the ADSM V2 API could still be used.

13.1 Who uses the Tivoli Storage Manager API client

The Tivoli Storage Manager API client can be used by any application in order to add the Tivoli Storage Manager functions directly into that application. Users can add the API to their program applications to automatically call Tivoli Storage Manager to initiate a backup, restore, archive or retrieve of a file, without having to leave the application to do so.

This book-formatted version is valid only for the date of publication.

The most recent version of this material is maintained on the ITSO Internet Web pages at:

http://www.redbooks.ibm.com/solutions/systemsmanagement/tsm/c_apicli.html Important: On-line Version Available!

This would be useful to applications which do not have a Tivoli Storage Manager component available to them, or to applications which need to backup or restore data between processing steps of an application job flow.

13.2 Understanding configuration files and options files

Configuration files and options files permit you to set the conditions and boundaries under which your Tivoli Storage Manager session runs. The Tivoli Storage Manager administrator, the end user, or the developer can set the available options. The values of various options enable the following functions to be performed:

• Initiate the connection to a Tivoli Storage Manager server.

• Control which objects are sent to the server and with what management class they are associated.

On the UNIX platform, the Tivoli Storage Manager options reside in two separate options files, the client system options file (dsm.sys)and theclient options file (dsm.opt). On other platforms, the options file,dsm.opt, contains all of the options. The end user sets up these files when the Tivoli Storage Manager API is first installed on the user's workstation.

The application can also specify options on the dsmInit()ordsmInitEx()function calls.With Tivoli Storage Manager V3.7, thedsmInitEx()incorporates extended version verification for APIs compatibility call. Either use the option string parameter or the API configuration file parameter.

The same option can derive from more than one configuration source. When this happens, the source with the highest priority takes precedence, in the sequence shown in Table 7.

Table 7. Options files

The different configuration sources, in order of decreasing priority, include:

1. Client system options (UNIX only). Options that a Tivoli Storage Manager or system administrator sets.

2. The API options list takes effect when it is passed to adsmInit() or dsmInitEx() call as a parameter. The list can contain client options such as:

compressalways

servername(UNIX only) tcpserveraddr(non-UNIX)

The API options list permits an application client to make changes to the values of the options in the API configuration file and the client options file.

For example, your application might query the end user for the user-preferred

UNIX Intel

1.dsm.sys (client system options) 1. N/A

2. option string (client options) 2. option string (all options)

3. API configuration file (client options) 3. API configuration file (all options) 4.dsm.opt(client options) 4.dsm.opt(all options)

Introducing the Tivoli Storage Manager API Client 153 format for displaying dates and times. On the basis of the end user's answers, you can construct an API options list with these two options and pass it into the call todsmInit(). You can also set the options parameter to NULL,

indicating there is no API options list for this Tivoli Storage Manager session.

3. The values in the API configuration file override the values set in the Tivoli Storage Manager client options file. Set up the options in the API configuration file to have values that you think will be appropriate in the end user's Tivoli Storage Manager session. The values take effect when the API configuration file name is passed as a parameter in thedsmInit() call.

You can also set this parameter to NULL, indicating there is no API configuration file for this Tivoli Storage Manager session.

4. On the UNIX platform,dsm.optcontains only the user options file. On other platforms,dsm.optcontains all of the options. You can override the options in these files using the methods mentioned above.

13.3 Setting up the API environment

The API uses unique environment variables to locate files. This permits you to use different files for API applications that the interactive client uses. Table 8 lists the API environment variables by platform.

Table 8. API environment variables

13.4 Using passwordaccess generate without TCA

Tivoli Storage Manager-authorized user (UNIX only):

The Trusted Communication Agent (TCA), a child process, normally controls access to the protected password file. It is possible to have the passwordaccess generatefunction without starting the TCA. To do this:

1. Write the application using thedsmSetUp()call to passargv[0], containing the name of the executable. We permit the application to run as Tivoli Storage Manager-authorized; however, the administrator should decide on the login name for the Tivoli Storage Manager-authorized user.

2. Set theSbit (set the effective user ID) toOn for the application executable.

The owner of that executable can then become a Tivoli Storage

Manager-authorized user. This permits the user to create a password file, update passwords, and run applications. The owner of the application executable should be the same as the User ID running the program. For example, “User” is User1, the name of the executable isdapimsp, and User1 has read-write permissions on the/home/user1 directory.

3. Instruct the users of the application to use the Tivoli Storage

Manager-authorized name to log in. Tivoli Storage Manager verifies that the login ID matches the application executable owner before it permits access to the protected password file.

4. Set thepassworddiroption in thedsm.sysfile to point to a directory where this user has read-write access. For example, under the server stanza indsm.sys, you would enter:

passworddir /home/user1

The permissions ondapismpare:

-rwsr-xr-x user1 group1 dapismp

5. Start the password file and ensure that the Tivoli Storage Manager-authorized user owns the file.

6. Rundapismplogged on as User1.

7. CalldsmSetUp()and pass in argv.

Note: When running in a multi-threaded mode, andpasswordaccessisgenerate, only the root, or Tivoli Storage Manager-authorized user, is permitted access, so that the TCA child process is not started.

OBJECT_MODE

=64

Support for 64-bit environment (where available) and

commmethod is tcpip

Variables UNIX Intel Netware

© Copyright IBM Corp. 2000 155