sqlca   SQLCA 構造体へのポインタ。

op   実行する動作または操作。

file_num   データベースのファイル番号。

page_num   データベースのページ番号。範囲内の値は、0 からページの最大数から 1 を引いた値までになります。

sqlda   SQLDA 構造体へのポインタ。

DB_BACKUP_START   これを呼び出してからバックアップを開始します。1 つのデータベースサーバに対して同時に実行できるバックアップはデータベースごとに 1 つだけです。バックアップが完了するまでデータベースチェックポイントは無効にされます (db_backup は、DB_BACKUP_END の op 値で呼び出されます)。バックアップが開始できない場合は、SQLCODE が SQLE_BACKUP_NOT_STARTED になります。それ以外の場合は、sqlca の SQLCOUNT フィールドにはデータベースページのサイズが設定されます。バックアップは一度に 1 ページずつ処理されます。

file_num、page_num、sqlda パラメータは無視されます。

DB_BACKUP_OPEN_FILE   file_num で指定されたデータベースファイルを開きます。これによって、指定されたファイルの各ページを DB_BACKUP_READ_PAGE を使用してバックアップできます。有効なファイル番号は、ルートデータベースファイルの場合は 0 から DB_BACKUP_MAX_FILE の値までで、トランザクションログファイルの場合は 0 から DB_BACKUP_TRANS_LOG_FILE の値までです。指定されたファイルが存在しない場合は、SQLCODE は SQLE_NOTFOUND になります。その他の場合は、SQLCOUNT はファイルのページ数を含み、SQLIOESTIMATE にはデータベースファイルが作成された時間を示す 32 ビットの値 (POSIX time_t) が含まれます。オペレーティングシステムファイル名は SQLCA の sqlerrmc フィールドにあります。

page_num と sqlda パラメータは無視されます。

DB_BACKUP_READ_PAGE   file_num で指定されたデータベースファイルから 1 ページを読み込みます。page_num の値は、0 から、DB_BACKUP_OPEN_FILE オペレーションを使用した db_backup に対する呼び出しの成功によって SQLCOUNT に返されるページ数未満の値までです。その他の場合は、SQLCODE は SQLE_NOTFOUND になります。sqlda 記述子は、バッファを指す DT_BINARY または DT_LONG_BINARY 型の変数で設定してください。このバッファは、DB_BACKUP_START オペレーションを使用した db_backup の呼び出しで SQLCOUNT フィールドに返されるサイズのバイナリデータを保持するのに十分な大きさにしてください。

DT_BINARY データは、2 バイトの長さフィールドの後に実際のバイナリデータを含んでいるので、バッファはページサイズより 2 バイトだけ大きくなければなりません。

DB_BACKUP_READ_RENAME_LOG   このアクションは、トランザクションログの最後のページが返された後にデータベースサーバがトランザクションログの名前を変更して新しいログを開始する点を除けば、DB_BACKUP_READ_PAGE と同じです。

データベースサーバが現時点でログの名前を変更できない場合 (バージョン 7.0.x 以前のデータベースで、完了していないトランザクションがある場合など) は、SQLE_BACKUP_CANNOT_RENAME_LOG_YET エラーが設定されます。この場合は、返されたページを使用しないで、要求を再発行して SQLE_NOERROR を受け取ってからページを書き込んでください。SQLE_NOTFOUND 条件を受け取るまでページを読むことを続けてください。

SQLE_BACKUP_CANNOT_RENAME_LOG_YET エラーは、何回も、複数のページについて返されることがあります。リトライループでは、要求が多すぎてサーバが遅くなることがないように遅延を入れてください。

SQLE_NOTFOUND 条件を受け取った場合は、トランザクションログはバックアップに成功してファイルの名前は変更されています。古いほうのトランザクションログファイルの名前は、SQLCA の sqlerrmc フィールドに返されます。

db_backup を呼び出した後に、sqlda->sqlvar[0].sqlind の値を調べてください。この値が 0 より大きい場合は、最後のログページは書き込まれていて、ログファイルの名前は変更されています。新しい名前はまだ sqlca.sqlerrmc にありますが、SQLCODE 値は SQLE_NOERROR になります。

この後、ファイルを閉じてバックアップを終了するとき以外は、db_backup を再度呼び出さないでください。再度呼び出すと、バックアップされているログファイルの 2 番めのコピーが得られ、SQLE_NOTFOUND を受け取ります。

DB_BACKUP_CLOSE_FILE   1 つのファイルの処理が完了したときに呼び出して、file_num で指定されたデータベースファイルを閉じます。

page_num と sqlda パラメータは無視されます。

DB_BACKUP_END   バックアップの最後に呼び出します。このバックアップが終了するまで、他のバックアップは開始できません。チェックポイントが再度有効にされます。

file_num、page_num、sqlda パラメータは無視されます。

DB_BACKUP_PARALLEL_START   並列バックアップを開始します。DB_BACKUP_START と同様、1 つのデータベースサーバに対して同時に実行できるバックアップはデータベースごとに 1 つだけです。バックアップが完了するまでデータベースチェックポイントは無効にされます (db_backup は、DB_BACKUP_END の op 値で呼び出されます)。バックアップが開始できない場合は、SQLE_BACKUP_NOT_STARTED を受け取ります。それ以外の場合は、sqlca の SQLCOUNT フィールドには各データベースページのサイズが設定されます。

file_num パラメータは、トランザクションログの名前を変更し、トランザクションログの最後のページが返された後で新しいログを開始するようデータベースに指示します。値が 0 以外の場合、トランザクションログの名前が変更されるか、再起動されます。それ以外の場合は、名前の変更も再起動も行われません。このパラメータにより、並列バックアップオペレーションの間は実行できない DB_BACKUP_READ_RENAME_LOG オペレーションが必要なくなります。

page_num パラメータは、データベースのページ数で表したクライアントバッファの最大サイズをデータベースサーバに通知します。サーバ側では、並列バックアップの読み込みで連続したページブロックを読み込もうとします。この値によって、サーバは割り付けるブロックのサイズを知ることができます。nnn の値を渡すと、サーバはクライアントが最大 nnnn ページのデータベースページをサーバから一度に受け入れる準備があることを認識します。サーバは、nnn ページのブロックに十分なメモリを割り付けられない場合、nnn より小さいサイズのページブロックを返す可能性があります。クライアント側で DB_BACKUP_PARALLEL_START を呼び出すまでデータベースページのサイズがわからない場合は、DB_BACKUP_INFO オペレーションでこの値をサーバに渡すことができます。この値は、バックアップページを取得する初回の呼び出し (DB_BACKUP_PARALLEL_READ) を実行する前に指定する必要があります。

DB_BACKUP_INFO   このパラメータは、並列バックアップに関する追加情報をデータベースに提供します。file_num パラメータは、提供される情報の種類を示し、page_num パラメータには値が指定されます。DB_BACKUP_INFO で次の追加情報を指定できます。

DB_BACKUP_PARALLEL_READ   このオペレーションでは、データベースサーバから 1 ブロック分のページを読み込みます。DB_BACKUP_OPEN_FILE オペレーションを使用してバックアップするファイルをすべて開いてから DB_BACKUP_PARALLEL_READ オペレーションを呼び出します。DB_BACKUP_PARALLEL_READ では file_num と page_num 引数は無視されます。

sqlda 記述子は、バッファを指す DT_LONGBINARY 型の変数で設定してください。DB_BACKUP_PARALLEL_START または DB_BACKUP_INFO オペレーションで指定した、nnn ページのサイズのバイナリデータを格納するのに十分なバッファを確保してください。

サーバは特定のデータベースファイルについてデータベースページの連続したブロックを返します。ブロックの最初のページのページ番号は、SQLCOUNT フィールドに返されます。ページが含まれているファイルのファイル番号は SQLIOESTIMATE フィールドに返され、この値は DB_BACKUP_OPEN_FILE 呼び出しで使用されるファイル番号の 1 つに一致します。返されるデータのサイズは DT_LONGBINARY 変数の stored_len フィールドから取得でき、常にデータベースページのサイズの倍数になります。この呼び出しによって返されるデータには指定されたファイルの連続したページのブロックが含まれていますが、別のデータブロックが順番に返されることを想定したり、データベースファイルのすべてのページが別のデータベースファイルのページの前に返されると想定することは危険です。呼び出し元では、他の別個のファイルの一部分や、別の呼び出しによって開かれたデータベースファイルの一部分を順番に関係なく受信できるよう準備しておく必要があります。

アプリケーションでは、読み込むデータのサイズが 0 になるか、sqlda->sqlvar[0].sqlind の値が 0 より大きくなるまで、このオペレーションを繰り返し呼び出してください。トランザクションログの名前を変更するか再起動してバックアップを開始すると、SQLERROR は SQLE_BACKUP_CANNOT_RENAME_LOG_YET に設定される場合があります。この場合は、返されたページを使用しないで、要求を再発行して SQLE_NOERROR を受け取ってからデータを書き込んでください。SQLE_BACKUP_CANNOT_RENAME_LOG_YET エラーは、何回も、複数のページについて返されることがあります。リトライループでは、要求が多すぎてデータベースサーバが遅くなることがないように遅延を入れてください。最初の 2 つの条件のいずれかを満たすまで、引き続きページを読み込みます。