Tivoli Header

Tivoli Storage Manager Using the Application Program Interface

Sending Data to a Server

The X/Open API permits application clients to send data to TSM server storage. Data can be either backed up or archived. All send operations must be performed within the bounds of a transaction. See The Transaction Model.

The backup component of the TSM system supports multiple versions of named objects that are stored on the server. Any object that is backed up to the server with the same name as an object which is already stored on the server from that client is subject to version control. Objects are considered to be in active or inactive states on the server. The latest copy of an object on the server that has not been deactivated is in the active state. Any other object, whether it is an older version or a deactivated copy, is considered to be inactive. Different management criteria defined by the management class constructs are assigned to active and inactive objects on the server.

The archive component of the TSM system stores objects on the server with retention or expiration period controls instead of version control. Each object stored is considered to be unique, even though its name might be the same as an object already archived. This permits an application to archive the same object multiple times, but with different expiration times that are assigned to each copy of the object.

The value of the compression option in the end user's dsm.sys file determines whether TSM will compress the object during a send operation.

Some types of data (for example, data that is already compressed) might actually grow larger when processed with the compression algorithm. When this happens, the return code, TSM_RC_ERROR, is generated and added to the TSM error log (dsierror.log). If you recognize that this might happen, but want the send operation to continue anyway, tell the end users to specify the following option in their options file before the application runs:

   COMPRESSAlways Yes

A send operation consists of the following steps:

  1. Make the BSABeginTxn call to start a transaction.
  2. Make the BSAResolveLifecycleGroup call.

    This call is optional. Use it to associate a particular management class with an object that you are storing on the TSM server. If you do not call BSAResolveLifecycleGroup, a management class is associated with the object during the call to BSACreateObject. For more information, see Associating a Management Class With Objects.

  3. Make the BSACreateObject call.

    The BSACreateObject call takes an ObjectDescriptor structure as an input parameter. This structure contains information about the object that is stored, such as the name of the object, and if it will be backed up or archived.

    The ObjectDescriptor.Owner.bsaObjectOwner value must match the value that is used on the BSAInit call. The ObjectDescriptor.Owner.appObjectOwner value must also match the one that is used on the BSAInit call, unless it was an empty string, signifying that the session was started with the root owner. In this case the object owner can be any value.

    The sizes of the objInfo and desc fields in the ObjectDescriptor structure are set by TSM. These sizes are determined by the constants TSM_MAX_OBJINFO and TSM_MAX_DESC in the custom.h header file.

    BSACreateObject can also send the first block of data to the TSM server. If the object has more data, go to the next step. If there is no more data, go to step 5.

  4. Make the BSASendData call.

    Repeat this call as many times as necessary until the entire object has been sent to the TSM server.

  5. Make the BSAEndData call.

    The BSAEndData call signifies that there is no more data for a particular object.

  6. If you want to send more than one object to the TSM server, repeat steps 3 through 5 for each object. Note that all objects sent within the same transaction must be for the same objectspaceName.

    TSM limits the number of objects that can be sent in one transaction. The limit is determined by the constant MAXOBJ. You can get this value by calling BSAGetEnvironment.

  7. Make the BSAEndTxn call to end the transaction.

Flowchart

Figure 23 displays the flowchart for performing backup or archive operations within a transaction.

Figure 23. Flowchart for Backup and Archive Operations

REQTEXT

The primary feature in this diagram is the loop between the following X/Open API calls from within a transaction:

BSACreateObject
BSASendData
BSAEndData


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