TSM Using the API


Interoperability

Interoperability, the backup-archive command-line access to API objects, manages API objects from the backup-archive command line. The following command-line actions are provided:

Path information for backup-archive client objects is actual directories. In contrast, API object path information might not have any relationship to existing directories; the path might be completely contrived. Interoperability does not change this aspect of these two object types. However, you must follow certain restrictions and conventions to use this feature successfully.


Naming Your API Objects

Establish a clear and consistent naming convention for API object names that consist of the filespace name, the high-level qualifier, and the low-level qualifier. The filespace name and high-level qualifiers refer to actual directory names, although this is not a requirement. Each can consist of multiple directory names that apply to the low-level qualifier. We strongly recommend that the low-level qualifier be the name of the object that is not prefixed with directory information. See "Identifying the Object" for more information.

Generally, filespace names must be fully qualified when they are referred from either the API or the backup-archive command line. For example, on a UNIX platform, if you register filespace /a and another filespace, /a/b, then, referring to /a will display objects related to filespace /a only. To view objects related to /a/b, fully specify /a/b as the filespace name. After registering both filespaces, if you back up object b into filespace /a, then a query for /a/b will continue to show objects related to filespace /a/b only.

The exception to this restriction occurs in filespace references when you attempt to query or delete file spaces with the API. In both cases, it is not necessary for filespace names to be fully qualified if a wildcard character is used. For example, /a* will refer both /a and /a/b.

Note:If interoperability is important to you, then avoid filespace names that overlap.

On Intel platforms, enclose filespace names in braces { } for API objects when you access from the backup-archive command line. Intel platforms automatically place filespace names in uppercase letters when you register or refer them. However, this is not true for the remainder of the object name specification. If you want full interoperability, we recommend that you place, in uppercase letters, the high-level qualifier, and the low-level qualifier in the application when you back up API objects. The examples below demonstrate these concepts. In both environments, it is not necessary to specify completely either the high-level or the low-level qualifier. However, if you do not, then you must use the wildcard character.

Platform Example
UNIX To query all backed-up files in filespace /A from the command line, enter:
   dsmc q ba "/A/*/*"
Note:There is at least one asterisk (*) for each of the high-level and low-level qualifiers.
Intel To query all backed-up files in filespace MYFS from the command line, enter:
   dsmc q ba "{MYFS}\*\*"
Note:There is at least one asterisk (*) for each of the high-level and low-level qualifiers.

Using Commands

To view and manage objects that other users own either on the same node or on a different node, first give access with the set access command. Then, specify the owner and the node. If you are using the backup-archive command line, specify the owner and node by using the fromowner and fromnode options:

   dsmc q ba "/A/*/*"  -fromowner=other_owner  -fromnode=other_node

See dsmInitEx for more information.

Table 11 describes the commands that you can use with API objects.

Table 11. Using Commands With API Objects

Command Description
Delete Archive Archived files that the current user owns can be deleted. The set access settings have no effect on this command.
Delete Filespace The delete filespace command affects API objects.
Query From the backup-archive command line, you can query backed up and archived API objects and objects that other users own, or that reside on other nodes. See Naming Your API Objects for information about querying API objects. Use the existing -fromowner option to query objects that a different user owns for which the set access permission has been given. Use the existing -fromnode option to query objects residing on another node for which the set access permission has been given. See dsmInitEx for more information.

Restore


Retrieve

Note:Use these commands for exception situations only.

These commands return data as bit files that are created using default file attributes. You can restore or retrieve API objects that other users own, or that are from a different node. The set access command determines which objects qualify.

Set Access The set access command permits users to manage API objects that another user owns, or that are from another node.


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