dsmRenameObj

Edit online

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 file space 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.

Restrictions:
  • Only the owner of the object can rename it.
  • The dsmRenameObj function is not supported if data retention protection is enabled on the IBM Storage Protect server or if you are connected to the IBM Storage Protect for Data Retention server.

The dsmRenameObj function call tests for these merge conditions:

  • The current dsmObjName object and the new high-level or low-level object must match on owner, copy group, and management class.
  • The current dsmObjName must have been backed up more recently than the currently active object with the new name.
  • There must be only an active copy of the current dsmObjName with no inactive copies.

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 file space 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 file space 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: There are no output parameters.

Return codes

The return code numbers are provided in parentheses ( ).

Table 1. 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 IBM® Storage Protect server must be at V3.7.4.0 or later for this function to work.