Naming your API objects

Edit online

Establish a consistent naming convention for API object names. The naming convention must cater for the file space name, the high-level qualifier, and the low-level qualifier. The file space name and high-level qualifiers can refer to actual directory names. Each object name can consist of more than one directory name that applies to the low-level qualifier.

For convenience, use the name of the object that is not prefixed with directory information as the low-level qualifier. For more information, see Object names and IDs.

File space names must be fully qualified when they are referred to from either the API or the backup-archive command line. For example, on a UNIX or Linux® operating system, you register the following file spaces:

/a
/a/b

When you refer to /a, objects that are related only to file space /a are displayed. To view objects that are related to /a/b, you must specify /a/b as the file space name.

After you register both file spaces, if you back up object b into file space /a, then a query for /a/b continues to display objects that are related only to file space /a/b.

The exception to this restriction occurs in file space references when you attempt to query or delete file spaces with the API. In both cases, the file space names do not have to be fully qualified if you use a wildcard character. For example, /a* refers to both /a and /a/b.

Tip: If interoperability is important for you, then avoid file space names that overlap.

On Windows systems, enclose file space names in braces { } for API objects when you access the objects from the backup-archive command line interface. Windows operating systems automatically place file space names in uppercase letters when you register or refer the names. However, this automatic function does not occur for the remainder of the object name specification. If you want full interoperability, place the high-level qualifier and the low-level qualifier in uppercase letters in the application when you back up API objects. If your application does not uppercase high-level qualifiers (directory names) and low-level qualifiers (file names) before it sends objects to the server, you will be unable to access the objects directly by name through the backup-archive client.

For example, if an object is stored on the server as {"FileSpacename"}\TEST\MYDIRNAME\file.txt, you cannot directly restore or query the file.txt object because your application did not uppercase the file name before the file was copied to the server. The only way to manipulate these objects is to use wildcard characters. For example, to query \TEST\MYDIRNAME\file.txt, a backup-archive client user must use wildcard characters for all parts of the object name that were not uppercased before they were sent to the server. The following command must be used to query this file.txt file:

dsmc query backup {"FileSpaceName"}\TEST\MYDIRNAME\*

If any other of the other qualifiers are also saved in lowercase text, those qualifiers must also be queried by using wildcards. For example, to query an object that is stored as {"FileSpaceName"}\TEST\mydirname\file.txt, use the following command:

dsmc query backup {"FileSpaceName"}\TEST\*\*

The examples that follow demonstrate these concepts. In both Windows and UNIX or Linux environments, you do not have to specify either the complete high-level or low-level qualifier. However, if you do not specify the complete qualifier, then you must use the wildcard character.

Platform	Example
Windows	To query all backed-up files in file space `MYFS`, enter the following string: `dsmc q ba "{MYFS}\\"` You must use at least one asterisk (*) for each of the high-level and low-level qualifiers.
UNIX or Linux	To query all backed-up files in file space `/A`, enter the following string: `dsmc q ba "/A//"` You must use at least one asterisk (*) for each of the high-level and low-level qualifiers.