![]() |
![]() |
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.
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.
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.