3.2.4.4.1.39 IVolumeClient::DiskMergeQuery (Opnum 44)

  • Article

The DiskMergeQuery method gathers disk and volume information needed to merge a foreign dynamic disk group into the primary disk group of the server. This is a synchronous task.

 HRESULT DiskMergeQuery(
   [in] int cchDgid,
   [in, size_is(cchDgid)] byte* dgid,
   [in] int numDisks,
   [in, size_is(numDisks)] LdmObjectId* diskList,
   [out] hyper* merge_config_tid,
   [out] int* numRids,
   [out, size_is(,*numRids)] hyper** merge_dm_rids,
   [out] int* numObjects,
   [out, size_is(,*numObjects)] MERGE_OBJECT_INFO** mergeObjectInfo,
   [in, out] unsigned long* flags,
   [out] TASK_INFO* tinfo
 );

cchDgid: Size of dgid in characters, including the terminating null character.

dgid: Null-terminated string containing the UUID of the disk group to be merged. This parameter is generated by converting a GUID to a null-terminated ASCII string and then treating the resulting string as a byte array.

numDisks: Number of disks passed in diskList.

diskList: Array of OIDs of type LdmObjectId that specify the disks of the dgid group to be merged.

merge_config_tid: Pointer to the modification sequence number of the disk group to be merged.

numRids: Pointer to the number of elements returned in merge_dm_rids.

merge_dm_rids: Pointer to an array of disk records representing the disks that will be merged.

numObjects: Number of elements returned in mergeObjectInfo.

mergeObjectInfo: Pointer to an array of MERGE_OBJECT_INFO structures that contain information about the volumes that will be merged.

flags: Disk merge query flags. The value of this field is generated by combining zero or more of the following applicable flags with a logical OR operation.

Value

Meaning

DSKMERGE_IN_NO_UNRELATED

0x00000001

Do not retrieve merge information for volumes of the foreign disk group that do not have extents on diskList . This is an input-only flag.

DSKMERGE_OUT_NO_PRIMARY_DG

0x00000001

The machine does not have a primary disk group. This is an output-only flag.

tinfo: Pointer to a TASK_INFO structure that the client can use to track the request's progress.<146>

Return Values: The method MUST return 0 or a nonerror HRESULT on success, or an implementation-specific nonzero error code on failure (as specified in [MS-ERREF]; see also section 2.2.1 for HRESULT values predefined by the Disk Management Remote Protocol).

Upon receiving this message, the server MUST validate parameters:

  1. Verify that dgid is a valid disk group ID belonging to a foreign dynamic disk group.

  2. Verify that the disk objects specified by diskList are in the list of storage objects and belong to the disk group specified by dgid.

  3. Verify that merge_config_tid is not NULL.

  4. Verify that numRids and merge_dm_rids are not NULL.

  5. Verify that numObjects and mergeObjectInfo are not NULL.

  6. Verify that flags is not NULL.

If parameter validation fails, the server MUST fail the operation immediately, returning an appropriate error as its response to the client.

Otherwise, the server MUST compose a response to the client as follows:

  1. The modification sequence number of the disk group specified by dgid MUST be returned in the output parameter merge_config_tid.

  2. Enumerate all dynamic disk records from the configuration of the disk group.

  3. Allocate a buffer large enough to contain the identifiers of the enumerated dynamic disk records.

  4. Populate the buffer with the identifiers of the enumerated dynamic disk records.

  5. The buffer MUST be returned to the client in the output parameter merge_dm_rids.

  6. The number of identifiers in the buffer MUST be returned in the output parameter numRids.

  7. If DSKMERGE_IN_NO_UNRELATED flag is set, attempt to enumerate only the volumes that have extent on diskList. If DSKMERGE_IN_NO_UNRELATED flag is not set, enumerate all volumes belonging to the disk group that will be merged.

  8. Allocate a second buffer large enough to contain MERGE_OBJECT_INFO structures that describe the enumerated volumes.

  9. Populate each MERGE_OBJECT_INFO structure in the second buffer with information about the volume.

  10. The second buffer MUST be returned to the client in the output parameter mergeObjectInfo.

  11. The number of MERGE_OBJECT_INFO structures in the second buffer MUST be returned to the client in the output parameter numObjects.

  12. If the machine does not have a primary disk group, the server MUST set the DSKMERGE_OUT_NO_PRIMARY_DG flag in the output parameter flags.

  13. Return a response that contains the preceding output parameters and the status of the operation.

  14. Send the task completion notification.

The server MUST NOT change the list of storage objects as part of processing this message.<147>