Click here to view and discuss this page in DocCommentXchange. In the future, you will be sent there automatically.

SQL Anywhere 11.0.1 (日本語) » SQL Anywhere サーバ - プログラミング » SQL Anywhere データ・アクセス API » SQL Anywhere Embedded SQL » ライブラリ関数のリファレンス

 

db_backup 関数

プロトタイプ
void db_backup(
SQLCA * sqlca,
int op,
int file_num,
unsigned long page_num,
struct sqlda * sqlda);
権限

DBA 権限、REMOTE DBA 権限 (SQL Remote の場合)、または BACKUP 権限を持つユーザとして接続してください。

説明
BACKUP 文を推奨

この関数を使用してアプリケーションにバックアップ機能を追加することもできますが、このタスクには BACKUP 文を使用することをおすすめします。BACKUP 文を参照してください。

実行されるアクションは、op パラメータの値によって決まります。

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

    file_numpage_numsqlda パラメータは無視されます。

  • 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_numpage_numsqlda パラメータは無視されます。

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

    注意

    db_backup を使用して並列バックアップを開始すると、ライタ・スレッドは作成されません。db_backup の呼び出し元でデータを受け取り、ライタとして動作するようにしてください。

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

    • DB_BACKUP_INFO_PAGES_IN_BLOCK   page_num 引数には、1 つのブロックで送信される最大ページ数が含まれます。

    • DB_BACKUP_INFO_CHKPT_LOG   これは、クライアント側では BACKUP 文の WITH CHECKPOINT LOG オプションと同等です。DB_BACKUP_CHKPT_COPY の page_num 値は COPY を示しますが、DB_BACKUP_CHKPT_NOCOPY の値は NO COPY を示します。値が指定されないと、デフォルトで COPY に設定されます。

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

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

    サーバは特定のデータベース・ファイルについてデータベース・ページの連続したブロックを返します。ブロックの最初のページのページ番号は、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 つの条件のいずれかを満たすまで、引き続きページを読み込みます。

dbbackup ユーティリティは、次のようなアルゴリズムを使用します。これは、C のコードではなく、エラー・チェックは含んでいません。

sqlda->sqld = 1;
sqlda->sqlvar[0].sqltype = DT_LONGBINARY

/* Allocate LONGBINARY value for page buffer. It MUST have */
/* enough room to hold the requested number (128) of database pages */
sqlda->sqlvar[0].sqldata = allocated buffer

/* Open the server files needing backup */
for file_num = 0 to DB_BACKUP_MAX_FILE
  db_backup( ... DB_BACKUP_OPEN_FILE, file_num ... )
  if SQLCODE == SQLE_NO_ERROR
    /* The file exists */
    num_pages = SQLCOUNT
    file_time = SQLE_IO_ESTIMATE
    open backup file with name from sqlca.sqlerrmc
end for

/* read pages from the server, write them locally */
while TRUE
  /* file_no and page_no are ignored */
  db_backup( &sqlca, DB_BACKUP_PARALLEL_READ, 0, 0, &sqlda );

  if SQLCODE != SQLE_NO_ERROR
     break;

  if buffer->stored_len == 0 || sqlda->sqlvar[0].sqlind > 0
     break;

  /* SQLCOUNT contains the starting page number of the block    */
  /* SQLIOESTIMATE contains the file number the pages belong to */
  write block of pages to appropriate backup file
end while

/* close the server backup files */
for file_num = 0 to DB_BACKUP_MAX_FILE
    /* close backup file */
    db_backup( ... DB_BACKUP_CLOSE_FILE, file_num ... )
end for

/* shut down the backup */
db_backup( ... DB_BACKUP_END ... )

/* cleanup */
free page buffer