dsmBeginGetData

オンライン編集

dsmBeginGetData 関数呼び出しは、ストレージ内のオブジェクトのリストに対するリストアまたはリトリーブ操作を開始します。このオブジェクトのリストは、 dsmGetList 構造に含まれています。アプリケーションは、 dsmBeginGetDataへの呼び出しの前に、照会からの値を使用してこのリストを作成します。

呼び出し側は、オブジェクト照会から取得された restore order (リストア順序) フィールドを使用して、この呼び出しに含まれているリストをソートする必要があります。これによって、データ・テープの巻き戻しや再マウントを行う必要なしに、考えられる最も効率のよい方法でストレージからオブジェクトがリストアされることが保証されます。

オブジェクト全体を取得する場合、最大 dsmGetList.numObjID は DSM_MAX_GET_OBJ です。オブジェクトの一部を取得する場合、最大は DSM_MAX_PARTIAL_GET_OBJ です。

リスト内の各オブジェクトを取得するには、 dsmBeginGetData への呼び出しの後に、 dsmGetObj への 1 つ以上の呼び出しを続けます。各オブジェクトが取得されるか、オブジェクトの追加データが不要になると、 dsmEndGetObj 呼び出しが送信されます。

すべてのオブジェクトが取得されるか、 dsmEndGetObj が取り消されると、 dsmEndGetData 呼び出しが送信されます。この後、再びサイクルを開始できます。

構文

dsInt16_t dsmBeginGetData (dsUint32_t       dsmHandle,
   dsBool_t     mountWait,
   dsmGetType   getType,
   dsmGetList  *dsmGetObjListP);

パラメーター

dsUint32_t dsmHandle (I)

この呼び出しを直前の dsmInitEx 呼び出しに関連付けるハンドル。

dsBool_t mountWait (I)

必要なデータが現在オフラインの場合に、オフライン・メディアがマウントされるまでアプリケーション・クライアントが待機するかどうかを示す真または偽のブール値。 mountWait が真の場合、アプリケーションはサーバーに必要なメディアがマウントされるのを待ちます。アプリケーションは、メディアがマウントされるか、または要求が取り消されるまで待ちます。

dsmGetType getType (I)

取得するオブジェクトがどのタイプであるかを示す、gtBackup および gtArchive からなるタイプのリスト。

dsmGetList *dsmGetObjListP (I)

リストアまたはリトリーブするオブジェクトまたは部分オブジェクトについての情報が入っている構造。この構造はオブジェクト ID のリストを指し、部分オブジェクトのリトリーブまたはリストアの場合は、関連したオフセットおよび長さのリストを指します。アプリケーションが部分オブジェクト・リストアまたはリトリーブ機能を使用する場合は、 dsmGetList.stVersion フィールドを dsmGetListPORVersionに設定します。部分オブジェクトのリストアまたはリトリーブでは、送信中にデータを圧縮することはできません。これを強制的に行うには、ObjAttr.objCompressed を bTrue に設定します。

この構造について詳しくは、図 1 および API タイプ定義ソース・ファイルを参照してください。

部分オブジェクトのリストアまたはリトリーブについて詳しくは、部分オブジェクトのリストアまたはリトリーブを参照してください。

戻りコード

戻りコード番号を括弧 ( ) 内に示してあります。

表 1. のリターンコード dsmBeginGetData
戻りコード	説明
DSM_RC_ABORT_INVALID_OFFSET (33)	部分オブジェクト・リトリーブ中に指定されたオフセットが、オブジェクトの長さより大きい。
DSM_RC_ABORT_INVALID_LENGTH (34)	部分オブジェクト・リトリーブ中に指定された長さがオブジェクトの長さより大きいか、またはオフセットにこの長さを加えると、オブジェクトの終わりを超える。
DSM_RC_NO_MEMORY (102)	要求を完了するための RAM が残っていない。
DSM_RC_NUMOBJ_EXCEED (2029)	dsmGetList.numObjId が DSM_MAX_GET_OBJ より大である。
DSM_RC_OBJID_NOTFOUND (2063)	オブジェクト ID が見つからなかった。このオブジェクトはリストアされなかった。
DSM_RC_WRONG_VERSION_PARM (2065)	アプリケーション・クライアントの API バージョンは、 IBM® Storage Protect ライブラリーのバージョンとは異なります。