Tivoli Header

Tivoli Storage Manager Using the Application Program Interface

dsmRenameObj

Note:
The TSM server must be at the 3.7.4.0 level or higher for this function to work.

The dsmRenameObj function call renames the high-level or low-level object name. For backup objects, pass in the current object name and changes either for high-level or low-level object names. For archive objects, pass in the current object filespace name and object ID, and changes either for high-level or low-level object names. Use this function call within dsmBeginTxn and dsmEndTxn calls.

The merge flag determines whether or not a duplicate backup object name is merged with the existing backups. If the new name corresponds to an existing object and merge is true, the current object is converted to the new name and it becomes the active version of the new name while the existing active object that had that name becomes the top most inactive copy of the object. If the new name corresponds to an existing object and merge is false, the function then returns the return code, DSM_RC_ABORT_DUPLICATE_OBJECT.

The dsmRenameObj function call tests for these merge conditions:

Note:
Only the owner of the object can rename it.

Syntax

dsInt16_t dsmRenameObj  (dsmRenameIn_t       *dsmRenameInP,
                         dsmRenameOut_t      *dsmRenameOutP);

Parameters

dsUint32_t dsmHandle (I)
The handle that associates this call with a previous dsmInitEx call.

dsmRenameIn_t *dsmRenameInP
This structure contains the input parameters.

dsUint8_t repository (I);
This parameter indicates whether the filespace to delete is in the backup repository or the archive repository.

dsmObjName *objNameP (I);
This parameter is a pointer to the structure that contains the current filespace name, high-level object name, low-level object name, and object type.

char newHl [DSM_MAX_HL_LENGTH + 1];
This parameter specifies the new high-level name.

char newLl [DSM_MAX_LL_LENGTH + 1];
This parameter specifies the new low-level name.

dsBool_t merge;
This parameter determines whether or not a backup object is merged with duplicate named objects. The values are either true or false.

ObjID;
The object ID for archive objects.

dsmRenameOut_t *dsmRnameOutP
This structure contains the output parameters.
Note:
Currently, there are no output parameters.

Return Codes

The return code numbers are provided in parentheses ( ).

Table 40. Return Codes for dsmRenameObj

Return Code Explanation
DSM_RC_ABORT_MERGE_ERROR (45) Server detected a merge error.
DSM_RC_ABORT_DUPLICATE_OBJECT (32) Object already exists and merge is false.
DSM_RC_ABORT_NO_MATCH (2) Object not found.
DSM_RC_REJECT_SERVER_DOWNLEVEL (58) The TSM server must be at the 3.7.4.0 level or higher for this function to work.


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