Tivoli Header

Tivoli Storage Manager Using the Application Program Interface

Starting Or Ending a Session

Tivoli Storage Manager is a session-based product, and all activities must be performed within a TSM session. To start a session, the application starts the BSAInit call. This call must be performed prior to any other API call except BSAQueryApiVersion. The BSAInit function sets up a session with the TSM server as indicated in that are passed in the call or are defined in the options files. Values in the environment pointer field are currently ignored.

Note:
The application client only registers new nodes with a TSM server if the server has closed registration. If a server has open registration, any nodes that are already registered with the server will be accepted by the application. However, if a server has open registration and BSAInit tries to register a new node, the return code, BSA_AUTH_FAILURE is generated. Application designers should tell their customers about this requirement so that customers can configure their servers accordingly.

The ObjectOwner fields are particularly important to a TSM session. The BSAObjectOwner is used as the TSM node name. The AppObjectOwner contains the TSM session owner name. The node name and password are used for session authentication with the TSM server. The session owner name is used to determine which objects can be accessed during the session.

Two modes for handling passwords, prompt and generate, are set in the passwordaccess option in the client options file. For the prompt mode, the node/owner/password must be supplied in the call to BSAInit. For the generate mode, the TSM trusted agent decides on the node and owner name. The password is stored in a file.

If the user's dsm.sys file sets passwordaccess prompt, then the TSM node and password (security token) must be supplied. The session owner can be whatever name you select. An empty string for the session owner ([0]='\0') is used to mean the root owner. The application has control of the object owner values.

If the user's dsm.sys file sets passwordaccess generate, then a value is not supplied for BSAObjOwner or AppObjOwner. These fields must be empty strings. The node name that is used will be the machine name, and the session owner will be the login user's name. The security token field is ignored in this situation.

If an application passes either node or session owner values when the mode is generate, it receives a return code of TSM_RC_PSWD_GEN. In this case, if your application supports passwordaccess generate, BSAInit must be issued again with empty ObjectOwner fields. If your application requires passwordaccess prompt, then stop and tell the user to change the option in their dsm.sys file.

You should follow BSAInit with a call to BSAGetEnvironment to retrieve the actual node and owner that is used for the session. If dsm.sys has passwordaccess generate, these values will be node = hostname, and owner = login user.

When using passwordaccess generate, the root user must start the first TSM session. This is necessary to create the file where the password is stored.

End a session with a BSATerminate call. This causes the X/Open API to close any connection with the TSM server and free all resources associated with this session.

Note:
Only one session can be active per call of the API. However, applications on UNIX platforms can circumvent this restriction by running with multiple processes, with each process owning its own TSM session.

Application Design Considerations

If the end user has set passwordaccess generate in the client options file, and is not the root user, then the Trusted Communication Agent (dsmtca) child process is forced to manage the session with the TSM server. The SIGCLD signal is used during ending. If you set passwordaccessto prompt, then a child process is not used.


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