Using the Application Program Interface


Appendix E. The X/Open API

The X/Open Backup Services API (XBSA) is a set of function definitions, data structures, and return codes that the Open Group developed them to present a standardized interface between applications that need to perform backup or archive operations, and the enterprise solutions that provide these services. Tivoli Storage Manager is such a solution. See www.opengroup.org/publications for more information.

Current implementation is based on the preliminary specifications, not the Technical Standard. Compatible header files are included with the TSM client package.


Introduction

The X/Open API enables an application client to use the TSM storage management functions. The X/Open API consists of a set of function calls that an application client can use to perform the following operations:

When you, as an application developer, install the X/Open API, you receive the following:

The X/Open API for TSM is available on the following platforms:

See the platform README.API for specific information.

For information about installing the X/Open API, see the Tivoli Storage Installing the Clients manual.


Setting Up Options Files

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

The same option can appear in more than one options file. When this happens, the file with the highest priority takes precedence. The options files, in order of decreasing priority, include:

  1. Administrator options. Options that a TSM administrator sets, whether on the client or the server, override any options that are set by you or the end user. For example, the administrator can specify whether or not objects can be compressed before being sent to a TSM server. In this case, setting the compression option in the client options file has no effect. The administrator can also decide that the client should decide to permit compression. Setting the compression option in the client options file then determines if objects are compressed before they are stored.

  2. The TSM options files on the UNIX platform include the user options file (dsm.opt) and the system options file (dsm.sys). The end user sets up these files when the API is first installed on the user's workstation.

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


Using the TSM X/Open API Sample Application

The API package that you receive includes a sample application. This sample application demonstrates the use of the X/Open API function calls in context. Install the sample application and view its source code to understand how you can use the function calls.

Build the Sample Application

The files listed in Table 39 comprise the source files and other files that you need to build the sample application included with the X/Open API.

Table 39. Files Available to Build X/Open API Sample Application

File Name Description
custom.h Platform custom integer definitions header file
xbsa.h Header file containing constants, return codes, structure and type definitions, and function prototypes for the Data Movement function group
policy.h Header file containing structure definitions relating to policy
dsmapitd.h Header file containing general type definitions
dsmapips.h Header file containing platform-specific type definitions

xapidata.h
xapint64.h
xapint64.c
xapipref.c
xapipref.h
xapiqry.c
xapiqry.h
xapismp.c
xapiutil.h
xapiutil.c
xapicont.c
xapidef.h
xapidel.c
xapidel.h
xapidisp.c
xapidisp.h
xapilist.c
xapilist.h
xapiour.c
xapiour.h
xapirecv.c
xapirecv.h
xapisend.c
xapisend.h
xapisess.c
xapisess.h

Modules for the command line driven sample application

makexapi.aix
makexapi.sol
Makexapi.hp


Makefile to build xapismp for AIX
Makefile to build xapismp for Solaris

xapismp X/Open API sample program

Follow these steps to compile the sample application and test the installation.

Note:Several steps have slight variations, depending on which UNIX platform you are using. See the README.API file for specific information.

  1. Copy the API library to the /usr/lib directory or create a symbolic link to the file from the /usr/lib directory.

  2. Copy the sample application files to the target directory.

  3. Copy the header files to the target directory.

  4. Copy the makefile to the target directory.

  5. Compile the sample.

  6. Ensure that your environment variables, especially DSMI_DIR, and options files are set up. See Setting Up Options Files and the Installing the Clients book for information.

  7. Log on as root the first time for password registration.

  8. Run xapismp to start the sample application.

  9. Follow the instructions that appear on the screen.

When you run the application, remember that:


Using the TSM X/Open API

This section describes how to use the X/Open Application Program Interface. You should be familiar with this section before you design or write an application that uses the X/Open API.

The TSM X/Open API supports the functions in XBSA Data Movement function group. These functions include the following:

BSABeginTxn BSAGetNextQueryObject1
BSAChangeToken BSAGetObject
BSACreateObject BSAInit
BSADeleteObject BSAMarkObjectInactive
BSAEndData BSAQueryApiVersion
BSAEndTxn BSAQueryObject
BSAGetData BSASendData
BSAGetEnvironment BSATerminate

The X/Open API also supports the BSAResolveLifecycleGroup. See the X/Open Specification for detailed information on each function.

Note:The following functions are part of the XBSA Data Movement function group, but are not currently used in the X/Open API. Calls to these functions return the code, BSA_RC_BAD_CALL_SEQUENCE.
BSACreateObjectF
BSAGetObjectF
BSASetEnvironment

The API package that you receive includes a sample application. Review the source code for the sample application to see examples of the X/Open API functions in context.

Data Field Mapping

Included here is a mapping between the BSA data fields and the corresponding TSM fields:

BSA Fields TSM Fields
BSAObjectOwner Node name
AppObjectOwner Session owner name
SecurityToken Password
objectspaceName Filespace name
Left part of pathname Highlevel name
Rightmost part of pathname Lowlevel name
LifecycleGroup Management class
ResourceType FileSpaceType and objInfo

Maintaining Version Control in the API

All APIs have some form of version control, and X/Open is no exception. Ensure that the version of the X/Open API you are using in your application is compatible with the version of the API library that the end users have installed on their workstations.

The first API call that is issued when using the X/Open API should be BSAQueryApiVersion. This call:

The X/Open API is upwardly compatible. Applications written to older versions or releases of the API library will still operate correctly if the end user is running a newer version.

Determining the release of the API library is very important because some releases may have different memory requirements and data structure definitions. Downward compatibility might be possible on an individual basis. However, it is not recommended. Downward compatibility, if a requirement, is the responsibility of the application client.

The API library and the Trusted Communication Agent module (dsmtca) must be at the same level.

The BSAQueryApiVersion call returns the version of the API library that is installed on the end user's workstation. You can then compare the returned value with the version of the X/Open API with which the application client was built.

The version number of the application client's API is entered in the compiled object code as a set of three constants:

   BSA_API_VERSION
   BSA_API_RELEASE
   BSA_API_LEVEL

These constants are defined in the header file custom.h. The application client's API version should usually be less than, or equal to, the API library installed on the user's system. Be careful with any other condition.

The BSAQueryApiVersion call can be made at any time, whether the API session has been started or not.

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 passwordaccess=prompt, then a child process is not used.

Session Security

TSM, a session-based system, has security components that permit applications to start sessions in a secure manner. These security measures prohibit unauthorized access to the server and help insure system integrity.

Every session that the server starts must complete a sign-on process. This sign-on process requires a password that, when coupled with the node name of the client, insures proper authorization when connecting to the server. The application client is responsible for providing this password to the X/Open API for session initialization.

Passwords have expiration periods associated with them. If a BSAInit call fails with the password-expired return code (BSA_RC_TOKEN_EXPIRED), update the password before you can successfully establish the session.

Only the root session owner can change the password. First, make the BSAInit call with an empty string in the appObjectOwner field. Then, call BSAChangeToken to update the password.

Objects stored in the system also have ownerships associated with them. See Identifying the Object to understand how an application can take advantage of this to support multi-user applications. The application client is responsible for insuring that security and ownership rules are met once a session is started.

Determining the Session Parameters

After BSAInit is called to start a session, the application can make a call to BSAGetEnvironment to determine the parameters set for the session. The BSAGetEnvironment call returns such items as the node, owner, and server names used for the session, and the maximum number of objects that can be created in a single transaction.

The objectOwner.bsaObjectOwner field contains the TSM node name. This corresponds to the BSAObjOwner field when passwordaccess is set to prompt. When passwordaccess is set to generate, this field contains the machine name.

The objectOwner.appObjectOwner field contains the TSM owner name. This corresponds to the AppObjOwner field when passwordaccess is set to prompt. When passwordaccess is set to generate, this field contains the login name.

The calling application must allocate an array of ADSM_ENV_STRS elements with strings of size BSA_MAX_DESC for the environment output. The application must also allocate an array of character pointers with ADSM_ENV_STRS+1 elements. The extra element is for the NULL termination pointer.

Figure 18. An Example of BSAGetEnvironment

   char *envP[ADSM_ENV_STRS+1];
   char envStrs[ADSM_ENV_STRS] [BSA_MAX_DESC];
   for (i=0; i<ADSM_ENV_STRS; i++)
     envP[i] = envStrs[i];
 
   envP[i] = NULL;
   rc = BSAGetEnvironment(bsaHandle, &objOwner, envP);

The format of the output is:

   envStrs[0] = "DSMSRVR=xxx"
   envStrs[1] = "MAXOBJ=xx"

where:

Associating a Management Class With Objects

One of the primary features that TSM offers is the use of policy (management classes) to define how objects are stored and managed in TSM storage. A management class is associated with an object when the object is backed up or archived. This management class determines the following:

Management classes have two components, backup copy group, and an archive copy group. A copy group is a set of attributes that define the management policies for an object that is backed up or archived. If a backup operation is being performed, the attributes in the backup copy group apply. If an archive is being performed, the attributes in the archive copy group apply.

Because the use of policy is a very important component of TSM, the API requires all objects that are sent to the server first be assigned to a management class. There are two ways to do this.

Note:The backup or archive copy group in a particular management class can be empty or NULL. If an object is bound to the NULL backup copy group, then that object cannot be backed up. If an object is bound to the NULL archive copy group, the object cannot be archived.

The Transaction Model

All data sent to, received from, or deleted from TSM storage by the X/Open API is performed within a transaction. This provides a high level of data integrity for the TSM product, but it does impose some restrictions that an application client must take into consideration.

Start a transaction with a call to BSABeginTxn and end it with a call to BSAEndTxn.

A single transaction is an atomic action. Data sent or received within the bounds of a transaction either is all committed at the end of the transaction, or all rolled back if the transaction ends prematurely.

The TSM product supports the use of only a single operation type within a transaction. For example, you cannot perform both a send and a get operation within the bounds of a single transaction. The one exception is during a get operation, where you precede the get with a query operation.

Transactions can consist of either single objects or multiple objects. Smaller objects should be sent or received in a multiple object transaction. This greatly improves total system performance, because transaction overhead is decreased. The application client determines whether single or multiple transactions are appropriate.

All objects within a multiple object transaction must be sent to, or received from, the same copy destination. If you must send an object to, or receive it from, a different destination than the previous object, end the current transaction and start a new one. Within the new transaction, you can send or receive the object to the new copy destination.

The TSM product limits the number of objects that can be sent or received in a multiple object transaction. You can find this limit by calling BSAGetEnvironment and examining the MAXOBJ value.

The application client must keep track of the objects sent or received within a transaction in order to perform retry processing or error processing if the transaction is ended prematurely. Either the server or the client can stop a transaction at any time. The application client must be prepared to handle sudden transaction ends that it did not start.

Querying the TSM System

The X/Open API permits an application client to query a TSM server for information on the records stored there. You can define a set of criteria that the records on the server must meet in order to be returned by the query. All query operations must be done within the bounds of a transaction. See The Transaction Model.

A query operation consists of the following steps:

  1. Make the BSABeginTxn call to start a transaction.

  2. Define the parameters of your query.

    Use the data fields in the QueryDescriptor structure to specify the parameters of your query. Start by setting the copyType field to backup, archive, or any, depending on whether you want to query only backup copies, only archive versions, or both.

    For all queries, you can specify an object name in the objName field, or use wildcard characters to identify a group of objects. For backup queries, use the status field to specify only active or inactive copies, or both. For archive queries, specify the description in the description field and set the upper and lower boundaries of the create and expiration times in these fields: createTimeLB, createTimeUB, expireTimeLB, and expireTimeUB.

  3. Make the BSAQueryObject call.

    To start the query operation,make the BSAQueryObject call, passing in the QueryDescriptor structure. One of the following three codes is returned:

  4. Make the BSAGetNextQueryObject call.

    If more than one object satisfied the query parameters, then a BSAGetNextQueryObjectcall must be made to obtain each object after the first. The object descriptor for each object is added to the ObjectDescriptor structure.

    After each object is returned, check the return code. If the BSAGetNextQueryObject call returns the code BSA_RC_MORE_DATA, make the BSAGetNextQueryObject call again. If there is no more data, go to the next step.

  5. Make the BSAEndTxn call to end the transaction.

    When all query data has been retrieved or no further query data is needed, the BSAEndTxn call must be made to end the transaction and stop the query process. This causes the X/Open API to flush any remaining data from the query stream and release any resources utilized for the query.

Flowchart

Figure 19 displays the flowchart for performing query operations.

Figure 19. Flowchart for Query Operations



REQTEXT


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 20 displays the flowchart for performing backup or archive operations within a transaction.

Figure 20. 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

Receiving Data from a Server

The X/Open API permits application clients to receive data from TSM storage using the restore and retrieve functions of the product. Restore accesses objects that were previously backed up, and retrieve accesses objects that were previously archived. All restore and retrieve operations must be performed within the bounds of a transaction. See The Transaction Model.

Note:Only the API can restore or retrieve objects that were backed up or archived with API calls.

Once a session is established with the TSM server, use the following procedure to restore or retrieve data:

  1. Make the BSABeginTxn call to start a transaction.

  2. Make the BSAQueryObject call to query the TSM server for backup or archive data. (This step can be performed outside the transaction.)

    Before beginning a restore or retrieve operation, query the TSM server to determine what objects can be received from storage. To issue the query, first fill in the applicable fields in the QueryDescriptor structure with the desired search parameters. Then make the BSAQueryObject call with the QueryDescriptor.

    If the session was started with a NULL owner name, it is not necessary to specify the owner field. If the session was started with an explicit owner name, then only objects that explicitly have that owner name associated with them are returned.

    The query returns all information in an ObjectDescriptor structure. Different information is returned depending on whether the object was originally backed up or archived. For example, a query on backup objects returns information on whether an object is active or inactive, while a query on archive objects returns information such as the object descriptions.

    All queries return all information that was originally stored with the object, in addition to the following:

    copyid
    The copyid provides an eight-byte number that uniquely identifies this object for this node in TSM storage. Use this ID to request a specific object from storage for restore or retrieve processing.

    restoreOrder
    The restoreOrder provides a mechanism for receiving objects from TSM storage in the most efficient manner possible. Sort the objects to restore on this value to insure that tapes are mounted only once and are read from front to back.

    Keep some or all of the query information for later processing. Keep the copyid and restoreOrder fields because they are needed for the actual restore operation. Keep any other information that is needed to properly open a data file or identify a destination.

  3. Determine the objects to restore or retrieve from the server.

    Once the backup or archive query has been performed, the application client must determine which objects, if any, are to be restored or retrieved.

  4. If more than one object is selected, sort the objects on the restore order field.

    Once the objects to restore or retrieve are selected, they must be sorted in ascending order (low to high) by the restoreOrder field. This sorting is critical to the performance of the restore operation. Sorting the objects on the restoreOrder field means that the data is read from the server in the most efficient order. All data on disk is restored first, followed by data on media classes that require volume mounts (such as tape). The restoreOrder field also insures that data on tape is read in order with processing starting at the front of a tape and progressing towards the end.

    Properly sorting on the restoreOrder field means that duplicate tape mounts and unnecessary tape rewinds do not occur.

  5. Make the BSAGetObject call.

    The BSAGetObject call uses the copyType and copyid fields of the ObjectDescriptor to begin obtaining the first object from the system. The call begins a restore or retrieve operation by identifying the object that is requested from the data stream.

    BSAGetObject obtains the first block of data that is associated with the object. If the object has more data, go to the next step. If the return code is BSA_RC_NO_MORE_DATA, go to step 7.

  6. Make the BSAGetData call.

    Repeat this call as many times as necessary until the object has been received from the TSM server.

  7. Make the BSAEndData call.

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

  8. If you want to receive more than one object from the TSM server, repeat steps 5 through 7 for each object.

  9. Make the BSAEndTxn call to end the transaction.

    After all data for all requested objects has been received, the BSAEndTxn call must be made. You can also use this call to discard any remaining data in the restore stream for objects not yet received.

Flowchart

Figure 21 displays the flowchart for performing restore or retrieve operations.

Figure 21. Flowchart for Restore and Retrieve Operations



REQTEXT


Deleting Objects from the Server

The X/Open API applications can make calls to either delete objects that were archived or deactivate objects that were backed up. The former is dependent on the node authorization that is given when a TSM administrator registered the node. Administrators can specify whether nodes can delete archive objects.

The BSADeleteObject call is used for deleting archive objects, and the BSAMarkObjectInactive call is used for deactivating backup objects.

When deleting an archive object, the object is marked in TSM storage for deletion when the system next performs its object expiration cycle. Once an archive object is deleted from the server, it cannot be retrieved.

When a backup object on the TSM server is deactivated, the object moves from an active state to an inactive state. These states have different retention policies associated with them that are based on the management class assigned.

Note:A call to BSAMarkObjectInactive affects all objects with the same objType and the same name.

A call to BSADeleteObject or to BSAMarkObjectInactive is always made within the bounds of a transaction. The flowcharts in Figure 22 show how a call to BSADeleteObject or BSAMarkObjectInactive is preceded by a call to BSABeginTxn and followed by a call to BSAEndTxn.

Figure 22. Flowcharts for Delete Archive (left) and Deactivate Backup (right) Operations



REQTEXT


Identifying the Object

The TSM server can be viewed as an object storage server whose main goal is to efficiently store and retrieve named objects. The server has two main storage areas to meet this requirement:

Each object stored on the server has a name associated with it. The client controls the following key components of the name:

Object space name
Pathname
Object type.

When making decisions about naming objects for an application, remember that it might be necessary to externalize the full object names to the end user. Specifically, the end user might need to specify the object in an Include or Exclude statement when the application is run.

Object Space Name

A very important component of the name is the object space name. This name can be viewed as the name of a file system or disk drive, or any other high-level qualifier that groups related data together. TSM uses the object space to identify the file system or disk drive the data is located on. Thus, actions can be performed on all entities within an object space with relative ease, such as querying all objects within a specified object space.

The TSM server also has administrative commands to query the object spaces on a given node in TSM storage, and delete them if necessary. All data that the application client stores must have an object space name associated with it. Select the name carefully to group similar data together in the system.

An application client should select different object space names than the file system names a backup-archive client would use, in order to avoid possible interference. The application client should publish its object space names, so that end users can identify the objects for Include and Exclude statements, if necessary.

Pathnames

Another component of the object name is the pathname. The pathname consists of the directory path the object belongs in, and the actual name of the object in that directory path. When the object space name and pathname are concatenated, they must form a syntactically correct name on the operating system on which the client is running. It is not necessary for the name to exist as an object on the system or resemble the actual data on the local file system. However, the name must meet the standard naming rules in order to be properly processed for management classes.

Object Type

The object type identifies the object as either a file or a directory. A file is an object that contains both attributes and binary data. A directory is an object that contains only attributes.

TSM also accepts the value BSAObjectType_DATABASE, but treats it as BSAObjectType_FILE.

Example

The following example demonstrates what the application client would code on a UNIX platform:

   /myobjspace/pathname

Setting the Owner Name

Each object has an owner name associated with it. The rules governing what objects can be accessed depend on what owner name is used when a session is started. This object owner value can be used to control access to the object.

If a session is started with an empty string for the owner, that session owner is treated with session, (or root) authority. This session can perform any action on any object that is owned by this node regardless of the actual owner of that object. The session owner is set during the call to BSAInit in the AppObjectOwner field of the ObjectOwner structure.

If a session is started with a specific owner name, the session can only perform actions on objects that have that owner name associated with them. Backups or archives into the system all must have this owner name associated with them.Any queries performed only return values that have this owner name associated with them. The object owner value is set during the BSACreateObject call in the Owner field of the ObjectDescriptor structure.

Table 40 summarizes the conditions under which a user has access to an object.

Table 40. Summary Of User Access To Objects

Session owner Object owner User access
" " (empty string) (root, system owner) " " (empty string) Yes
" " (empty string) (root, system owner) specific name Yes
specific name " " (empty string) No
specific name same name Yes
specific name different name No

Using XOpen Functions With TSM

This section describes the following XOpen functions and how to use them with TSM.


TSM Changes to the XBSA Header Files

The X/Open API contains the header files custom.h, xbsa.h, and policy.h. TSM uses these header files with the following changes:

Changes to custom.h

The TSM X/Open API supports the following additional constants and return codes in custom.h:

/* XBSA library version, release, level
*/
#define BSA_API_VERSION     3
#define BSA_API_RELEASE     7
#define BSA_API_LEVEL       0
 
/* Constants used
 */
#define TSM_MAX_DESC               100     /* TSM max Desc size             */
#define TSM_MAX_OBJINFO            100     /* TSM max object information size*/
#define TSM_LOWEST_BOUND           0x0000  /* value for LowerBound max       */
#define TSM_HIGHEST_BOUND          0xFFFF  /* value for UpperBound max       */
#define TSM_ENV_STRS               2       /* number of env strings          */
#define ObjectDescriptorVersion     1       /* ver for ObjectDescriptor       */
#define UserDescriptorVersion       1       /* ver for UserDescriptor         */
#define BSAObjectType_DATABASE      4       /* ObjectType for Databases       */
 
/* Return Codes Used
 */
#define BSA_RC_OK                           0x00
#define BSA_RC_SUCCESS                      0x00
 
#define TSM_RC_ERROR                       0x60 /* see TSM error log        */
#define TSM_RC_INVALID_NODE                0x61 /* BSAObjOwner not match Init*/
#define TSM_RC_INVALID_COPYTYPE            0x62 /* invalid copyType          */
#define TSM_RC_INVALID_OBJTYPE             0x63 /* invalid objectType        */
#define TSM_RC_INVALID_STATUS              0x64 /* invalid object status     */
#define TSM_RC_INVALID_ST_VER              0x65 /* invalid structure version */
#define TSM_RC_OWNER_TOO_LONG              0x66 /* owner too long            */
#define TSM_RC_PSWD_TOO_LONG               0x67 /* pswd  too long            */
#define TSM_RC_PSWD_GEN                    0x68 /* pswd access = generate    */

Changes to xbsa.h

The TSM X/Open API supports the following changes to the type definitions in xbsa.h:

/* Changed tm typedef to 'struct tm' for AIX compiler                     */
/* ref BSAEvent, ObjectDescriptor, QueryDescriptor, Schedule              */
/*                                                                        */
/* For the function prototypes, int and long have been                    */
/* replaced with typedefs from custom.h.                                  */
/*                                                                        */
/* Included BSAGetNextQueryObject function prototype here since it was    */
/* accidentally omitted from the Data movement subset.                    */

Changes to policy.h

The TSM X/Open API supports the following changes to the function prototypes in policy.h:

/* For the function prototypes, int and long have been                    */
/* replaced with typedefs from custom.h.                                  */
/*                                                                        */
/* BSAGetNextQueryObject defined in xbsa.h because it should be part      */
/* of the Data Movement subset.                                           */

Footnotes:

1
In the X/Open Specification, BSAGetNextQueryObject was accidentally omitted from the list of functions in XBSA's Data Movement function group.


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