TSM Using the API


Introducing the API

The Tivoli Storage Manager (TSM) Application Program Interface (API) enables an application client to use the TSM functions. The API includes function calls that an application can use to perform the following operations:

When you, as an application developer, install the API, you receive:

Note:When you install the API, all files which includes the library, message file, and, for UNIX, the dsmtca, must be at the same level.

For information about installing the API, see Tivoli Storage Manager Installing the Clients.


Understanding Configuration Files and Options Files

Configuration files and options files set the conditions and boundaries under which your session runs. The administrator, the end user, or you can set the available options. The values of various options permit you to do the following:

On UNIX platforms, the Tivoli Storage Manager options reside in two separate options files: the client system options file (dsm.sys), and the client 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 API is first installed on the user's workstation.

The application also can specify options on the dsmInitEx call. Use either 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, as in the sequence that is displayed in Table 2:

Table 2. Options Files

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)

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

  1. Client system options (UNIX only). Options that a Tivoli Storage Manager administrator or a system administrator sets.
  2. The API options list takes effect when it is passed as a parameter to a dsmInitEx call. 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 ask the end user if compression is required. Depending on the user's answers, you can construct an API options list with this option and pass it into the call to dsmInitEx.

    For information about the API options list format, see the options parameter located on page ***. You can also set this parameter to NULL, indicating that there is no API options list for this 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 with values that you think will be appropriate in the end user's TSM session. The values take effect when the API configuration file name is passed as a parameter in the dsmInitEx call.

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

  4. On UNIX platforms, dsm.opt contains only the user options file. On other platforms, dsm.opt contains all of the options. You can override the options in these files by using the methods that are mentioned above.

For more information about the available options, see Tivoli Storage Manager Installing the Clients.


Setting Up the API Environment

The API uses unique environment variables to locate files. This permits you to use different files for API applications from those that the interactive client uses. Applications can use the dsmSetup function call to override the values that are set by the environment variables.

Table 3 lists the API environment variables by platform.

Table 3. API Environment Variables

Variables UNIX Intel Netware
DSMI_CONFIG The fully-qualified name for the client options file. The fully-qualified name for the client options file. There are no environment variables. The dsm.opt, dscameng.txt, and dsierror.log files reside in the same directory as the dsmapi.nlm file. This directory becomes the search path for these files.
DSMI_DIR Points to the path containing dsm.sys, dsmtca, the en_US subdirectory, and any other national language support (NLS) language. The en_US subdirectory must contain dsmclientV3.cat. Points to the path containing dscameng.txt and any NLS message file.
DSMI_LOG Points to the path for the dsierror.log file. Points to the path for the dsierror.log file.

Using Passwordaccess Generate Without TCA

TSM-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 generate function without starting the TCA. To do this:

  1. Write the application with a call to dsmSetUp which will pass argv[0]. The argv[0] contains the name of the application that calls the API. We permit the application to run as TSM-Authorized; however, the Tivoli Storage Manager administrator should decide on the login name for the TSM-Authorized user.
  2. Set the S bit (set the effective user ID) to On for the application executable. The owner of that application executable can then become a TSM-Authorized user. This permits the user to create a password file, update passwords, and run applications. The owner of the application executable must be the same as the User ID that runs the program. For example, "User" is User1, the name of the application executable is applA, and User1 has read-write permissions on the /home/user1 directory. The permissions on applA are:
       -rwsr-xr-x user1    group1   applA
    
  3. Instruct the users of the application to use the TSM-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 the passworddir option in the dsm.sys file to point to a directory where this user has read-write access. For example, under the server stanza in dsm.sys, you would enter:
       passworddir /home/user1
    
  5. Start the password file and ensure that the TSM-Authorized user owns the file.
  6. Run applA logged on as User1.
  7. Call dsmSetUp and pass in argv.

Note:When you are running in a multi-threaded mode and passwordaccess is generate, only the root, or TSM-Authorized user, is permitted access. The TCA child process, then, does not start.


[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]