API - Embarcadero Websitedocs.embarcadero.com/.../1.2_JA/html/Pdf/APIGuide.pdf · 2009-02-06 · ii sql ステートメントを処理する api アプリケーションの作成

API ガイド

Borland Software Corporation20450 Stevens Creek Blvd., Suite 800, Cupertino, CA 95014 USAwww.borland.com

Borland®

InterBase® 2007

Borland Software Corporation は、本書に記載されているアプリケーションに対する特許を取得または申請している場合があります。本書の提供は、これらの特許に関する権利を付与することを意味するものではありません。

COPYRIGHT © 2003-2006 Borland Software Corporation. All rights reserved.

Borland のブランド名および製品名はすべて、米国 Borland Software Corporation の米国およびその他の国における商標または登録商標です。その他の製品名は、各所有者の商標または登録商標です。

Part no: INT0070WW21003 7E1R0503

0203040506 9 8 7 6 5 4 3 2 1

目次
表 v
第 1 章API ガイドの使い方対象読者 . . . . . . . . . . . . . . . . . . . . 1-1このガイドの内容 . . . . . . . . . . . . . . . 1-1データベースとアプリケーションのサンプル . 1-3

第 2 章アプリケーションの必要条件すべてのアプリケーションの必要条件 . . . . . 2-1

ibase.h のインクルード . . . . . . . . . . . 2-2データベースの必要条件 . . . . . . . . . . 2-2トランザクションの必要条件 . . . . . . . . 2-3

その他の必要条件 . . . . . . . . . . . . . . . 2-4Microsoft Windows の必要条件 . . . . . . 2-4DSQL の必要条件 . . . . . . . . . . . . . . 2-4BLOB の必要条件 . . . . . . . . . . . . . . 2-5配列の必要条件 . . . . . . . . . . . . . . . 2-5イベントの必要条件 . . . . . . . . . . . . . 2-6エラー処理の必要条件 . . . . . . . . . . . 2-6サービスの必要条件 . . . . . . . . . . . . . 2-7

コンパイルとリンク . . . . . . . . . . . . . . 2-7

第 3 章InterBase API によるプログラミング

アプリケーション開発の基本手順 . . . . . . . 3-1サポートされている開発環境 . . . . . . . . . 3-1ユーザー名とパスワードの必要条件 . . . . . . 3-2ユーザー名とパスワードの指定 . . . . . . . . 3-2環境変数の使い方 . . . . . . . . . . . . . . . 3-3

デフォルトのデータベースディレクトリの設定 . . . . . . . . . . . . . . . . . . . . . . . 3-3

ユーザー名とパスワードの設定 . . . . . . . 3-4データ型 . . . . . . . . . . . . . . . . . . . . 3-4呼び出し規約 . . . . . . . . . . . . . . . . . . 3-4アプリケーションの構築（ビルド） . . . . . . 3-4

コンパイラ . . . . . . . . . . . . . . . . . 3-4リンク . . . . . . . . . . . . . . . . . . . . 3-5インクルードファイル . . . . . . . . . . . 3-5Microsoft C++ を使用する場合 . . . . . . 3-6Borland C/C++ を使用する場合 . . . . . 3-7統合開発環境（IDE）の設定 . . . . . . . . 3-7モジュール定義ファイル . . . . . . . . . . 3-8

ダイナミックリンクライブラリ（DLL）を使用する . . . . . . . . . . . . . . . . . . . . 3-8

サンプルプログラム . . . . . . . . . . . . 3-9

第 4 章データベースの操作データベースへの接続 . . . . . . . . . . . . . 4-2

データベースハンドルの作成 . . . . . . . . 4-2DPB の作成と値の設定 . . . . . . . . . . . 4-3DPB パラメータ . . . . . . . . . . . . . . 4-4DPB へのパラメータの追加 . . . . . . . . 4-7データベースへの接続 . . . . . . . . . . . 4-8

接続に関する情報の要求 . . . . . . . . . . . 4-10要求バッファ . . . . . . . . . . . . . . . 4-10結果バッファ . . . . . . . . . . . . . . . 4-10ステータス情報 . . . . . . . . . . . . . . 4-11結果バッファ項目と結果バッファ値 . . . 4-11isc_database_info() の呼び出し例 . . . . 4-14

データベース接続の解除 . . . . . . . . . . . 4-15データベースの削除 . . . . . . . . . . . . . 4-16

第 5 章トランザクションの操作トランザクションの開始 . . . . . . . . . . . . 5-2

トランザクションハンドルの作成 . . . . . 5-2トランザクションパラメータバッファの作成

. . . . . . . . . . . . . . . . . . . . . . . 5-3isc_start_transaction() の呼び出し . . . . 5-11isc_start_multiple() の呼び出し . . . . . 5-12

トランザクションの終了 . . . . . . . . . . . 5-14isc_commit_transaction() の使い方 . . . 5-15isc_commit_retaining() の使い方 . . . . 5-15isc_prepare_transaction() の使い方 . . 5-16isc_prepare_transaction2() の使い方 . . . 5-17isc_rollback_transaction() の使い方 . . . 5-17isc_rollback_retaining() の使い方 . . . 5-17

第 6 章動的 SQL の操作DSQL プログラミングプロセスの概要 . . . . 6-1DSQL API アプリケーションの制限事項 . . . 6-2

データベースへのアクセス . . . . . . . . . 6-2トランザクションの操作 . . . . . . . . . . 6-3データベースの作成 . . . . . . . . . . . . 6-4BLOB データの処理 . . . . . . . . . . . . 6-4配列データの処理 . . . . . . . . . . . . . . 6-4

i

SQL ステートメントを処理する API アプリケーションの作成 . . . . . . . . . . . . . . . . . 6-4

API 呼び出しが SQL ステートメントを処理できるかどうかの判定 . . . . . . . . . . . . 6-5

SQL ステートメントを文字列として表す . 6-5SQL ステートメント文字列内でパラメータを指定する . . . . . . . . . . . . . . . . . . 6-6

XSQLDA . . . . . . . . . . . . . . . . . . . . 6-6XSQLDA のフィールド . . . . . . . . . . 6-8XSQLVAR のフィールド . . . . . . . . . . 6-9入力デスクリプタ . . . . . . . . . . . . . 6-10出力デスクリプタ . . . . . . . . . . . . . 6-11XSQLDA_LENGTH マクロの使い方 . . 6-11SQL データ型マクロ定数 . . . . . . . . . 6-11可変長文字列データ型の操作 . . . . . . . 6-14NUMERIC データ型と DECIMAL データ型の操作 . . . . . . . . . . . . . . . . . . . . 6-14

データ型の強制変換 . . . . . . . . . . . . 6-15数値データの配置（アラインメント） . . . 6-16

DSQL のプログラミング手法 . . . . . . . . 6-16手法 1 : パラメータのない非クエリー SQL ステートメント . . . . . . . . . . . . . . 6-17

手法 2 : パラメータのある非クエリー SQL ステートメント . . . . . . . . . . . . . . 6-18

手法 3 : パラメータのないクエリー SQL ステートメント . . . . . . . . . . . . . . . . . 6-21

手法 4 : パラメータのあるクエリー SQL ステートメント . . . . . . . . . . . . . . . . . 6-25

未知の文タイプを実行時に判定する . . . . . 6-32

第 7 章BLOB データの操作BLOB の概要 . . . . . . . . . . . . . . . . . . 7-2

BLOB データの格納方法 . . . . . . . . . . 7-2BLOB サブタイプ . . . . . . . . . . . . . . 7-3BLOB のデータベース上での格納形式 . . . 7-3

BLOB デスクリプタ . . . . . . . . . . . . . . 7-4BLOB デスクリプタの値の設定 . . . . . . . . 7-4BLOB データの操作 . . . . . . . . . . . . . . 7-5

BLOB からデータを読み取る . . . . . . . . 7-6BLOB にデータを書き込む . . . . . . . . 7-10BLOB の削除 . . . . . . . . . . . . . . . 7-14

BLOB に関する情報の要求 . . . . . . . . . 7-14項目リストバッファ . . . . . . . . . . . . 7-15結果バッファ . . . . . . . . . . . . . . . 7-15BLOB バッファ項目 . . . . . . . . . . . 7-16ステータスメッセージ . . . . . . . . . . 7-16isc_blob_info() の呼び出し例 . . . . . . . 7-16

BLOB データのフィルタリング . . . . . . . 7-18独自のフィルタを使う . . . . . . . . . . 7-18

データベースに対する外部 BLOB フィルタの宣言 . . . . . . . . . . . . . . . . . . . 7-18

外部 BLOB フィルタの作成 . . . . . . . 7-19フィルタリングを必要とするアプリケーションの作成 . . . . . . . . . . . . . . . . . . 7-24

第 8 章配列データの操作配列の概要 . . . . . . . . . . . . . . . . . . . 8-1

配列のデータベースへの格納 . . . . . . . . 8-2配列デスクリプタ . . . . . . . . . . . . . . 8-2配列デスクリプタの値の設定 . . . . . . . . 8-4

配列データのアクセス . . . . . . . . . . . . . 8-5配列からデータを読み取る . . . . . . . . . 8-6配列にデータを書き込む . . . . . . . . . 8-10配列の削除 . . . . . . . . . . . . . . . . 8-15

第 9 章データの変換InterBase 形式から C 形式への日付と時刻の変換

. . . . . . . . . . . . . . . . . . . . . . . . 9-2C 形式から InterBase 形式への日付と時刻の変換

. . . . . . . . . . . . . . . . . . . . . . . . 9-3数値のバイト順の逆転 . . . . . . . . . . . . . 9-3

第 10 章エラー条件の処理エラーステータスベクターの設定 . . . . . . 10-1ステータスベクターの情報を使う . . . . . . 10-2

ステータスベクターをチェックしてエラーの有無を判定する . . . . . . . . . . . . . . 10-2

InterBase エラーメッセージの表示 . . . 10-3InterBase エラーメッセージの取り込み . 10-3

エラーに対する SQLCODE 値の設定 . . . . 10-5SQL エラーメッセージの表示 . . . . . . 10-5SQL エラーメッセージの取り込み . . . . 10-6

ステータスベクターの解析 . . . . . . . . . 10-7ステータスベクターの解析方法 . . . . . 10-7クラスタの先頭の long 値の意味 . . . . . 10-7クラスタの 2 番めの long 値の意味 . . . 10-9クラスタの 3 番めの long の意味 . . . .10-10ステータスベクターの解析の例 . . . . .10-11

第 11 章イベントの操作InterBase のイベントメカニズム . . . . . . 11-1

イベントパラメータバッファ . . . . . . . 11-2同期イベントの通知 . . . . . . . . . . . 11-2非同期イベントの通知 . . . . . . . . . . 11-2

ii

トランザクションのイベント制御 . . . . 11-3isc_event_block( ) による EPB の作成 . . . . 11-3isc_wait_for_event() によるイベントの待機 . 11-4isc_que_events() による処理の続行 . . . . . 11-5

AST の作成 . . . . . . . . . . . . . . . . 11-6isc_que_events() の例 . . . . . . . . . . . 11-6

isc_event_counts() による発生イベントの判定. . . . . . . . . . . . . . . . . . . . . . . . 11-8

isc_cancel_events() による通知の取り消し 11-10

第 12 章サービスの操作サービス API の概要 . . . . . . . . . . . . . 12-1

一般情報 . . . . . . . . . . . . . . . . . . 12-1サービスパラメータバッファの使い方 . . 12-2isc_service_attach() による Services Manager への接続 . . . . . . . . . . . . . . . . . 12-3

isc_service_detach() による Services Manager からの接続解除 . . . . . . . . . . . . . 12-4

isc_service_start() によるサービスタスクの起動. . . . . . . . . . . . . . . . . . . . . . . . 12-5要求バッファの使用 . . . . . . . . . . . . 12-5タスク識別子の概要 . . . . . . . . . . . . 12-5データベースのバックアップと復元 . . . 12-6データベースプロパティの設定 . . . . . 12-10データベース保守の起動 . . . . . . . . 12-12データベースとサーバーのステータスレポートの要求 . . . . . . . . . . . . . . . . . 12-15

ユーザーの設定 . . . . . . . . . . . . . 12-16ソフトウェアライセンスの管理 . . . . . 12-18

Services Manager に対するクエリー . . . 12-19タイムアウトのブロックと指定 . . . . . 12-19サービス API を使ったクエリーの例 . . 12-20結果バッファの使用 . . . . . . . . . . . 12-21サーバー設定のクエリー . . . . . . . . 12-22セキュリティ設定のクエリー . . . . . . 12-29サービスタスクのクエリー . . . . . . . 12-34

Delphi および C++Builder でのサービス API の使用 . . . . . . . . . . . . . . . . . . . . 12-36

第 13 章インストール API とライセンス APIInterBase のインストール API について . . 13-2

インストール API のファイル . . . . . . 13-2インストール API が行うこと . . . . . . 13-3インストール API 関数 . . . . . . . . . . 13-3インストールハンドル . . . . . . . . . . 13-4エラー処理 . . . . . . . . . . . . . . . . 13-5コールバック関数 . . . . . . . . . . . . . 13-5

インストール API 用に定義されているデータ型 . . . . . . . . . . . . . . . . . . . . 13-6

InterBase インストールの記述 . . . . . . . 13-7手順の概要 . . . . . . . . . . . . . . . . 13-7実環境のサンプル . . . . . . . . . . . . . 13-9

ライセンス API の使い方 . . . . . . . . . . 13-9ライセンス API のロード . . . . . . . . . 13-9ib_license.dat ファイルの用意 . . . . . . 13-9サーバー機能の追加 . . . . . . . . . . .13-10

標準的なインストールのためのサンプルコード . . . . . . . . . . . . . . . . . . . . . . .13-11

第 14 章XML のエクスポートInterBase API を使った XML の生成 . . . 14-1

IB_XMLDA 構造体 . . . . . . . . . . . 14-2XML 生成の例 . . . . . . . . . . . . . . . . 14-4

XML 出力構造体 . . . . . . . . . . . . . 14-5C プログラム . . . . . . . . . . . . . . . 14-5xmlda_flags の使い方 . . . . . . . . . . 14-9

第 15 章API 関数リファレンス関数のカテゴリ . . . . . . . . . . . . . . . 15-1

配列関数 . . . . . . . . . . . . . . . . . 15-2BLOB 関数 . . . . . . . . . . . . . . . . 15-2データベース関数 . . . . . . . . . . . . . 15-3変換関数 . . . . . . . . . . . . . . . . . 15-3DSQL 関数 . . . . . . . . . . . . . . . . 15-4エラー処理関数 . . . . . . . . . . . . . . 15-5イベント関数 . . . . . . . . . . . . . . . 15-5情報関数 . . . . . . . . . . . . . . . . . 15-5インストール関数 . . . . . . . . . . . . . 15-6ライセンス関数 . . . . . . . . . . . . . . 15-6サービス関数 . . . . . . . . . . . . . . . 15-7トランザクション制御関数 . . . . . . . . 15-7

関数リファレンスの表記 . . . . . . . . . . . 15-8isc_add_user() . . . . . . . . . . . . . . . 15-8isc_array_get_slice() . . . . . . . . . . . .15-12isc_array_get_slice2() . . . . . . . . . . .15-12isc_array_lookup_bounds() . . . . . . . .15-16isc_array_lookup_bounds2() . . . . . . .15-16isc_array_lookup_desc() . . . . . . . . . .15-19isc_array_lookup_desc2() . . . . . . . . .15-19isc_array_put_slice() . . . . . . . . . . . .15-22isc_array_put_slice2() . . . . . . . . . . .15-22isc_array_set_desc() . . . . . . . . . . . .15-29isc_array_set_desc2() . . . . . . . . . . .15-29isc_attach_database() . . . . . . . . . . .15-31isc_blob_default_desc() . . . . . . . . . .15-33

iii

isc_blob_default_desc2() . . . . . . . . . 15-34isc_blob_gen_bpb() . . . . . . . . . . . . 15-35isc_blob_gen_bpb2() . . . . . . . . . . . 15-35isc_blob_info() . . . . . . . . . . . . . . 15-37isc_blob_lookup_desc() . . . . . . . . . 15-38isc_blob_lookup_desc2() . . . . . . . . . 15-38isc_blob_set_desc() . . . . . . . . . . . . 15-40isc_blob_set_desc2() . . . . . . . . . . . 15-41isc_cancel_blob() . . . . . . . . . . . . . 15-42isc_cancel_events() . . . . . . . . . . . . 15-43isc_close_blob() . . . . . . . . . . . . . . 15-44isc_commit_retaining() . . . . . . . . . . 15-45isc_commit_transaction() . . . . . . . . 15-46isc_create_blob2() . . . . . . . . . . . . . 15-47isc_create_database() . . . . . . . . . . . 15-50isc_database_info() . . . . . . . . . . . . 15-50isc_decode_sql_date() . . . . . . . . . . 15-52isc_decode_sql_time() . . . . . . . . . . 15-53isc_decode_timestamp() . . . . . . . . . 15-54isc_delete_user() . . . . . . . . . . . . . 15-54isc_detach_database() . . . . . . . . . . 15-58isc_drop_database() . . . . . . . . . . . 15-59isc_dsql_allocate_statement() . . . . . . 15-60isc_dsql_alloc_statement2() . . . . . . . 15-61isc_dsql_describe() . . . . . . . . . . . . 15-63isc_dsql_describe_bind() . . . . . . . . . 15-65isc_dsql_execute() . . . . . . . . . . . . 15-67isc_dsql_execute2() . . . . . . . . . . . . 15-71isc_dsql_execute_immediate() . . . . . 15-74isc_dsql_exec_immed2() . . . . . . . . . 15-77isc_dsql_fetch() . . . . . . . . . . . . . . 15-79isc_dsql_free_statement() . . . . . . . . 15-82isc_dsql_prepare() . . . . . . . . . . . . 15-84isc_dsql_set_cursor_name() . . . . . . . 15-87isc_dsql_sql_info() . . . . . . . . . . . . 15-89isc_dsql_xml_buffer_fetch() . . . . . . . 15-91isc_dsql_xml_fetch() . . . . . . . . . . . 15-92isc_dsql_xml_fetch_all() . . . . . . . . . 15-94isc_encode_sql_date() . . . . . . . . . . 15-95isc_encode_sql_time() . . . . . . . . . . 15-96isc_encode_timestamp() . . . . . . . . . 15-97isc_event_block() . . . . . . . . . . . . . 15-98isc_event_counts() . . . . . . . . . . . . 15-99isc_expand_dpb() . . . . . . . . . . . . . 15-101isc_get_client_version() . . . . . . . . . 15-102

isc_get_client_major_version() . . . . . 15-103isc_get_client_minor_version() . . . . . 15-103isc_get_segment() . . . . . . . . . . . . 15-103isc_install_clear_options() . . . . . . . . 15-105isc_install_execute() . . . . . . . . . . . 15-106isc_install_get_info() . . . . . . . . . . . 15-108isc_install_get_message() . . . . . . . . 15-109isc_install_load_external_text() . . . . . 15-109isc_install_precheck() . . . . . . . . . . 15-110isc_install_set_option() . . . . . . . . . 15-112isc_install_unset_option() . . . . . . . . 15-113isc_interprete() . . . . . . . . . . . . . . 15-114isc_license_add() . . . . . . . . . . . . . 15-115isc_license_check() . . . . . . . . . . . . 15-116isc_license_remove() . . . . . . . . . . . 15-116isc_license_display() . . . . . . . . . . . 15-117isc_license_get_msg() . . . . . . . . . . 15-118isc_modify_user() . . . . . . . . . . . . 15-118isc_open_blob2() . . . . . . . . . . . . . 15-121isc_portable_integer() . . . . . . . . . . 15-123isc_prepare_transaction() . . . . . . . . 15-124isc_prepare_transaction2() . . . . . . . 15-125isc_print_sqlerror() . . . . . . . . . . . . 15-126isc_print_status() . . . . . . . . . . . . . 15-127isc_put_segment() . . . . . . . . . . . . 15-128isc_que_events() . . . . . . . . . . . . . 15-130isc_rollback_retaining() . . . . . . . . . 15-133isc_rollback_transaction() . . . . . . . . 15-135isc_service_attach() . . . . . . . . . . . 15-136isc_service_detach() . . . . . . . . . . . 15-137isc_service_query() . . . . . . . . . . . . 15-137isc_service_start() . . . . . . . . . . . . 15-139isc_sqlcode() . . . . . . . . . . . . . . . 15-140isc_sql_interprete() . . . . . . . . . . . . 15-140isc_start_multiple() . . . . . . . . . . . 15-141isc_start_transaction() . . . . . . . . . . 15-144isc_transaction_info() . . . . . . . . . . 15-147isc_uninstall_execute() . . . . . . . . . 15-149isc_uninstall_precheck() . . . . . . . . . 15-150isc_vax_integer() . . . . . . . . . . . . . 15-150isc_version() . . . . . . . . . . . . . . . 15-151isc_wait_for_event() . . . . . . . . . . . 15-153

索引 I-1

iv

表
1.1 API ガイドの構成 . . . . . . . . . . . 1-23.1 InterBase で使用される環境変数 . . . 3-33.2 InterBase ライブラリファイルの名前 . 3-53.3 Microsoft C のコンパイラオプション 3-63.4 Borland C のコンパイラオプション . 3-74.1 API データベース関数 . . . . . . . . . 4-14.2 DPB のパラメータ（目的別） . . . . . 4-44.3 DPB パラメータ（アルファベット順） . 4-54.4 isc_expand_dpb( ) によって認識される DPB
パラメータ . . . . . . . . . . . . . . . 4-74.5 isc_expand_dbp() のパラメータ . . . . 4-74.6 ステータスメッセージの戻り項目 . . . 4-114.7 データベース特性に関するデータベース情報

項目 . . . . . . . . . . . . . . . . . . 4-124.8 環境特性に関するデータベース情報項目

. . . . . . . . . . . . . . . . . . . . . 4-134.9 パフォーマンス統計値に関するデータベース

情報項目 . . . . . . . . . . . . . . . . 4-134.10 操作回数に関するデータベース情報項目

. . . . . . . . . . . . . . . . . . . . . 4-145.1 API トランザクション関数 . . . . . . 5-15.2 他の API トランザクション関数 . . . . 5-25.3 TPB 定数 . . . . . . . . . . . . . . . . 5-45.4 読み取り操作と書き込み操作による排他レベ

ルの相互作用 . . . . . . . . . . . . . . 5-86.1 XSQLDA のフィールド . . . . . . . . 6-86.2 XSQLVAR のフィールド . . . . . . . 6-96.3 SQL のデータ型、マクロ式、C のデータ型

. . . . . . . . . . . . . . . . . . . . . 6-126.4 SQL ステートメント文字列と推奨される処

理方法 . . . . . . . . . . . . . . . . . 6-166.5 文のタイプ . . . . . . . . . . . . . . . 6-327.1 API BLOB 関数 . . . . . . . . . . . . 7-17.2 BLOB 情報の要求項目と戻り値 . . . . 7-167.3 ステータスメッセージの戻り項目 . . . 7-167.4 isc_blob_ctl のフィールドの説明 . . . 7-227.5 動作定数 . . . . . . . . . . . . . . . . 7-237.6 BLOB パラメータバッファのパラメータタ

イプ . . . . . . . . . . . . . . . . . . 7-268.1 API 配列アクセス関数 . . . . . . . . . 8-18.2 配列デスクリプタのフィールド . . . . 8-38.3 配列デスクリプタのデータ型 . . . . . . 8-310.1 エラー処理関数 . . . . . . . . . . . . 10-110.2 ステータスベクタークラスタの先頭の long

値の解釈 . . . . . . . . . . . . . . . . 10-810.3 ステータスベクターの数値デスクリプタの

#define . . . . . . . . . . . . . . . . . 10-9

11.1 API イベント関数 . . . . . . . . . . . 11-112.1 Services Manager 接続文字列の構文（プロ

トコル別） . . . . . . . . . . . . . . . 12-312.2 サービス API のタスク . . . . . . . . 12-512.3 サービス API のデータベースのバックアッ

プに関する引数 . . . . . . . . . . . . 12-612.4 サービス API のデータベースの復元に関す

る引数 . . . . . . . . . . . . . . . . . 12-812.5 サービス API のデータベースプロパティに

関する引数 . . . . . . . . . . . . . . 12-1112.6 サービス API のデータベースの検証に関す

る引数 . . . . . . . . . . . . . . . . 12-1312.7 サービス API のデータベースのスイープに

関する引数 . . . . . . . . . . . . . . 12-1412.8 サービス API の limbo トランザクションに

関する引数 . . . . . . . . . . . . . . 12-1412.9 サービス API のステータスレポートに関す

る引数 . . . . . . . . . . . . . . . . 12-1512.10サービス API のユーザーの表示に関する引

数 . . . . . . . . . . . . . . . . . . 12-1612.11 サービス API の isc_action_svc_add_user

の引数 . . . . . . . . . . . . . . . . 12-1612.12サービス API のユーザーの削除に関する引

数 . . . . . . . . . . . . . . . . . . 12-1712.13サービス API のソフトウェアライセンスに

関する引数 . . . . . . . . . . . . . . 12-1812.14サービス API のサーバー設定に関するクエ

リー項目 . . . . . . . . . . . . . . . 12-2212.15サービス API のソフトウェアライセンスに

関する引数 . . . . . . . . . . . . . . 12-2612.16サービス API のセキュリティ設定に関する

クエリー項目 . . . . . . . . . . . . 12-2912.17サービス API のユーザー情報に関する引数

. . . . . . . . . . . . . . . . . . . . 12-3012.18サービス API のデータベース接続情報に関

する引数 . . . . . . . . . . . . . . . 12-3312.19サービス API のタスクに関するクエリー項

目 . . . . . . . . . . . . . . . . . . 12-3512.20サービス API の limbo トランザクションに

関する引数 . . . . . . . . . . . . . . 12-3513.1 InterBase インストールの作成に必要なイン

ストール API ファイル . . . . . . . . 13-213.2 ibinstall.dll のエントリポイント . . . 13-413.3 インストール API 用に定義されているデー

タ型 . . . . . . . . . . . . . . . . . . 13-713.4 isc_license_add() が返すエラーコード

. . . . . . . . . . . . . . . . . . . . 13-10

v

15.1 配列関数 . . . . . . . . . . . . . . . . 15-215.2 BLOB 関数 . . . . . . . . . . . . . . . 15-215.3 データベース関数 . . . . . . . . . . . 15-315.4 日付時刻および変換関数 . . . . . . . . 15-315.5 DSQL 関数 . . . . . . . . . . . . . . . 15-415.6 エラー処理関数 . . . . . . . . . . . . 15-515.7 イベント関数 . . . . . . . . . . . . . . 15-515.8 情報関数 . . . . . . . . . . . . . . . . 15-515.9 インストール関数 . . . . . . . . . . . 15-615.10ライセンス関数 . . . . . . . . . . . . 15-715.11 サービス関数 . . . . . . . . . . . . . . 15-715.12トランザクション制御関数 . . . . . . 15-715.13関数の説明の形式 . . . . . . . . . . . 15-815.14 isc_adduser() のエラーメッセージ . 15-1015.15配列デスクリプタフィールドのデータ型

. . . . . . . . . . . . . . . . . . . . 15-18

15.16配列デスクリプタフィールドのデータ型 . . . . . . . . . . . . . . . . . . . . 15-21

15.17配列デスクリプタフィールドのデータ型 . . . . . . . . . . . . . . . . . . . . 15-30

15.18 BLOB デスクリプタフィールド . . . 15-3415.19 BLOB デスクリプタフィールド . . . 15-3915.20 isc_deleteuser() のエラーメッセージ

. . . . . . . . . . . . . . . . . . . . 15-5615.21 isc_license_add() が返すエラーコード

. . . . . . . . . . . . . . . . . . . . 15-11515.22 isc_license_check() が返すエラーコード

. . . . . . . . . . . . . . . . . . . . 15-11615.23 isc_license_remove() が返す戻り値 . 15-11715.24 isc_modifyuser() のエラーメッセージ

. . . . . . . . . . . . . . . . . . . . 15-12015.25トランザクション情報要求項目 . . . 15-14715.26ステータスメッセージの戻り項目 . . 15-148

vi

第章

第 1 章 API ガイドの使い方

API ガイドは、InterBase API（アプリケーションプログラミングインターフェース）と

ホストプログラミング言語（C または C++）を使用するデータベースアプリケーションの

プログラム記述、前処理、コンパイル、およびリンクの方法について、タスクを中心に説

明しています。

この章ではこのマニュアルが対象とする読者と、各章の概要について説明しています。

対象読者

API ガイドは、次の事項について知識のあるデータベースアプリケーションプログラマを

対象としています。

• SQL および動的 SQL（DSQL）

• リレーショナルデータベースプログラミング

• C プログラミング

このガイドの内容

API ガイドは次の 2 つの部分からなります。

• タスク中心のユーザーズガイド：データベースの接続 / 解除など、データベース関連のタ

スクを実行する API 関数呼び出しの使い方を説明します。

• API 関数リファレンス：各関数の目的、構文、パラメータ、必要条件、制限事項、戻り値、

使用例、関連関数を示します。

次の表に、API ガイドの各章の概要を示します。

第 1 章 A P I ガイドの使い方 1-1

このガイドの内容

表 1.1 API ガイドの構成

章説明

第 2 章「アプリケーションの必要条件」 API 呼び出しを使うプログラミングに共通の構造体とその要素について説明します。

第 3 章「InterBase API によるプログラミング」 InterBase API を使う InterBase アプリケーションに固有の必要事項について説明します。

第 4 章「データベースの操作」データベースへの接続と解除、および接続に関する情報の要求の方法について説明します。

第 5 章「トランザクションの操作」さまざまなモードでのトランザクションの開始、およびトランザクションのコミットとロールバックについて説明します。

第 6 章「動的 SQL の操作」 API 呼び出しを使用する DSQL のデータ定義文とデータ操作文の処理方法について説明します。

第 7 章「BLOB データの操作」アプリケーションでの BLOB データの選択、挿入, 更新、および削除の方法について説明します。

第 8 章「配列データの操作」アプリケーションでの配列データの選択、挿入 ,更新、および削除の方法について説明します。

第 9 章「データの変換」アプリケーションでの日付 /時刻データの選択、挿入 ,更新、削除、および isc_portable_integer() を使ってバイト順を入れ替える方法について説明します。

第 10 章「エラー条件の処理」アプリケーションでのデータベースエラーの捕捉と処理の方法について説明します。

第 11 章「イベントの操作」トリガーとアプリケーションの相互作用、およびイベントの登録と待機、アプリケーションのイベントへの応答について説明します。

第 12 章「サービスの操作」ユーザー識別子の作成、データベースの検査、データベースのバックアップ、データベースステータス情報の収集などの機能を制御するサービス API について説明します。

第 13 章「インストール API とライセンス API」自動埋め込みインストールと関連するライセンス管理を記述するために必要な API について説明します。

第 14 章「XML のエクスポート」 XML のエクスポート方法について説明します。

第 15 章「API 関数リファレンス」各関数の構文、使い方、例を示します。

1-2 A P I ガイド

データベースとアプリケーションのサンプル

データベースとアプリケーションのサンプル

InterBase の Examples サブディレクトリには、サンプルのデータベースとアプリケーショ

ンのソースコードが入っています。API ガイドの例は、可能な限りこのサンプルデータベー

スとソースコードを使用しています。

第 1 章 A P I ガイドの使い方 1-3

1-4 A P I ガイド

第章

第 2 章アプリケーションの必要条件

この章では、API 関数を使用するデータベースアプリケーションのプログラミングにおけ

る必要条件の概要を説明し、各事項について以降の章で詳細な情報が記載されている箇所

を示しています。

API アプリケーションは、特定の API 関数とその構造体を必ず使用しなければなりませ

ん。たとえば、どのアプリケーションも低 1 つのデータベースに接続し、低 1 つのト

ランザクションを実行しなければなりません。このため、すべてのアプリケーションにお

いて、データベースハンドルとトランザクションハンドルを宣言して値を設定しなければ

なりません。データベースパラメータバッファ（DPB）、トランザクションパラメータバッ

ファ（TPB）、およびサービスパラメータバッファ（SPB）の宣言と登録が必要な場合もあ

ります。この章ではこうした必要事項の概要を示し、以降の章で詳細な情報が記載されて

いる箇所を示します。

API アプリケーションによっては、アプリケーションで動的 SQL（DSQL）文を処理でき

る関数など、特殊な API 関数を使用するものがあります。これらのアプリケーションでは、

さらに多くの条件が必要になります。この章では、これらの必要条件についても簡単に説

明し、このマニュアルでさらに詳細な情報が記載されているページを紹介します。

すべてのアプリケーションの必要条件

以下の節では、すべてのアプリケーションに共通の必要条件について説明します。

• ibase.h のインクルード

• データベースの必要条件

• トランザクションの必要条件

第 2 章アプリケーションの必要条件 2-1


ibase.h のインクルード

InterBase の include サブディレクトリには、ヘッダーファイル ibase.h が含まれています。

ibase.h は、API アプリケーションで使用するすべてのソースコードモジュールでインク

ルードする必要があります。ibase.h には、API 関数のプロトタイプが宣言されています。

また、さまざまな API 関数で必要となる構造体の typedef 宣言、パラメータ定義、マクロ

も含まれています。

ibase.h をソースコードモジュールにインクルードするには、ソースコードの先頭近くに次

の #include 文を挿入します。

#include <ibase.h>

コンパイラの検索パスに ibase.h がない場合は、完全なパス名を指定して、ファイル名を引

用符で囲んでください。

重要 ibase.h をインクルードしないと、アプリケーションのコンパイルとリンクが正常に実行で

きない場合があります。

データベースの必要条件

データベースを操作するアプリケーションは、アクセスするデータベースごとにデータ

ベースハンドルを 1 つ指定しなければなりません。データベースハンドルは、データベー

スを API 関数を使って接続したり、API 呼び出しで参照するのに使用する long ポインタ

です。ヘッダーファイル ibase.h には、データベースハンドルの宣言に使用する #define 文が含まれています。

データベースとの接続を確立するときは、データベースパラメータバッファ（DPB）を通

じて、ユーザー名とパスワードの組み合わせなどのデータベース接続オプションを接続先

に渡すことができます。通常は、データベースの接続ごとに DPB を 1 つ設定しますが、1つの DPB を複数の接続で共有することもできます。

データベースハンドルの宣言データベースハンドルは使用前に宣言し、0 に初期化しておかなければなりません。次の

コードは、データベースハンドルの宣言と初期化を行う方法を示したものです。

#include <ibase.h>

. . .

/* データベースハンドルを宣言します */isc_db_handle db1;

. . .

/* ハンドルを初期化します */db1 = 0L;

データベースハンドルの宣言、初期化、および使用の詳細については、第 4 章「データベー

スの操作」を参照してください。

2-2 A P I ガイド


DPB の設定DPB は、データベース接続オプションを記述するバイト配列です。DPB はデータベース

に接続する前に割り当てて値を設定しておかなければなりません。DPB に渡せるパラメー

タは ibase.h で定義されています。

DPB の割り当て、値の設定、および使用の詳細については、第 4 章「データベースの操

作」を参照してください。

トランザクションの必要条件

アプリケーションはいずれも、アクセスするトランザクションごとに、トランザクション

ハンドルを 1 つ指定しなければなりません。トランザクションハンドルは、API 関数から

のトランザクションの起動や、API 呼び出しからの参照に使用する long ポインタです。

ヘッダーファイル ibase.h には、トランザクションハンドルの宣言に使用する #define 文が

含まれています。

トランザクションを起動するときは、トランザクションパラメータバッファ（TPB）を通

じて、アクセス方法や排他レベルなどのトランザクション特性オプションをスタートアッ

プ呼び出しに渡すことができます。通常は、トランザクションごとに TPB を 1 つ設定しま

すが、操作特性が同一であれば、複数のトランザクションが 1 つの TPB を共有することも

できます。

トランザクションハンドルの宣言トランザクションハンドルは、使用前に宣言して 0 に初期化しておかなければなりません。

次のコードは、トランザクションハンドルの宣言と初期化を行う方法を示しています。

#include <ibase.h>

. . .

/* トランザクションハンドルを宣言します */isc_tr_handle tr1;

. . .

/* ハンドルを初期化します */tr1 = 0L;

トランザクションハンドルの宣言 , 初期化、および使用の詳細については、第 5 章「トラ

ンザクションの操作」を参照してください。

TPB の設定TPB は、トランザクション特性オプションを記述するパラメータを格納するバイト配列で

す。TPB は、トランザクションを起動する前に割り当てて値を設定しておかなければなり

ません。TPB に渡せるパラメータは ibase.h で定義されています。

TPB の割り当て、値の設定、および使用の詳細については、第 5 章「トランザクションの

操作」を参照してください。


その他の必要条件


以降の節では、Microsoft Windows などのプラットフォームで作成した API アプリケー

ション、および DSQL ステートメントを処理する関数など、一般クラスの API 関数に必

要な条件について説明します。

Microsoft Windows の必要条件

Microsoft Windows 上で作成した InterBase クライアントアプリケーションには、

Windows 環境および C/C++ コンパイラに特有のプログラミング条件があります。

InterBase のヘッダーファイル ibase.h には、API 関数のプロトタイプが含まれています。

Windows アプリケーションについては、以下の宣言文がプロトタイプに使用されます。

#define ISC_FAR __far

#define ISC_EXPORT ISC_FAR __cdecl __loadds __export

たとえば、ibase.h の isc_attach_database() のプロトタイプは次のとおりです。

ISC_STATUS ISC_EXPORT isc_attach_database(ISC_STATUS ISC_FAR *,short,char ISC_FAR,isc_db_handle ISC FAR *,short,char ISC_FAR *);

Windows クライアントアプリケーションが呼び出しを行って C データ型をキャストする

場合は、明示的に ISC_FAR 宣言を使用しなければなりません。

メモ ISC_EXPORT キーワードは、Windows 以外のプラットフォームでは未定義のため、API 関数リファ

レンスから除外されます。

Windows の必要条件の詳細については、第 3 章「InterBase API によるプログラミン

グ」を参照してください。

DSQL の必要条件

DSQL クエリーを作成または要求する API アプリケーションでは、データベース間のデー

タ転送に使用する拡張 SQL デスクリプタエリア（XSQLDA）の宣言、初期化、値の設定を

行う際に注意が必要です。また、isc_dsql_allocate_statement() や isc_dsql_describe() など

の多くの API 関数は、DSQL の処理にステートメントハンドルも使用します。

ibase.h には、XSQLDA 構造体および XSQLDA の基本構造体である XSQLVAR の typedef宣言が含まれています。また、ステートメントハンドルを宣言する #define、アプリケー

ション内の XSQLDA インスタンスに使用するスペースを割り当てるマクロ、

isc_dsql_sql_info() に渡される DSQL 情報パラメータを定義する #define も含まれていま

す。

次のコードは、アプリケーション内で使用する XSQLDA 構造体を宣言する方法、およびス

テートメントハンドルを宣言する方法を示したものです。

2-4 A P I ガイド


#include <ibase.h>

. . .

XSQLDA *insqlda;

isc_stmt_handle sql_stmt;

. . .

API を使用した DSQL プログラミングの詳細については、第 6 章「動的 SQL の操作」を

参照してください。

BLOB の必要条件

フィルタリングが必要な BLOB データを操作するには、API アプリケーションで BLOBごとに BLOB パラメータバッファ（BPB）を設定しなければなりません。BPB はアプリ

ケーションで宣言する可変長のバイトベクターで、BLOB の制御情報を保存します。BPBには BLOB の内容が含まれます。また、BLOB のフィルタリングを指定する BLOB サブ

タイプを示す定数（ibase.h で定義されている）も含めることができます。

BLOB データを操作するアプリケーションは、BLOB のキャラクタセット情報を格納する

BLOB デスクリプタを宣言して登録しなければなりません。BLOB デスクリプタは ibase.hで定義されています。BLOB デスクリプタを宣言するには、次のようなコードをアプリケー

ションに組み込む必要があります。

#include <ibase.h>

. . .

ISC_BLOB_DESC_V2 descriptor_name;

BLOB フィルタは BLOB のフォーマットを変換（圧縮状態から非圧縮状態など）すること

ができます。BLOB フィルタを使用する場合は、BLOB データのアクセス時にフィルタを

使用できるように、フィルタ関数を別に作成して、データベースに対して定義しておきま

す。

BLOB データにアクセスするアプリケーションでは、API の DSQL 関数を広範囲に活用

する必要があります。

BLOB および BLOB フィルタの操作の詳細については、第 7 章「BLOB データの操作」

を参照してください。DSQL の詳細については、第 6 章「動的 SQL の操作」を参照して

ください。

配列の必要条件

配列を処理する API 関数は、ibase.h で定義されている配列デスクリプタおよび配列 ID を使用する必要があります。配列をアクセスするアプリケーションでは API の DSQL 関数

を広範囲に使用しなければなりません。

次のコードは、配列デスクリプタと配列 ID を宣言する方法、および使用前に配列 ID を 0に初期化する方法を示しています。

#include <ibase.h>

. . .



ISC_ARRAY_DESC_V2 desc;

ISC_QUAD array_id;

. . .

array_id = 0L;

. . .

メモ ISC_ARRAY_DESC_V2 構造体は、長さ METADATALENGTH の長いメタデータ名をサポート

します。古い ISC_ARRAY_DESC 構造体は、32 バイト以下のメタデータ名しかサポートし

ません。

配列の操作の詳細については、第 8 章「配列データの操作」を参照してください。DSQLの詳細については、第 6 章「動的 SQL の操作」を参照してください。

イベントの必要条件

InterBase のイベントは、特定の状態や動作の発生を通知するために、トリガーまたはス

トアドプロシージャからアプリケーションに渡されるメッセージです。通常は、レコード

の挿入、修正、削除など、データベースの変更を指します。

アプリケーションがイベントに応答するには、イベントの関連性を登録しておかなければ

なりません。イベントの関連性を登録するには、イベントパラメータバッファ (EPB) をア

プリケーションで設定して登録しなければなりません。EPB はいくつかの API イベント関

数にパラメータとして渡され、どのイベントが発生したかを判定するのに使用されます。

C では、次のように、EPB は char ポインタとして宣言されます。

char *event_buffer, *result_buffer;

バッファを宣言したら、isc_event_block() が呼び出してバッファ領域を割り当て、初期値

を設定します。

イベントの詳細については、第 11 章「イベントの操作」を参照してください。

エラー処理の必要条件

ほとんどの API 関数では、20 個の long の配列であるエラーステータスベクターを使って

ステータス情報を返します。InterBase のエラーステータスを処理するには、次のように、

アプリケーションでステータスベクターを宣言する必要があります。

#include <ibase.h>

. . .

ISC_STATUS status_vector[20];

ISC_STATUS は、プログラミングでの利便性とプラットフォームからの独立性のために、

ibase.h の中で #define により定義されています。

ibase.h には、すべての InterBase エラーステータスを定義する #define 文も含まれていま

す。これらのエラーステータスに基づくステータスベクターから、API エラー処理関数を

使ってエラーメッセージを作成したり、エラー番号のかわりに #define を使って特定のエ

ラーステータスに対するステータスベクターを解析することができます。#define をこのよ

うに使えば、ソースコードを理解しやすい形で保守できます。

2-6 A P I ガイド

コンパイルとリンク

イベントの詳細については、第 11 章「イベントの操作」を参照してください。

サービスの必要条件

InterBase は、アプリケーションがサーバーやデータベースのプロパティに関する情報を

要求したり、サーバーやデータベースを管理するためのタスクを起動できるようにする

API インターフェースを提供します。アプリケーションは、InterBase サーバーのローカ

ルインスタンスやネットワーク上のリモートサーバーへの接続を開始することができま

す。この接続を介して、アプリケーションはサーバーに要求を送り、結果のデータを受け

取ります。

この API 機能の詳細については、第 12 章「サービスの操作」を参照してください。

コンパイルとリンク

ほとんどのプラットフォームでは、標準の C/C++ アプリケーションと同じように API アプリケーションをコンパイルできます。使用しているコンパイラの詳細については、コン

パイラのマニュアルを参照してください。コンパイルに関してもう 1 つ参考になるのが

examples ディレクトリ内のファイルです。環境ごとに、システムのデフォルトコンパイ

ラを使用するメイクファイルの例が入っています。

ほとんどのプラットフォームでは、InterBase ライブラリの実行時のダイナミックリンク

をサポートしています。ただし、Microsoft Windows でダイナミックリンクを使用する

には、アプリケーションに InterBase クライアントライブラリを明示的にリンクしなけれ

ばなりません。

Microsoft Windows では、注意すべきコンパイラオプションがいくつかあります。

Windows 上でのリンクの詳細については、第 3 章「InterBase API によるプログラミ

ング」を参照してください。

他のプラットフォームについては、InterBase の『埋め込み SQL ガイド』でそれぞれのコ

ンパイルとリンクの方法を参照してください。


2-8 A P I ガイド

第章

第 3 章 InterBase API によるプログラミング

この章では、C/C++ によるクライアント上の InterBase アプリケーションプログラミン

グに特有の情報を提供しています。ここでは、読者が Borland C/C++ または MicrosoftC/C++、InterBase、および『言語リファレンス』を始めとする InterBase の各マニュア

ルの記載内容を理解していることを前提としています。

アプリケーション開発の基本手順

InterBase クライアントを使用するアプリケーションを開発する基本的な手順は、以下の

とおりです。

• 開発用プラットフォームを選択します。InterBase クライアントライブラリは、MicrosoftWindows 98/ME、Windows 2000、Windows NT、Linux、および適切な UNIX シス

テムで使用できます。

• C または C++ でアプリケーションのコーディングを行います。

• アプリケーションのコンパイルとリンクを行います。

• アプリケーションをテストし、デバッグします。

• 稼動クライアントプラットフォームにアプリケーションを配布します。

サポートされている開発環境

開発者は、InterBase クライアントライブラリを使用して、Windows 98、Windows 2000、Windows NT、Linux、または UNIX 上のリモート InterBase サーバーに接続する

InterBase SQL クライアントアプリケーションを設計することができます。

第 3 章 I n t e r B a s e A P I によるプログラミング 3-1

ユーザー名とパスワードの必要条件

詳細については、『操作ガイド』を参照してください。

ユーザー名とパスワードの必要条件

InterBase クライアントアプリケーションをコンパイル、リンク、および実行するときに

は、クライアントは常に有効なユーザー名とパスワードを InterBase サーバーに送信しな

ければなりません。サーバーはこのユーザー名とパスワードを、セキュリティデータベー

スに格納されているユーザー名とパスワードと照合します。正当なユーザー名とパスワー

ドであれば、クライアントはサーバー上の InterBase データベースに接続できます。正当

でない場合、サーバーは接続を拒否します。

正しく接続するには、次の手順をとる必要があります。

1 SYSDBA 特権を持つユーザーが、クライアントのユーザー名とパスワードをサーバーの

セキュリティデータベース（デフォルトは admin.ib）に追加しなければなりません。

この操作は、Windows プラットフォームでは IBConsole を使って行います。UNIX では gsec ユーティリティを使います。

2 クライアントは、有効なユーザー名とパスワードをサーバーに送信します。パスワード

では大文字と小文字が区別されます。

UNIX ログイン：環境によっては、InterBase セキュリティデータベースにユーザー名がなくて

もデータベースに接続できることがあります。これは、以下の条件がすべて満たされる場

合にのみ可能になります。

• クライアントとサーバーがともに UNIX 上で動作している

• ユーザーの現在のログインがサーバーホスト上にある

• トラスティを持つクライアントからログインしている。トラスティを持つクライア

ントは、サーバー上の /etc/hosts.equiv または /etc/gds_hosts.equiv ファイル、また

はサーバー上のユーザーのホームディレクトリにある .rhosts ファイルに一覧されて

いる

• 接続文字列にユーザー名とパスワードを指定していない

メモ InterBase には、定義済みのユーザー ID が 1 つ用意されています。このユーザー ID はSYSDBA で、デフォルトのパスワードは masterkey です。このユーザー ID はデータベース

管理者用で、他のユーザー ID では利用できない特別な特権が与えられています。このユー

ザー ID をエンドユーザーのアプリケーションに使用してはなりません。

ユーザー名とパスワードの指定

クライアントアプリケーションは、データベースと接続する際にユーザー名とパスワード

を指定しなければなりません。無効なユーザー名とパスワードを指定すると、エラーが発

生します。ユーザー名とパスワードは次のようにして指定します。

• isc_dpb_user_name と isc_dpb_password でデータベースパラメータブロック（DPB）を作

成し、isc_attach_database() を使ってパラメータブロックを渡します。

3-2 A P I ガイド

環境変数の使い方

• isc_expand_dpb() を使用して、isc_dpb_user_name と isc_dpb_password パラメータを既存

の DPB に追加します。

DPB、isc_attach_database()、および isc_expand_dpb() の詳細については、第 4 章「デー

タベースの操作」を参照してください。

環境変数の使い方

InterBase クライアントアプリケーションは、プログラムのパラメータを設定する 3 つの

環境変数を使用できます。これらの変数は、アプリケーションの実行時に使用できなけれ

ばなりません。たとえば、Windows の起動後に DOS ウィンドウで設定すると、そのウィ

ンドウでの DOS アプリケーションでは使用できますが、Windows プログラムからは使

用できません。

次の表に 3 つの環境変数とその用途をまとめます。

ISC_USER と ISC_PASSWORD を使用して、リモート InterBase データベースサーバーに渡

す有効なユーザー名とパスワードを設定します。

重要セキュリティにかかわる場合は、ISC_PASSWORD 環境変数は使用しないでください。

autoexec.bat などで ISC_PASSWORD 環境変数が定義されるクライアントにアクセスできる

ユーザーからは、容易にパスワードを見ることができてしまいます。

デフォルトのデータベースディレクトリの設定

リモートサーバー上のデフォルトデータベースディレクトリに自動的に接続するには、

ISC_DATABASE 環境変数を作成して、ホスト名とパス名を含むデータベースディレクトリ

のフルパスを指定しなければなりません。

メモホスト名は、サーバーのオペレーティングシステムとネットワークプロトコルによって異

なります。前の例は、一般的な UNIX サーバーをホストとする場合の構文です。使用して

いるシステムのリファレンスマニュアルを参照してください。

表 3.1 InterBase で使用される環境変数

変数用途例

ISC_DATABASE リモートサーバーで使用する、デフォルトのサーバーとデータベースディレクトリを指定する

SET ISC_DATABASE =ingold:/usr/interbase/

examples

ISC_USER PC クライアントアプリケーションに使用するユーザー名を指定する

SET ISC_USER = HERMES

ISC_PASSWORD PC クライアントアプリケーションに使用する、大文字 / 小文字が区別されるパスワードを指定する

SET ISC_PASSWORD = Ichneumon


データ型

ユーザー名とパスワードの設定

PC クライアント上で使用するデフォルトのユーザー名とパスワードを設定するには、2 つの環境変数 ISC_USER と ISC_PASSWORD を作成します。

ISC_USER と ISC_PASSWORD が設定されていても、isc_attach_database() への引数として

移用される DPB に別のユーザー名とパスワードを指定できます。データベースパラメータ

ブロックに指定されたユーザー名とパスワードは、OS の環境変数の設定に優先します。

メモこのような環境変数の使用は安全ではなく、推奨はできません。

データ型

InterBase は、アプリケーション開発に使用するさまざまなデータ型をサポートしていま

す。これらのデータ型は、プラットフォームに依存しないように typedef で定義されてい

ます。InterBase クライアントライブラリも、さまざまなプラットフォームでの互換性を

保持するためにパックされたデータ構造体を使ってコンパイルされています。詳細につい

ては、『言語リファレンス』を参照してください。

InterBase のデータ型の詳細については、『言語リファレンス』を参照してください。

呼び出し規約

関数呼び出しの規約はプラットフォームによって異なります。特に次の点に注意してくだ

さい。

• UNIX プラットフォームでは、常に C の呼び出し規約（cdecl）を使用します。

• Windows NT および Windows 2000 では、引数の個数が固定されている関数には、常に

標準呼び出し規約（_stdcall）を使用します。引数の個数が可変の関数は

isc_start_transaction()、isc_expand_dpb()、isc_event_block() の 3 つだけです。これらには

cdecl 規約を使用します。

アプリケーションの構築（ビルド）

この節では、InterBase アプリケーションの構築に必要なコンパイラとライブラリについ

て説明します。

コンパイルとリンクについての情報：プラットフォームごとに、コンパイルとリンクに関する

プラットフォーム固有の情報が記載されたメイクファイルが examples ディレクトリにあ

ります。テキストエディタでメイクファイルを開いて参照してください。

コンパイラ

InterBase に含まれるインポートライブラリは、下記のコンパイラでテストされています。

3-4 A P I ガイド


Windows プラットフォーム

• Borland C++ 5.0

• Microsoft Visual C++ 2.0

• Microsoft Visual C++ 4.0

Solaris• C SPARCWorks SC4.2 C コンパイラ

• C++ SPARCWorks SC3.0.1 C++ コンパイラ

• COBOL　MicroFocus Cobol 4.0

• ADA SPARCWorks SC4.0 Ada コンパイラ

• FORTRAN SPARCWorks SC4.0 Fortran コンパイラ

LINUX• GCC G++

リンク

InterBase のライブラリファイルは、インストールディレクトリの lib サブディレクトリに

入っています。アプリケーションは、InterBase クライアントライブラリとリンクしなけれ

ばなりません。クライアントライブラリの名前は、プラットフォームとコンパイラによっ

て異なります。

ボーランドのバージョン 5.0 より前のコンパイラでは gds32.lib は使用できません。

インクルードファイル

アプリケーションでは、ヘッダーファイル ibase.h をインクルードして InterBase の型定義

と関数プロトタイプを取り込まなければなりません。このファイルは、InterBase インス

トールディレクトリの include サブディレクトリにあります。

UNIX プラットフォームでは、下位互換性のためにインストールディレクトリに gds.hファイルが入っています。

表 3.2 InterBase ライブラリファイルの名前

プラットフォーム / コンパイラ InterBase ライブラリファイル

Windows / Borland C++ gds32.lib

Windows / Microsoft Visual C++ 2.0 および 4.0 gds32_ms.lib

Solaris / すべて gdsmt

HPUX / すべて gds



Microsoft C++ を使用する場合

Microsoft C++ でアプリケーションをコンパイルする場合は次のオプションを使用しま

す。

たとえば、Microsoft コンパイラでは、次のようなコマンドを使って InterBase を使用す

る DLL を構築します。

cl -c -Zi -DWIN32 -D_MT -LD udf.c

lib -out:udf.lib -def:funclib.def -machine:i586 -subsystem:console

link -DLL -out:funclib.dll -DEBUG:full,mapped -DEBUGTYPE:CV

-machine:i586 -entry:_DllMainCRTStartup@12 -subsystem:console

-verbose udf.obj udf.exp gds32.lib ib_util_ms.lib crtdll.lib

次のコマンドは、Microsoft のコンパイラを使って InterBase の実行形式ファイルをビル

ドします。

cl -Zi -DWIN32 -D_MT -MD udftest.c udf.lib gds32.lib ib_util_ms.lib crtdll.lib

メモユーザー定義ライブラリのコンパイルとリンクの詳細については、『開発者ガイド』の

「UDF の操作」を参照してください。

ダイナミックランタイムライブラリの使用

• Microsoft Visual C++ 2.0 または Microsoft Visual C++ 4.0 を使用する。

• コンパイルとリンクを個別に行う。

• ダイナミックランタイムライブラリ（msvcrt20.dll または msvcrt40.dll）を使用す

る。

上のすべてに該当する場合は、/MD コンパイラフラグを指定してランタイムライブラリ

（RTL）をコンパイルし、正しいインポートライブラリをリンクする必要があります。

表 3.3 Microsoft C のコンパイラオプション

オプション動作

c リンクせずにコンパイルする（DLL のみ）

Zi 完全なデバッグ情報を生成する

DWIN32 WIN32 をヌル文字列として定義する

D_MT マルチスレッドの静的にリンクされるライブラリを使用する

3-6 A P I ガイド


Borland C/C++ を使用する場合

Borland C++ でアプリケーションをコンパイルする場合は次のオプションを使用します。

次のコマンドは、ソースファイル udf.c から funclib.dll という DLL を作成します。

implib mygds32.lib ¥interbas¥bin¥gds32.dll

bcc32 -v -a4 -DWIN32 -tWM -tWCD -efunclib.dll udf.c mygds32.lib

次のコマンドは、埋め込みの SQL コマンドを持つソースファイル udftest.e から、

udftest.exe という InterBase の実行形式ファイル（funclib.dll を呼び出す）を作成します。

implib udf.lib funclib.dll

gpre -e udftest.e

bcc32 -v -a4 -DWIN32 -tWM -tWC udftest.c udf.lib mygds32.lib

Borland C コマンドラインリンカを使ってアプリケーションをリンクする場合は、/c オプ

ション（大文字と小文字を区別したリンク）を使用します。

メモボーランドの統合開発環境（IDE）には同等な一般リンカオプションがあります。IDE のデ

フォルトでは、大文字と小文字を区別したリンク（/c オプション）だけがオンになってお

り、InterBase のすべてのエントリポイントで未解決シンボルエラーが出ます。

統合開発環境（IDE）の設定

ボーランドの統合開発環境（IDE）には、コマンドラインオプションと同等なオプション

があります。

IDE のデフォルト大文字と小文字を区別したリンク（/c オプション）は IDE のデフォルトです。

表 3.4 Borland C のコンパイラオプション

オプション動作

v ソースデバッグを有効にする

a4 構造体フィールドの配置をダブルワード境界にする

DWIN32 • 文字列 "WIN32" を定義する

• 引数なしの場合はヌル文字列として定義される

tWM ターゲットはマルチスレッド対応

tWC: • ターゲットはコンソール .EXE、すべての関数がエクスポート可能

• -tWCD オプションと同時には指定できない

tWCD ターゲットはコンソール .DLL、すべての関数がエクスポート可能。-tWC オプションと同時には指定できない



IDE の［プロジェクトオプション］ダイアログボックスIDE の［プロジェクトオプション］ダイアログボックスで以下のオプションを選択します。

対応するコマンドラインオプションも示しています。

ディレクトリインクルードディレクトリ：ibhome¥include

ライブラリディレクトリ：ibhome¥lib

メモデフォルトの InterBase ホームディレクトリ（interbase_home_dir）は、

c:¥Program Files¥Borland¥InterBase です。

コンパイラソースコード｜言語仕様： Borland 拡張

32 ビットコンパイラ

プロセッサ｜データの配置： Double word（-a4 オプションはダブルワード境界）

リンカ一般｜大 /小文字を区別してリンク：オン（/c オプション）

モジュール定義ファイル

モジュール定義ファイルを作成することにより、Borland C++ Builder でリンクとコンパ

イルを行う際の問題がいくつか解決されます。

• STACKSIZE パラメータは少なくとも 10KB（10,240 バイト）に設定する必要があり、16KB（16,384 バイト）が推奨されます。サンプルの .def ファイルが、InterBase のインストール

ディレクトリに入っています。

• Borland C++ Builder では gds32.dll から下線記号（_）なしでエクスポートされた API 関数の先頭に下線記号を添付するため、次の例に示すように、これらの関数についてはモ

ジュール定義ファイルにエリアスを追加しなければならない場合があります。

IMPORTS

_isc_start_transaction = GDS32.isc_start_transaction

ダイナミックリンクライブラリ（DLL）を使用する

InterBase アプリケーションは gds32.dll を使用し、gds32.dll は適切なネットワーク DLLをロードします。これらの DLL は、呼び出しているアプリケーションがすべて終了すると

自動的にアンロードされます。アプリケーションが（一般保護障害などで）異常終了した

場合は、DLL がメモリから正しくアンロードされない場合があります。その場合は、

Windows をいったん終了してから再起動し、リソースを解放してください。

3-8 A P I ガイド


サンプルプログラム

InterBase API の使い方を示すサンプルプログラムは、InterBase のインストールディレ

クトリの examples サブディレクトリにあります。また、サンプルの .def ファイルもありま

す。アプリケーションの例題を作成するには、EXAMPLES ディレクトリに以下のように

入力します。

NT の場合は、ボーランドのコンパイラとリンカ用の makefile.bc、Microsoft のコンパイ

ラとリンカ用の makefile.msc という 2 つのメイクファイルがあります。どのファイルにつ

いても、環境変数 IBASE を修正して絶対パスを指すようにしなければなりません。

.bc メイクファイルの場合は、BCDIR 変数を修正して、Borland のコンパイラとリンカへの

絶対パスを指すようにしてください。

.msc メイクファイルの場合は、MSCDIR 変数を修正して、Microsoft のコンパイラとリン

カへの絶対パスを指すようにしてください。

NT でサンプルアプリケーションを構築するには次のコマンドを使います。

make -B -f makefile.bc all

Microsoft C++ でサンプルアプリケーションを構築するには次のコマンドを使います。

nmake -B -f makefile.msc all

UNIX システムでサンプルアプリケーションを構築するには次のコマンドを使います。

make all


3-10 A P I ガイド

第章

第 4 章データベースの操作

この章では、データベース接続パラメータを指定するデータベースパラメータバッファ（DPB）を設定する方法、データベースハンドルを設定して初期化する方法、およびデータ

ベースのアクセスを制御する 5 つの API 関数を使用する方法について説明します。また、

要求する項目の設定方法、および接続先データベースの情報を抽出する前にバッファの値

を返す方法についても説明します。

次の表は、データベースの操作に使用する API 関数を要約したものです。表の中の関数の

順序は、アプリケーションで通常記述されるに対応しています。

表 4.1 API データベース関数

関数用途

isc_expand_dpb() 実行時にユーザーが入力するユーザー名やパスワードなど、データベースアクセスの追加パラメータを指定します。値が設定されている DPB を必要とし、返される DPB 用により大きなブロックを割り当てます。

isc_attach_database() データベースに接続し、使用するキャッシュバッファの数など、データベースアクセスに関する初期パラメータを設定します。すでに宣言され、値が設定されている DPB を使用します。

isc_database_info() 使用しているオンディスク構造体（ODS）のバージョンなど、接続先データベースについて要求された情報を抽出します。

isc_detach_database() 接続先データベースとの接続を解除し、その接続に割り当てられたシステムリソースを解放します。

isc_drop_database() データベースファイルと、シャドウファイルなどのサポートファイルを削除します。

第 4 章データベースの操作 4-1

データベースへの接続


データベースへの接続は、以下の 4 段階の処理で行います。

1 接続するデータベースごとに、データベースハンドルを作成して初期化する。

2 接続するデータベースごとに、DPB を作成して値を設定する。

3 値を設定した DPB にデータベースパラメータを追加する場合は、実際に接続する前に isc_expand_dpb() を呼び出す。

4 接続するデータベースごとに、isc_attach_database() を呼び出す。

これらのステップについて、この章の以降の節で説明します。

データベースハンドルの作成

アプリケーション内でアクセスするデータベースは、いずれも固有のデータベースハンドルと関連付けられていなければなりません。データベースハンドルは、すべての API 関数

に共通の FILE 構造体を指すポインタです。ibase.h には、データベースハンドルの宣言に使

用する C の typedef 宣言が入っています。

typedef void ISC_FAR *isc_db_handle;

アプリケーションでこの typedef を使ってデータベースハンドルを宣言するには、各ソー

スファイルモジュールで ibase.h をインクルードします。

#include <ibase.h>

データベースハンドルの宣言使用するデータベースハンドルを設定するには、同時にアクセスするデータベースそれぞ

れに、isc_db_handle 型の変数を宣言します。次のコードは 2 つのハンドルを宣言します。

#include <ibase.h>

. . .

isc_db_handle db1;

isc_db_handle db2;

データベースの接続を解除すれば、そのデータベースハンドルを他のデータベースに割り

当てて接続することができます。複数のデータベースにアクセスするアプリケーションで、

一部のデータベースだけにアクセスする場合は、同時に接続するデータベースのハンドル

だけを宣言するだけです。たとえば、合計 3 つのデータベースにアクセスするアプリケー

ションで、そのうちの 2 つと接続する場合は、2 つのデータベースハンドルを宣言するだ

けで済みます。

データベースハンドルの初期化データベースハンドルは、使う前に 0 に設定しておかないとデータベースに接続できませ

ん。次のコードは、2 つのデータベースハンドルを 0 に設定しています。

#include <ibase.h>

. . .

isc_db_handle db1;

4-2 A P I ガイド


isc_db_handle db2;

. . .

/* データベースに接続する前に、データベースハンドルを 0 に設定する */db1 = 0L;

db2 = 0L;

データベースハンドルを 0 に初期化すれば、isc_attach_database() を使ってデータベース

との接続を確立できます。0 以外のデータベースハンドルを isc_attach_database() に渡す

と、接続が失敗してエラーコードが返されます。isc_attach_database() によるデータベー

ス接続の確立については、4-8 ページの「データベースへの接続」を参照してください。

DPB の作成と値の設定

データベースとの接続は、データベースパラメータバッファ（DPB）を作成して必要な値

を設定し、DPB のアドレスを isc_attach_database() に渡すことにより、さまざまな方法で

行うことができます。

たとえば、リモートサーバーのデータベースに接続するためのユーザー名とパスワード、お

よびデータベースのシャドウファイルを起動するパラメータを DPB に含めることができ

ます。DPB のパラメータの一覧は、4 ページの表 4.2 「DPB のパラメータ（目的別）」に

あります。

通常は、データベースに接続するときに DPB を 1 つ作成しますが、パラメータが同じで

あれば、複数の接続で 1 つの DPB を共有することもできます。DPB が作成されていない

場合や、isc_attach_database() に渡されていない場合は、デフォルトのパラメータセット

を使ってデータベースに接続されます。

ヒント DPB パラメータのいくつかは、gfix オプションに直接対応しています。実際には gfix はこれを使って実装されており、特定の DPB パラメータを設定してデータベースに接続しま

す。これに対して、要求された操作（スイープ、非同期書き込み、終了など）をデータベー

ス自身が行います。

DPB は、アプリケーションで明示的に宣言する char 配列変数で、次の部分から構成され

ます。

• パラメータバッファのバッファを指定するバイト。コンパイル時の定数 isc_dpb_version1に固定。

• 1 つ以上の連続するバイトクラスタ。各クラスタでパラメータを 1 つ記述する。

各クラスタの構成要素は次のとおりです。

• 1 バイトのパラメータタイプ。すべてのパラメータタイプについて、コンパイル時の定数

（isc_dpb_num_buffers など）が定義されている。

• クラスタの残りの部分に続くバイト数を指定する 1 バイト。

• 可変長のバイト。パラメータタイプに応じて、数字または文字列として解釈される。

たとえば次のコードは、データベースの接続時に、使用するキャッシュバッファの数を設

定する 1 つのパラメータを使って DPB を作成します。

char dpb_buffer[256], *dpb, *p;

short dpb_length;



/* データベースパラメータバッファを作成します */dpb = dpb_buffer;

*dpb++ = isc_dpb_version1;

*dpb++ = isc_num_buffers;

*dpb++ = 1;

*dpb++ = 90;

dpb_length = dpb - dpb_buffer;

重要データベースパラメータバッファ内の数字は、下位のバイトを先頭にし、上位のバイ

トを後とする汎用フォーマットで表さなければなりません。符号付き数字は、後のバ

イトに符号が付きます。API 関数 isc_portable_integer() を使うと、数値のバイト順を入れ

替えられます。詳細については、15-123 ページの「isc_portable_integer()」を参照し

てください。

DPB パラメータ

表 4.2 は、DPB のパラメータを目的ごとにまとめたものです。表 4.3 は、パラメータをア

ルファベット順に一覧し、それぞれの値の範囲と長さを示します。

表 4.2 DPB のパラメータ（目的別）

説明パラメータ

ユーザー検査パラメータ

ユーザー名 isc_dpb_user_name

パスワード isc_dpb_password

暗号化パスワード isc_dpb_password_enc

システムデータベース管理者のユーザー名 isc_dpb_sys_user_name

ソフトウェアライセンスの使用許可キー isc_dpb_license

データベース暗号化キー isc_dpb_encrypt_key

環境制御

キャッシュバッファの数 isc_dpb_num_buffers

dbkey コンテキストの範囲 isc_dpb_dbkey_scope

システム管理

同期または非同期にデータベースへの書き込みを強制実行する isc_dpb_force_write

レコード修正時のバックアップバージョン格納用に、各データベースページに少量のスペースを確保するかどうかを指定する

isc_dpb_no_reserve

データベースが不完全な場合にマークを付けるかどうかを指定する

isc_dpb_damaged

内部構造の整合性チェックを実行する isc_dpb_verify

4-4 A P I ガイド


次の表は、DPB パラメータのアルファベット順の一覧です。パラメータごとに、パラメー

タとともに渡される値の目的と長さ（バイト数）、実際に渡される値を示します。

シャドウの制御

データベースの同期コピーを複製するデータベースシャドウオプションを有効にする

isc_dpb_activate_shadow

データベースシャドウを削除する isc_dpb_delete_shadow

再生ログシステムの制御

すべてのデータベース呼び出しを記録する再生ログシステムを有効にする

isc_dpb_begin_log

再生ログシステムを無効にする isc_dpb_quit_log

キャラクタセットとメッセージファイルの仕様

言語別のメッセージファイル isc_dpb_lc_messages

使用するキャラクタセット isc_dpb_lc_ctype

表 4.2 DPB のパラメータ（目的別） ( 続き )

説明パラメータ

表 4.3 DPB パラメータ（アルファベット順）

パラメータ用途長さ値

isc_dpb_activate_shadow データベースの同期コピーを複製するデータベースシャドウオプションを有効にする

1（無視） 0（無視）

isc_dpb_damaged データベースが不完全な場合にマークを付けるかどうかを指定する数字

1 = マークを付ける

0 = マークを付けない

1 0 または 1

isc_dpb_dbkey_scope dbkey コンテキストの範囲。0 = 現行トランザクションに範囲を限定する。1 = データベースセッションに範囲を拡大する

1 0 または 1

isc_dpb_delete_shadow 不要になったデータベースシャドウを削除する

1（無視） 0（無視）

isc_dpb_encrypt_key 暗号化キーを示す大 255 文字の文字列文字列内のバイト数

キーを格納する文字列

isc_dpb_force_write データベースへの書き込みの同期 / 非同期を指定する

0 = 非同期、1 = 同期

1 0 または 1

isc_dpb_lc_ctype 使用するキャラクタセットを指定する文字列文字列内のバイト数

キャラクタセット名を含む文字列



isc_dpb_delete_shadow のように、追加パラメータが不要なパラメータもあります。その場

合も、パラメータの長さと値バイトを指定しなければなりません。長さは 1、値は 0 に設

定してください。これらのパラメータ値は InterBase では無視されますが、DPB のフォー

マットを維持するために必要です。

isc_dpb_lc_messages 言語別のメッセージファイルを指定する文字列

文字列内のバイト数

メッセージファイル名を含む文字列

isc_dpb_license ソフトウェアライセンスの使用許可キーを示す文字列


キーを格納する文字列

isc_dpb_no_reserve レコード修正時のバックアップバージョン格納用に、各データベースページに少量のスペースを確保するかどうかを指定する。一次レコードと同じページにバックアップバージョンを格納しておくと更新動作が適化される

0 = スペースを確保する（デフォルト）

1 = スペースを確保しない

1 0 または 1

isc_dpb_num_buffers データベースと併用するキャッシュバッファの割り当て数。デフォルト = 2,048

長さインジケータのバイト数（1、2、または 4）

割り当てられるバッファ数

isc_dpb_password パスワードを示す大 255 文字の文字列文字列内のバイト数

パスワードを含む文字列

isc_dpb_password_enc 暗号化パスワードを示す大 255 文字の文字列


パスワードを含む文字列

isc_dpb_set_db_sql_dialect クライアントによって使用される SQL ダイアレクトを示す数値。データベースヘッダーページでダイアレクトを設定するために gfixユーティリティによって使用される

ダイアレクト 3 は、InterBase 6 で導入された機能にアクセスできる

1 1 - V5.x と V6 互換

2 - 診断

3 - V6 のみ

isc_dpb_sql_dialect クライアントによって使用される SQL ダイアレクトを示す数値。ダイアレクト 3 は、InterBase 6 で導入された機能にアクセスできる

1 1 - V5.x と V6 互換

2 - 診断

3 - V6 のみ

isc_dpb_sql_role_name ログインロール名の文字列文字列内のバイト数

文字列

isc_dpb_sys_user_name システムデータベース管理者（SYSDBA）名を示す大 255 文字の文字列


SYSDBA 名を含む文字列

isc_dpb_user_name ユーザー名を示す大 255 文字の文字列文字列内のバイト数

ユーザー名を含む文字列

表 4.3 DPB パラメータ（アルファベット順） ( 続き )

パラメータ用途長さ値

4-6 A P I ガイド


DPB へのパラメータの追加

実行時に既存の DPB にパラメータを追加できると便利な場合があります。たとえば、アプ

リケーションの実行時にユーザー名やパスワードを指定し、その値を動的に設定すること

ができます。isc_expand_dpb() 関数を使うと、値の設定された DPB に以下のパラメータ

を実行時に渡すことができます。

重要上記のパラメータを実行時に追加することが予想される場合は、isc_expand_dpb() を呼び

出す前に通常の大きさより大きい DPB を作成しておくと、実行時に DPB の格納スペース

を再割り当てする必要がなくなります。isc_expand_dbp() はスペースを再割り当てできま

すが、そのスペースはデータベースの接続を解除したときに自動的には解放されません。

isc_expand_dpb() は、次のパラメータを必要とします。

3 番めのパラメータ（...）は、置き換え可能な任意の数のパラメータを表します。各パラ

メータは、一意の名前を持つ char ポインタです。後のパラメータは、NULL または 16進数の 0 でなければなりません。

重要 isc_expand_dpb() は、DPB に新しいブロックを割り当てます。メモリリークを避けるため

に、この領域は isc_free() を呼び出して解放してください。

次のコードは、実行時にユーザーが入力したユーザー名とパスワードを、isc_expand_dpb()を呼び出して DPB に追加する方法を示しています。


char uname[256], upass[256];

short dpb_length;

/* データベースパラメータバッファを作成します */

表 4.4 isc_expand_dpb( ) によって認識される DPB パラメータ

パラメータ用途

isc_dpb_user_name ユーザー名を示す大 255 文字の文字列

isc_dpb_password パスワードを示す大 255 文字の文字列

isc_dpb_lc_messages 言語別のメッセージファイルを指定する文字列

isc_dpb_lc_ctype 使用するキャラクタセットを指定する文字列

isc_dpb_sql_role_name ロール名を示す大 255 文字の文字列

表 4.5 isc_expand_dbp() のパラメータ

パラメータ型説明

dpb char ** DPB へのポインタ

dpb_size unsigned short * DPB の現在使用されている部分の末尾を指すポインタ

… char * DPB に追加する項目タイプと項目へのポインタ



dpb = dpb_buffer;



*dpb++ = 1;

*dpb++ = 90;


dpb = dpb_buffer;

/* ユーザーに名前とパスワードを要求します */prompt_user("Enter your user name: ");

gets(uname);

prompt_user("¥nEnter your password: ");

gets(upass);

/* 文字列バッファがオーバーフローするか？ */if ((sizeof (dpb_buffer) - dpb_length) <=

strlen (uname) + strlen (upass) +

sizeof (isc_dpb_user_name) + sizeof (isc_dpb_password))

/* expand_dpb を呼び出します */{

isc_expand_dpb(&dpb, &dpb_length, isc_dpb_user_name, uname,isc_dpb_password, upass, NULL);

}

else

/* しない。ローカルでパラメータを追加します */.....


データベースハンドルを作成して初期化し、任意の接続パラメータを指定して DPB を設定

したら、isc_attach_database() を使って既存のデータベースとの接続を確立します。

isc_attach_database() は、データベース接続のシステムリソースを割り当てるとともに、

データベースハンドルを特定のデータベースに結び付け、ハンドルを必要とする以降の

API 呼び出しで使用できるようにします。

isc_attach_database() には、6 つのパラメータが必要です。

• エラーステータス配列を指すポインタ。接続エラーが発生した場合、ここに報告される。

• 接続するデータベース名の長さ（バイト数）。データベース名にノード名とパスが含まれる

場合は、それらを含めた長さを指定する。

• 接続するデータベースの名前を含む文字列。データベース名には、ノード名とパス指定を

含めることができる。

4-8 A P I ガイド


• 接続するデータベースと関連付ける、宣言 / 初期化済みのデータベースハンドルを指すポ

インタ。このハンドルは、このデータベースにアクセスすることを指定するために、以降

の API 呼び出しで使用されます。

• DPB の長さ（バイト数）。DPB を渡さない場合は 0 に設定します。

• DPB を指すポインタ。DPB を渡さない場合は NULL に設定します。

データベースとの接続ごとに、isc_attach_database() を個別に呼び出す必要があります。

次のコードは、InterBase のサンプルデータベース employee.ib との接続を確立し、接続に

使用する DPB を指定します。

#include <ibase.h>

. . .

isc_db_handle db1;


short dpb_length;

char *str = "employee.ib";


. . .

/* データベースに接続する前に、データベースハンドルを 0 に設定します */db1 = 0L;

/* DPB を初期化します */dpb = dpb_buffer;



*dpb++ = 1;

*dpb++ = 90;


/* データベースに接続します */isc_attach_database(status_vector, strlen(str), str, &db1, dpb_length,

dbp_buffer);

if (status_vector[0] == 1 && status_vector[1])

{

error_exit();

}

. . .

次のコードは、DPB を渡さずにデータベースと接続する方法を示しています。

#include <ibase.h>

. . .

isc_db_handle db1;



. . .


/* データベースに接続します */


接続に関する情報の要求

isc_attach_database(status_vector, strlen(str), str, &db1, 0, NULL);


{

error_exit();

}

. . .


アプリケーションでデータベースに接続すると、接続に関する情報が必要になります。

isc_database_info() を呼び出すと、接続に使用されるオンディスク構造体（ODS）のバー

ジョン、割り当てられたデータベースキャッシュバッファの数、読み取りや書き込みを行

うデータベースページの数、ライトアヘッドログ（WAL）の情報など、接続に関する情報

をアプリケーションから問い合わせることができます。

isc_database_info() には、エラーステータスベクターへのポインタとデータベースハンドル

に加えて、アプリケーションが割り当てる 2 つのバッファが必要です。つまり、アプリケー

ションに必要な情報を指す要求バッファ、および InterBase が要求された情報を返す結果

バッファです。要求バッファは、isc_database_info() を呼び出す前の情報を使ってアプリ

ケーションで登録します。isc_database_info() には、要求バッファのポインタ、および要求

バッファのサイズ（バイト数）が渡されます。

結果バッファは、InterBase が返す情報を保持できるサイズで作成しなければなりません。

isc_database_info() には、結果バッファへのポインタ、およびバイト単位で表した結果バッ

ファのサイズも渡されます。結果バッファにデータを保持しきれない場合は、ibase.h で定

義した isc_info_truncated の値を結果バッファの終バイトに格納します。

要求バッファ

要求バッファは、要求された情報項目ごとに、連続バイトの値を 1 つ保持する char 型の配

列です。各バイトは、項目タイプ、要求された情報の種類を示します。ibase.h には、すべ

ての項目タイプに対応するコンパイル時定数が定義されています。

結果バッファ

結果バッファは、要求された項目ごとに、連続したクラスタを 1 つずつ返します。各クラ

スタは、次の 3 つの部分で構成されます。

1 1 バイトの戻り項目タイプ： ibase.h には、すべての項目についてコンパイル時定数が

定義されています。

2 2 バイトの数値：クラスタの残りの部分に続く、クラスタの構成バイト数を指定しま

す。

3 可変長のバイトに格納される値：戻り項目タイプに応じて、数字や文字列として解釈さ

れます。



結果バッファの内容を変換し、必要に応じて各クラスタの内容を解釈する作業は、呼び出

しプログラム側の責任で行います。3. の値は、単なる数字か文字列（連続した文字）の場

合が多いですが、項目のタイプに応じて解釈される任意の数のバイト列である場合もあり

ます。

結果バッファに返されるクラスタはアラインメントされていません。数値はすべて汎用形

式で表され、下位バイトが先頭、上位バイトが後になります。符号付き数値は、

後のバイトに符号が付きます。使用システムに固有のデータ型に数値を変換する必要があ

る場合は、解釈を行う前に変換してください。変換には、API 呼び出しの

isc_portable_integer() を使用することができます。

ステータス情報

InterBase は、要求に対する情報の他に、次のステータスメッセージを結果バッファに戻

します。ステータスメッセージの長さは符号なしの 1 バイトです。

結果バッファ項目と結果バッファ値

以下の節では、下記のデータベース情報の分類ごとに、要求バッファ項目と結果バッファ

の内容を説明します。

• データベース特性

• 環境特性

• パフォーマンス統計値

• データベース操作カウント

データベース特性データベース特性を判定する項目として、データベースのサイズ、オンディスク構造体

（ODS）のバージョン番号などが使用できます。次の表は、受け渡しが可能な要求バッファ

の項目、および結果バッファに返される項目タイプ別の情報をリストにしたものです。

Table 4.6 ステータスメッセージの戻り項目

項目説明

isc_info_end メッセージの終わり

isc_info_truncated 結果バッファが小さいため、要求された情報を保持できない

isc_info_error 要求された情報は利用できない。ステータスベクターをチェックし、エラーコードとエラーメッセージを確認すること



:

表 4.7 データベース特性に関するデータベース情報項目

要求バッファの項目結果バッファの内容

allocation 割り当てられているデータベースページの数

base_level データベースのバージョン（レベル）番号 • 数字 1 を保持する 1 バイト

• バージョン番号を保持する 1 バイト

db_id • データベースのファイル名とサイト名

• 数字を保持する 1 バイト。2 はローカル接続、4 はリモート接続を示す

• データベースのファイル名の長さ d（バイト数）を保持する 1 バイト

• データベースのファイル名を保持する長さ d バイトの文字列

• サイト名の長さ l （バイト数）を保持する 1 バイト

• サイト名を保持する長さ l バイトの文字列

implementation データベースの実装番号

• 数字 1 を保持する 1 バイト

• 実装番号を保持する 1 バイト

• 1 または 12 の「クラス」番号を保持する 1 バイト

no_reserve 0 または 1 • 0：データベースページごとに、変更されたレコードのバックアップ

バージョンを保持するスペースが確保されていることを示す（デフォルト）

• 1：スペースは確保されていない

ods_minor_version オンディスク構造体（ODS）のマイナーバージョン番号。マイナーバージョン番号が大きくなった場合は、構造体とは無関係の変更であることを示す。同じメジャーバージョン番号を持つデータベースエンジンでは、データベースをアクセスできてもマイナーバージョン番号は異なる場合がある

ods_version • ODS のメジャーバージョン番号

page_size 接続したデータベースのページ当たりのバイト数。isc_info_allocation と併せてデータベースのサイズを決める

sql_dialect データベースソフトウェアでサポートされる SQL ダイアレクト

version 実装されているデータベースのバージョンを識別する文字列

• 数字 1 を保持する 1 バイト

• 後に続く文字列の長さ n を指定する 1 バイト

• バージョンを識別する文字列を保持する n バイト

バージョン文字列は表示専用。base_level と version は、バージョンの機能を識別するために使用される



環境特性環境特性を判定する項目には、使用中のメモリ量や、現在割り当てられているデータベー

スキャッシュバッファ数などがあります。各項目について次の表で説明します。

メモプラットフォームによっては、すべての環境情報が得られないことがあります。

パフォーマンス統計値データベースのパフォーマンス統計値を要求する項目が 4 つあります。初のプロセスが

データベースと接続してから、後のプロセスがデータベースとの接続を解除するまでの

累積統計値です。

たとえば、isc_info_reads に対する戻り値は、現行データベースが初に接続してからの読

み取り回数になります。つまり、呼び出しプログラムがデータベースに接続してからの読

み取り回数ではなく、合計の読み取り回数になります。

次の表 4.9 は、パフォーマンス統計値の内容を要約したものです。

データベース操作カウント接続中の呼び出しプログラムが実行したデータベース操作の回数を取得する情報項目があ

ります。各項目の値はテーブルごとに算出されます。

この情報項目を要求すると、以下の情報が結果バッファに返されます。

表 4.8 環境特性に関するデータベース情報項目


current_memory 使用中のサーバーのメモリ量（バイト数）

forced_writes データベースの書き込みモードを指定する数字（0 は非同期、1 は同期）

max_memory 初のプロセスがデータベースに接続してから、一度に使用した大メモリ量（バイト数）

num_buffers 現在割り当てられているメモリバッファの数

sweep_interval 不要になったデータベースレコードバージョンを削除する「スイープ」と「スイープ」の実行の間にコミットされたトランザクションの数

user_names 現在データベースに接続しているすべてのユーザー名。接続ユーザーごとに、isc_info_user_names バイト、ユーザー名のバイト数を指定する 1バイト、およびユーザー名が結果バッファに保持される

表 4.9 パフォーマンス統計値に関するデータベース情報項目


fetches メモリバッファキャッシュからの読み取り回数

marks メモリバッファキャッシュへの書き込み回数

reads ページの読み取り回数

writes ページの書き込み回数



• 項目タイプ（isc_info_insert_count など）を指定する 1 バイト

• 後に続く値ペアを構成するバイト数を示す 2 バイト

• データベースが後に接続されてから、指定したタイプの操作が行われたデータベースの

各テーブルに対応する値ペア

各ペアの構成要素は次のとおりです。

• テーブル ID を指定する 2 バイト

• そのテーブルに対して行われた操作（挿入など）の回数を示す 4 バイト

ヒントテーブル ID から実際のテーブル名を判定するには、RDB$RELATION システムテーブルの

クエリーを実行します。

次の表は、データベースの操作回数を返す項目を説明したものです。

isc_database_info() の呼び出し例

次のコードは、現在接続されているデータベースのページサイズとバッファ数を要求し、結

果バッファの内容をチェックします。

char db_items[] = {

isc_info_page_size, isc_info_num_buffers,

isc_info_end};

char res_buffer[40], *p, item;

int length;

SLONG page_size = 0L, num_buffers = 0L;


isc_database_info(

表 4.10 操作回数に関するデータベース情報項目


backout_count レコードのバージョンを破棄した回数

delete_count データベースが後に接続されてから、データベースに対して削除を実行した回数

expunge_count 削除がコミットされているレコードおよびそのすべての親の削除回数

insert_count データベースに後に接続してから、データベースに挿入が行われた回数

purge_count レコードの旧バージョン（コミットによって不要になった古い親バージョンのレコード）を削除した回数

read_idx_count データベースに後に接続してから、インデックスを使って実行した読み取り回数

read_seq_count データベースに後に接続してから、データベースの順次読み取りを行った回数。つまり、各テーブルの行を順次スキャンした回数

update_count データベースに後に接続してから、データベースを更新した回数


データベース接続の解除

status_vector,

&handle,/* 先の isc_attach_database() 呼び出しで設定されます */sizeof(db_items),

db_items,

sizeof(res_buffer),

res_buffer);

if (status_vector[0] == 1 && status_vector[1]) {

/* エラーが発生しました */isc_print_status(status_vector);

return(1);

};

/* 結果バッファに返された値を抽出します */for (p = res_buffer; *p != isc_info_end ; ) {

item = *p++

length = isc_portable_integer(p, 2);

p += 2;

switch (item){

case isc_info_page_size:

page_size = isc_portable_integer(p, length);

break;

case isc_info_num_buffers:

num_buffers = isc_portable_integer(p, length);

break;

default:

break;

}

p += length;

};

データベース接続の解除

アプリケーションでデータベースへのアクセスが終わり、変更をコミットまたはロール

バックしたら、isc_detach_database() の呼び出しによって、アプリケーションのデータベー

スへの接続を解除し、接続に割り当てられていたシステムリソースを解放してデータベー

スハンドルを 0 に設定します。

isc_detach_database() には、エラーステータスベクターを指すポインタ、および接続を解

除するデータベースのハンドルを指すポインタの 2 つの引数が必要です。次の文は、デー

タベースハンドル db1 によって示されるデータベースとの接続を解除します。

isc_detach_database(status_vector, &db1);

isc_detach_database() は、接続を解除するデータベースごとに呼び出す必要があります。


データベースの削除

データベースの削除

不要になったデータベースをシステムから削除するには、isc_drop_database() を使用しま

す。これにより、データベースのデータ、メタデータ、二次ファイル、シャドウファイル、

ライトアヘッドログ（WAL）をすべて完全に消去します。

削除できるデータベースは、isc_attach_database() の呼び出しによって接続されているも

のに限ります。isc_attach_database() によりデータベースのハンドルが設定されます。

isc_drop_database() を呼び出すときには、削除するデータベースのハンドルを渡さなけれ

ばなりません。

次のコードは、データベースハンドル db1 によって示されるデータベースを削除します。

#include <ibase.h>

. . .

isc_db_handle db1;



. . .


/* データベースに接続します */isc_attach_database(status_vector, strlen(str), str, &db1, 0, NULL);


{

error_exit();

}

isc_drop_database(status_vector, &db1);


{

error_exit();

}

. . .


第章

第 5 章トランザクションの操作

この章では、次の操作を行う方法について説明します。

• パラメータを格納するトランザクションパラメータバッファ（TPB）を設定する

• トランザクションハンドルを設定および初期化する

• トランザクションを制御する API 関数を使用する

• トランザクション ID を取得する

アプリケーション内のデータ定義とデータ操作は、1 つの作業単位として扱わなければなら

ない一連の動作を完了させるために協調して機能するトランザクションと文のコンテキス

トの中で行われます。

InterBase では、1 つの接続で同時に複数のトランザクションを開くことができます。これ

らの同時に開かれるトランザクションは互いに独立しており、競合が生じる場合がありま

す。1 つのデータベースを異なる複数の方法で使用するアプリケーションでは、1 つの接続

内で複数の並列トランザクションを開けることを活用できます。

次の表は、トランザクションの操作にも使用される API 関数とその用途を示します。

表 5.1 API トランザクション関数

関数用途

isc_start_transaction() 1 つ以上のデータベースに対して新規のトランザクションを開始する。すでに宣言され値を設定された TPB を使用する

isc_commit_retaining() トランザクションの変更をコミットし、その後のトランザクション処理に使用できるようにトランザクションのコンテキストを現状のまま維持する

isc_commit_transaction() トランザクションの変更をコミットし、トランザクションを終了する

isc_rollback_transaction() トランザクションの変更をロールバックし、トランザクションを終了する

第 5 章トランザクションの操作 5-1

トランザクションの開始

次の表は、使用頻度が少ないトランザクション API 関数を通常使用される順序で要約した

ものです。


トランザクションは、次の 3 段階の手順で開始します。

1 同時に実行するトランザクションごとに、トランザクションハンドルを作成して初期化

する。

2 必要に応じて、トランザクションごとに TPB を作成して値を設定する。

3 開始するトランザクションごとに isc_start_transaction() を呼び出す。

これらのステップについて、この章の以降の節で説明します。

メモ可変個のパラメータの受け渡しができないアプリケーションを作成する場合は、

isc_start_transaction() のかわりに isc_start_multiple() を使用します。

トランザクションハンドルの作成

アプリケーション内で使用するトランザクションは、いずれも固有のトランザクションハ

ンドルに結び付けられている必要があります。トランザクションハンドルは、すべての APIトランザクション関数が使用するアドレスを指すポインタです。ibase.h ヘッダーファイル

には、トランザクションハンドルの宣言に使用する次のような C の typedef 宣言が含まれ

ています。

typedef void ISC_FAR *isc_tr_handle;

アプリケーションでこの typedef 定義を使ってトランザクションハンドルを宣言するに

は、すべてのソースファイルモジュールで次のように ibase.h をインクルードする必要があ

ります。

#include <ibase.h>

表 5.2 他の API トランザクション関数

関数用途

isc_start_multiple() 1 つ以上のデータベースに対して新規のトランザクションを開始する。FORTRAN などのプログラミング言語は可変個の引数をサポートしていないため、isc_start_transaction() のかわりに使用する

isc_prepare_transaction() isc_commit_transaction() を呼び出す前に、2 相コミットの第 1 段階を実行する。InterBase の自動 2 相コミットを変更することが必須の場合にのみ使用する

isc_prepare_transaction2() isc_commit_transaction() を呼び出す前に、2 相コミットの第 1 段階を実行する。InterBase の自動 2 相コミットを変更することが必須の場合にのみ使用する

isc_rollback_retaining() 1 つ以上のデータベースに対して新規のトランザクションを開始する。FORTRAN などのプログラミング言語は可変個の引数をサポートしていないため、isc_start_transaction() のかわりに使用する

5-2 A P I ガイド


トランザクションハンドルの宣言使用するトランザクションハンドルを設定するには、同時に起動するトランザクションご

とに、isc_tr_handle 型の変数を宣言します。次のコードは、2 つのハンドルを宣言します。

#include <ibase.h>

. . .

isc_tr_handle tr1;

isc_tr_handle tr2;

トランザクションをコミットまたはロールバックした後は、以降の isc_start_transaction()の呼び出しで、そのトランザクションハンドルを他のトランザクションに割り当てること

ができます。複数のトランザクションを使用するアプリケーションで、一部のトランザク

ションだけを開始する場合は、同時に開始するトランザクションのハンドルだけを宣言す

れば済みます。たとえば、合計 3 つのトランザクションを起動するアプリケーションで、

そのうちの 2 つだけを同時に起動する場合は、2 つのトランザクションハンドルを宣言す

ればよいのです。

トランザクションハンドルの初期化トランザクションハンドルを使って新規トランザクションを起動するには、ハンドルを 0に設定しておかなければなりません。次のコードは、2 つのトランザクションハンドルを 0に設定する方法を示したものです。

#include <ibase.h>

. . .

isc_tr_handle tr1;

isc_tr_handle tr2;

. . .

/* トランザクションを開始する前に、トランザクションハンドルを 0 に設定する */tr1 = 0L;

tr2 = 0L;

トランザクションハンドルを 0 に初期化すると、新規のトランザクションを確立する

isc_start_transaction() の呼び出しで使用できるようになります。0 以外のトランザクショ

ンハンドルを isc_start_transaction() に渡すと、起動に失敗し、エラーコードが返されま

す。isc_start_transaction() による新規のトランザクションの開始の詳細については、5-11ページの「isc_start_transaction() の呼び出し」を参照してください。

トランザクションパラメータバッファの作成

トランザクションパラメータバッファ（TPB）は、isc_start_transaction() に引数として渡

されるアプリケーション定義のオプションのバイトベクターです。isc_start_transaction()は、トランザクションの属性を設定して、テーブルの読み取りアクセスと書き込みアクセ

スの両方が可能なトランザクション、読み取り専用アクセスのトランザクション、または

同時に起動した他のトランザクションとテーブルを共有できるかなどの動作特性を設定し

ます。通常はトランザクションごとに TPB を 1 つずつ設定しますが、動作特性が同じな

ら、複数のトランザクションで 1 つの TPB を共有することもできます。



メモ TPB が作成されていないトランザクションについては、isc_start_transaction() に NULL ポインタを渡します。このようなトランザクションには、デフォルトの属性が自動的に代入

されます。デフォルトの TPB の詳細については、5-11 ページの「デフォルトの TPB の使

い方」を参照してください。

TPB は、C プログラムでは 1 バイトずつの要素で構成する文字（char）配列として宣言し

ます。次の例は、一般的な宣言方法を示したものです。

static char isc_tpb[] = {isc_tpb_version3,

isc_tpb_write,

isc_tpb_read_committed,

isc_tpb_no_rec_version,

isc_tpb_wait};

この例は、InterBase のヘッダーファイル f で定義されているパラメータ定数を使用してい

ます。各 TPB の先頭の要素は isc_tpb_version3 定数でなければなりません。

次の表に、有効な TPB 定数とそれらの意味を一覧します。また、isc_start_transaction() に NULLTPB ポインタが渡された場合に、デフォルトの属性のセットとして割り当てられる定数を

示します。

表 5.3 TPB 定数

パラメータ説明

isc_tpb_version3 InterBase バージョン 3 のトランザクション

isc_tpb_consistency テーブルロックのトランザクションモデル。このモードはSERIALIZABLE

isc_tpb_concurrency 処理能力と並列性が高く、REPEATABLE READ の整合性を持つトランザクション。このモードでは、InterBase マルチジェネレーショントランザクションモデルがフルに活用される（デフォルト）

isc_tpb_shared 指定したテーブルの並列アクセスをすべてのトランザクションで共有する。ロックオプションを設定するには、isc_tpb_lock_read とisc_tpb_lock_write を併用する（デフォルト）

isc_tpb_protected 指定したテーブルの並列アクセスを制約する。ロックオプションを設定するには、isc_tpb_lock_read と isc_tpb_lock_write を併用する

isc_tpb_wait 競合するリソースが解放されるまで、操作を再試行せずにトランザクションを待機させることを指定する（デフォルト）

isc_tpb_nowait リソースが解放されるまでトランザクションを待機させず、更新競合エラーを即時に返すことを指定する

isc_tpb_read テーブルデータの選択だけをトランザクションに許可する読み取り専用アクセスモード

isc_tpb_write テーブルデータの選択、挿入、更新、削除をトランザクションに許可する、読み取りと書き込みの両方が可能なアクセスモード（デフォルト）

isc_tpb_lock_read 指定したテーブルの読み取り専用アクセス。ロックオプションを設定するには、isc_tpb_shared、isc_tpb_protected、およびisc_tpb_exclusive を併用する

5-4 A P I ガイド


重要 isc_tpb_read_commited、isc_tpb_no-rec-version、および isc_tpb_nowait を組み合わせ

て使用すると、デッドロックが頻繁に発生します。これらを組み合わせて使用することは

推奨されません。

TPB パラメータは、以下の情報クラスを指定します。

• トランザクションのバージョン番号は、InterBase エンジンが内部で使用します。これは

TPB に指定される先頭の属性で、必ず isc_tpb_version3 に設定しなければなりません。

• アクセスモードは、トランザクションと結び付いた関数が実行できる動作を記述します。

有効なアクセスモードは次のとおりです。

isc_tpb_read

isc_tpb_write

• 排他レベルは、他の並列トランザクションが実行する動作に関連したトランザクションに

ついてデータベースのビューを記述します。有効な排他レベルは次のとおりです。

isc_tpb_concurrency

isc_tpb_consistency

isc_tpb_read_committed, isc_tpb_rec_version

isc_tpb_read_committed, isc_tpb_no_rec_version

• ロック対応は、ロックの競合エラーが発生した場合に、トランザクションの応答方法を記

述します。有効なロック対応は次のとおりです。

isc_tpb_wait

isc_tpb_nowait

isc_tpb_lock_write 指定したテーブルの読み取りと書き込みの両方が可能なアクセス。ロックオプションを設定するには、isc_tpb_shared、isc_tpb_protected、および isc_tpb_exclusive を併用する（デフォルト）

isc_tpb_read_committed 他の並列トランザクションがコミットした変更を読み取ることができる、処理能力と並列性が高いトランザクション。このモードでは、トランザクションは REPEATABLE READ を提供しない

isc_tpb_rec_version 未コミットのレコードのバージョンが保留状態であっても、isc_tpb_read_committed を指定したトランザクションが後にコミットされたバージョンを読み取ることを可能にする

isc_tpb_no_rec_version isc_tpb_read_committed を指定したトランザクションが、コミット済みのレコードの新バージョンだけを読み取ることを可能にする。レコードの未コミットバージョンが保留状態であり、isc_tpb_wait が指定されている場合、トランザクションはレコードがコミットまたはロールバックされるまで待機しなければならない。これに従わない場合は、ロック競合エラーが報告される

表 5.3 TPB 定数 ( 続き )

パラメータ説明



• テーブル予約モードは、トランザクションがアクセスする特定のテーブルについて、アク

セス方法と競合対応を記述します。テーブル予約を使用すると、トランザクションが実際

にテーブルをアクセスするときではなく、トランザクションが起動したときにテーブルが

予約されます。有効なテーブル予約モードは次のとおりです。

isc_tpb_shared, isc_tpb_lock_write

isc_tpb_shared, isc_tpb_lock_read

isc_tpb_protected, isc_tpb_lock_write

isc_tpb_protected, isc_tpb_lock_read

以下の節では、TPB パラメータについて詳しく説明します。

メモテーブルを予約することは、デッドロックを生じないプログラムを作成する方法の 1 つで

す。アプリケーションで短い TP 形式のトランザクションを使用する場合、保護付き読み

出しと保護付き書き込みで使用されるすべてのテーブルを必要に応じて予約すると、パ

フォーマンスを向上させることができます。この方法は、対話形式のアプリケーションで

は使用すべきではありません。テーブルを予約するトランザクションは、予約されていな

いテーブルにアクセスしようとするとエラーを受け取ります。

トランザクションバージョン番号の指定TPB の先頭パラメータは、トランザクション処理に使用するバージョン番号を指定します。

これは常に isc_tpb_version3 に設定しなければなりません。次の TPB 宣言は、先頭パラ

メータの正しい使い方と位置を示したものです。

static char isc_tpb[] = {isc_tpb_version3, ...};

アクセスモードの指定アクセスモードパラメータは、トランザクションがテーブルに対して実行できる動作を記

述します。デフォルトのアクセスモード isc_tpb_write では、トランザクションはテーブル

データの読み取りと書き込みの両方を行うことができます。isc_tpb_read モードでは、テー

ブルデータの読み取りに制限されます。次の TPB 宣言は、読み取り専用のトランザクショ

ンを指定します。

static char isc_tpb[] = {isc_tpb_version3, isc_tpb_read};

TPB には、1 つのアクセスモードパラメータだけを指定します。複数のパラメータを指定

すると、新たに宣言したパラメータが優先され、以前のパラメータは無効になります。

アクセスモードパラメータを指定せずに TPB を宣言した場合は、読み取りと書き込みの両

方が可能なトランザクションとして解釈されます。

排他レベルの指定排他レベルパラメータは、他の並列トランザクションが実行する動作に関連したトランザ

クションについて、データベースのビューを記述します。

5-6 A P I ガイド


isc_tpb_concurrencyデフォルトでは、トランザクションは起動直後のデータベースの固定したビューを認識し、

同時に開かれた他のトランザクションとテーブルへの読み書きアクセスを共有します。こ

のモードは、並列トランザクションがデータを共有することから、「並列」モードと呼ばれ

ます。次の宣言は、排他レベルに isc_tpb_concurrency を指定する TPB を作成します。


isc_tpb_write,

isc_tpb_concurrency};

isc_tpb_read_committed2 つ目の排他レベル isc_tpb_read_committed は、データベースの一貫したビューを提供し

ません。並列トランザクションとは異なり、READ COMMITTED されるトランザクショ

ンは、そのトランザクションの起動後にアクティブになったトランザクションがコミット

した変更を認識します。isc_tpb_rec_version と isc_tpb_no_rec_version の 2 つのパラメー

タは、isc_tpb_read_committed パラメータと併用する必要があります。これは、コミッ

ト済み変更に対するトランザクションのアクセス許可を詳しく指定できるパラメータで

す。

• デフォルトの isc_tpb_no_rec_version パラメータは、行の新バージョンの読み取りだけを

トランザクションに許可します。未コミットの行に変更がある場合は、読み取りできませ

ん。この動作がデフォルトですが、トランザクションで不要な待機条件をもたらす場合が

あります。このオプションは、isc_tpb_nowait と併用して、デッドロックメッセージを回

避する必要があります。

• isc_tpb_rec_version は、新しい未コミットのバージョンがある場合でも、行の後にコミッ

トされたバージョンの読み取りを許可します。

たとえば次の宣言では、行の新のコミット済みバージョンの読み取りを許可する

isc_tpb_rec_version 排他レベルを指定した TPB を作成します。


isc_tpb_write,

isc_tpb_read_committed,

isc_tpb_rec_version};

isc_tpb_consistencyInterBase は、アクセスを制限する排他レベルもサポートします。isc_tpb_consistency は、他

のトランザクションが書き込んだテーブルへのアクセスを禁止します。この排他レベルが

設定されたトランザクションが書き込んだテーブルは、他のトランザクションも書き込む

ことができません。この排他レベルは、読み取りと書き込みの両方が可能な他の並列トラ

ンザクションより前にテーブルの書き込みを行ったトランザクションだけに、テーブル

データの変更を許可することを目的としています。isc_tpb_consistency は、テーブルの共

有アクセスを制限するため、注意して使用する必要があります。ただし、このモードは

SERIALIZABLE なので、トランザクションの一貫性の要件がも高い場合にも合致しま

す。テーブル予約と組み合われば、デッドロックも生じないようにできます。

TPB には、1 つの排他レベルパラメータ（isc_tpb_read_committed 排他モードの場合はパ

ラメータも）を指定します。複数のパラメータを指定すると、新たに宣言したパラメータ

が優先され、前のパラメータは無効になります。



排他モードパラメータを指定せずに TPB を宣言した場合は、isc_tpb_concurrency と解釈さ

れます。

排他レベルの相互作用同一のデータベースをアクセスする 2 つのトランザクションの間に、ロックの競合エラー

が発生したかどうかを判定するには、各トランザクションの排他レベルとアクセスモード

を考慮しなければなりません。次の表は、可能な組み合わせをまとめたものです。

この表からわかるように、isc_tpb_concurrency と isc_tpb_read_committed の両方を指定

したトランザクションは、競合エラーが発生する確率がも低くなります。たとえば、ト

ランザクションに isc_tpb_concurrency を、アクセスモードに isc_tpb_write を指定した t1と、トランザクションに isc_tpb_read_committed を、アクセスモードに isc_tpb_write を指定した t2 がある場合は、両者が同じ行を更新しようとした場合に限り競合エラーが発生

します。t1 と t2 のアクセスモードがどちらも isc_tpb_read の場合は、他のトランザクショ

ンと競合することはありません。

トランザクションに isc_tpb_consistency を、アクセスモードに isc_tpb_write を指定した

場合は、そのトランザクションだけが更新できるテーブルのアクセスは確保できますが、

isc_tpb_concurrency と isc_tpb_read_committed を指定した isc_tpb_read モードのトラ

ンザクションを除く、すべての並列トランザクションと競合します。トランザクションに

isc_tpb_consistency を、アクセスモードに isc_tpb_read を指定した場合は、読み取り専用

のトランザクションとは併用できますが、データの挿入、更新、削除を行うトランザクショ

ンと競合します。

ロック対応の指定ロック対応を指定するパラメータは、書き込み動作（既存行の更新と削除）の実行中に、ア

クセス競合エラーが発生した場合の措置を記述します。このパラメータは、次の 2 種類か

ら選択できます。

• デフォルトの isc_tpb_wait は、ロックされたリソースが解放されるまで、トランザクショ

ンを待機させることを指定します。リソースが解放されると、トランザクション動作を再

実行します。

• isc_tpb_nowait は、ロックの解放を待たずに、トランザクションがロック競合エラーをた

だちに返すことを指定します。

表 5.4 読み取り操作と書き込み操作による排他レベルの相互作用

isc_tpb_concurrency, isc_tpb_read_committed isc_tpb_consistency

isc_tpb_write isc_tpb_read isc_tpb_write isc_tpb_read

concurrency, read_committed

isc_tpb_write 同時に更新が実行されると競合する可能性がある

— 必ず競合必ず競合

isc_tpb_read — — — —

consistencyisc_tpb_write 必ず競合 — 必ず競合必ず競合

isc_tpb_read 必ず競合 — 必ず競合 —

5-8 A P I ガイド


次の宣言は、書き込みアクセス、並列排他モード、isc_tpb_nowait を指定した TPB を作成

します。


isc_tpb_write,

isc_tpb_concurrency,

isc_tpb_nowait};

TPB には、1 つのロック対応パラメータだけを指定します。複数のパラメータを指定する

と、新たに宣言したパラメータが優先され、前のパラメータは無効になります。

宣言された TPB でロック対応パラメータが省略された場合は、isc_tpb_concurrency として解

釈されます。

テーブル予約モードの指定通常トランザクションがテーブルのアクセス権を得るのは、実際に読み取りや書き込みを

行うときだけです。テーブル予約パラメータは、トランザクションの起動時にテーブルへ

のアクセスを取得するために TPB に渡すことができるパラメータです。テーブル予約で

は、トランザクションがアクセスする特定のテーブルについて、アクセス方法と競合解決

方法を指定します。テーブル予約には、次の 3 つの目的があります。

• デフォルトの isc_tpb_wait は、リソースが解放されるまでトランザクションが待機するよ

うに指定します。リソースが解放されると、トランザクションは操作を再実行します。競

合しているトランザクションがコミットされた場合、待機中のトランザクションは、更新

競合エラーを受け取ります。競合しているトランザクションがロールバックされた場合、

待機中のトランザクションは、エラーを生成せずに処理されます。

• isc_tpb_nowait は、リソースの解放を待たずに、トランザクションが更新競合エラーをた

だちに返すことを指定します。このモードでは、エラーを受け取ったトランザクションが

操作をもう一度再実行した場合に「ライブロック」状態となる可能性があります。その場

合は、リソースがまだロックされたままなので再度失敗します。

次の宣言は、書き込みアクセス、並列排他モード、および isc_tpb_nowait の競合解決を指

定した TPB を作成します。


isc_tpb_write,


isc_tpb_nowait};

TPB では、競合解決パラメータは 1 つだけ指定する必要があります。複数のパラメータを

指定すると、後の宣言が前の宣言より優先します。競合解決パラメータを指定せずに TPBを宣言した場合は、isc_tpb_concurrency として解釈されます。

テーブル予約の指定通常、トランザクションは、テーブルに実際に読み書きするときにのみテーブルへの固有

のアクセスを取得します。TPB にテーブル予約パラメータを渡すことによって、トランザ

クションの開始時にテーブルへのアクセスを取得することができます。テーブル予約は、ト

ランザクションがアクセスする特定のテーブルについて、アクセス方法と競合解決を記述

します。テーブル予約には、次の 3 つの目的があります。



• 本当に必要なときにのみロックをかける場合に、デッドロックと更新競合を防止する（デ

フォルト動作）。

• トリガーや整合性制約の影響を受ける恐れのあるテーブルをロックする、関連ロックをか

ける。明示的関連ロックは必須ではありませんが、指定しておくと、間接的なテーブル競

合による更新の競合が発生することはなくなります。

• 任意数のテーブルに対する、トランザクションの共有アクセスレベルを変更する。たとえ

ば、isc_tpb_write アクセスおよび isc_tpb_concurrency 排他レベルを指定したトランザク

ションは、特定のテーブルに対する排他的な更新権が必要になる場合があります。テーブ

ル予約パラメータを使うと、テーブルに対する排他的な書き込みアクセスを確保すること

ができます。

有効なテーブル予約モードは次のとおりです。

• isc_tpb_shared、isc_tpb_lock_write は、isc_tpb_write アクセスモードと、isc_tpb_concurrencyまたは isc_tpb_read_committed 排他レベルを指定したトランザクションに対し、更新を許

可します。上記と同じ排他レベルと、isc_tpb_read アクセスモードを指定した他のトランザ

クションは、データの読み取りを行うことができます。

• isc_tpb_shared、isc_tpb_lock_read は、すべてのトランザクションにデータの読み取りを許

可し、isc_tpb_write アクセスモードを指定したトランザクションに対して更新を許可しま

す。これは、も制限が少ない予約モードです。

• isc_tpb_protected、isc_tpb_lock_write は、他のトランザクションに対して更新を禁止しま

す。isc_tpb_concurrency または isc_tpb_read_committed の排他レベルを指定した他のトラ

ンザクションは、データの読み取りはできますが、更新できるのは isc_tpb_protected、isc_tpb_lock_write を指定したトランザクションだけです。

• isc_tpb_protected、isc_tpb_lock_read は、すべてのトランザクションに対して更新を禁止し、すべてのトランザクションに読み取りを許可します。

予約するテーブルの名前は、予約パラメータの直後に指定しなければなりません。トラン

ザクションで参照されるすべてのテーブルを予約する必要があります。これには、トリガー

またはストアドプロシージャを通して参照されるテーブルも含まれます。たとえば次の

TPB 宣言は、EMPLOYEE というテーブルを予約し、読み取りアクセスを保護する読み取り

保護（protected read）モードを指定します。


isc_tpb_write,


isc_tpb_nowait,

isc_tpb_protected, isc_tpb_lock_read, "EMPLOYEE"};

複数のテーブルを同時に予約することもできます。以下の宣言文は、2 つのテーブルを予約

し、1 つを読み取り保護（protected read）モード、もう 1 つを書き込み保護（protectedwrite）モードに指定します。


isc_tpb_write,


isc_tpb_nowait,

isc_tpb_protected, isc_tpb_lock_read, "COUNTRY",

isc_tpb_protected, isc_tpb_lock_write, "EMPLOYEE"};



デフォルトの TPB の使い方トランザクションの TPB を作成するのは任意です。TPB を作成しない場合は、TPB を指

すポインタのかわりに NULL ポインタを isc_start_transaction() に渡す必要があります。

その場合は、次のような TPB が宣言されたと見なされます。


isc_tpb_write,


isc_tpb_wait};

isc_start_transaction() の呼び出し

トランザクションハンドルと TPB を設定したら、次のプロシージャ宣言に従って

isc_start_transaction() を呼び出すことによりトランザクションを起動できます。

ISC_STATUS isc_start_transaction(ISC_STATUS *status vector,isc_tr_handle *trans_handle,short db_count,isc_db_handle *&db_handle,unsigned short tpb_length,char *tpb_ad);

1 つのデータベースだけを対象として実行するトランザクションについては、db_count を1 に設定します。db_handle には、isc_attach_database() 呼び出しによってすでに設定した

データベースハンドルを指定します。tpb_length は、次パラメータに受け渡す TPB のサイ

ズです。tpb_ad は、TPB のアドレスです。次のコードは、isc_start_transaction() の一般

的な呼び出し例です。

#include <ibase.h>

. . .


isc_db_handle db1;

isc_tr_handle tr1;

static char isc_tbp[] = {isc_tpb_version3,

isc_tpb_write,


isc_tpb_wait};

. . .

/* ここで、データベースおよびトランザクションハンドルを初期化する */db1 = 0L;

tr1 = 0L;

. . .

/* ここのデータベースへの接続コードは省略する */isc_start_transaction(status_vector,

&tr1,

1,

&db1,

(unsigned short) sizeof(isc_tpb),



isc_tpb);

複数のデータベースに対してトランザクションを起動することもできます。これには、

db_count パラメータをデータベースの使用数に設定し、データベースごとに db_handle、tpb_length、tpb_ad を指定します。次に示すのは、2 つのデータベースと接続してトラン

ザクションを起動するコードの一部です。

isc_start_transaction(status_vector,&tr1,

2,

&db1,


&tpb);

&db2,


&tpb);

isc_start_transaction() の構文の詳細な解説は、15-144 ページを参照してください。

isc_start_multiple() の呼び出し

複数のデータベースに対するトランザクションの起動には、isc_start_multiple() を使用す

る方法もあります。ただし、次の条件を満たす場合以外は勧められません。

• 関数呼び出しで、任意の数の引数を利用できない言語を使用する場合

• 必要なデータベース接続が実行時まで不明な場合

C プログラムでは、isc_start_multiple() が必要になることはめったにありません。

isc_start_multiple() は、対象となる各データベースの情報を、トランザクション状態ブロッ

ク（TEB）の配列を使って InterBase に渡します。TEB は、トランザクションの対象とな

るデータベースごとに 1 つずつ指定しなければなりません。TEB は、アプリケーションで

宣言しなければならない、次のような構造体です。

typdef struct {

long *db_ptr;

long tpb_len;

char *tpb_ptr;

} ISC_TEB;

db_ptr は、宣言済みで、初期化と値の設定の済んだデータベースハンドルを指すポインタ

です。tpb_len は、そのデータベースに使用するトランザクションパラメータバッファ

（TPB）のサイズをバイト単位で指定します。tpb_ptr は、TPB そのものを指すポインタで

す。データベースハンドルの宣言 , 初期化、および値の設定については、4-2 ページの「デー

タベースハンドルの作成」を参照してください。TPB の作成と値の設定については、5-3ページの「トランザクションパラメータバッファの作成」を参照してください。

TEB 構造体をアプリケーション内で使用するには、ISC_TEB タイプの配列変数を宣言しま

す。配列の数は、トランザクションの対象となるデータベースの数と一致させます。次の

宣言は、2 つのデータベースを利用できる 2 つの TEB 配列を作成します。

ISC_TEB teb_array[2];



TEB 配列を宣言して、データベースごとに TBP を作成したら、TEB の各項目に値を代入

することができます。次のコードは、2 つの TEB に値を割り当てる方法を示しています。

. . .


isc_db_handle db1, db2;

isc_tr_handle trans;


. . .

db1 = db2 = 0L;

trans = 0L;

/* ここで、2 つの TPB（isc_tpb1 と isc_tpb2）を作成するとします */

/* ここで、データベースに接続するとします */

/* TEB 配列に値を代入します */teb_array[0].db_ptr = &db1;

teb_array[0].tpb_len = sizeof(isc_tpb1);

teb_array[0].tpb_ptr = isc_tpb1;

teb_array[1].db_ptr = &db2;



. . .

TEB に値を代入したら、次の構文で isc_start_multiple() を呼び出すことができます。

ISC_STATUS isc_start_multiple(

ISC_STATUS *status_vector,

isc_tr_handle *trans_handle,

short db_handle_count,

void *teb_vector_address);

次のコードは、2 つのデータベースを対象としたトランザクションを起動します。

. . .


isc_db_handle db1, db2;



. . .

db1 = db2 = 0L;

trans = 0L;

/* ここで、2 つの TPB（isc_tpb1 と isc_tpb2）を作成するとします */

/* ここで、データベースに接続するとします */

/* TEB 配列に値を代入します */teb_array[0].db_ptr = &db1;



teb_array[1].db_ptr = &db2;




トランザクションの終了

/* トランザクションを開始します */isc_start_multiple(status_vector, &trans, 2, teb_array);

. . .


トランザクションのタスクが完了した場合、またはエラーによってトランザクションが完

了できなかった場合は、トランザクションを終了する必要があります。これにより、デー

タベースは通常の状態に戻ります。トランザクションを終了する API 関数には次の 2 つが

あります。

• isc_commit_transaction()。トランザクションの変更を永久的なものとしてデータベースに

書き込みます。複数のデータベースに対するトランザクションの場合は、2 相コミットを

自動的に実行して、すべての変更が正常に完了できるようにします。

• isc_rollback_transaction()。トランザクションによる変更が取り消され、トランザクション

を起動する前の状態にデータベースを戻します。通常、何らかのエラーが発生し、トラン

ザクションによるタスクの完了が不可能な場合に使用します。

isc_commit_transaction() と isc_rollback_transaction() は、現在起動されているトランザク

ションに関連したレコードストリームを閉じます。また、トランザクション名が 0 に初期

化されるとともに、そのトランザクションに割り当てられていたシステムリソースが解放

されます。解放されたシステムリソースは、この後、アプリケーションやプログラムで利

用できます。

isc_rollback_transaction() は、エラー発生時にトランザクションの終了処理を行うための内

部エラー処理ルーチンで使用されます。これは、何らかの理由でトランザクションの処理

が完了しなかった場合に、処理の再実行に先立ってロールバックすることができます。ま

た、プログラムが復旧不可能なエラーに陥ったときに、データベースを元の状態に復元す

ることもできます。

トランザクションを制御する API 関数は、この他にも次の 4 つがあります。

• isc_commit_retaining()。トランザクションをコミットし、現行トランザクションのコンテ

キスト、つまりトランザクションが使用したシステムリソースやカーソルの状態を現状の

まま維持します。トランザクションを終了して新規トランザクションを起動し、カーソル

を元の状態に復旧させる労力を省けます。ただし isc_commit_retaining() は、データベース

の必要な機能であるガベージコレクションを禁止します。

• isc_rollback_retaining()。トランザクションの更新をロールバックしますが、現在のコンテ

キストを保持します。ロールバックの原因はトランザクションのコンテキストにある場合

が多いので、コンテキストの保持は、単に次のロールバックが可能であることを保証する

だけです。この呼び出しには、十分な注意が必要です。

• isc_prepare_transaction() と isc_prepare_transaction2()。isc_commit_transaction() を呼び出

す前に、自動 2 相コミットの第 1 段階を実行してコミットを完了させます。

重要トランザクションの終了前にプログラムが終了する場合、トランザクションの処理は自動

的にロールバックされますが、データベースは閉じられません。開いているデータベース

は、isc_detach_database() を明示的に呼び出して必ず閉じてください。



データベースの接続解除の詳細については、第 4 章「データベースの操作」を参照してく

ださい。

isc_commit_transaction() の使い方

isc_commit_transaction() は、それまでのトランザクションによる変更をデータベースに保

存することができます。isc_commit_transaction() により、トランザクションに関連するレ

コードストリームが閉じられると同時に、トランザクション名が 0 に初期化されます。ま

た、トランザクションに割り当てられていたシステムリソースが解放され、他の目的に利

用できるようになります。コミットが完了する前に、すべての変更はディスクに書き込ま

れ、メタデータのすべての更新が完了します。

isc_commit_transaction() の構文は次のとおりです。

ISC_STATUS isc_commit_transaction(ISC_STATUS *status_vector,isc_tr_handle *trans_handle);

次の呼び出しは、トランザクションをコミットします。

isc_commit_transaction(status_vector, &trans);

ここで、status_vector は、宣言済みのエラーステータスベクターを指すポインタです。transは、宣言済みの初期化されたトランザクションハンドルを指すポインタです。

ヒント isc_tpb_read アクセスモードで起動したトランザクションも、

isc_rollback_transaction() ではなく、isc_commit_transaction() を呼び出して終了する必要が

あります。データベースは変更されませんが、新規トランザクションを起動する労力を大

幅に省けます。

isc_commit_retaining() の使い方

トランザクションが使用した名前、システムリソースやカーソルの状態などのトランザ

クションコンテキストを新たに設定せずに、トランザクションの変更をデータベースに

書き込む場合は、isc_commit_transaction() のかわりに isc_commit_retaining() を使用

します。ただし isc_commit_retaining() は、データベースの必要な機能であるガベージコ

レクションを禁止します。isc_commit_retaining() の関数プロトタイプは次のとおりです。

ISC_STATUS isc_commit_retaining(ISC_STATUS *status_vector,isc_tr_handle *trans_handle);

isc_commit_retaining() は、未処理の変更をデータベースに書き込み、レコードストリーム

や、カーソルをクローズせずに、またシステムリソースを現状のまま維持して現行トラン

ザクションを終了し、既存のレコードストリームやシステムリソースを使って新規トラン

ザクションを起動します。

次の呼び出しは、指定したトランザクションをコミットし、現行のカーソル状態とシステ

ムリソースを現状のまま維持します。

isc_commit_retaining(status_vector, &trans);




isc_commit_retaining() 呼び出しの後で isc_rollback_transaction() を呼び出した場合、

isc_commit_retaining() 呼び出しの後に行われた更新と書き込みだけがロールバックされ

ます。

isc_prepare_transaction() の使い方

isc_commit_transaction() により、複数のデータベースを対象としたトランザクションをコ

ミットすると、2 相コミットが自動的に実行されます。2 相コミットの第 1 段階では、すべ

てのデータベース関係先に、InterBase エンジンがポーリングします。すべてのデータベー

ス関係先が利用可能であることを確認し、RDB$TRANSACTION システムテーブルの

RDB$TRANSACTION_DESCRIPTION フィールドに、トランザクションを記述するメッセー

ジを書き込んで、トランザクションを limbo 状態にします。トランザクションの変更が、

実際にデータベースに書き込まれるのは第 2 段階になってからです。

アプリケーションによっては、2 相コミットと他の処理を組み合わせなければならない場合

があります。そのような場合は、まず isc_prepare_transaction() を呼び出して 2 相コミッ

トの第 1 段階を実行し、アプリケーション自体の別のタスクを実行してから、

isc_commit_transaction() を呼び出してコミットを完了します。

isc_prepare_transaction() の構文は次のとおりです。

ISC_STATUS isc_prepare_transaction(ISC_STATUS *status_vector,isc_tr_handle *trans_handle);

次のコードは、isc_prepare_transaction() を呼び出してからアプリケーションのルーチンを

実行し、isc_commit_transaction() でコミットを完了する方法を示したものです。


isc_db_handle db1;


. . .

/* ハンドルを初期化します */db1 = 0L;

trans = 0L;

. . .

/* ここで、データベースに接続し、 */

/* トランザクションを開始するとします */. . .

/* 2 相コミットの第 1 段階を実行します */isc_prepare_transaction(status_vector, &trans);

/* ここで、アプリケーションは独自の処理を行います */my_app_function();

/* 2 相コミットを完了します */isc_commit_transaction(status_vector, &trans);



重要 2 相コミットの第 1 段階を実行した後は、第 2 段階を早急に実行しなければなりません。そ

うしないと、第 2 段階を実行するまでにネットワークやサーバーのトラブルが発生する確

率が高くなるからです。

isc_prepare_transaction2() の使い方

isc_prepare_transaction2() は、isc_prepare_transaction() と同様に、2 相コミットの第 1 段階を実行します。ただし、アプリケーション独自のトランザクション記述を入力し、

RDB$TRANSACTION システムテーブルの

RDB$TRANSACTION_DESCRIPTION フィールドに挿入できる点が異なります。

重要 isc_prepare_transaction2() の呼び出しは、自動 2 相コミット中に InterBase がRDB$TRANSACTION_DESCRIPTION に書き込む情報を、前もってチェックし理解してから

使用してください。2 相コミットが失敗した場合に、誤った情報や不完全な情報があると、

データベースが復旧できなくなる場合があります。

isc_prepare_transaction2() の構文については、15-125 ページを参照してください。

isc_rollback_transaction() の使い方

isc_rollback_transaction() は、トランザクションを起動する前の状態にデータベースを復元

する場合に使用します。まず、トランザクションに関連したレコードストリームを閉じて

トランザクション名を 0 にリセットします。次に、トランザクションに割り当てられたシ

ステムリソースを解放して他の用途に利用できるようにします。通常は、エラー処理ルー

チン内で使用されます。isc_rollback_transaction() の構文は次のとおりです。

ISC_STATUS isc_rollback_transaction(ISC_STATUS *status_vector,isc_tr_handle *trans_handle);

次の呼び出しは、トランザクションをロールバックします。

isc_rollback_transaction(status_vector, &trans);


isc_rollback_transaction() の構文については、15-135 ページを参照してください。

isc_rollback_retaining() の使い方

isc_rollback_retaining() は、データベースをトランザクション起動前の状態に戻します。

isc_rollback_retaining() は、トランザクションに関連付けられているレコードストリーム

を閉じず、トランザクション名をリセットせず、トランザクションに割り当てられている

システムリソースを解放しません。ロールバックの原因となったエラーがトランザクショ

ンのコンテキストにある場合があるので、isc_rollback_retaining() の使用には注意が必要

です。そのような場合、コンテキストが解放されるまでエラーは解決されません。

isc_rollback_retaining() の構文は次のとおりです。

ISC_STATUS isc_rollback_retaining9



ISC_STATUS *status vector,

isc_tr_handle *trans_handle);

たとえば、次の呼び出しは、トランザクションをロールバックしますが、コンテキストを

保持します。

isc_rollback_retaining(status_vector, &trans);

ここで、status_vector は前に宣言されたエラーステータスベクターへのポインタであり、

trans_handle は前に宣言され初期化されているトランザクションハンドルです。

isc_rollback_retaining() の完全な構文については、15-133 ページを参照してください。


第章

第 6 章動的 SQL の操作

この章では、API の動的 SQL（DSQL）関数により、動的に作成した SQL ステートメン

トを処理してデータの定義や操作を行う方法について説明します。低レベルの API 呼び出

しを使うと、実行時にクライアントアプリケーションで SQL ステートメントを作成する

か、またはエンドユーザーに対して SQL ステートメントの入力を求められるため、エンド

ユーザーが理解しやすいデータベースインターフェースを提供できます。また、アプリケー

ション開発者は埋め込み DSQL ステートメントによる高レベルアクセスでは通常利用で

きない、マルチデータベースなどの InterBase 機能にアクセスすることもできます。たと

えば、InterBase の isql ユーティリティは、低レベルの API 呼び出しを基本とした DSQLアプリケーションです。

API の DSQL 関数名は、他の API 関数と区別しやすいように isc_dsql で始まっていま

す。

DSQL プログラミングプロセスの概要

API による DSQL アプリケーションの作成と実行は、次の手順で行います。

• アプリケーションに DSQL API 関数を埋め込みます。

• ホスト言語のデータ型（変数）やマクロなどを使って入出力エリアを作成します。実行時

には、このエリア（XSQLDA）を介して文とパラメータが受け渡されます。

• 埋め込んだ API 関数や入出力エリアについてプログラミングを行い、実行時の SQL ステートメントが問題なく処理されるようにします。

これらのステップについて、以降の各節で詳しく説明します。

第 6 章動的 S Q L の操作 6-1

D S Q L A P I アプリケーションの制限事項

DSQL API アプリケーションの制限事項

DSQL には数多くの利点がありますが、次のような制限もあります。

• 動的なトランザクション処理を行うことはできません。トランザクションは、コンパイル

時に宣言しておかなければなりません。

• BLOB データや配列データに動的にアクセスすることはできません。ただし、静的に扱わ

れる標準の SQL ステートメントを使って BLOB データと配列データに対してアクセスす

ることは可能です。または、低レベルの API 呼び出しでもアクセスできます。

• データベースの作成は、EXECUTE IMMEDIATE と CREATE DATABASE の組み合わせによる

処理に限られます。

DSQL でのデータベースアクセスについては、6-2 ページの「データベースへのアクセス」

を参照してください。DSQL アプリケーションでのトランザクション操作については、6-3ページの「トランザクションの操作」を参照してください。DSQL での BLOB データの操

作については、6-4 ページの「BLOB データの処理」を参照してください。DSQL での配

列データの扱いについては、6-4 ページの「配列データの処理」を参照してください。デー

タベースの動的な作成については、6-4 ページの「データベースの作成」を参照してくださ

い。

データベースへのアクセス

InterBase API では、データベースハンドルを使ってアプリケーションを複数のデータ

ベースに一度に接続することができます。データベースハンドルは、アプリケーションの

コンパイル時に宣言し、初期化しておかなければなりません。一度にアクセスするデータ

ベースごとに、データベースハンドルを 1 つ作成し、初期化しなければなりません。次の

コードは、1 つのデータベースハンドル db1 を作成し、0 に初期化します。

#include <ibase.h>

isc_db_handle db1;

. . .

db1 = 0L;

宣言と初期化が終われば、そのデータベースハンドルを実行時にデータベースに動的に割

り当てることができます。その例を次に示します。

#include <ibase.h>

. . .

char dbname[129];


. . .

prompt_user("Name of database to open: ");

gets(dbname);

isc_attach_database(status_vector, 0, dbname, &db1, NULL, NULL);

isc _detach_database() を使ってデータベースの接続を解除すると、データベースハンド

ルが自動的に NULL に設定され、そのデータベースハンドルを使って他のデータベースに

接続することができます。次のコードは、データベースとの接続を解除し、データベース

ハンドルを 0 に設定して別のデータベースに接続します。

6-2 A P I ガイド

D S Q L A P I アプリケーションの制限事項


isc_attach_database(status_vector, 0, "employee.ib", &db1, NULL, NULL);

データベース操作の API 関数については、第 4 章「データベースの操作」を参照してくだ

さい。

トランザクションの操作

InterBase では、アプリケーションのコンパイル時にすべてのトランザクションハンドル

を宣言しておかなければなりません。コンパイル時に設定したトランザクションハンドル

は実行時に変更することはできません。さらに、実行時にトランザクション名を動的に宣

言することもできません。isc_dsql_describe()、isc_dsql_describe_bind()、isc_dsql_execute()、isc_dsql_execute2()、isc_dsql_execute_immeidate()、isc_dsql_exec_immed2()、isc_dsql_prepare() など、実行時に SQL ステートメントを処理

するほとんどの API 関数は、トランザクションハンドルパラメータを組み込むことができ

ます。これらの関数が処理する SQL ステートメントは、TRANSACTION 句の使用を許可す

る SQL 構文でもトランザクションハンドルを渡すことはできません。

トランザクションハンドルを使用するには、事前に宣言して 0 に初期化しておかなければ

なりません。以下のコードは、SQL ステートメントを割り当て、実行できるように準備し

ておく API 呼び出し内で、トランザクションハンドルの宣言と初期化を行います。

#include <ibase.h>

. . .

isc_tr_handle trans; /* トランザクションハンドルを宣言します */

isc_stmt_handle stmt; /* ステートメントハンドルを宣言します */char *sql_stmt = "SELECT * FROM EMPLOYEE";

isc_db_handle db1;


. . .

trans = 0L; /* トランザクションハンドルを 0 に初期化します */

stmt = NULL; /* ハンドルを割り当てる前に NULL に設定します */

/* ここでは、ここでデータベース接続を実行し、 */

/* トランザクションを開始するものとします */. . .

/* SQL ステートメントハンドルを割り当てます */isc_dsql_allocate_statement(status_vector, &db1, &stmt);

/* 実行するための文を作成します */isc_dsql_prepare(status_vector, &trans, &stmt, 0, sql_stmt, 1, NULL);

メモ SQL SET TRANSACTION ステートメントは、isc_dsql_prepare() で準備することはできま

せんが、次の条件に一致する場合は、isc_dsql_execute_immeidate() で処理することが

できます。

1 それまでのトランザクションがコミット（またはロールバック）済みであること

2 トランザクションハンドルが NULL に設定されていること

SQL ステートメントの使い方の詳細については、『埋め込み SQL ガイド』を参照してくだ

さい。SQL ステートメントの構文については、『言語リファレンス』を参照してください。


S Q L ステートメントを処理する A P I アプリケーションの作成

データベースの作成

新規データベースは、API アプリケーションで以下のように作成します。

1 isc_detach_database() を使って接続中のデータベースの接続を解除します。データベー

スの接続を解除すると、そのデータベースハンドルは自動的に NULL に設定されます。

2 処理に使う CREATE DATABASE ステートメントを用意します。

3 isc_dsql_execute_immeidate() または isc_dsql_exec_immed2() を使用して、作成し

た文を実行します。

次のコードは、接続中のすべてのデータベースの接続を解除し、新規のデータベースを作

成します。既存のデータベースハンドルは NULL に設定されるため、そのデータベースを

使って後続の DSQL ステートメントで新規のデータベースを作成できます。

char *str = "CREATE DATABASE ¥"new_emp.ib¥"";

. . .


isc_dsql_execute_immediate(status_vector, &db1, &trans, 0, str, 1,NULL);

BLOB データの処理

DSQL では、BLOB を直接処理したり、BLOB カーソルを使用することはできません。

BLOB を処理するには、SQL ステートメントを処理するアプリケーションで API 呼び出

しを使用します。BLOB データの処理については、第 7 章「BLOB データの操作」を参

照してください。

配列データの処理

DSQL では配列を直接処理することはできません。配列データを処理するには、DSQL アプリケーションで API 呼び出しを使用します。配列処理関数については、第 8 章「配列

データの操作」を参照してください。

SQL ステートメントを処理する API アプリケーションの作成

SQL ステートメントを処理する API アプリケーションを作成すると、開発者は InterBaseに対する低レベルのコードを直接作成できるとともに、エンドユーザーが理解しやすい

SQL インターフェースを提供することができます。API SQL アプリケーションは、次の

ような点が実行時までわからない場合に有効です。

• SQL ステートメントで使う文字列

• 変数の数

• 変数のデータ型

• データベースオブジェクトへの参照

6-4 A P I ガイド

S Q L ステートメントを処理する A P I アプリケーションの作成

API DSQL アプリケーションの作成は、通常の SQL アプリケーションに比べて複雑です。

これは、DSQL の処理のほとんどが、拡張 SQL デスクリプタエリア（XSQLDA）データ

構造体の明示的割り当てと処理が必要になるためです。

DSQL ステートメントを処理する API を使用するには、次の手順に従います。

1 API 呼び出しで SQL ステートメントを処理できるかどうかを調べる。

2 アプリケーションで SQL ステートメントを文字列として指定する。

3 必要に応じて、入力パラメータと戻り値に使用する XSQLDA を割り当てる。

4 適切な API プログラミング技法を使って SQL ステートメントを処理する。

API 呼び出しが SQL ステートメントを処理できるかどうかの判定

DSQL では、ほとんどの SQL ステートメントを処理できます。たとえば、DELETE やINSERT などのデータ操作文、ALTER TABLE、CREATE INDEX、SELECT などのデータ定義

文も処理できます。

DSQL API 関数で処理できない SQL ステートメントを次の表に示します。

これらの文は、DSQL 要求の処理や SQL カーソルの操作に使用するもので、アプリケー

ションの作成時に必ず指定しておかなければなりません。DSQL で使用すると、実行時エ

ラーが発生します。

SQL ステートメントを文字列として表す

DSQL アプリケーションでは、SQL ステートメントが通常の SQL アプリケーションとは

異なります。つまり、DSQL アプリケーションでは、ユーザーがプロンプトで入力した

SQL ステートメントが直接 DSQL アプリケーションに取り込まれます。これは、isql の場合も同じです。この他、ユーザーとの対話による応答として、アプリケーションで生成

されることもあります（この場合、アプリケーションで SQL ステートメントを文字列とし

て記述する必要があります）。DSQL では SQL ステートメントにかかわらず、SQL ステー

トメント文字列として指定しなければならず、この文字列が DSQL に渡され処理が行われ

ることになります。

SQL ステートメント文字列では、通常の埋め込みアプリケーションで必要な先頭の EXECSQL 接頭辞および末尾のセミコロン（;）は必要ありません。たとえば、次のホスト言語の

変数宣言は、有効な SQL ステートメント文字列を指定しています。

char *str = "DELETE FROM CUSTOMER WHERE CUST_NO = 256";

CLOSE DECLARE CURSOR

DESCRIBE EXECUTE

EXECUTE IMMEDIATE FETCH

OPEN PREPARE


X S Q L D A

メモこの文字変数の宣言の後にあるセミコロンは、C の文のターミネータであり、SQL ス

テートメント文字列の一部ではありません。

SQL ステートメント文字列内でパラメータを指定する

SQL ステートメント文字列の中には、式の中で評価の対象となる 1 つの数値または文字の

値がパラメータとして含まれるものがあります。こういったパラメータは、文字列として

指定する SQL ステートメントの任意の場所に記述できます。ただし、値がデータベースオ

ブジェクトの名前として解釈されるような場所には記述できません。

SQL ステートメント文字列の中のパラメータは、定数として、または実行時にプレースホ

ルダとして渡すこともできます。次の文文字列は、定数として 256 を渡しています。

char *str = "DELETE FROM CUSTOMER WHERE CUST_NO = 256";

複数の定数を組み合わせて実行時に文字列を作成することもできます。この記述方法は、値

パラメータが実定数ではなくテーブル名や列名の場合、またはその SQL ステートメントを

アプリケーションで 1 回しか実行しない場合などに役立ちます。

パラメータをプレースホルダとして渡す場合は、次のように文文字列に埋め込んだ疑問符

（?）として値を渡します。

char *str = "DELETE FROM CUSTOMER WHERE CUST_NO = ?";

DSQL 関数がプレースホルダを含む SQL ステートメントを処理するときに、疑問符は拡

張 SQL デスクリプタエリア（XSQLDA）に格納されている値で置き換えられます

（XSQLDA はアプリケーションで前もって宣言して割り当てておく必要があります）。した

がって、プレースホルダを使って SQL ステートメントを作成しておくと、その後は値を変

更して何度でもその SQL ステートメントを実行することができます。

プレースホルダは多くの場合、SELECT ステートメントの WHERE 句の検索条件や UPDATEステートメントの SET 句などで使用されます。

XSQLDA

DSQL アプリケーションでは、拡張 SQL デスクリプタエリア（XSQLDA）を宣言しなけ

ればなりません。XSQLDA は構造体で、InterBase の include ディレクトリの中のヘッダー

ファイル ibase.h で定義されています。また、XSQLDA を使用するには、XSQLDA のイン

スタンスを宣言する必要があります。

XSQLDA はホスト言語のデータ構造体で、DSQL で SQL ステートメントが処理される際

は、この構造体を介してデータのデータベースへの移動、またはデータのデータベースか

らの移動が行われます。XSQLDA には、入力デスクリプタ（入力 XSQLDA）と出力デスク

リプタ（出力 XSQLDA）の 2 種類があります。どのデスクリプタも XSQLDA 構造体で、構

造は同じです。

XSQLDA の sqlvar フィールドは XSQLVAR 構造体です。sqlvar は特に重要なフィールド

です。これは、アプリケーションでは入力パラメータまたは返される列ごとに、XSQLVARを 1 つずつ定義しておかなければならないためです。XSQLVAR も、InterBase の includeディレクトリにある ibase.h で定義されている構造体です。

6-6 A P I ガイド

X S Q L D A

アプリケーションでは、事前に XSQLVAR のインスタンスを宣言しておく必要はありませ

ん。ただし、DSQL ステートメントを実行する前に、必要とされる数の XSQLVAR 構造体

用の記憶領域を動的に割り当てなければなりません。割り当てた記憶領域は、DSQL ステー

トメントの実行後、必要に応じて解放します。

次の図は、XSQLDA と XSQLVAR の関係を示したものです。

XSQLDA の 1 つのインスタンス

short version

char sqldaid[8]

ISC_LONG sqldabc

short sqln

short sqld

XSQLVAR sqlvar[1]

XSQLVAR の n 個のインスタンスの配列

1 番めのインスタンス n 番めのインスタンス

short sqltype short sqltype

short sqlscale short sqlscale

short sqlsubtype … short sqlsubtype

short sqllen short sqllen

char *sqldata char *sqldata

short *sqlind short *sqlind

short sqlname_length short sqlname_length

char sqlname[METADATALENGTH] char sqlname[METADATALENGTH]

short relname_length short relname_length

char relname[METADATALENGTH] char relname[METADATALENGTH]

short ownname_length short ownname_length

char ownname[METADATALENGTH] char ownname[METADATALENGTH]

short aliasname_length short aliasname_length

char aliasname[METADATALENGTH] char aliasname[METADATALENGTH]


X S Q L D A

• 入力 XSQLDA は、1 つの XSQLDA 構造体と、入力パラメータと同じ数の XSQLVAR 構造体

で構成されます。

• 出力 XSQLDA は、1 つの XSQLDA 構造体と、1 つの SQL ステートメントで返されるデー

タと同じ数の XSQLVAR 構造体で構成されます。

XSQLDA とその XSQLDA に含まれる XSQLVAR 構造体は、メモリ内の連続した領域に一

括して割り当てられます。

isc_dsql_prepare()、isc_dsql_describe()、isc_dsql_describe_bind() の各関数は、XSQLVAR構造体の適切な割り当て数を判定するために使用できます。格納に必要なメモリ領域は、

XSQLDA_LENGTH マクロで割り当てることができます。

XSQLDA_LENGTH マクロの詳細については、6-11 ページの「XSQLDA_LENGTH マク

ロの使い方」を参照してください。

XSQLDA のフィールド

次の表に、XSQLDA 構造体を構成するフィールドとその説明を示します。

表 6.1 XSQLDA のフィールド

フィールド定義説明

short version XSQLDA 構造体のバージョンを示す。これは SQLDA_CURRENT_VERSION に設定する。この値は ibase.h で定義されている

char sqldaid[8] 将来の使用のために予約

ISC_LONG sqldabc 将来の使用のために予約

short sqln sqlvar 配列の要素の数を示す。アプリケーションで設定される。アプリケーションで XSQLDA 格納用のメモリ領域を割り当てるときは、必ずこの項目を設定しなけばならない

short sqld 入力 XSQLDA では入力パラメータの数、出力 XSQLDA では取り出されるデータの数を示す。isc_dsql_describe()、isc_dsql_describe_bind()、isc_dsql_prepare() いずれかの実行中に InterBase が設定する。

入力 XSQLDA で sqld が 0 の場合は、SQL ステートメントの入力パラメータがないことを示す。出力 XSQLDA で sqld が 0 の場合は、SQL ステートメントが SELECT ステートメントではないことを示す

XSQLVAR sqlvar XSQLVAR 構造体の配列。配列要素の数は sqln フィールドで示される

6-8 A P I ガイド

X S Q L D A

XSQLVAR のフィールド

次の表では、XSQLVAR 構造体のフィールドについて説明します。

表 6.2 XSQLVAR のフィールド


short sqltype パラメータまたは選択リスト項目の SQL データ型を表す。isc_dsql_describe()、isc_dsql_describe_bind()、isc_dsql_prepare() のいずれかの実行時に InterBase が設定する

short sqlscale 数値データ型（DECIMAL、NUMERIC）の小数点以下の桁数を負の数値で表す。isc_dsql_describe()、isc_dsql_describe_bind()、isc_dsql_prepare() のいずれかの実行時に InterBase が設定する

short sqlprecision 数値データ型（DECIMAL、NUMERIC）の有効桁数を表す。isc_dsql_describe()、isc_dsql_describe_bind()、isc_dsql_prepare() のいずれかの実行時に InterBase が設定する

short sqlsubtype BLOB データのサブタイプを示す。isc_dsql_describe()、isc_dsql_describe_bind()、isc_dsql_prepare() のいずれかの実行時に InterBase が設定する

short sqllen sqldata フィールドのデータの大サイズ（バイト数）。isc_dsql_describe()、isc_dsql_describe_bind()、isc_dsql_prepare() のいずれかの実行時に InterBase が設定する

char *sqldata 入力 XSQLDA では、選択リスト項目またはパラメータのアドレス。アプリケーションで設定する

出力 XSQLDA では、選択リスト項目の値。InterBase が設定する

short *sqlind 入力 XSQLDA では、インジケータ変数のアドレスを指定する。アプリケーションで設定する。出力 XSQLDA では、FETCH で取り出される選択リスト項目の列インジケータの値のアドレスを指定する。

この値が 0 の場合は、列のデータは NULL でないことを示す。-1 の場合は、列のデータは NULL であることを示す。InterBase が設定する

short sqlname_length sqlname フィールドのデータのサイズ（バイト数）を指定する。isc_dsql_prepare() または isc_dsql_describe() の実行時に InterBase が設定する

char sqlname[METADATALENGTH] 列名が格納される。NULL（¥0）で終了しない。isc_dsql_prepare() または isc_dsql_describe() の実行時に InterBase が設定する

short relname_length relname フィールドのデータのサイズ（バイト数）を指定する。isc_dsql_prepare() または isc_dsql_describe() の実行時に InterBase が設定する


X S Q L D A

入力デスクリプタ

入力 XSQLDA（入力デスクリプタ）は、DSQL で処理する SQL ステートメント文字列に

パラメータが含まれているときに使用します。これは、SQL ステートメントにパラメータ

が含まれている場合には、事前にパラメータに対して値を渡してから SQL ステートメント

を実行しなければならないためです。パラメータがある場合、アプリケーションで

DESCRIBE を使ってパラメータの数を指定するとともに（この数は XSQLDA の sqldフィールドに格納されます）、各構造体を XSQLVAR 構造体に割り当てます。たとえば、次

の SQL ステートメント文字列には 2 つのパラメータがあり、したがって、アプリケーショ

ンでは DESCRIBE を使ってこの数を指定する（sqld が 2）とともに、プレースホルダの

XSQLVAR への割り当てなどの必要な処理を行います。

char *str = "UPDATE DEPARTMENT SET BUDGET = ? WHERE LOCATION = ?";

これで、SQL ステートメントが実行されたときには、初の XSQLVAR によって BUDGET列の値が、2 番めの XSQLVAR によって LOCATION 列の値が InterBase に渡されることに

なります。

入力デスクリプタの詳細については、6-16 ページの「DSQL のプログラミング手法」を参


char relname[METADATALENGTH] テーブル名が格納される。NULL（¥0）で終了しない。isc_dsql_prepare() または isc_dsql_describe() の実行時に InterBase が設定する

short ownname_length ownname フィールドのデータのサイズ（バイト数）を指定する。isc_dsql_prepare() または isc_dsql_describe() の実行時に InterBase が設定する

char ownname[METADATALENGTH] テーブルのオーナー名が格納される。NULL（¥0）で終了しない。isc_dsql_prepare() または isc_dsql_describe() の実行時に InterBase が設定する

short aliasname_length aliasname フィールドのデータのサイズ（バイト数）を指定する。isc_dsql_prepare() または isc_dsql_describe() の実行時に InterBase が設定する

char aliasname[METADATALENGTH] 列のエリアスが格納される。列にエリアスが設定されていなければ列名が格納される。NULL（¥0）で終了しない。isc_dsql_prepare() または isc_dsql_describe() の実行時に InterBase が設定する

表 6.2 XSQLVAR のフィールド ( 続き )



X S Q L D A

出力デスクリプタ

出力 XSQLDA（出力デスクリプタ）は、クエリーによってその値がアプリケーションに返

される場合に使用します。この場合、戻り値の数は XSQLDA の sqld フィールドに格納さ

れます。戻り値は、それぞれ個別の XSQLVAR 構造体に格納されます。また、XSQLDA のsqlvar フィールドには、初の XSQLVAR 構造体が格納されます。次は、出力 XSQLDA を必要とする SQL ステートメントの例です。

char *str = "SELECT * FROM CUSTOMER WHERE CUST_NO > 100";

出力デスクリプタの使い方の詳細については、6-16 ページの「DSQL のプログラミング手

法」を参照してください。

XSQLDA_LENGTH マクロの使い方

XSQLDA_LENGTH マクロは ibase.h ヘッダーファイルで定義されており、このマクロを使

用して、入力 XSQLDA または出力 XSQLDA に割り当てられるメモリのバイト数を計算で

きます。XSQLDA_LENGTH の定義は次のようになっています。

#define XSQLDA_LENGTH (n) (sizeof (XSQLDA) + (n – 1) * sizeof(XSQLVAR))

n は、SQL ステートメント文字列の中のパラメータの数（入力 XSQLDA）、または、クエ

リーで返されるデータの数（出力 XSQLDA）です。たとえば、次の C 言語の文は

XSQLDA_LENGTH マクロの使用例で、パラメータが 5 つの XSQLDA、または取り出され

るデータの数が 5 つの XSQLDA に割り当てられるメモリの大きさ（バイト数）が算出され

ます。

XSQLDA *my_xsqlda;

. . .

my_xsqlda = (XSQLDA *)malloc(XSQLDA_LENGTH(5));

. . .

XSQLDA_LENGTH マクロの使い方の詳細については、6-16 ページの「DSQL のプログラ

ミング手法」を参照してください。

SQL データ型マクロ定数

InterBase には、SQL のデータ型と NULL ステータスを示すマクロ定数が用意されていま

す。このマクロ定数を使用して、XSQLVAR のデータ型を表すことができます。パラメータ

のデータ型を指定する場合は、このマクロ定数を使わなければなりません。また、取り出

されるデータのデータ型を変換するときにも使います。次の表は、SQL のデータ型、その

データ型に対応するマクロ定数、C のデータ型または InterBase の typedef を一覧にした

ものです。XSQLVAR の sqlind フィールドが使われているかどうかも記載してあります。

sqlind フィールドが使われている場合、ここに標識変数の値が格納され、この値によって、

引数または取り出されるデータが NULL（不定）かどうかを判定できます。


X S Q L D A

表 6.3 SQL のデータ型、マクロ式、C のデータ型

SQL データ型マクロ式 C データ型または typedef

sqlind が使われるか？

配列 SQL_ARRAY ISC_QUAD いいえ

配列 SQL_ARRAY + 1 ISC_QUAD はい

Blob SQL_BLOB ISC_QUAD いいえ

Blob SQL_BLOB + 1 ISC_QUAD はい

BOOLEAN SQL_BOOLEAN 符号付き short いいえ

BOOLEAN SQL_BOOLEAN + 1 符号付き short はい

CHAR SQL_TEXT char[] いいえ

CHAR SQL_TEXT + 1 char[] はい

DATE SQL_DATE ISC_DATE いいえ

DATE SQL_DATE + 1 ISC_DATE はい

DECIMAL SQL_SHORT、SQL_LONG, SQL_DOUBLE、or SQL_INT64

int、long、double、ISC_INT64

いいえ

DECIMAL SQL_SHORT + 1、SQL_LONG + 1、SQL_DOUBLE + 1、または SQL_INT64 + 1


はい

DOUBLE PRECISON

SQL_DOUBLE double いいえ

DOUBLE PRECISION

SQL_DOUBLE + 1 double はい

INTEGER SQL_LONG long いいえ

INTEGER SQL_LONG + 1 ISC_LONG はい

FLOAT SQL_FLOAT float いいえ

FLOAT SQL_FLOAT + 1 float はい

NUMERIC SQL_SHORT、SQL_LONG, SQL_DOUBLE、or SQL_INT64

int、long、double、 ISC_INT64

いいえ

NUMERIC SQL_SHORT + 1、SQL_LONG + 1、SQL_DOUBLE + 1、または SQL_INT64 + 1


はい


X S Q L D A

SQL の DECIMAL と NUMERIC の 2 つのデータ型は、InterBase 内部では、SMALLINT、INTEGER、DOUBLE PRECISION、または 64 ビット整数データ型のいずれかで格納され

ます。この場合、DECIMAL または NUMERIC 列に実際に対応するマクロ定数を判定するこ

とができます。手順は、isql でテーブルの列の定義を確認し、列のデータが InterBase のどのデータ型で格納されているかを確認します。確認後、対応するマクロ定数を選択して

ください。

パラメータや選択リスト項目のデータ型に関する情報は、XSQLVAR 構造体の sqltypeフィールドに格納されます。この場合、sqltype フィールドの値で示される情報には次の 2つがあります。

• パラメータまたは選択リスト項目のデータ型

• sqlind フィールドが使われているかどうかの情報。このフィールドが使われている場合、そ

の値によりパラメータまたは取り出されるデータが NULL であるか（値は -1）、または

NULL でないか（値は 0）がわかります。

たとえば、XSQLVAR 構造体の sqltype フィールドが SQL_TEXT の場合、パラメータまた

は選択リスト項目のデータ型は CHAR で、sqlind フィールドは使用されず、NULL の検査

は行われない（理論的には、NULL 値の格納が禁止されている）ことを表します。一方、

sqltype フィールドが SQL_TEXT+1 の場合、パラメータまたは選択リストのデータ型は同じ

く CHAR で、sqlind フィールドが使用され、パラメータまたは選択リスト項目が NULL であるかどうかの検査が可能であることを示します。

ヒント C 言語の場合には、SQLTYPE & 1 を使ってパラメータや選択リスト項目に NULL が格納

されているかどうかを確認できます。sqltype & 1 による評価が 0 の場合、パラメータや選

択リスト項目には NULL は格納されていませんまた、評価が 1 の場合、パラメータや選択

リスト項目に NULL が格納されていることになります。次のコードは、sqltype & 1 の使

用例です。

if (sqltype & 1 == 0) {

SMALLINT SQL_SHORT short いいえ

SMALLINT SQL_SHORT + 1 short はい

TIME SQL_TIME ISC_TIME いいえ

TIME SQL_TIME + 1 ISC_TIME はい

TIMESTAMP SQL_TIMESTAMP ISC_TIMESTAMP いいえ

TIMESTAMP SQL_TIMESTAMP + 1 ISC_TIMESTAMP はい

VARCHAR SQL_VARYING 初の 2 バイトは文字列の長さを示す short。残りは char[ ]

いいえ

VARCHAR SQL_VARYING + 1 初の 2 バイトは文字列の長さを示す short。残りは char[ ]

はい

表 6.3 SQL のデータ型、マクロ式、C のデータ型 ( 続き )

SQL データ型マクロ式 C データ型または typedef

sqlind が使われるか？


X S Q L D A

/* NULL を含まないパラメータまたは選択リスト項目 */}

else {

/* NULL を含むパラメータまたは選択リスト項目 */}

isc_dsql_prepare() と isc_dsql_describe() は、デフォルトで type+1 のマクロ式を返します。

したがって、必ず sqlind フィールドを検査して値が NULL であるかどうかを確かめる必要

があります。

可変長文字列データ型の操作

VARCHAR、CHARACTER VARYING、NCHAR VARYING の各データ型は、DSQL では取り

扱いに注意が必要です。この種のデータ型では、データの初の 2 バイトには文字列の長

さに関する情報が収められているためです。文字列の実際のバイトは、その残りのデータ

に格納されています。

アプリケーションでこのような可変長文字列の抽出と処理のコーディングを避けるには、

SQL マクロ式を使って固定長のデータ型に強制的に変換することができます。可変長デー

タを強制的に固定長に変換する方法については、6-15 ページの「データ型の強制変換」を


アプリケーションで可変長データを直接処理することもできます。それには、まず文字列

の初の 2 バイトを取り出して文字列自体の長さを判定し、次に文字列をバイト単位で読

み取って NULL 終端のバッファに格納します。

NUMERIC データ型と DECIMAL データ型の操作

DECIMAL と NUMERIC の 2 つのデータ型は、内部では格納される列の精度とサイズの定

義によって、SMALLINT、INTEGER、DOUBLE PRECISION、または 64 ビット整数データ型

のいずれかで格納されます。DECIMAL または NUMERIC の値が、実際に 3 つのうちのど

のデータ型でデータベースに格納されているかは、isql を使ってテーブルの列の定義を確

認します。たとえば、定義が NUMERIC であれば、データは実際には DOUBLE PRECISIONで格納されていることになります。

DECIMAL または NUMERIC のデータが、SMALLINT、INTEGER,、または 64 ビット整数で

格納されている場合は、その値は整数の形で格納されています。この場合、DSQL でデー

タの取り出しを行うと、XSQLVAR の sqlscale フィールドは負の数値に設定されます。この

負の数値は、10 分の 1 を表す係数で、格納されている整数（sqldata に返される）をこの

係数で割ることによって、NUMERIC または DECIMAL の値が小数点以下の桁数付きの数値

に変換されます。たとえば、sqlscale が -1 の場合、整数を 10 で割ることで、小数点以下の

桁数付きの数値に変換されます。また、-2 では 100、-3 では 1000 で割ることで、正しく

変換されます。


X S Q L D A

データ型の強制変換

DSQL で入力パラメータまたは選択リストを処理する場合、データ型の変換が必要なこと

があります。この変換処理をデータ型の強制変換と呼んでいます。たとえば、パラメータ

または取り出されるデータのデータ型が VARCHAR の場合、データ型の強制変換が必要に

なります。VARCHAR のデータは、初の 2 バイトに文字列の長さを示す情報が格納され

ています。その残りが実際の文字列となります。このため、VARCHAR（SQL_VARYING）を

CHAR（SQL_TEXT）に変換すると、データ処理が簡単になります。

データ型の強制変換を行う場合、変換するデータ型に互換性があることが必要です。たと

えば、SQL_VARYING から SQL_TEXT へ、SQL_SHORT から SQL_LONG への変換などは互

換性があるため問題ありません。

文字データ型の強制変換VARCHAR（SQL_VARYING）を CHAR（SQL_TEXT）に変換する場合、パラメータまた

は選択リスト項目の XSQLVAR 構造体の sqltype フィールドを変換先の SQL マクロ定数

（SQL_TEXT）に変更します。次の文の var は XSQLVAR 構造体を指すポインタで、この

XSQLVAR の sqltype フィールドは SQL_VARYING です。このフィールドを SQL_TEXT デー

タ型に変換しています。

var->sqltype = SQL_TEXT;

文字データ型を変換したときは、データの格納に必要なメモリ領域を確保しなければなり

ません。この場合、XSQLVAR の sqllen フィールドには変換元のデータサイズに関する情

報が含まれています。XSQLVAR の sqldata フィールドをデータのアドレスに設定してくだ

さい。

数値データ型の強制変換数値データ型を他のデータ型に変換する場合、パラメータまたは選択リスト項目の

XSQLVAR 構造体の sqltype フィールドを変換先の SQL マクロ定数に変更します。次の文

の var は、XSQLVAR 構造体を指すポインタで、この XSQLVAR の sqltype フィールドは

SQL_SHORT データ型です。この項目を SQL_LONG データ型に変換しています。

var->sqltype = SQL_LONG;

重要桁数の大きいデータ型を桁数の小さいデータ型に強制変換してはなりません。データが失

われる原因となります。

NULL インジケータの設定パラメータまたは選択リスト項目の値が NULL の場合もあります。この場合、sqlind フィー

ルドを使って引数または取り出されるデータの NULL ステータス（値が NULL かどうか）

を調べることができます。なお、sqlind フィールドの値を格納するには、メモリ領域の確

保が必要です。

入力 XSQLDA では、値が NULL の場合、sqlind フィールドを -1 に設定します。そうでな

い場合、0 に設定します。

出力 XSQLDA では、sqlind フィールドが -1 の場合、データは NULL であることを示しま

す。それ以外のときは、データは NULL でないことを示します。


D S Q L のプログラミング手法

数値データの配置（アラインメント）

一般に、データ型が数値の変数は、コンパイラによりメモリ境界に規則的に並ぶように割

り付けられます（アラインメントされます）。これに対して、XSQLDA 構造体や XSQLVAR構造体で見られるように、動的に割り当てられたバッファに数値データが格納される場合

は、バッファ中に規則正しくアラインメントされるように注意する必要があります。

RISC プロセッサの場合など、プラットフォームによっては、動的に割り当てられた構造体

の数値データがメモリの中で必ず正しくアラインメントされるように注意する必要があり

ます。アラインメントは、データ型とプラットフォームによって異なります。

たとえば、Sun SPARCstation では、16 ビット整数は 2 で割り切れるアドレスに格納しな

ければなりません。また、32 ビット整数は 4 で割り切れるアドレスに格納しなければなり

ません。通常、システムにより所定のアラインメントの値が決まっており、このアライン

メントの値で先頭のバイトのアドレスが割り切れる場合、データは正しくアラインメント

されていることになります。アラインメントの要件は、システムやコンパイラによって異

なることがあるので、付属のマニュアルを参照してください。

なお、数値データのアラインメントについては便利な一般法則があります。これは、デー

タ型のサイズが、必ずそのデータ型のアラインメントの値であるというものです。式を使っ

て表すと、データ型を T とした場合、(T) のサイズが n に等しければ、n で割り切れるア

ドレスが T のアラインメントのためのアドレスということになります。したがって、次の

マクロの式を使えば、データのアラインメントが可能になります。

#define ALIGN(ptr, n) ((ptr + n - 1) & ~(n - 1))

上の例で、ptr は char のポインタです。

次のコードは、ALIGN マクロの使用例です。

char *buffer_pointer, *next_aligned;

next_aligned = ALIGN(buffer_pointer, sizeof(T));

DSQL のプログラミング手法

文字列としての SQL ステートメントを処理する場合の DSQL プログラミング手法には、

全部で 4 つの種類があります。どの DSQL プログラミング手法が適切かは、SQL ステー

トメントの内容によって異なります。また、SQL ステートメントにプレースホルダ（入力

パラメータ）があるかどうかも、選択の要因となります。次の表は、使用すべき DSQL プログラミング手法を示したものです。

表 6.4 SQL ステートメント文字列と推奨される処理方法

クエリーか？プレースホルダがあるか？使用する処理方法

いいえいいえ手法 1

いいえはい手法 2

はいいいえ手法 3

はいはい手法 4



手法 1 : パラメータのない非クエリー SQL ステートメント

SQL ステートメントがクエリーではなく、プレースホルダパラメータもない場合、次の 2とおりの処理方法があります。

• isc_dsql_execute_immediate() を使って準備と実行を一括して行います。通常、SQL ステー

トメントの実行が一度限りの場合に使用します。

• isc_dsql_allocate_statement() を使って実行する文の文字列を割り当て、isc_dsql_prepare()で SQL ステートメントを解析して SQL ステートメントに名前を付け、isc_dsql_execute()を使って SQL ステートメントを実行します。通常、その SQL ステートメントをアプリ

ケーションで何度も実行する場合に使用します。

isc_dsql_execute_immediate() の使い方1 isc _dsql_execute_immediate() を使って SQL ステートメントを実行する場合、手順

は次のようになります。実行が一度限りの場合に使用します。

2 ユーザーからの SQL ステートメントの入力を求めます。または、処理する SQL ステートメント文字列を作成します。以下の文は、SQL ステートメント文字列を作成し

ます。

char *str = "UPDATE DEPARTMENT SET BUDGET = BUDGET * 1.05";

3 isc_dsql_execute_immediate() を使用して、SQL ステートメント文字列を分析し、実行

します。

isc_dsql_execute_immediate(status_vector, &db1, &trans, 0, str, 1, NULL);

メモ次のように、isc_dsql_execute_immediate() には文字列定数も使用できます。

isc_dsql_execute_immediate(status_vector, &db1, &trans, 0,"UPDATE DEPARTMENT SET BUDGET = BUDGET * 1.05", 1, NULL);

isc_dsql_execute_immediate() の構文とパラメータについては、第 15 章「API 関数リ

ファレンス」を参照してください。

isc_dsql_prepare() と isc_dsql_execute() の使い方isc_dsql_allocate_statement()、isc_dsql_prepare()、isc_dsql_execute() を組み合わせて SQLステートメント文字列を何度か実行する手順は次のようになります。

1 ユーザーからの SQL ステートメントの入力を求めます。または、処理する SQL ステートメント文字列を作成します。以下の文は、SQL ステートメント文字列を作成し

ます。

char *str = "UPDATE DEPARTMENT SET BUDGET = BUDGET * 1.05";

2 SQL ステートメントハンドルを宣言して初期化し、isc_dsql_allocate_statement() を使って割り当てます。

isc_stmt_handle stmt; /* ステートメントハンドルを宣言します */

stmt = NULL; /* ハンドルを割り当てる前に NULL に設定します */. . .

isc_dsql_allocate_statement(status_vector, &db1, &stmt);



3 isc_dsql_prepare() を使って SQL ステートメント文字列を分析し、SQL ステートメン

トに名前を付けます。解析後のフォーマットを参照するステートメントハンドル

（stmt）が設定されます。ステートメントハンドルは、その後の isc_dsql_execute() の呼び出しに使用されます。

isc_dsql_prepare(status_vector, &trans, &stmt, 0, str, 1, NULL);

次のように、isc_dsql_prepare() には文字列定数も使用できます。

isc_dsql_prepare(status_vector, &trans, &stmt, 0,"UPDATE DEPARTMENT SET BUDGET = BUDGET * 1.05", 1, NULL);

4 isc_dsql_execute() を使用して、名前を割り当てた SQL ステートメントを実行します。

次の文は、stmt という名前の SQL ステートメントを実行します。

isc_dsql_execute(status_vector, &trans, &stmt, 1, NULL);

作成した文文字列は、アプリケーション内で必要に応じて何度も使用できます。

手法 2 : パラメータのある非クエリー SQL ステートメント

SQL ステートメントがクエリーではなく、プレースホルダパラメータがある場合、次の 2段階の手順で処理を行います。

1 SQL ステートメント文字列のパラメータを処理するための入力 XSQLDA を作成しま

す。

2 パラメータのある SQL ステートメント文字列を作成し、実行します。

入力 XSQLDA の作成SQL ステートメントにプレースホルダパラメータがある場合、そのプレースホルダが実際

のデータに置き換えられた後、SQL ステートメント文字列が実行されるという流れで処理

が行われます。この場合、パラメータのある SQL ステートメント文字列を作成したときに

は、パラメータの値は不定です。このため、入力 XSQLDA を作成し、この入力 XSQLDAを介して SQL ステートメントの実行時にパラメータの値を渡すという処理が必要になり

ます。入力 XSQLDA の作成は、次の手順で行います。

1 入力 XSQLDA を格納するための変数を宣言します。この入力 XSQLDA によってパラ

メータが処理されます。たとえば、in_sqlda という XSQLDA の変数を宣言する場合

は、次のようになります。

XSQLDA *in_sqlda;

2 必要に応じて、宣言した XSQLDA の XSQLVAR 構造体にアクセスするための変数を宣

言します。

XSQLVAR *var;

この変数（ポインタ）の宣言はオプションで必ずしも必要ではありませんが、この変数

を宣言することで、後続の文での XSQLVAR 構造体の参照が簡単になります。

3 XSQLDA_LENGTH マクロを使って XSQLDA を格納するためのメモリを割り当てます。

たとえば、in_sqlda のメモリを割り当てる場合、記述は次のようになります。

in_sqlda = (XSQLDA *)malloc(XSQLDA_LENGTH(10));



上の文は、XSQLVAR 10 個分の領域を割り当てています。つまり、in_sqlda には、10 個のパラメータを格納するだけの領域が与えられたことになります。

4 XSQLDA の version フィールドに SQLDA_VERSION1 を設定し、sqln フィールドに XSQLVAR 構造体の割り当て数を設定します。

in_sqlda->version = SQLDA_CURRENT_VERSION;

in_sqlda->sqln = 10;

パラメータのある SQL ステートメント文字列の作成と実行以上の要領でパラメータを格納する準備ができたら、処理対象となる SQL ステートメント

文字列を作成します。また、ローカル変数を使用して、文字列中のプレースホルダパラメー

タをそれぞれ、XSQLVAR 構造体の sqldata フィールドに割り当てます。

パラメータのある非クエリーの SQL ステートメント文字列の作成と実行は、次の手順で行

います。

1 ユーザーからの SQL ステートメント文字列の入力を求めます。または、処理する SQL ステートメント文字列を作成します。たとえば、次の文は、位置指定子パラメー

タがある SQL ステートメント文字列を作成する場合の例です。

char *str = "UPDATE DEPARTMENT SET BUDGET = ?, LOCATION = ?";

この文にはパラメータが 2 つあり、それぞれ、BUDGET 列の値、LOCATION 列の値が

割り当てられます。

2 ステートメントハンドルを宣言して初期化し、isc_dsql_allocate() を使って割り当てま

す。




3 isc_dsql_prepare() を使って文文字列を分析します。これにより、解析後のフォーマッ

トを参照するステートメントハンドル（stmt）が設定され、その後の isc_dsql_describe_bind() 呼び出しまたは isc_dsql_execute() 呼び出しに使用されます。

isc_dsql_prepare(status_vector, &trans, &stmt, 0, str, 1, in_sqlda);

4 isc_dsql_describe_bind() を使用して、入力 XSQLDA に SQL ステートメント内のパラ

メータに関する情報を入力します。

isc_dsql_describe_bind(status_vector, &stmt, 1, in_sqlda);

5 XSQLDA の sqln フィールドの値と XSQLVAR の sqld フィールドの値を比較し、各パラ

メータ情報をすべて格納できるだけの XSQLVAR が割り当てられていることを確認しま

す。sqln フィールドの値は、sqld フィールドの値と同じか大きくなければなりません。

そうでない場合は、先に XSQLDA に割り当てた格納をいったん解放し、パラメータ数

（sqld フィールドで示されます）に見合うだけの領域を割り当てます。また、sqln と version を再設定してから、sqld フィールドを再実行します。

if (in_sqlda->sqld > in_sqlda->sqln)

{

n = in_sqlda->sqld;



free(in_sqlda);

in_sqlda = (XSQLDA *)malloc(XSQLDA_LENGTH(n));

in_sqlda->sqln = n


isc_dsql_describe_bind(status_vector, &stmt, 1, in_sqlda);

}

6 パラメータを表す XSQLVAR それぞれに対して処理を行います。この処理は、次の 4 段階に分かれます。

a パラメータのデータ型を強制変換する。この処理はオプションです。

b XSQLVAR 構造体の sqldata フィールドが示すデータを格納する領域を確保する。この処理は、ローカル変数の格納領域が動的に割り当てられていない場合に限り必要です。下の例は、ローカル変数の格納領域を動的に割り当てる方法を示したものです。

c パラメータに値を設定する。値は、パラメータに定義されているデータ型でなければなりません。この処理は必須です。

d パラメータに NULL インジケータを設定する。

以上の処理を記述すると、次のようなコードになります。ここでは、XSQLDA である in_sqlda の中の各 XSQLVAR 構造体をループで処理しています。

for (i=0, var = in_sqlda->sqlvar; i < in_sqlda->sqld; i++, var++)

{

/* ここで、XSQLVAR パラメータ構造体を処理する

var は、パラメータ構造体を示す */

dtype = (var->sqltype & ~1) /* ここで、NULL フラグを削除します */switch(dtype)

{

case SQL_VARYING: /* SQL_TEXT に強制変換します */var->sqltype = SQL_TEXT;

/* ローカル変数の格納領域を割り当てます */var->sqldata = (char *)malloc(sizeof(char)*var->sqllen);

. . .

break;

case SQL_TEXT:

var->sqldata = (char *)malloc(sizeof(char)*var->sqllen);

/* パラメータに値を設定します */. . .

break;

case SQL_LONG:

var->sqldata = (char *)malloc(sizeof(long));

/* パラメータに値を設定します */*(long *)(var->sqldata) = 17;

break;

. . .



} /* switch ステートメントの終わり */if (sqltype & 1)

/* NULL ステータスを保持する変数を割り当てます */{

var->sqlind = (short *)malloc(sizeof(short));

}

} /* for ループの終わり */

データ型の強制変換と NULL インジケータについては、6-15 ページの「データ型の強

制変換」を参照してください。

7 isc_dsql_execute() を使用して、名前を付けた SQL ステートメントを実行します。次

の文は、stmt という名前の文字列を実行します。

isc_dsql_execute(status_vector, &trans, &stmt, 1, in_sqlda);

SQL ステートメント文字列の再実行パラメータを指定した非クエリーステートメント文字列を作成したら、その SQL ステー

トメントをアプリケーションで繰り返し使うことができます。この場合、パラメータ（入

力 XSQLDA）に新しいデータを入れ、NULL インジケータを設定します。

作成済みの文に別のパラメータと NULL インジケータを設定するには、6-19 ページの「パ

ラメータのある SQL ステートメント文字列の作成と実行」のステップ 6 を繰り返してく

ださい。

手法 3 : パラメータのないクエリー SQL ステートメント

SQL ステートメント文字列がクエリーでパラメータがない場合、次の 3 段階の手順で処理

を行います。

1 出力 XSQLDA を作成し、クエリーの実行時に取り出される選択リスト項目を処理する。

2 SQL ステートメント文字列（クエリー）を作成する。

3 カーソルを使って SQL ステートメントを実行するとともに、出力 XSQLDA から選択リ

スト項目を取り出す。

出力 XSQLDA の作成クエリーでは、通常 1 つまたは複数行が返されます。この行に含まれる列のデータを選択リスト項目と呼びます。ただし、SQL ステートメント文字列の作成時には、返されるデー

タの数は不定なので、出力 XSQLDA を作成し、実行時にこの出力 XSQLDA にいったん選択リスト項目を格納するという処理が必要になります。出力 XSQLDA の作成は、次の手順

で行います。

1 出力 XSQLDA を格納するための変数を宣言する。次の宣言は、out_sqlda という XSQLDA を作成します。

XSQLDA *out_sqlda;


言します。



XSQLVAR *var;



3 XSQLDA_LENGTH マクロを使って XSQLDA を格納するためのメモリを割り当てる。

次の文は、out_sqlda のメモリを割り当てます。

out_sqlda = (XSQLDA *)malloc(XSQLDA_LENGTH(10));

上の文では、XSQLVAR 構造体 10 個分の領域を割り当てています。つまり、

out_sqlda には、選択リスト項目を大 10 個まで格納できる領域が与えられることに

なります。

4 XSQLDA の version フィールドに SQLDA_VERSION1 を設定します。また、sqln フィールドを、割り当てられた XSQLVAR 構造体の数に設定します。

out_sqlda->version = SQLDA_CURRENT_VERSION;

out_sqlda->sqln = 10;

パラメータなしのクエリー SQL ステートメント文字列の作成以上の要領でデータを格納する XSQLDA の作成ができたら、クエリー SQL ステートメン

ト文字列を作成し、SQL ステートメント文字列の実行に備えます。実行すると、InterBaseによりクエリーの記述に従って行が取り出され、選択リスト項目が作成されます。

クエリーの SQL ステートメント文字列は、次のように作成します。

1 ユーザーに SQL ステートメント文字列の入力を求めます。または、クエリー SQL ステートメント文字列を作成します。次の文は、クエリー SQL ステートメント文字列を

作成する場合の例です。

char *str = "SELECT * FROM CUSTOMER";

この文では、SELECT の右にアスタリスク（*）を記述しています。このアスタリスク

は、テーブルのすべての列を表すワイルドカード記号です。したがって、このクエリー

では、テーブルのすべての列と同じ数のデータが返されます。


す。




3 isc_dsql_prepare() を使って SQL ステートメント文字列を分析します。これにより、

文（stmt）が設定されます。ステートメントハンドルは、isc_dsql_describe() や isc_dsql_execute() などの呼び出しに使用されます。

isc_dsql_prepare(status_vector, &trans, &stmt, 0, str, 1, NULL);

4 isc_dsql_describe() を使用して、SQL ステートメントから返される選択リスト項目の

情報を出力 XSQLDA に渡します。

isc_dsql_describe(status_vector, &trans, &stmt, out_sqlda);



5 XSQLDA の sqln フィールドの値と XSQLDA の sqld フィールドの値を比較し、クエ

リーで返される選択リスト項目をすべて格納できるだけの数の XSQLVAR が割り当て

られているかどうかを検査します。ここで、sqln フィールドの値が sqld フィールドの

値より小さいときは、先に割り当てた領域をいったん解放し、sqld フィールドで示さ

れる選択リストの数に必要な領域を再度割り当てます。また、sqln と version を設定し

直し、isc_dsql_describe() を再実行します。この処理の記述は次のようになります。

if (out_sqlda->sqld > out_sqlda->sqln)

{

n = out_sqlda->sqld;

free(out_sqlda);

out_sqlda = (XSQLDA *)malloc(XSQLDA_LENGTH(n));

out_sqlda->sqln = n;


isc_dsql_describe(status_vector, &trans, 1, out_sqlda);

}

6 データを表す XSQLVAR 構造体ごとに処理を行います。次の手順に従います。

a データのデータ型を強制変換する（オプション）。


c パラメータに NULL 値インジケータを設定する。

以上の処理を記述するコードは次のようになります。ここでは、XSQLDA 構造体 out_sqlda の中の各 XSQLVAR 構造体をループで処理しています。

for (i=0, var = out_sqlda->sqlvar; i < out_sqlda->sqld; i++, var++)

{

dtype = (var->sqltype & ~1) /* ここで、フラグビットを削除します */switch(dtype)

{

case SQL_VARYING:


var->sqldata = (char *)malloc(sizeof(char)*var->sqllen + 2);

break;

case SQL_TEXT:


break;

case SQL_LONG:


break;

. . .

/* 残りの型を処理します */} /* switch ステートメントの終わり */if (sqltype & 1)



{

/* NULL ステータスを保持する変数を割り当てます */var->sqlind = (short *)malloc(sizeof(short));

}


データ型の強制変換と NULL インジケータについては、6-15 ページの「データ型の強制

変換」を参照してください。

カーソルのコンテキスト内での SQL ステートメント文字列の実行以上のようにしてクエリー SQL ステートメント文字列の準備ができたら、カーソルを使っ

て SQL ステートメントを実行して選択リストを取り出します。InterBase でのカーソル宣

言はすべてコンパイルの時点で固定されるとともに、埋め込んだ文もアプリケーションに

挿入されます。したがって、DSQL アプリケーションを作成する場合には、事前に使用す

るカーソルを想定して宣言しておく必要があります。

カーソルが必要なのは、オプションの FOR UPDATE OF 句を指定する SELECT ステートメン

トについて、isc_dsql_fetch() を使って抽出する行に対する、UPDATE ステートメントと

DELETE ステートメントを処理する場合に限ります。

以下の説明は、カーソルが必要な状況についてのものです。カーソルを使わずに文を実行

して行を取り出す方法については、15-79 ページの「isc_dsql_fetch()」を参照してくだ

さい。

カーソルを使って SQL ステートメントを実行する場合は、ループ構造を使用します。この

場合、まず 1 行だけ取り出し、その行について選択リスト項目（列のデータ）を処理しま

す。その後、同様に次の行の取り出しと選択リストの処理を行います。

カーソルによる SQL ステートメントの実行と行の取り出しと選択リスト項目の処理は、次

の手順で行います。

1 isc_dsql_execute() を使用して、作成した文字列を実行します。

isc_dsql_execute(status_vector, &trans, &stmt, 1, NULL);

2 isc_dsql_cursor_name() を使用して、文字列の実行に必要なカーソルを宣言して開き

ます。次の文は、SQL ステートメント文字列 stmt の実行に使用するカーソル dyn_cursor を宣言します。

isc_dsql_set_cursor_name(status_vector, &stmt, "dyn_cursor", NULL);

カーソルを開くと SQL ステートメントが実行され、行のアクティブセットが作成され

ます。

3 isc_dsql_fetch() を使って 1 行ずつ取り出し、各行について選択リスト項目（列のデー

タ）を処理します。以下は、dyn_cursor カーソルを使って行を 1 行ずつ取り出すとと

もに、各行について選択リスト項目を処理しているループの例です。ここでは、アプリ

ケーション独自の関数 process_column() を使って行の列データを処理しています。

while ((fetch_stat = isc_dsql_fetch(status_vector, &stmt, 1, out_sqlda))

== 0)

{

for (i = 0; i < out_sqlda->sqld; i++)



{

process_column(sqlda->sqlvar[i]);

}

}

if (fetch_stat != 100L)

{

/* 取得する行が残っていない場合、isc_dsql_fetch は

100 を返します */SQLCODE = isc_sqlcode(status_vector);

isc_print_sqlerror(SQLCODE, status_vector);

return(1);

}

上の例の process_column() 関数は、返された各選択リスト項目を処理します。次の概

略コードは、このような関数の設定方法を示します。

void process_column(XSQLVAR *var)

{

/* NULL 値かどうかをテストします */if ((var->sqltype & 1) && (*(var->sqlind) = -1))

{

/* NULL 値を処理します */}

else

{

/* データを処理します */}

. . .

}

4 すべての行を取り出したら、isc_dsql_free_statement() を使ってカーソルを閉じます。

isc_dsql_free_statement(status_vector, &stmt, DSQL_close);

パラメータのないクエリーステートメント文字列の再実行パラメータのないクエリーステートメント文字列を作成したら、それをアプリケーション

で繰り返し使用できます。この場合、カーソルを閉じてから、もう一度開きます。

カーソルをもう一度開いて選択リスト項目を処理するには、6-24 ページの「カーソルのコ

ンテキスト内での SQL ステートメント文字列の実行」のステップ 2 ～ 4 を繰り返してく

ださい。

手法 4 : パラメータのあるクエリー SQL ステートメント

SQL ステートメントがクエリーでプレースホルダパラメータがある場合、SQL クエリー

ステートメント文字列の処理は次の手順で行います。

1 入力 XSQLDA を作成し、SQL ステートメント文字列のパラメータを処理する。

2 出力 XSQLDA を作成し、クエリーの実行時に取り出される選択リスト項目を処理する。



3 パラメータのあるクエリー SQL ステートメント文字列を用意する。

4 カーソルを使用して、入力 XSQLDA に格納されているパラメータの値をもとに SQL ステートメントを実行するとともに、出力 XSQLDA から選択リスト項目を取り出しま

す。

入力 XSQLDA の作成SQL ステートメントに位置指定子パラメータがある場合、そのプレースホルダパラメータ

が実際のデータに置き換えられた後、SQL ステートメントが実行されるという流れで処理

が行われます。この場合、パラメータのある SQL ステートメントを作成したときには、パ

ラメータの値は不定です。このため、入力 XSQLDA を作成し、この入力 XSQLDA を介し

て SQL ステートメントの実行時にパラメータの値を渡すという処理が必要になります。入

力 XSQLDA の作成は次の手順で行います。

1 入力 XSQLDA を格納するための変数を宣言します。この入力 XSQLDA によってパラ

メータが処理されます。たとえば、in_sqlda という XSQLDA の変数を宣言する場合

は、次のようになります。

XSQLDA *in_sqlda;


言します。

XSQLVAR *var;



3 XSQLDA_LENGTH マクロを使用して、XSQLDA を格納するためのメモリを割り当て

ます。次の文は、in_sqlda のメモリを割り当てます。


上の文では、XSQLVAR 構造体 10 個分の領域を割り当てています。つまり、in_sqlda には、10 個の入力パラメータを格納するだけの領域が与えられることになります。構

造体が割り当てられると XSQLVAR ごとに sqldata フィールドに値が設定されます。



in_sqlda->sqln = 10;

出力 XSQLDA の作成ほとんどのクエリーでは、選択リストの形で 1 行または複数行のデータが返されます。返

される項目の数と種類は SQL ステートメント文字列を実行する前にはわからないので、返

される選択リスト項目を格納する出力 XSQLDA は実行時に作成しなければなりません。出

力 XSQLDA の作成は次の手順で行います。

1 出力 XSQLDA を格納するための変数を宣言します。たとえば、XSQLDA の変数 out_sqlda を宣言する場合は次のようになります。

XSQLDA *out_sqlda;




言します。

XSQLVAR *var;



3 XSQLDA_LENGTH マクロを使って XSQLDA を格納するためのメモリを割り当てる。

次の文は、out_sqlda のメモリを割り当てます。


上の文では、XSQLVAR 構造体 10 個分の領域を割り当てています。つまり、

out_sqlda には、選択リスト項目を大 10 個まで格納できる領域が与えられることに

なります。




パラメータのあるクエリー SQL ステートメント文字列の用意SQL ステートメント文字列のパラメータを格納する入力 XSQLDA と、文を実行したとき

に返される選択リスト項目を格納する出力 XSQLDA が作成できたら、その SQL ステート

メント文字列を実行することができます。SQL ステートメント文字列の準備が整うと、

InterBase は SQL ステートメント文字列内のプレースホルダパラメータを、使用される実パ

ラメータに関する情報に置き換えます。パラメータに関する情報を入力 XSQLDA に割り当

てないと（多くの場合は調整も行わないと）、SQL ステートメントは実行できません。文

文字列を実行すると、InterBase は出力 XSQLDA に選択リスト項目を格納します。

パラメータのあるクエリー SQL ステートメント文字列は、次の手順で作成します。

1 ユーザーからの SQL ステートメント文字列の入力を求めます。または、処理する SQL ステートメント文字列を作成します。たとえば、次の文は、位置指定子パラメー

タがある SQL ステートメント文字列を作成する場合の例です。

char *str = "SELECT * FROM DEPARTMENT WHERE BUDGET = ?, LOCATION = ?";

この文にはパラメータが 2 つあり、それぞれ、BUDGET 列の値、LOCATION 列の値が

割り当てられます。


す。




3 isc_dsql_prepare() を使って SQL ステートメント文字列を準備します。これにより、

ステートメントハンドル stmt が設定されます。ステートメントハンドルは、後続の isc_dsql_describe()、isc_dsql_describe_bind()、isc_dsql_execute2() の呼び出しに使用

されます。



isc_dsql_prepare(status_vector, &trans, &stmt, 0, str, 1, out_xsqlda);

4 isc_dsql_describe_bind() を使用して、入力 XSQLDA に SQL ステートメント内のパラ

メータに関する情報を入力します。

isc_dsql_decribe_bind(status_vector, &stmt, 1, in_xsqlda);

5 XSQLDA の sqln フィールドの値と XSQLDA の sqld フィールドの値を比較し、パラ

メータをすべて格納できるだけの数の XSQLVAR が割り当てられているかどうかを検

査します。sqln フィールドの値が sqld フィールドの値より小さいときは、先に XSQLDA に割り当てた領域をいったん解放し、sqld フィールドで示されるパラメータ

の数に必要な領域を再度割り当てます。また、sqln と version を設定し直し、

isc_dsql_describe_bind() を再実行します。

if (in_sqlda->sqld > in_sqlda->sqln)

{

n = in_sqlda->sqld;

free(in_sqlda);

in_sqlda = (XSQLDA *)malloc(XSQLDA_LENGTH(n));

in_sqlda->sqln = n;


isc_dsql_decribe_bind(status_vector, &stmt, 1, in_xsqlda);

}

6 パラメータを表す XSQLVAR それぞれに対して処理を行います。この処理は、次の 4 段階に分かれます。

a パラメータのデータ型を強制変換する（オプション）。


c パラメータに値を設定する。値は、パラメータに定義されているデータ型で設定しなければなりません。この処理は必須です。

d パラメータに NULL 値インジケータを設定する。

これらの処理は、上記の順序で行わなければなりません。次のコードは、in_sqlda の中の XSQLVAR 構造体（パラメータに対応）ごとにループして、これらの処理を行って

います。

for (i=0, var = in_sqlda->sqlvar; i < in_sqlda->sqld; i++, var++)

{

/* ここで、XSQLVAR パラメータ構造体を処理する

パラメータ構造体は、var で示す */


{

case SQL_VARYING: /* SQL_TEXT に強制変換します */var->sqltype = SQL_TEXT;



/* 適切な格納領域を割り当てます */var->sqldata = (char *)malloc(sizeof(char)*var->sqllen);

/* パラメータに値を設定します。SQL_LONG のケースを参照 */. . .

break;

case SQL_TEXT:


/* パラメータに値を設定します。SQL_LONG のケースを参照 */. . .

break;

case SQL_LONG:


/* パラメータに値を設定します */*(long *)(var->sqldata) = 17;

break;

. . .


{


}




7 isc_dsql_describe() を使用して、SQL ステートメントから返される選択リスト項目の

情報を出力 XSQLDA に渡します。

isc_dsql_describe(status_vector, &trans, &stmt, out_xsqlda);

8 XSQLDA の sqln フィールドの値と XSQLDA の sqld フィールドの値を比較し、選択リ

ストを全部格納できるだけの数の XSQLVAR が割り当てられているかどうかを検査し

ます。sqln フィールドの値が sqld フィールドの値より小さいときは、先に XSQLDA に割り当てた領域をいったん解放し、データの数（sqld フィールドで示されます）に

見合うだけの領域を再度割り当てます。また、sqln と version を設定し直し、もう一度 DESCRIBE OUTPUT を実行します。この処理の記述は次のようになります。

if (out_sqlda->sqld > out_sqlda->sqln)

{

n = out_sqlda->sqld;

free(out_sqlda);

out_sqlda = (XSQLDA *)malloc(XSQLDA_LENGTH(n));

out_sqlda->sqln = n;


isc_dsql_describe(status_vector, &trans, &stmt, out_xsqlda);

}

9 データを表す XSQLVAR 構造体ごとに処理を行います。次の手順に従います。



a データのデータ型を強制変換する（オプション）。

b XSQLVAR の sqldata フィールドが示すデータを格納する領域を確保する。この処理は、実行時にローカル変数の領域の割り当てがまだ行われていない場合に限り必要です。次の例は、ローカル変数の記憶領域を動的に割り当てています。

c データ用の NULL 値インジケータを用意します（オプション）。

以上の処理を記述するコードは次のようになります。ここでは、XSQLDA 構造体 out_sqlda の中の各 XSQLVAR 構造体をループで処理しています。

for (i=0, var = out_sqlda->sqlvar; i < out_sqlda->sqld; i++, var++)

{


{

case SQL_VARYING:


break;

case SQL_TEXT:


break;

case SQL_LONG:


break;

/* 残りの型を処理します */


{


}




クエリー SQL ステートメント文字列のカーソルによる実行パラメータのあるクエリー SQL ステートメント文字列の準備ができたら、カーソルを使っ

て SQL ステートメントを実行して選択リストを取り出します。InterBase でのカーソル宣

言はすべてコンパイラの時点で固定され、埋め込んだ文もアプリケーションに挿入されま

す。したがって、DSQL アプリケーションを作成する場合には、事前に使用されると思わ

れるカーソルを想定し、宣言しておく必要があります。

カーソルを使って SQL ステートメントを実行する場合は、ループ構造を使用します。この

場合、まず 1 行だけ取り出し、その行について選択リスト項目（列のデータ）を処理しま

す。その後、同様に次の行の取り出しと選択リストの処理を行います。



カーソルによる SQL ステートメントの実行と行の取り出しと選択リスト項目の処理は、次

の手順で行います。

1 isc_dsql_execute2() を使って作成した文を実行します。

isc_dsql_execute2(status_vector, &trans, &stmt, 1, in_xsqlda, out_xsqlda);

2 isc_dsql_set_cursor_name() を使用して、SQL ステートメント文字列の実行に必要な

カーソルを宣言します。次の文は、という SQL ステートメント stmt で使うカーソル dyn_cursor を宣言します。

isc_dsql_set_cursor_name(status_vector, &stmt, "dyn_cursor", NULL);

カーソルを開くと SQL ステートメントが実行され、行のアクティブセットが作成され

ます。

3 isc_dsql_fetch() を使って 1 行ずつ取り出し、各行について選択リスト項目（列のデー

タ）を処理します。たとえば次のコードは、dyn_cursor を使って行を 1 行取り出すと

ともに、各行について選択リスト項目を処理するループの例です。ここでは、アプリ

ケーション独自の関数 process_column() を使って行の列のデータを処理しています。

while ((fetch_stat = isc_dsql_fetch(status_vector, &stmt, 1, out_sqlda)) == 0)

{for (i = 0; i < out_sqlda->sqld; i++)

{process_column(sqlda->sqlvar[i]);

}

}


/* isc_dsql_fetch は、取得する行が残っていない場合に 100 を返します */{SQLCODE = isc_sqlcode(status_vector);


return(1);

}

すべての行を取り出したら、isc_dsql_free_statement() を使ってカーソルを閉じます。

isc_dsql_free_statement(status_vector, &stmt, DSQL_close);

パラメータのあるクエリー SQL ステートメント文字列の再実行PREPARE を使ってパラメータを持つクエリー SQL ステートメント文字列の用意ができ

たら、その SQL ステートメントをアプリケーションで繰り返し使うことができます。この

場合、プレースホルダ（入力パラメータ）に新しいデータを入れるとともに NULL 値イン

ジケータの設定を行います。また、SQL ステートメントから返されるデータの情報を出力

XSQLDA に渡します。さらに、カーソルを閉じて、再度開く必要があります。

• 入力 XSQLDA に新しいパラメータを設定する方法については、6-27 ページの「パラメー

タのあるクエリー SQL ステートメント文字列の用意」のステップ 3 ～ 5 の手順を使用し

てください。

• 出力 XSQLDA に新しい情報を設定する方法については、6-27 ページの「パラメータのあ

るクエリー SQL ステートメント文字列の用意」のステップ 6 ～ 8 の手順を使用してくだ

さい。


未知の文タイプを実行時に判定する

• カーソルを再度開いて選択リスト項目を処理する方法については、6-30 ページの「クエ

リー SQL ステートメント文字列のカーソルによる実行」のステップ 2 ～ 4 の手順を使用

してください。


isc_dsql_sql_info() を使うと、実行時にユーザーが入力した文のように、タイプの不定な文

を判定することができます。

要求できる情報は次のとおりです。

• 文のタイプ

• 文が必要とする入力パラメータの数

• 文が返す出力値の数

• データ型、小数点以下の桁数、長さなど、入力パラメータと出力値に関する詳細情報

isc_dsql_sql_info() を使うには、要求する情報のタイプを記述する項目リストバッファ、お

よび関数から戻された情報を保持する結果バッファを割り当てます。たとえば、タイプが

不定の、作成済みの文を判定するには、1 つの要素で構成する項目リストバッファを割り当

て、ibase.h で定義されている isc_info_stmt_type マクロ定数を設定します。

char type_item[];

type_item[] = {isc_info_sql_stmt_type};

メモ ibase.h のコメント「SQL information items」の下には、情報を要求する他のマクロも含

まれています。

結果バッファは、呼び出しから返されるデータを保持するのに十分なサイズでなければな

りません。バッファのサイズは、要求する情報によって決まります。isc_dsql_sql_info() の割り当てスペースが不十分な場合は、事前に設定した isc_info_truncated が結果バッファ

の終バイトに保持されます。通常、文のタイプ情報を要求する場合は、8 バイトのバッ

ファがあれば十分です。これ以上のバッファを宣言してもかまいません。文のタイプを判

定する要求を実行すると、以下の情報が結果バッファに返されます。

1 isc_info_sql_stmt_type を保持する 1 バイト

2 その後に続く値を構成するバイト数を示す数字 n を保持する 2 バイト

3 文のタイプを指定する 1 バイトまたは 2 バイト。次の表は、返される文のタイプをま

とめたものです。

表 6.5 文のタイプ

タイプ数値

isc_info_sql_stmt_select 1

isc_info_sql_stmt_insert 2

isc_info_sql_stmt_update 3

isc_info_sql_stmt_delete 4



4 isc_info_end（0）を含む終バイト

結果バッファに保持される値はアラインメントされていません。数字は、下位バイトが

先頭、上位バイトが末尾の汎用フォーマットで表されます。符号付き数字は、終バイ

トに符号が付きます。数字は、使用システムに固有のデータ型に変換してから解釈してく

ださい。

メモタイプを除く文に関する情報は、isc_dsql_sql_info() 以外の関数を呼び出した方が簡単に判

定できます。たとえば、入力 XSQLDA にある情報を判定するには、isc_dsql_describe_bind()を呼び出します。出力 XSQLDA にある情報を判定するには、isc_dsql_prepare() または

isc_dsql_describe() を呼び出します。

isc_info_sql_stmt_ddl 5

isc_info_sql_stmt_get_segment 6

isc_info_sql_stmt_put_segment 7

isc_info_sql_stmt_exec_procedure 8

isc_info_sql_stmt_start_trans 9

isc_info_sql_stmt_commit 10

isc_info_sql_stmt_rollback 11

isc_info_sql_stmt_select_for_upd 12

表 6.5 文のタイプ

タイプ数値




第章

第 7 章 BLOB データの操作

この章では、InterBase の動的にサイズ変更可能なデータ型である BLOB、および API 関数を使って BLOB を操作する方法について説明します。個々のアプリケーションによっ

て、この章のすべてを読む必要があるか、一部だけ読めばよいかが変わってくるでしょう。

たとえば、ビットマップグラフィックから別のフォーマットへの変換や、MIDI サウンド

データから Wave フォーマットへの変換など、BLOB データのデータ型を変換しようとす

るのであれば、この章全体を読む必要があります。フィルタと呼ばれる変換ルーチンの記

述方法については、7-18 ページの「BLOB データのフィルタリング」を参照してくださ

い。BLOB データと BLOB フィルタの操作の詳細については、『埋め込み SQL ガイド』を


BLOB データを変換する必要がなければ、7-18 ページの「BLOB データのフィルタリン

グ」以降は読む必要はありません。

次の表は、BLOB データの操作に使用できる API 関数の一覧です。各関数については、章

の後半で説明と使用例を示します。

表 7.1 API BLOB 関数

関数用途

isc_blob_default_desc2() サブタイプ、キャラクタセット、セグメントサイズなど、BLOB に関するデフォルトの情報とともに、BLOB デスクリプタをロードする

isc_blob_gen_bpb2() ソース（変換元）とターゲット（変換先）の BLOB デスクリプタからBLOB パラメータバッファ（BPB）を作成し、BLOB サブタイプとキャラクタセットの情報に動的なアクセスを可能にする

isc_blob_info() 開いている BLOB の情報を返す

isc_blob_lookup_desc2() 与えられたテーブル名と BLOB 列名に対し、BLOB のサブタイプ、キャラクタセット、セグメントサイズを判定する

isc_blob_set_desc2() 渡されたパラメータから、BLOB デスクリプタを初期化します

第 7 章 B L O B データの操作 7-1

B L O B の概要

BLOB の概要

BLOB は、標準データ型としてデータベースに格納するのが困難なオブジェクトです。

BLOB を使うと次のデータを格納できます。

• ビットマップイメージ

• サウンド

• ビデオセグメント

• テキスト

InterBase は BLOB データをサポートしているため、トランザクション管理、保守、標準

API 関数呼び出しによるアクセスなど、データベース管理システムのあらゆる利点を活用

することができます。BLOB データは、データベースに直接格納されます。他のシステム

では、データベース以外のファイルを指すポインタだけがデータベースに格納されます。

InterBase では、実際の BLOB がデータベースに格納され、データベース内における

BLOB の位置を示す、識別ハンドルを対応するテーブルに設定します。データベース内に

BLOB データを維持しておくことにより、データのアクセスと管理の効率が大幅に向上し

ます。

BLOB データの格納方法

BLOB データは、ビットマップイメージ、サウンド、ビデオ、テキストの 4 種類に分かれ

ます。データベースへの BLOB の格納に先立ち、現在使用しているプラットフォームやシ

ステムに対応したファイル形式で BLOB データを用意しておかなければなりません。この

場合のファイルとしては次のようなものがあります。

• TIFF、PICT、BMP、WMF、GEM、TARGA などのビットマップまたはベクターグラフィック

ファイル

• MIDI または WAV のサウンドファイル

• Video for Windows のファイル（.AVI）または QuickTime ムービーのファイル（.MOV）

isc_cancel_blob() BLOB を廃棄する

isc_close_blob() 開いている BLOB を閉じる

isc_create_blob2() 書き込みアクセス用に BLOB を作成して開き、必要に応じて BLOB のサブタイプを変換するフィルタを指定する

isc_get_segment() SELECT ステートメントの実行によって返される行の BLOB 列からデータを抽出する

isc_open_blob2() 抽出の対象となる既存の BLOB を開き、必要に応じて BLOB のサブタイプを変換するフィルタを指定する

isc_put_segment() BLOB にデータを書き込む

表 7.1 API BLOB 関数 ( 続き )

関数用途

7-2 A P I ガイド

B L O B の概要

• ASCII、MIF、DOC、WPx などのテキストファイル

• CAD ファイル

これらのファイルは、他のデータ項目やレコードを InterBase に格納するのと同様に、プ

ログラムによってメモリからデータベースにロードしなければなりません。BLOB データ

の作成と格納の詳細については、7-10 ページの「BLOB にデータを書き込む」を参照して

ください。

BLOB サブタイプ

BLOB データは、InterBase の他のデータ型と同じように扱えますが、BLOB データにつ

いてはデータの型付け（typing）の規則に柔軟性があります。BLOB データとして定義で

きるネイティブなデータ型が多数あるので、InterBase はそれらの型を統一的な形で扱い、

プログラマが独自のデータ型を「サブタイプ」として定義することも可能にしています。

InterBase では、定義済みのサブタイプも 2 つ用意しています。0 は、構造が定義されない

サブタイプで、バイナリデータまたは型が未決定のデータに使用します。1 は、プレーンな

テキストに使用します。

ユーザー定義のサブタイプは、-1 ～ -32,678 の負の整数で表されます。

BLOB 列のサブタイプは、BLOB 列を定義するときに指定します。

BLOB 列に格納されているデータが、そのサブタイプに正しく対応しているかどうかは、

アプリケーション側の責任になります。InterBase は BLOB データの型またはフォーマッ

トのチェックを行いません。

BLOB のデータベース上での格納形式

InterBase では、テーブルレコードの BLOB 項目に BLOB データ自体を格納するのではな

く、BLOB ID を格納します。BLOB ID は、BLOB データを参照する一意の数値です。

BLOB データは、一連の BLOB セグメントの形でデータベース内に格納されます。BLOBセグメントは、BLOB データの読み書きの単位となります。個々のセグメントの長さは、

書き込みを行う際に指定します。

セグメントは、データが大きすぎるために、1 つのアプリケーションメモリバッファに書き

込めない場合に便利です。複数のセグメントを使用する必要はなく、すべての BLOB デー

タを 1 つのセグメントに保持してもかまいません。

アプリケーションで BLOB を作成する際は、一度に 1 セグメントずつデータを書き込まな

ければなりません。BLOB を読み取る際も、一度に 1 セグメントずつ読み取ります。セグ

メントの書き込みの詳細については、7-10 ページの「BLOB にデータを書き込む」を参照

してください。セグメントの読み取りの詳細については、7-6 ページの「BLOB からデー

タを読み取る」を参照してください。


B L O B デスクリプタ

BLOB デスクリプタ

BLOB デスクリプタは、BLOB 情報に動的にアクセスするために使用します。たとえば、

フィルタリング（変換）に使用する BLOB データに関する情報を格納するのに使用するこ

とができます。テキスト BLOB データについてはキャラクタセットの情報、テキスト

BLOB データと非テキスト BLOB データについてはサブタイプの情報です。BLOB の書

き込みや読み取りを行う際にフィルタを使用する場合は、2 つの BLOB デスクリプタが必

要になります。すなわち、フィルタのソースデータを記述するデスクリプタ、およびター

ゲットを記述するデスクリプタです。

BLOB デスクリプタは、ibase.h ヘッダーファイルに次のように定義されている構造体で

す。

typedef struct {

short blob_desc_version /* デスクリプタのバージョン */

short blob_desc_subtype; /* BLOB データの型 */

short blob_desc_charset; /* キャラクタセット */

short blob_desc_segment_size; /* セグメントサイズ */

unsigned char blob_desc_field_name [METADATALENGTH]; /* BLOB 列の名前 */

unsigned char blob_desc_relation_name [METADATALENGTH]; /* テーブルの名前 */} ISC_BLOB_DESC_V2;

メモ ISC_BLOB_DESC_V2 は、68 バイトのメタデータ名に対応します。

古い ISC_BLOB_DESC デスクリプタは、32 バイトの名前しか格納できません。これは、下

位互換性のために残されており、今後は削除される予定です。

blob_desc_version フィールドは、isc_blob_default_desc2()、isc_blob_lookup_desc2()、および

isc_blob_set_desc2() によってBLB_DESC_CURRENT_VERSION に設定されます。isc_blob_gen_bpb2()では、blob_desc_version フィールドを手作業で BLB_DESC_CURRENT_VERSION に設定する必要が

あります。

METADATALENGTH は、ibase.h で定義されています。

InterBase が認識するキャラクタセットの詳細については、『言語リファレンス』を参照し

てください。

BLOB のセグメントサイズは、アプリケーションが BLOB から読み取ったり、BLOB に書き込む大バイト数です。このサイズでバッファを独自に割り当てることができます。

blob_desc_relation_name および blob_desc_field_name フィールドには、NULL 終端の文

字列が含まれています。

BLOB デスクリプタの値の設定

BLOB デスクリプタの値を設定する方法は、次の 4 とおりあります。

• isc_blob_default_desc2() を呼び出す。デスクリプタの各項目に、デフォルト値が格納され

ます。デフォルトのサブタイプは 1（TEXT）、セグメントサイズは 80 バイト、キャラクタ

セットは、実行するプロセスに対応するデフォルトのキャラクタセットです。

7-4 A P I ガイド

B L O B データの操作

• isc_blob_lookup_desc2() を呼び出す。データベースのシステムメタデータにアクセスして検

索し、指定した BLOB 列をデスクリプタ項目にコピーします。

• isc_blob_set_desc2() を呼び出す。データベースのメタデータにアクセスせずに、呼び出し

に使用するパラメータを使ってデスクリプタを初期化します。

• デスクリプタの各フィールドを直接設定します。

次の例は、isc_blob_lookup_desc2() を呼び出し、PROJECT という表の PROJ_DESC という

BLOB 列に関する現在のサブタイプとキャラクタセットの情報を検索します。情報は、

from_desc というソースデスクリプタに格納されます。

isc_blob_lookup_desc2 (

status_vector,

&db_handle; /* 先の isc_attach_database() 呼び出しで設定されます */

&tr_handle, /* 先の isc_start_transaction() 呼び出しで設定されます */

"PROJECT", /* テーブル名 */

"PROJ_DESC", /* 列名 */

&from_desc, /* この関数呼び出しによって入力される Blob デスクリプタ */

&global /* この関数から返されるグローバルな列名 */)

データのフィルタリングを要求するアプリケーションでの BLOB デスクリプタの使い方、

および BLOB デスクリプタの値を設定する別の例については、7-24 ページの「フィルタリ

ングを必要とするアプリケーションの作成」を参照してください。

BLOB データの操作

InterBase は、次の BLOB データ操作をサポートします。

• BLOB からの読み取り。

• BLOB への書き込み。書き込みには以下の操作が含まれます。

a BLOB データを含む新規行の挿入

b 行の BLOB 列が参照するデータの置換

c 行の BLOB 列が参照するデータの更新

• BLOB の削除

以下の節では、上記の操作を実行する方法について説明します。データの読み取りや書き

込みの際にサブタイプを変換するフィルタの使い方は用例には含まれていません。フィル

タの使い方については、7-24 ページの「フィルタリングを必要とするアプリケーションの

作成」を参照してください。

BLOB データの選択、挿入、更新に必要な SELECT ステートメント、INSERT ステートメン

ト、UPDATE ステートメントを実行するには、動的 SQL（DSQL）API 関数および XSQLDAデータ構造体が必要になります。以降の節では、例文を実行するための DSQL プログラミ

ング方法についても説明します。DSQL プログラミングの詳細については、第 6 章「動的

SQL の操作」を参照してください。



BLOB からデータを読み取る

既存の BLOB からデータを読み取るには、次の 6 つのステップが必要になります。

1 目的の行の BLOB 列（および他の列）を選択する SELECT ステートメントクエリーを

作成する。

2 取り出す行の列データを保持する出力 XSQLDA 構造体を準備する。

3 実行する SELECT ステートメントを作成する。

4 文を実行する。

5 選択した行を 1 行ずつ取り出す。

6 各行から BLOB データを読み取りって処理する。

SELECT ステートメントの作成文の文字列をユーザーに入力させるか、関連する BLOB データを含む行を選択する SQLクエリーの文字列を作成します。次の文は、PROJECT テーブルの各行から 3 つの列を選択

する SQL クエリーステートメントの文字列を作成します。

char *str ="SELECT PROJ_NAME, PROJ_DESC, PRODUCT FROM PROJECT WHERE ¥PRODUCT IN ('software', 'hardware', 'other') ORDER BY PROJ_NAME";

出力 XSQLDA の作成通常のクエリーは、選択リストと呼ばれるデータ行を返します。取り出される行ごとに、列

データを格納する出力 XSQLDA を作成しておかなければなりません。BLOB 列の列データ

は、実際のデータをアクセスするのに必要な内部 BLOB 識別子（BLOB ID）になります。

XSQLDA を作成する手順は次のとおりです。

1 XSQLDA を保持する変数を宣言します。次の宣言は、out_sqlda という XSQLDA を作

成します。

XSQLDA *out_sqlda;

2 XSQLDA_LENGTH マクロを使い、XSQLDA のメモリを割り当てます。XSQLDA には、

取り出す列ごとに、XSQLVAR 構造体を 1 つずつ設定しなければなりません。次の文は、

3 つの XSQLVAR 構造体を持つ出力 XSQLDA（out_sqlda）の格納スペースを割り当てま

す。


3 XSQLDA の version フィールドに SQLDA_CURRENT_VERSION を設定し、sqln フィー

ルドに XSQLVAR 構造体の割り当て数を設定します。



実行する SELECT ステートメントの準備選択した各行の列データを保持する XSQLDA を作成したら、実行するクエリーステート

メントの文字列を作成します。手順は次のとおりです。

7-6 A P I ガイド




stmt = NULL; /* ハンドルを割り当てる前に NULL に設定します */isc_dsql_allocate_statement(status_vector, &db_handle, &stmt);

2 isc_dsql_prepare() を使用して、文字列が実行できるように準備します。文字列（str）に

構文エラーがないかどうかをチェックし、効率的に実行できるフォーマットに変換して、

そのフォーマットを参照するようにステートメントハンドル（stmt）を設定します。ス

テートメントハンドルは、その後の isc_dsql_execute() 呼び出しに使用されます。

次の例のように、出力 XSQLDA を指すポインタが isc_dsql_prepare() に渡される場合

は、XSQLDA のほとんどの項目とすべての XSQLVAR 構造体に、文の対応する列のデー

タ型、長さ、名前などの情報が格納されます。

isc_dsql_prepare() の呼び出し例を次に示します。

isc_dsql_prepare(

status_vector,

&trans, /* 先の isc_start_transaction() 呼び出しで設定されます */

&stmt, /* この関数の呼び出しによって設定されるステートメントハンドル */

0, /* 文の文字列が NULL で終わることを指定します */

str, /* 文の文字列 */1, /* da_version 番号 */

out_sqlda /* 列データを格納するための XSQLDA */);

3 列ごとに、XSQLVAR 構造体を設定します。XSQLVAR 構造体の設定には次のステップが

含まれます。

コンパイル時に型がわかっている列の場合は次のようにします。

a 列のデータ型を指定する（前述の手順で、isc_dsql_prepare() によって設定されてい

ない場合）。

b XSQLVAR の sqldata フィールドを、対応するローカル変数を示すように設定する。

実行時に型がわかっていない列の場合は次のようにします。

a SQL_VARYING から SQL_TEXT のように項目のデータ型を強制変換する（オプショ

ン）。

b XSQLVAR の sqldata フィールドが示すデータに対し、ローカルな格納スペースを動

的に割り当てる。

どちらの場合にも共通の手順は次のとおりです。

a sqldata に抽出するデータのバイト数を指定する。

b パラメータの NULL 値インジケータを用意する。

BLOB（および配列）列のデータ抽出は他のタイプの列とは異なるため、XSQLVAR の各フィールドも異なる方法で設定しなければなりません。BLOB や配列以外の列の場合

は、isc_dsql_prepare() を使用して、XSQLVAR の sqltype フィールドを対応する項目の

型に設定します。セレクトリストの行データを取り出して抽出するデータは、その列に



割り当てられた sqldata スペースに保持されます。BLOB 列の場合は、SQL_BLOB（NULL インジケータを使用する場合は、SQL_BLOB + 1）という型に設定しなければ

なりません。行データの取り出しでは、BLOB データ自体ではなく、内部 BLOB 識別

子（BLOB ID）が sqldata のスペースに保持されるため、BLOB ID と同じサイズのエ

リアを示すように sqldata を設定しなければなりません。BLOB ID がわかっている場合

に実際の BLOB データを取り出す方法については、7-6 ページの「BLOB からデータ

を読み取る」を参照してください。

次のコード例は、コンパイル時に型がわかっている BLOB 列と BLOB 以外の列を割り

当てる方法を示したものです。実行時にしかわからないデータ型を扱う例は、第 6 章「動的 SQL の操作」にあります。

#define PROJLEN 20

#define TYPELEN 12

ISC_QUAD blob_id;

char proj_name[PROJLEN + 1];

char prod_type[TYPELEN + 1];

short flag0, flag1, flag2;

out_sqlda->sqlvar[0].sqldata = proj_name;

out_sqlda->sqlvar[0].sqltype = SQL_TEXT + 1;

out_sqlda->sqlvar[0].sqllen = PROJLEN;

out_sqlda->sqlvar[0].sqlind = &flag0;

out_sqlda->sqlvar[1].sqldata = (char *) &blob_id;

out_sqlda->sqlvar[1].sqltype = SQL_Blob + 1;

out_sqlda->sqlvar[1].sqllen = sizeof(ISC_QUAD);


out_sqlda->sqlvar[2].sqldata = prod_type;


out_sqlda->sqlvar[2].sqllen = TYPELEN;


文の実行クエリーステートメントの文字列が作成できたら、文を実行できます。

isc_dsql_execute(

status_vector,

&trans, /* isc_start_transaction() の呼び出しによって前もって設定されます */

&stmt, /* 上の isc_dsql_allocate_statement() によって割り当てられます */

1, /* da_version 番号 */

NULL /* stmt に入力値がないため NULL */);

上の文は、文の実行によって返される行で構成する選択リストを作成します。

7-8 A P I ガイド


選択した行の取り出しループ構造により、セレクトリストの行を 1 行ずつ読み取り、対応する列データを出力

XSQLDA に取り出し、その行を処理してから、次の行を取り出します。isc_dsql_fetch() を実行するたびに、out_sqlda の XSQLVAR 構造体に列データが取り出されます。BLOB 列の

場合は、実際の BLOB データではなく、BLOB ID が取り出されます。

ISC_STATUS fetch_stat;

long SQLCODE;

. . .

while ((fetch_stat =

isc_dsql_fetch(status_vector, &stmt, 1, out_sqlda))

== 0)

{

proj_name[PROJLEN] = '¥0';

prod_type[TYPELEN] = '¥0';

printf("¥nPROJECT: %–20s TYPE: %–15s¥n¥n",

proj_name, prod_type);

/* Blob データの読み取りと処理（次のセクションを参照） */}


{

/* 取得する行が残っていない場合、isc_dsql_fetch は

100 を返します */SQLCODE = isc_sqlcode(status_vector);


return(1);

}

BLOB データの読み取りと処理BLOB データの読み取りと処理を行うには次のようにします。

1 BLOB ハンドルを宣言して初期化します。

isc_blob_handle blob_handle; /* Blob ハンドルを宣言します */

blob_handle = NULL; /* ハンドルを使用する前に NULL に設定します */

2 読み取った BLOB セグメントを保持するバッファを作成します。バッファのサイズは、

BLOB から読み取るセグメントの大サイズを予想して設定する必要があります。

char blob_segment[80];

3 読み取ったセグメントの実際の長さを保持する符号なし 16 ビット変数を宣言します。

unsigned short actual_seg_len;

4 取り出した blob_id を使って BLOB を開きます。

isc_open_blob2(

status_vector,

&db_handle,

&trans,



&blob_handle,/* Blob を参照するためにこの関数によって設定されます */

&blob_id,/* out_sqlda by isc_dsql_fetch() によって out_sqlda に入れられる Blob ID */

0, /* BPB の長さ = 0。フィルタは使用されません */

NULL /* NULL BPB。フィルタが使用されないため */);

5 isc_get_segment() を繰り返し呼び出すことにより、すべての BLOB データを読み取り、

各 BLOB セグメントの内容と長さを抽出します。読み取ったセグメントを処理します。

次の例での処理は、読み取った各 BLOB を出力することになります。

blob_stat = isc_get_segment(

status_vector,

&blob_handle, /* isc_open_blob2() によって設定されます */

&actual_seg_len, /* 読み取ったセグメントの長さ */

sizeof(blob_segment), /* セグメントバッファの長さ */

blob_segment /* セグメントバッファ */);

while (blob_stat == 0 || status_vector[1] == isc_segment)

{

/* セグメントが正しく読み取られた場合、isc_get_segment は 0 を返します */

/* バッファ（blob_segment）が小さすぎてセグメントの */

/* 一部しか読み取られない場合、status_vector[1] は */

/* isc_segment に設定されます。この場合は、後続の isc_get_segment() */

/* の呼び出しによって、バッファの残りが読み取られます */printf("%*.*s", actual_seg_len, actual_seg_len, blob_segment);

blob_stat = isc_get_segment(status_vector, &blob_handle,

&actual_seg_len, sizeof(blob_segment), blob_segment);

printf("¥n");

};

printf("¥n");

6 BLOB を閉じます。

isc_close_blob(status_vector, &blob_handle);

BLOB にデータを書き込む

次の操作を行うには、BLOB を新たに作成し、そこにデータを書き込む必要があります。

• テーブルに挿入する行に、BLOB データを組み込む。

• 行の BLOB 列が参照するデータの置換

• 行の BLOB 列が参照するデータの更新

行の BLOB 列の入力には、実際の BLOB データが含まれているわけではありません。そ

のデータを参照する BLOB ID が保持されており、データは他の場所に格納されいます。

BLOB 列を設定または修正する場合は、BLOB 列に格納されいる BLOB ID を設定または

再設定する必要があります。BLOB ID を保持している BLOB 列を修正し、別の BLOB を参照するか、NULL を保持できるようにすると、以前に格納されていた BLOB ID の参照

先となる BLOB は、次のガベージコレクションで削除されます。



この操作は、すべて次の手順で行います。

1 適切な DSQL ステートメントを作成します。新規行をテーブルに挿入する場合は

INSERT ステートメント、行を修正する場合は UPDATE ステートメントを作成します。

各文には、実行時に文のパラメータ値を入力するための入力 XSQLDA 構造体が必要に

なります。新規 BLOB の BLOB ID も渡される値の 1 つです。

2 新規 BLOB を作成して、データを書き込みます。

3 UPDATE ステートメントか INSERT ステートメントを実行し、新規 BLOB の BLOB IDをテーブルの BLOB 列と関連付けます。

BLOB データを直接更新することはできません。BLOB データを修正するには次の操作が

必要です。

4 新規 BLOB を作成する。

5 編集や修正を行うためのバッファに既存の BLOB データを読み取る。

6 修正後のデータを新規 BLOB に書き込む。

7 既存 BLOB の BLOB ID を新規 BLOB の BLOB ID と置き換えるように BLOB 列を

変更する UPDATE ステートメントを作成して実行する。

以下の節では、BLOB データの挿入、置換、更新に必要な手順を説明します。

UPDATE ステートメントまたは INSERT ステートメントの作成UPDATE ステートメントまたは INSERT ステートメントの作成は、次の手順で行います。

1 UPDATE ステートメントまたは INSERT ステートメントの文字列をユーザーに入力させ

るか、関連する BLOB データを含む行の挿入または更新を行う文字列を作成します。次

の文は、PROJECT テーブルの行にある PROJ_DESC という BLOB 列を更新します。

PROJ_ID フィールドには、実行時に指定する値が保持されます。

char *upd_str =

"UPDATE PROJECT SET PROJ_DESC = ? WHERE PROJ_ID = ?";

次の INSERT ステートメントは、値を含む新規行を 4 つの列に挿入します。

char *in_str = "INSERT INTO PROJECT (PROJ_NAME, PROJ_DESC, PRODUCT,

PROJ_ID) VALUES (?, ?, ?, ?)";

これ以降のステップでは UPDATE ステートメントだけを取り上げて説明しますが、

INSERT ステートメントでも同様です。

2 UPDATE ステートメントの実行時にパラメータ値を入力するための、入力 XSQLDA を保持する変数を宣言します。次の宣言は、in_sqlda という XSQLDA を作成します。

XSQLDA *in_sqlda;

3 XSQLDA_LENGTH マクロを使って入力 XSQLDA のメモリを割り当てます。XSQLDAには、UPDATE ステートメントに渡すパラメータごとに、XSQLVAR 副構造体を 1 つず

つ設定しなければなりません。次の文は、2 つの XSQLVAR 副構造体を持つ入力 XSQLDA（in_sqlda）の格納スペースを割り当てます。







in_sqlda->sqln = 2;

5 XSQLDA に、渡すパラメータごとに XSQLVAR 構造体を 1 つずつ設定します。XSQLVAR構造体の設定には次のステップを使います。

a 項目のデータ型を指定します。

b コンパイル時に型がわかっているパラメータの場合は、XSQLVAR の sqldata フィー

ルドを、渡すデータを保持するローカル変数を示すように設定します。

c 実行時に型がわかっていないパラメータの場合は、XSQLVAR の sqldata フィールド

が示すデータに対し、ローカル格納スペースを割り当てます。

d データのバイト数を指定します。

BLOB（および配列）列のデータ格納は、他のタイプの列とは異なるため、XSQLVAR の各

項目も異なる方法で設定しなければなりません。BLOB や配列以外の列の場合は、sqldataが示すスペースから、入力パラメータのデータが与えられます。BLOB 列の場合は、

SQL_BLOB（NULL インジケータを使用する場合は、SQL_BLOB + 1）にタイプを設定

しなければなりません。sqldata スペースには、BLOB データ自体ではなく、内部 BLOB識別子（BLOB ID）に対応する格納スペースを設定しなければなりません。BLOB の作

成、sqldata スペースへの BLOB ID の格納、および BLOB の列への関連付けについては、

7-12 ページの「新規 BLOB の作成とデータの格納」を参照してください。

次のコード例は、コンパイル時に型がわかっている 1 つのテキスト列と 1 つの BLOB 列を

割り当てる方法を示したものです。実行時にしかわからないデータ型を扱う例は、第 6 章「動的 SQL の操作」にあります。

#define PROJLEN 5

char proj_id[PROJLEN + 1];

ISC_QUAD blob_id;

in_sqlda->sqlvar[0].sqldata = (char *) &blob_id;

in_sqlda->sqlvar[0].sqltype = SQL_Blob + 1;

in_sqlda->sqlvar[0].sqllen = sizeof(ISC_QUAD);

in_sqlda->sqlvar[1].sqldata = proj_id;

in_sqlda->sqlvar[1].sqltype = SQL_TEXT;

in_sqlda->sqlvar[1].sqllen = 5;

proj_id 変数には、実行時に値を代入する必要があります。コンパイル時に値がわかってい

る場合は不要です。blob_id 変数は、以下に説明するように、新たに作成した BLOB を参

照するように設定する必要があります。

新規 BLOB の作成とデータの格納書き込むデータを保持する新規 BLOB を作成するには次のようにします。

1 BLOB ハンドルを宣言して初期化します。

isc_blob_handle blob_handle; /* Blob ハンドルを宣言します */

blob_handle = NULL;/* ハンドルを使用する前に NULL に設定します */



2 BLOB_ID を宣言して初期化します。

ISC_QUAD blob_id; /* Blob ID を宣言する */

blob_id = NULL; /* ハンドルを使用する前に NULL に設定します */

3 isc_create_blob2() を呼び出して新規 BLOB を作成します。

isc_create_blob2(

status_vector,

&db_handle,

&trans,

&blob_handle, /* 新しい Blob を参照するためにこの関数によって設定 */

&blob_id,/* この関数によって設定される Blob ID */

0, /* Blob パラメータバッファの長さ = 0。フィルタは使用されません */

NULL /* NULL Blob パラメータバッファ。フィルタが使用されないため */);

この関数は、新規 BLOB を作成します。次に、書き込みアクセス用に開いて、新規

BLOB を示すように blob_handle を設定します。

isc_create_blob2() は、BLOB ID を BLOB に割り当て、新規 BLOB ID を示すように

blob_id を設定します。blob_id は、更新する BLOB 列を指定する、UPDATE ステートメ

ントの入力パラメータの sqldata フィールドが示す変数です。UPDATE ステートメント

を実行すると、新規 BLOB を使って BLOB 列が更新されます。

4 isc_put_segment() を繰り返して呼び出すことにより、BLOB にデータを書き込みます。

次の例は、データ行を読み取り、blob_handle が参照する BLOB に各データを連結しま

す。get_line() は、書き込みを行うデータの次の行を読み取ります。

char *line;

unsigned short len;

. . .

line = get_line();

while (line)

{

len = strlen(line);

isc_put_segment(

status_vector,

&blob_handle,/* isc_create_blob2() によって前もって設定されます */

len, /* 書き込むデータを含むバッファの長さ */

line /* Blob に書き込むデータを含むバッファ */);


{

isc_print_status(status_vector);

return(1);

};

line = get_line();

};

5 BLOB を閉じます。


B L O B に関する情報の要求


新規 BLOB を BLOB 列と関連付けるUPDATE ステートメントを実行して、文が選択した行の BLOB 列に新規 BLOB を関連付

けます。

isc_dsql_execute_immediate(

status_vector,

&db_handle,

&trans,

0, /* 実行する文字列が NULL で終わることを示します */

upd_str, /* 実行する UPDATE ステートメント文字列 */


in_sqlda /* UPDATE ステートメントにパラメータを提供する XSQLDA */);

BLOB の削除

BLOB を削除する方法は、次の 4 とおりあります。

• BLOB を含む行を削除する。DSQL を使い、DELETE ステートメントを実行することがで

きます。

• 他の BLOB と置き換える。BLOB ID を含む BLOB 列を修正し、別の BLOB を参照する

ようにすると、以前に格納されていた BLOB ID の参照先となる BLOB は、次のガベージ

コレクションで削除されます。

• BLOB を参照する列を NULL に再設定する。たとえば、次のような文を実行する DSQL を使用します。

UPDATE PROJECT SET PROJ_DESC = NULL WHERE PROJ_ID = 'VBASE'

以前に格納されていた BLOB ID の参照先となる BLOB は、次のガベージコレクション

で削除されます。

• 作成した BLOB を、テーブルの行の特定列と関連付ける前に廃棄する。isc_cancel_blob()関数を使用します。

isc_cancel_blob(status_vector, &blob_handle);

BLOB に関する情報の要求

アプリケーションで BLOB を開いた後は、その BLOB に関する情報を要求できます。

BLOB セグメントの総数、長セグメントのバイト単位の長さなど、BLOB 情報を問い合

わせるには、isc_blob_info() を使用します。

isc_blob_info() は、エラーステータスベクターを指すポインタと BLOB ハンドルの他に、

アプリケーションが割り当てる 2 つのバッファを必要とします。すなわち、アプリケーショ

ンに必要な情報を指定する項目リストバッファ、および要求された情報を InterBase が戻



すのに使用する結果バッファです。項目リストバッファは、isc_blob_info() を呼び出す前

の情報を使ってアプリケーションが登録します。isc_blob_info() には、項目リストバッファ

のポインタ、およびバイト単位で表した項目リストバッファのサイズが渡されます。

結果バッファは、InterBase が返す情報を保持するのに十分なサイズで作成しなければな

りません。isc_blob_info() には、結果バッファのポインタ、およびバイト単位で表した結

果バッファのサイズも渡されます。InterBase が戻す情報が多いために、結果バッファに

保持しきれない場合は、ibase.h で定義されている isc_info_truncated の値を、結果バッファ

の終バイトに保持します。

項目リストバッファ

項目リストバッファは、要求された情報項目ごとに、連続バイトの値を 1 つずつ保持する

文字型の配列です。各バイトが項目のタイプを表し、要求された情報の種類を指定します。

ibase.h には、すべての項目タイプに対応するコンパイル時の定数が定義されています。

#define isc_info_blob_num_segments 4

#define isc_info_blob_max_segment 5

#define isc_info_blob_total_length 6

#define isc_info_blob_type 7

結果バッファ

結果バッファは InterBase が返す情報クラスタを格納するバイトベクターです。要求され

た項目ごとに、連続したクラスタが 1 つずつ返されます。各クラスタの構成要素は次のと

おりです。

1 1 バイトの項目タイプ：項目リストバッファが指定するいずれかの項目タイプに一致し

ます。

2 2 バイトの数値：クラスタの残りの部分に続く、クラスタの構成バイト数を指定します。

3 可変数バイトに格納される値：項目のタイプに応じて解釈されます。

結果バッファの内容を解釈し、必要に応じて各クラスタの暗号を解読する作業は、呼び出

しプログラム側で行う必要があります。

結果バッファに返されるクラスタはアラインメントされていません。数値はすべて汎用形式

で表され、下位バイトが先頭、上位バイトが後になります。符号付き数値は、後の

バイトに符号が付きます。使用システムに固有のデータ型に数値を変換する必要がある場合

は、解釈を行う前に変換してください。変換には、API 呼び出しの isc_portable_integer() を使用することができます。



BLOB バッファ項目

次の表に、要求できる情報項目と返される値をまとめます。

ステータスメッセージ

InterBase は、要求に対する情報の他に、次のステータスメッセージを結果バッファに戻

します。ステータスメッセージの長さは符号なしの 1 バイトです。

isc_blob_info() の呼び出し例

次のコードは、開いた BLOB のセグメント数と大セグメントのサイズを要求し、結果

バッファの内容をチェックします。

char blob_items[] = {

isc_info_blob_max_segment, isc_info_blob_num_segments};


short length;

SLONG max_size = 0L, num_segments = 0L;

ISC_STATUS statu?s_vector[20];

isc_open_blob2(

status_vector,

&db_handle,/* isc_attach_database() によって設定されるデータベースハンドル */

&tr_handle, /* isc_start_transaction() によって設定されるトランザクションハンドル */

&blob_handle, /* Blob を参照するためにこの関数によって設定されます */

表 7.2 BLOB 情報の要求項目と戻り値

要求 / 戻り項目戻り値

isc_info_blob_num_segments セグメントの総数

isc_info_blob_max_segment 長セグメントの長さ

isc_info_blob_total_length BLOB の合計サイズ（バイト数）

isc_info_blob_type BLOB のタイプ（0：セグメント形式、1：ストリーム形式）

表 7.3 ステータスメッセージの戻り項目

項目説明



isc_info_error 要求された情報は利用できない。ステータスベクターのエラーコードとメッセージを確認すること



&blob_id, /* 開く Blob の Blob ID */

0, /* BPB の長さ = 0。フィルタは使用されません */

NULL /* NULL BPB。フィルタが使用されないため */);


{


return(1);

}

isc_blob_info(

status_vector,

&blob_handle, /* 上の isc_open_blob2() 呼び出しによって設定されます */

sizeof(blob_items),/* 項目リストバッファの長さ */

blob_items, /* 項目リストバッファ */

sizeof(res_buffer),/* 結果バッファの長さ */

res_buffer /* 結果バッファ */);


{



return(1);

};

/* 結果バッファに返された値を抽出します */for (p = res_buffer; *p != isc_info_end ;)

{

item = *p++

length = (short)isc_portable_integer(p, 2);

p += 2;

switch (item)

{

case isc_info_blob_max_segment:

max_size = isc_portable_integer(p, length);

break;

case isc_info_blob_num_segments:

num_segments = isc_portable_integer(p, length);

break;

case isc_info_truncated:

/* ハンドルエラー */break;

default:

break;

}

p += length;


B L O B データのフィルタリング

};

BLOB データのフィルタリング

BLOB フィルタは、BLOB データを他のサブタイプに変換するルーチンです。

InterBase には、サブタイプ 0（未構造化データ）をサブタイプ 1（TEXT）に変換したり、

サブタイプ 1 をサブタイプ 0 に変換する特殊な BLOB フィルタが内蔵されています。

これらの標準フィルタに加えて、特殊なデータ変換を行う独自の外部フィルタを作成する

こともできます。たとえば、イメージフォーマットを変換するフィルタを作成し、解像度

が異なるモニタに同一のイメージを表示することができます。また、バイナリ BLOB から

単純なテキストへの変換、または逆の変換を行うことにより、システム間のファイル移動

が簡単になります。

フィルタを定義する際は、-32,768 ～ -1 のサブタイプ識別子を割り当てることができます。

以降のトピックでは、BLOB フィルタの作成方法、およびフィルタリングが必要なアプリ

ケーションの作成方法について説明します。BLOB フィルタの作成方法の詳細については、

『埋め込み SQL ガイド』を参照してください。

独自のフィルタを使う

サブタイプ 0 とサブタイプ 1 間の変換を行う標準の InterBase フィルタとは異なり、外部

BLOB フィルタは、ルーチンのライブラリの一部として作成され、アプリケーションにリ

ンクされます。

BLOB フィルタは、C、Pascal、または C 言語から呼び出せる言語で作成することができ

ます。BLOB フィルタを独自に使用するには次のようにします。

1 作成するフィルタの種類を決める。

2 ホスト言語でフィルタを作成する。

3 共有フィルタライブラリを作成する。

4 フィルタライブラリが利用できるようにする。

5 データベースに対し、フィルタを定義する。

6 フィルタリングを必要とするアプリケーションを作成する。

2、5、6 の各ステップについて、以降の節で詳しく説明します。

データベースに対する外部 BLOB フィルタの宣言

データベースに対して外部 BLOB フィルタを宣言する場合、DECLARE FILTER ステートメ

ントを使います。たとえば、次の文は SAMPLE という外部 BLOB フィルタの宣言例です。

DECLARE FILTER SAMPLE

INPUT TYPE –1 OUTPUT_TYPE –2

ENTRY POINT 'FilterFunction'



MODULE_NAME 'filter.dll';

上の例では、フィルタの入力サブタイプは -1、出力サブタイプは -2 と定義されています。

サブタイプ -1 が小文字のテキストを指定し、サブタイプ -2 が大文字のテキストを指定す

る場合は、BLOB データを小文字テキストから大文字テキストに変換することが SAMPLEフィルタの目的になります。

ENTRY_POINT パラメータと MODULE_NAME パラメータは、フィルタの起動時に

InterBase が呼び出す外部ルーチンを指定します。MODULE_NAME パラメータは、フィル

タの実行可能コードを保持するダイナミックリンクライブラリ filter.dll を指定します。

ENTRY_POINT パラメータは、DLL へのエントリポイントを指定します。この例では単純

なファイル名を使用していますが、アプリケーションのユーザーがファイルをロードする

には、完全なパス名を指定する方がよいでしょう。

外部 BLOB フィルタの作成

フィルタを独自に作成する場合は、変換するデータ型を十分に理解しておかなければなり

ません。InterBase は、BLOB データのデータ型を厳密にチェックしないため、自分で確

認しなければなりません。

フィルタ関数の定義フィルタを作成する際は、プログラムの宣言部にフィルタ関数と呼ばれるエントリポイン

トを組み入れる必要があります。フィルタを使用する BLOB について、アプリケーション

が BLOB のアクセス動作を実行すると、InterBase がフィルタ関数を呼び出します。

InterBase とフィルタとの交信は、フィルタ関数を通して行われます。フィルタ関数自身

も、実行可能コードを含む他の関数を呼び出すことができます。

フィルタ関数の名前とフィルタ実行可能コードの名前は、DECLARE FILTER ステートメン

トの ENTRY_POINT パラメータと MODULE_NAME パラメータを使って宣言します。

フィルタ関数は、次の呼び出しシーケンスに従って宣言を行います。

filter_function_name(short action, isc_blob_ctl control);

action パラメータは、8 つの動作マクロ定義の 1 つです。control パラメータは、InterBaseの ibase.h ヘッダーファイルで定義されている BLOB 制御構造体 isc_blob_ctl のインスタ

ンスです。これらのパラメータについては後で説明します。

次のスケルトンフィルタコードは、jpeg_filter というフィルタ関数を宣言します。

#include <ibase.h>

#define SUCCESS 0

#define FAILURE 1

ISC_STATUS jpeg_filter(short action, isc_blob_ctl control)

{

ISC_STATUS status = SUCCESS;

switch (action)

{

case isc_blob_filter_open:. . .

break;



case isc_blob_filter_get_segment:

. . .

break;

case isc_blob_filter_create:

. . .

break;

case isc_blob_filter_put_segment:

. . .

break;

case isc_blob_filter_close:

. . .

break;

case isc_blob_filter_alloc:

. . .

break;

case isc_blob_filter_free:

. . .

break;

case isc_blob_filter_seek:

. . .

break;

default:

. . .

break;

}

return status;

}

action パラメータからは、8 つの動作から 1 つが選択され、jpeg_filter フィルタ関数に渡さ

れます。control パラメータからは、BLOB 制御構造体 isc_blob_ctl のインスタンスが渡さ

れます。

上記のコードで、省略記号（...）は、case ステートメントに指定された動作やイベントに

基づいて動作を実行するコードを表します。動作のほとんどはアプリケーションによって

呼び出される API 関数に対応するものです。各動作に対応するコードのタイプについて

は、『埋め込み SQL ガイド』を参照してください。

BLOB 制御構造体の定義BLOB 制御構造体（isc_blob_ctl）は、InterBase とフィルタ間で機能し、この構造体を介

して BLOB データが変換されます。

BLOB 制御構造体 isc_blob_ctl は、ibase.h で次のように typedef 定義されています。

typedef struct isc_blob_ctl {

ISC_STATUS (*ctl_source)();

/* 内部 InterBase Blob アクセスルーチン */struct isc_blob_ctl *ctl_source_handle;



/* 内部 InterBase Blob アクセスルーチンに渡す isc_blob_ctl のインスタンス */

short ctl_to_sub_type;/* ターゲットのサブタイプ */

short ctl_from_sub_type;/* ソースのサブタイプ */

unsigned short ctl_buffer_length; /* バッファの長さ */

unsigned short ctl_segment_length; /* 現在のセグメントの長さ */unsigned short ctl_bpb_length; /* Blob パラメータバッファの長さ */

char *ctl_bpb;/* Blob パラメータバッファへのポインタ */

unsigned char *ctl_buffer; /* セグメントバッファへのポインタ */

ISC_LONG ctl_max_segment; /* Blob の長セグメントの長さ */

ISC_LONG ctl_number_segments; /* セグメントの総数 */

ISC_LONG ctl_total_length; /* Blob の全体の長さ */

ISC_STATUS *ctl_status;/* ステータスベクターへのポインタ */

long ctl_data[8];/* アプリケーション固有のデータ */} *ISC_Blob_CTL;

isc_blob_ctl の使用目的は実行する動作によって異なります。

たとえば、isc_put_segment() という API 関数をアプリケーションが呼び出した場合は、

isc_blob_filter_put_segment の動作がフィルタ関数に渡されます。フィルタ関数に渡され

る制御構造体の、ctl_buffer フィールド項目が示すバッファには、書き込むセグメントデー

タが保持されています。これは、isc_put_segment() の呼び出しでアプリケーションが指定

します。このバッファは、フィルタ関数に渡される情報を保持するため、IN フィールドと

呼ばれます。case ステートメントの isc_blob_filter_put_segment には、フィルタリングの

実行と、データベースに書き込むデータの受渡しに関する指示を指定しなければなりませ

ん。これには、*ctl_source 内部 InterBase BLOB アクセスルーチンを使用します。

ctl_source の詳細については、『埋め込み SQL ガイド』を参照してください。

一方、API 関数 isc_get_segment() をアプリケーションで呼び出した場合は、フィルタ関

数に渡される、制御構造体の ctl_buffer が示すバッファは空になります。このような状況

では、InterBase は isc_blob_get_segment の動作をフィルタ関数に渡します。フィルタ関

数 isc_blob_get_segment の動作処理では、アプリケーションに返すデータベースのセグメ

ントデータを ctl_buffer に入れる指示を指定する必要があります。これには、*ctl_source内部 InterBase BLOB アクセスルーチンを呼び出します。このバッファは、フィルタ関数

の出力に使用されるため、OUT フィールドと呼ばれます。

次の表は、BLOB 制御構造体（isc_blob_ctl）のフィールドおよびその内容をまとめたもの

です。また、フィールドがフィルタ関数の入力に使われるか（IN フィールド）、フィルタ

関数からの出力（OUT フィールド）に使われるかについても示します。



表 7.4 isc_blob_ctl のフィールドの説明

フィールド名説明

(*ctl_source)() InterBase の内部 BLOB アクセスルーチンへのポインタ（IN）

*ctl_source_handle InterBase の内部 BLOB アクセスルーチンに渡す、isc_blob_ctl インスタンスへのポインタ（IN）

ctl_to_sub_type 変換先のサブタイプを示す情報。フィルタが複数の種類の変換を行う多目的フィルタの場合、変換先となるサブタイプの特定に使用される。多目的フィルタは、次の ctl_from_sub_type と併せて終的に特定する（IN）

ctl_from_sub_type 変換元のサブタイプを示す情報フィールド。フィルタが複数の種類の変換を行う多目的フィルタの場合、変換元のサブタイプの特定に使用される。多目的フィルタは、上の ctl_to_sub_type と併せて終的に特定する（IN）

ctl_buffer_length isc_blob_filter_put_segment の場合は、ctl_buffer に格納されたセグメントデータの長さを格納（IN）

isc_blob_filter_get_segment の場合は、ctl_buffer によって示されるバッファのサイズを格納（IN）

ctl_segment_length 現在のセグメントの長さ。isc_blob_filter_put_segment の場合、このフィールドは使われない。

isc_blob_filter_get_segment の場合は、OUT フィールドで、取り出されたセグメントの長さを格納（取り出されたセグメントが一部のときは、ctl_buffer_length で示されるバッファの長さは実際のセグメントの長さより短くなる）

ctl_bpb_length BLOB パラメータバッファの長さ

*ctl_bpb BLOB パラメータバッファを指すポインタ

*ctl_buffer セグメントバッファを指すポインタ。isc_blob_filter_put_segment の場合は、IN フィールドで、セグメントデータを格納

isc_blob_filter_get_segment の場合は、OUT フィールドで、フィルタ関数によりアプリケーションに返されるセグメントデータを格納

ctl_max_segment BLOB のセグメント長の大値。初期値は 0。このフィールドはフィルタ関数が設定する。情報フィールド

ctl_number_segments BLOB セグメントの総数。初期値は 0。このフィールドはフィルタ関数が設定する。情報フィールド

ctl_total_length BLOB 全体の長さ。初期値は 0。フィルタ関数が設定する。情報フィールド

*ctl_status InterBase ステータスベクターを指すポインタ（OUT）

ctl_data [8] 8 つの要素からなるユーザー定義が可能な配列。このフィールドは、isc_blob_filter_open ハンドラで作成されたメモリポインタやファイルハンドルなどのリソースポインタを格納します。次にフィルタ関数を呼び出したときは、そのリソースポインタが利用できるようになる。（IN/OUT）



フィルタ関数の動作のプログラミングアプリケーションで、BLOB に対して API BLOB 関数を呼び出してフィルタリングが行

われる場合、InterBase は action パラメータを介してフィルタ関数に対応する動作メッ

セージを渡します。この動作は、全部で 8 種類あります。ibase.h には、次の 8 種類の動作

がマクロ定義されています。

次の表は、8 種類の動作を列挙し、フィルタ関数が呼び出されるときの対応する動作を指定

しています。動作のほとんどは、アプリケーションが API BLOB 関数を呼び出したときに

発生するイベントの結果です。

BLOB フィルタの作成方法の説明はここまでです。フィルタの詳細、フィルタ関数の動作

をプログラムする方法、およびフィルタの応用例については、『埋め込み SQL ガイド』を


#define isc_blob_filter_open 0

#define isc_blob_filter_get_segmen 1

#define isc_blob_filter_close 2

#define isc_blob_filter_create 3

#define isc_blob_filter_put_segment 4

#define isc_blob_filter_alloc 5

#define isc_blob_filter_free 6

#define isc_blob_filter_seek 7

表 7.5 動作定数

動作フィルタが起動される動作

isc_blob_filter_open アプリケーションで isc_open_blob2() を呼び出したとき

isc_blob_filter_get_segment アプリケーションで isc_get_segment() を呼び出したとき

isc_blob_filter_close アプリケーションで isc_close_blob() を呼び出したとき

isc_blob_filter_create アプリケーションで isc_create_blob2() を呼び出したとき

isc_blob_filter_put_segment アプリケーションで isc_put_segment() を呼び出したとき

isc_blob_filter_alloc InterBase によりフィルタリングが終了した場合。この動作は、アプリケーションの処理とは無関係

isc_blob_filter_free InterBase によるフィルタリングが終了した場合。この動作は、アプリケーションの処理とは無関係

isc_blob_filter_seek 内部でのフィルタ使用のため予約。この動作は、外部 BLOBフィルタには使われません。



フィルタリングを必要とするアプリケーションの作成

BLOB の読み取りや書き込みを行う際に、BLOB データのフィルタリングが必要な場合は、

アプリケーション内で次の手順に従って作業してください。

1 ソースとターゲットのサブタイプを指定する BLOB パラメータバッファ（BPB）を作成

します。TEXT サブタイプの場合は、必要に応じてキャラクタセットを設定します。

2 読み取りアクセスを行う BLOB を開く場合は isc_open_blob2()、書き込みアクセスを行

う BLOB を開く場合は isc_create_blob2() を呼び出します。この呼び出しでは、使用す

るフィルタの種類を InterBase が判定するための情報を保持した、BPB が渡されます。

BLOB パラメータバッファBLOB パラメータバッファ（BPB）は、BLOB の読み取りや書き込みを行う際に、BLOBデータのフィルタリングが必要な場合に使用します。

BPB は、アプリケーション内で宣言され、ソースとターゲットのサブタイプを含む文字型

の配列変数です。BPB に関連した BLOB の読み取りや書き込みを行うと、BPB に指定さ

れたソースとターゲットのサブタイプに基づき、対応するフィルタが自動的に起動します。

ソースとターゲットのサブタイプがどちらも 1（TEXT）で、BPB が指定するソースとター

ゲットのキャラクタセットが異なる場合は、BPB に関連した BLOB の読み取りや書き込み

を行うと、ソースのキャラクタセットがターゲットのキャラクタセットに自動変換されま

す。

BLOB パラメータバッファを作成する方法は、次の 2 とおりあります。

1 API 呼び出しにより、ソースとターゲットのデスクリプタを間接的に作成し、デスクリ

プタの情報から BPB を作成します。

2 適切な値を使って BPB 配列を登録し、直接作成します。

API 呼び出しを使って BPB を作成する場合は、BPB のフォーマットを知らなくてもかま

いません。BPB を直接作成する場合は、フォーマットを知っておく必要があります。

次の項では、上記の 2 つの方法について説明します。BPB のフォーマットは、BPB を直接

作成する手順の項に記載します。

API 呼び出による BLOB パラメータバッファの作成BPB を間接的に作成するには、API 呼び出しを使ってソースとターゲットの BLOB デス

クリプタを作成します。さらに、isc_blob_gen_bpb2() を呼び出して、デスクリプタの情報

から BPB を作成します。作成手順は次のとおりです。

1 次のように、ソースとターゲットに対応する 2 つの BLOB デスクリプタを宣言します。

#include <ibase.h>

ISC_BLOB_DESC_V2 from_desc, to_desc;

2 isc_blob_default_desc2()、isc_blob_lookup_desc2()、isc_blob_set_desc2() のいずれかの

関数を呼び出し、BLOB デスクリプタに情報を格納するか、デスクリプタの各項目を直

接設定します。次の例は、TOURISM というテーブルの GUIDEBOOK という BLOB 列に

対応する、現行のサブタイプとキャラクタセットの情報を検索し、from_desc というソー



スデスクリプタに格納します。さらに、ターゲットデスクリプタ to_desc をデフォルト

のサブタイプ（TEXT）とキャラクタセットに設定し、ソースデータが単純なテキストに

変換されるようにします。

isc_blob_lookup_desc2 (

status_vector,

&db_handle; /* isc_attach_database() の呼び出しによって前もって設定されます */

&tr_handle, /* isc_start_transaction() の呼び出しによって前もって設定されます */

"TOURISM", /* テーブルの名前 */

"GUIDEBOOK", /* 列名 */

&from_desc, /* この関数呼び出しによって入力される Blob デスクリプタ */&global);


{

/* 処理エラー */isc_print_status(status_vector);

return(1);

};

isc_blob_default_desc2 (

&to_desc, /* この関数呼び出しによって入力される Blob デスクリプタ */

"", /* NULL テーブル名（この例では不要） */

""); /* NULL 列名（この例では不要） */

BLOB デスクリプタの詳細については、7-18 ページの「BLOB データのフィルタリン

グ」を参照してください。

3 BPB として使用する文字配列を宣言します。バッファに格納する予定のすべての情報が

入るだけのサイズを確保する必要があります。

char bpb[20];

4 BPB データの実際の長さを格納する符号なしの 16 ビット変数を宣言します。

unsigned short actual_bpb_length;

5 isc_blob_gen_bpb2() を呼び出し、isc_blob_gen_bpb2() に渡されたソースとターゲット

の BLOB デスクリプタに基づいて次のように BPB を登録します。

isc_blob_gen_bpb2(

status_vector,

&to_desc, /* ターゲットの Blob デスクリプタ */

&from_desc,/* ソースの Blob デスクリプタ */

sizeof(bpb), /* BPB バッファの長さ */

bpb, /* 生成される BPB が格納されるバッファ */

&actual_bpb_length /* 生成される BPB の実際の長さ */);

BLOB パラメータバッファを直接作成するBPB は直接作成することもできます。

BPB の構成要素は次のとおりです。



• パラメータバッファのバージョンを指定する 1 バイト。コンパイル時の定数 isc_bpb_version1に必ず設定される。

• 1 つ以上の連続するバイトクラスタ。各クラスタでパラメータを 1 つ記述する。


• 1 バイトのパラメータタイプ。すべてのパラメータタイプについて、コンパイル時の定数

（isc_bpb_target_type など）が定義される。

• クラスタの残りの部分に続くバイト数を指定する 1 バイト。

• パラメータのタイプに応じて解釈される、任意の数のバイト。

メモ BLOB パラメータバッファの数字は、下位バイトが先頭で、上位バイトが後に汎用

フォーマットで表さなければなりません。符号付き数字は、後のバイトに符号が付きま

す。API 関数 isc_portable_integer() を使用すると、バイト順を逆転することができます。

isc_portable_integer() の詳細については、15-123 ページの「isc_portable_integer()」を参照してください。

次の表は、パラメータのタイプと意味を記載したものです。

BPB には、先頭に isc_bpb_version1 を指定し、ソースとターゲットのサブタイプを指定す

るクラスタを組み入れなければなりません。キャラクタセットのクラスタは、オプション

です。ソースとターゲットのサブタイプがどちらも 1（TEXT）で、BPB が指定するソース

とターゲットのキャラクタセットが異なる場合は、BPB に関連付けられた BLOB の読み取

りや書き込みを行うと、ソースのキャラクタセットがターゲットのキャラクタセットに自

動的に変換されます。

次の例は、ソースのサブタイプが -4、ターゲットのサブタイプが 1（TEXT）のフィルタに

ついて、BPB を直接作成する方法を示したものです。

char bpb[] = {

isc_bpb_version1,

isc_bpb_target_type,

1, /* ターゲットのサブタイプを指定する、後に続くバイト数 */

1, /* ターゲットのサブタイプ（TEXT） */isc_bpb_source_type,

1, /* ソースのサブタイプを指定する、後に続くバイト数 */

–4, /* ソースのサブタイプ */};

実行時までソースとターゲットのサブタイプがわからない場合は、実行時に各値を適切な

BPB の位置に割り当てることができます。

表 7.6 BLOB パラメータバッファのパラメータタイプ

パラメータタイプ説明

isc_bpb_target_type ターゲットのサブタイプ

isc_bpb_source_type ソースのサブタイプ

isc_bpb_target_interp ターゲットのキャラクタセット

isc_bpb_source_interp ソースのキャラクタセット



フィルタの使用要求フィルタの使用は、読み取り / 書き込みアクセスを行う BLOB を開いたとき、または作成

したときに要求することができます。isc_open_blob2() や isc_create_blob2() の呼び出しで

は、使用するフィルタの種類を InterBase が判定するための情報を保持した、BPB が渡さ

れます。

次の例は、書き込みアクセスに使用する BLOB を作成して開く方法を示したものです。

BLOB へのデータの書き込み、および新しい BLOB を参照するテーブル行の BLOB 列の

更新の詳細については、7-10 ページの「BLOB にデータを書き込む」を参照してください。

読み取りアクセスの BLOB を開くには、開く BLOB を選択するというステップも必要に

なります。詳細については、7-6 ページの「BLOB からデータを読み取る」を参照してく

ださい。

isc_blob_handle blob_handle; /* 先頭で宣言します */

ISC_QUAD blob_id; /* 先頭で宣言します */. . .

isc_create_blob2(

status_vector,

&db_handle,

&tr_handle,

&blob_handle, /* この関数によって入力されます */

&blob_id, /* この関数によって入力されます */

actual_bpb_length, /* BPB データの長さ */

&bpb /* BLOB パラメータバッファ */)


{


return(1);

}



第章

第 8 章配列データの操作

この章では、配列データ型の内容、および API 関数を使って配列データを操作する方法に

ついて説明します。抽出や書き込みを行う配列または配列の一部を指定する配列デスクリ

プタをセットアップする方法、および配列のアクセスを制御する 2 つの API 関数の使い方

についても説明します。

以下の表は、配列を操作する API 関数をまとめたものです。配列デスクリプタの登録に使

用する関数を先に記載し、その後に配列データをアクセスする関数を記載します。

配列の概要

InterBase は、ほとんどのデータ型の配列をサポートしています。配列を使用すると、1 つの列に複数のデータを集合として格納できます。格納された配列は、1 つのまとまりとし

て、またはスライスと呼ばれる一連のデータ単位として扱うことができます。配列は、次

のような場合に使用されます。

• 個々のデータがすべて同じデータ型である場合

表 8.1 API 配列アクセス関数

関数用途

isc_array_lookup_desc2() 指定したテーブルの指定した配列型の列を構成するすべての要素について、データ型、長さ、小数点以下の桁数、次元を検索し、配列デスクリプタに格納する。

isc_array_lookup_bounds2() isc_array_lookup_desc2() 関数と同じ動作を実行し、さらに各次元の上限と下限を検索して格納する。

isc_array_set_desc2() 渡されたパラメータに基づいて配列デスクリプタを初期化する。

isc_array_get_slice2() 配列からデータを抽出します。

isc_array_put_slice2() 配列にデータを書き込む。

第 8 章配列データの操作 8-1

配列の概要

• 複数のデータをグループ化でき、各グループを 1 つの列に格納して管理および操作する場

合。つまり、グループを構成するデータを個別の列に置くと適切でない場合

• 各項目を個別に識別またはアクセスしなければならない場合

配列を構成するデータを配列要素と呼びます。配列には、InterBase でサポートされてい

るデータ型の要素を格納できます。ただし、配列の配列は要素として格納することはでき

ません。配列要素はすべて、同じデータ型でなければなりません。

InterBase は、1 ～ 16 次元の多次元配列をサポートします。多次元配列は、行優先順で格

納されます。

配列の次元には、添字と呼ばれる上限から下限までの範囲があります。配列の添え字は、配

列型の列を作成したときに定義されます。配列の作成方法については、『言語リファレンス』

を参照してください。

配列のデータベースへの格納

InterBase では、テーブルレコードの配列項目に配列データそのものを格納するのではな

く、配列 ID を格納します。配列 ID は、配列データを参照する一意の数値です。配列デー

タはデータベースとは異なる場所に格納されます。

配列デスクリプタ

配列デスクリプタは、ISC_ARRAY_DESC_V2 構造体に抽出したり、書き込む配列または配

列の一部を記述するのに使用します。ISC_ARRAY_DESC_V2 は、InterBase のヘッダーファ

イルに次のように定義されている構造体です。

typedef struct {

short array_desc_version;

unsigned char array_desc_dtype;

char array_desc_scale;

unsigned short array_desc_length;

char array_desc_field_name [METADATALENGTH];

char array_desc_relation_name [METADATALENGTH];

short array_desc_dimensions;

short array_desc_flags;

ISC_ARRAY_BOUND array_desc_bounds [16];

} ISC_ARRAY_DESC_V2;

ISC_ARRAY_BOUND は次のように定義されています。

typedef struct {

short array_bound_lower; /* 下限 */

short array_bound_upper; /* 上限 */} ISC_ARRAY_BOUND;

8-2 A P I ガイド

配列の概要

メモ ISC_ARRAY_DESC_V2 構造体は、長さ METADATALENGTH の長いメタデータ名をサポート

します。古い ISC_ARRAY_DESC 構造体は、32 バイト以下のメタデータ名しかサポートし

ません。

array_desc_version フィールドは、isc_array_lookup_bounds2()、isc_array_lookup_desc2()、および isc_array_set_desc2() によって、ARRAY_DESC_CURRENT_VERSION に設定されま

す。

配列デスクリプタの array_desc_dtype フィールドは、以下の表に記載されているデータ型

で表さなければなりません。

Table 8.2 配列デスクリプタのフィールド

フィールド説明

array_desc_version ARRAY_DESC_CURRENT_VERSION に設定する

array_desc_dtype データ型（以下を参照）

array_desc_scale 数値データ型の小数点以下の桁数

array_desc_length 配列の各要素の長さ（バイト数）

array_desc_field_name NULL 終端の列名

array_desc_relation_name NULL 終端の関係名

array_desc_dimensions 配列の次元数

array_desc_flags 行優先順か、列優先順のどちらで配列をアクセスするかを指定

• 0: 行優先順

• 1: 列優先順

array_desc_bounds 各次元の上限と下限

Table 8.3 配列デスクリプタのデータ型

array_desc_dtype の値対応する InterBase のデータ型

blr_boolean_dtype BOOLEAN

blr_blob_id ISC_QUAD 構造体

blr_cstring NULL で終わる文字列

blr_cstring2 NULL で終わる文字列

blr_double DOUBLE PRECISION

blr_float FLOAT

blr_long INTEGER

blr_quad ISC_QUAD 構造体

blr_short SMALLINT


配列の概要

配列デスクリプタには、16 個の ISC_ARRAY_BOUND 構造体が含まれており、利用可能な

次元ごとに 1 つずつ割り当てられています。n 個の次元を持つ配列には、先頭の n 個の

ISC_ARRAY_BOUND 構造体に対応する上限と下限が設定されています。実際の配列次元の

数は、配列デスクリプタの array_desc_dimensions フィールドに指定されます。

配列からデータを抽出する際は、抽出する配列スライス（配列全体、または連続した配列

要素で構成する配列のサブセット）を定義する配列デスクリプタを入力します。同様に、配

列にデータを書き込む際は、書き込み先の配列スライスを定義する配列デスクリプタを入

力します。

配列デスクリプタの値の設定

配列デスクリプタに値を設定する方法は、次の 4 とおりあります。

• isc_array_lookup_desc() を呼び出す。これは、データベースのシステムメタデータテーブ

ルを検索し、指定したテーブルの指定した配列型の列に対応するデータ型、長さ、小数点

以下の桁数、次元を配列デスクリプタに格納します。デスクリプタには、テーブル名と列

名も格納され、array_desc_flags フィールドを初期化し、行優先順で配列がアクセスされる

ことを指示します。たとえば次のように呼び出します。

isc_array_lookup_desc2(

status_vector,

&db_handle, /* isc_attach_database() によって設定 */

&tr_handle, /* isc_start_transaction() によって設定 */

"PROJ_DEPT_BUDGET", /* テーブルの名前 */

"QUART_HEAD_CNT", /* 配列の列名 */

&desc /* 入力されるデスクリプタ */);

• isc_array_lookup_bounds2() を呼び出す。これは、isc_array_lookup_desc2() と同様の機能

を実行しますが、isc_array_lookup_bounds2() は各次元の上限と下限も配列デスクリプタに

格納します。

• isc_array_set_desc2() を呼び出す。これは、データベースのメタデータにアクセスせずに、

パラメータを使ってデスクリプタを初期化します。たとえば、次のように呼び出します。

blr_sql_date DATE

blr_sql_time TIME

blr_text CHAR

blr_text2 CHAR

blr_timestamp TIMESTAMP

blr_varying VARCHAR

blr_varying2 VARCHAR

Table 8.3 配列デスクリプタのデータ型 ( 続き )

array_desc_dtype の値対応する InterBase のデータ型

8-4 A P I ガイド

配列データのアクセス

short dtype = SQL_TEXT;

short len = 8;

short numdims = 2;

isc_array_set_desc2(

status_vector,

"TABLE1", /* テーブルの名前 */

"CHAR_ARRAY", /* 配列の列名 */

&dtype, /* 要素のデータ型 */

&len, /* 各要素の長さ */

&numdims, /* 配列の次元数 */

&desc /* 入力されるデスクリプタ */);

• デスクリプタの各フィールドを直接設定する。次の例は、デスクリプタ desc のarray_desc_dimensions フィールドを設定しています。

desc.array_desc_dimensions = 2;

isc_array_lookup_bounds2()、isc_array_lookup_desc2()、および isc_array_set_desc2() の構文

の詳細については、第 15 章「API 関数リファレンス」を参照してください。


InterBase は、以下の配列データ操作をサポートします。

• 配列または配列スライスからの読み取り

• 配列への書き込み

• テーブルに挿入する行に、新規配列を組み入れる。

• 行の配列型の列が参照する配列を新規配列と置き換える。

• 配列または配列スライスのデータを修正し、行の配列型の列が参照する配列を更新す

る。

• 配列の削除

配列データの選択、挿入、更新に必要な SELECT ステートメント、INSERT ステートメント、

UPDATE ステートメントを実行するには、動的 SQL（DSQL）API 関数と XSQLDA デー

タ構造体が必要になります。以下の節では、例文を実行するための DSQL プログラミング

方法についても説明します。

DSQL と XSQLDA の詳細については、第 6 章「動的 SQL の操作」を参照してください。

メモ配列に対して次の処理は実行できません。

• DSQL 内で動的に配列次元を参照する。

• 配列要素を個別に NULL に設定する。

• 配列に対し、MIN() や MAX() などの集計関数を使用する。

• SELECT ステートメントの GROUP BY 句で、配列を参照する。

• 配列スライスからの選択を行うビューを作成する。



配列からデータを読み取る

配列または配列スライスからデータを読み取るには、以下の手順を使います。

1 目的の行の配列型の列（および他の列）を選択する SELECT ステートメントを作成す

る。

2 取り出す行の列データを保持する出力 XSQLDA 構造体を準備する。

3 実行する SELECT ステートメントを作成する。

4 文を実行する。

5 抽出する配列または配列スライスを記述する情報に基づき、配列デスクリプタを登録す

る。

6 選択した行を 1 行ずつ取り出す。

7 各行から配列データを読み取って処理する。

SELECT ステートメントの作成文の文字列をユーザーに入力させるか、関連する配列データを含む行を選択する SQL クエ

リーの文字列を作成します。クエリーには、配列の列名、および参照するデータが含まれ

ている他の列の列名を指定します。次の文は、PROJECT_DEPT_BUDGET テーブルの各行か

ら、QUART_HEAD_CNT という名前の配列型の列、および DEPT_NO という列を選択する

SQL クエリーステートメントの文字列を作成します。

char *sel_str =

"SELECT DEPT_NO, QUART_HEAD_CNT FROM PROJ_DEPT_BUDGET ¥

WHERE year = 1994 AND PROJ_ID = 'VBASE'";

出力 XSQLDA の作成通常のクエリーは、選択リストと呼ばれるデータ行を返します。取り出される行ごとに、列

データを格納する出力 XSQLDA を作成しておかなければなりません。配列型の列の列デー

タは、実際のデータをアクセスするのに必要な内部配列識別子（配列 ID）になります。

XSQLDA を作成する方法は次のとおりです。

1 XSQLDA を保持する変数を宣言します。次の宣言は、XSQLDA 構造体 out_sqlda を作

成します。

XSQLDA *out_sqlda;

2 XSQLDA_LENGTH マクロを使用して、XSQLDA のメモリを割り当てます。XSQLDA には、取り出す列ごとに、XSQLVAR 副構造体を 1 つずつ設定しなければなりません。次

の文は、2 つの XSQLVAR 副構造体を持つ出力 XSQLDA（out_sqlda）の格納スペースを

割り当てます。



ルドに XSQLVAR 副構造体の割り当て数を設定します。



8-6 A P I ガイド


実行する SELECT ステートメントの準備選択した各行の列データを保持する XSQLDA を作成したら、実行するクエリーステート

メントの文字列を作成します。手順は次のとおりです。



stmt = NULL; /* ハンドルを割り当てる前に NULL に設定します */isc_dsql_allocate_statement(status_vector, &db_handle, &stmt);

2 isc_dsql_prepare() を使用して、SQL ステートメント文字列が実行できるように作成し

ます。SQL ステートメント文字列（sel_str）に構文エラーがないかをチェックし、効率

的に実行できるフォーマットに解析してそのフォーマットを参照するようにステートメ

ントハンドル（stmt）を設定します。ステートメントハンドルは、その後の

isc_dsql_execute() 呼び出しに使用されます。

次の例のように、出力 XSQLDA を指すポインタが isc_dsql_prepare() に渡される場合

は、XSQLDA のほとんどの項目とすべての XSQLVAR 副構造体に、文の対応する列の

データ型、長さ、名前などの情報が格納されます。

isc_dsql_prepare() の呼び出し例を次に示します。

isc_dsql_prepare(

status_vector,

&trans, /* 先の isc_start_transaction() 呼び出しで設定されます */

&stmt, /* この関数の呼び出しによって設定されるステートメントハンドル */

0, /* 文の文字列が NULL で終わることを指定します */

sel_str,/* 文の文字列 */1, /* da_version 番号 */

out_sqlda /* 列データを格納するための XSQLDA */);

3 列ごとに、XSQLVAR 構造体を設定します。XSQLVAR 構造体の設定には次のステップが

含まれます。

コンパイル時に型がわかっている列の場合は次のようにします。

• 列のデータ型を指定する（前述の手順で、isc_dsql_prepare() によって設定されてい

ない場合）。

• XSQLVAR の sqldata フィールドを、対応するローカル変数を示すように設定する。

実行時に型がわかっていない列の場合は次のようにします。

• SQL_VARYING から SQL_TEXT のように項目のデータ型を強制変換する（オプショ

ン）。

• XSQLVAR の sqldata フィールドが示すデータに対し、ローカルな格納スペースを動

的に割り当てる。

どちらの場合にも共通の手順は次のとおりです。

パラメータの NULL 値インジケータを用意する。



• 配列型の（および BLOB）列のデータ抽出は他の型の列とは異なるため、XSQLVARの各フィールドも異なる方法で設定しなければなりません。配列以外の列（または

BLOB 以外の列）の場合は、isc_dsql_prepare() を使って XSQLVAR の sqltype フィー

ルドを対応する項目型に設定します。選択リストの行データを取り出して抽出された

データは、その列に割り当てられた sqldata のスペースに格納されます。配列型の列

の場合は、SQL_ARRAY（配列型の列に NULL が使用できる場合は SQL_ARRAY + 1）という型に設定しなければなりません。行データの取り出しでは、配列データそのも

のではなく、内部配列識別子（配列 ID）が sqldata のスペースに格納されるため、配

列 ID と同じサイズのエリアを示すように sqldata を設定しなければなりません。配

列 ID がわかっている実際の配列または配列スライスのデータを取り出す方法は、

8-10 ページの「配列データの読み取りと処理」を参照してください。

• 次のコードは、コンパイル時に型がわかっている配列型の列と配列型以外の列を割り

当てる方法を示しています。DSQL と XSQLDA、および実行時にしか型がわからな

い列の操作については、第 6 章「動的 SQL の操作」を参照してください。

ISC_QUAD array_id = 0L;

char dept_no[6];

short flag0, flag1;

out_sqlda->sqlvar[0].sqldata = (char *) dept_no;



out_sqlda->sqlvar[1].sqldata = (char *) &array_id;

out_sqlda->sqlvar[1].sqltype = SQL_ARRAY + 1;


文の実行クエリーステートメントの文字列が作成できたら、文を実行できます。

isc_dsql_execute(

status_vector,

&trans, /* isc_start_transaction() の呼び出しによって前もって設定されます */

&stmt, /* 上の isc_dsql_prepare() によって設定されます */


NULL /* stmt に入力値がないため NULL */);

この文は、文の実行によって返される行で構成する選択リストを作成します。

配列デスクリプタの値の設定読み取る配列または配列スライスを記述する配列デスクリプタの作成は、次の手順で行い

ます。

1 配列デスクリプタを作成します。


8-8 A P I ガイド


2 データの読み取り元となる配列型の列に関する情報をデスクリプタに入力します。これ

には、isc_array_lookup_bounds2()、isc_array_lookup_desc2()、isc_array_set_desc2() のいずれか 1 つを呼び出すか、デスクリプタの各項目を直接設定します。配列デスクリプ

タの内容、および各関数の使い方については、8-2 ページの「配列デスクリプタ」を参


デスクリプタの範囲は、読み取るスライスの範囲に設定しなければなりません。

一部のスライスではなく、配列データ全体を抽出する場合は、初期に宣言した配列型の

列全体の範囲に設定します。たとえば、isc_array_lookup_bounds2() の呼び出しによっ

て次のようにデスクリプタを入力します。


isc_array_lookup_bounds2(

status_vector,

&db_handle,

&trans,


"QUART_HEAD_CNT", /* 配列の列名 */&desc);

たとえば、配列型の列 QUART_HEAD_CNT が 4 つの要素で構成する 1 次元の配列で、

作成時に添字の下限が 1、上限が 4 と宣言されていたとします。ここで

isc_array_lookup_bounds2() を呼び出すと、範囲を示す配列デスクリプタの項目には次

の情報が格納されます。

desc.array_desc_bounds[0].array_bound_lower == 1

desc.array_desc_bounds[0].array_bound_upper == 4

配列の 1 スライスだけを読み取る場合は、それに合わせて上限と下限を変更します。た

とえば、配列の先頭 2 要素だけを読み取る場合は、次のように上限を 2 に変更します。

desc.array_desc_bounds[0].array_bound_upper = 2

選択した行の取り出しループ構造により、選択リストを 1 行ずつ読み取り、対応する列データを出力 XSQLDA に取り出し、その行を処理してから次の行を取り出します。isc_dsql_fetch() を実行するたび

に、次の行の列データが取り出され、out_sqlda の対応する XSQLVAR 構造体に保持されま

す。配列型の列の場合は、実際の配列データではなく、配列 ID が取り出されます。

ISC_STATUS fetch_stat;

long SQLCODE;

. . .

while ((fetch_stat = j

isc_dsql_fetch(status_vector, &stmt, 1, out_sqlda)) == 0)

{

/* 配列データを読み取って処理します */}


{

/* isc_dsql_fetch は、取得する行が残っていない場合に 100 を返します */



SQLCODE = isc_sqlcode(status_vector);


return(1);

}

配列データの読み取りと処理配列または配列スライスデータの読み取りと処理を行うには、以下のようにします。

1 読み取った配列データを保持するバッファを作成します。バッファのサイズは、配列ス

ライスから読み取る全要素（配列全体）を格納できるだけの十分なサイズにする必要が

あります。次の文は、32 ビットの要素を 4 つ保持できる配列バッファを宣言します。

long hcnt[4];

2 配列バッファのサイズを指定する 16 ビットの変数を宣言します。

short len;

3 変数をバッファの長さに設定します。

len = sizeof(hcnt);

4 isc_array_get_slice2() を呼び出して、配列または配列スライスのデータをバッファに読

み取り、読み取ったデータを処理します。以下の例では、配列バッファ hcnt に配列デー

タを読み取り、データを出力するという「処理」を行います。

isc_array_get_slice2(

status_vector,

&db_handle,/* isc_attach_database() によって設定されます */

&trans, /* isc_start_transaction() によって設定されます */&array_id, /* out_sqlda by isc_dsql_fetch() によって out_sqlda に入れられる

配列 ID*/

&desc, /* 読み取るスライスを指定する配列デスクリプタ */

(void *) hcnt,/* データの読み取り先のバッファ */

(long *) &len/* バッファの長さ */);


{


return(1);

}

/* dept_no を NULL で終わる文字列にします */dept_no[out_sqlda->sqlvar[0].sqllen] = '¥0';

printf("Department #: %s¥n¥n", dept_no);

printf("¥tCurrent head counts: %ld %ld %ld %ld¥n",

hcnt[0], hcnt[1], hcnt[2], hcnt[3]);

配列にデータを書き込む

配列または配列スライスにデータを書き込むには isc_array_put_slice2() を呼び出します。

これは以下の操作に使用します。



• テーブルに挿入する行に、新規配列を組み入れる。

• 行の配列型の列に格納されている内容を新規配列と置き換える。

• 配列または配列スライスのデータを修正し、行の配列型の列が参照する配列を更新する。

行の配列型の列の入力には、実際の配列データが格納されているわけではありません。そ

のデータを参照する配列 ID が格納されているだけで、データは他の場所に格納されていま

す。配列型の列を設定または修正する場合は、配列型の列に格納されている配列 ID を設定

または変更する必要があります。配列 ID を保持している配列型の列を修正し、別の配列を

参照するか、NULL を含むようにすると、以前に格納されていた配列 ID の参照先となる配

列は、次のガベージコレクションで削除されます。

配列データの挿入、置換、更新は、以下の手順で行います。

1 書き込み先となる配列または配列スライスを記述する情報を使って配列デスクリプタを

作成します。

2 書き込むデータを入れた配列バッファを作成します。

3 適切な DSQL ステートメントを作成します。新規行をテーブルに挿入する場合は

INSERT ステートメント、既存の行を修正する場合は UPDATE ステートメントを作成し

ます。

4 isc_array_put_slice2() を呼び出して、新規配列を作成（または既存配列をコピー）し、

配列または配列スライスに配列バッファのデータを書き込みます。

5 UPDATE ステートメントまたは INSERT ステートメントを実行し、修正または挿入する

テーブルの行の配列型の列と新規配列とを関連付けます。これにより、新規配列の配列

ID が含まれるように配列型の列が設定されます。

配列デスクリプタの準備書き込み先の配列または配列スライスを記述する配列デスクリプタの作成は次の手順で行

います。

1 配列デスクリプタを作成します。


2 データの書き込み先となる配列型の列に関する情報をデスクリプタに入力します。これ

には、isc_array_lookup_bounds2()、isc_array_lookup_desc2()、isc_array_set_desc2() のいずれかの関数を呼び出すか、デスクリプタに直接入力します。配列デスクリプタの内

容、および各関数の使い方については、8-2 ページの「配列デスクリプタ」を参照して

ください。

デスクリプタの範囲は、書き込み先スライスの範囲に設定しなければなりません。

一部のスライスではなく、配列データ全体に書き込む場合は、初期に宣言した配列型の列

全体の範囲に設定します。たとえば、isc_array_lookup_bounds2() の呼び出しによって次

のようにデスクリプタを入力します。


status_vector,

db_handle,

&trans,




"QUART_HEAD_CNT", /* 配列の列名 */&desc);

たとえば、配列型の列 QUART_HEAD_CNT が 4 つの要素で構成する 1 次元の配列で、作成時

に添字の下限が 1、上限が 4 と宣言されていたとします。ここで isc_array_lookup_bounds2()を呼び出すと、範囲を示す配列デスクリプタのフィールドには次の情報が保持されます。

desc.array_desc_bounds[0].array_bound_lower == 1desc.array_desc_bounds[0].array_bound_upper == 4

配列の 1 スライスだけを書き込んだり修正する場合は、それに合わせて上限と下限を変更

します。たとえば、配列の先頭の 2 要素だけに書き込む場合は、上限を 2 に変更します。

desc.array_desc_bounds[0].array_bound_upper == 2

配列バッファの準備配列に書き込むデータを保持する、配列バッファを作成します。バッファのサイズは、書

き込む配列スライスの全要素（配列全体）を格納できるだけの十分なサイズにする必要が

あります。次の文は、32 ビットの要素を 4 つ格納する配列バッファを宣言します。

long hcnt[4];

1 配列バッファの長さを指定する変数を作成します。

short len;

len = sizeof(hcnt);

2 書き込むデータを配列バッファに入力します。

新規配列を作成する場合は、たとえば次のようにデータをバッファに入力します。

hcnt[0] = 4;

hcnt[1] = 5;

hcnt[2] = 6;

hcnt[3] = 6;

新規配列を作成せずに、既存の配列データを修正する場合は、8-6 ページの「配列から

データを読み取る」に記載されているすべてのステップを実行し、既存の配列データを

配列バッファに読み取ってから、バッファのデータを修正します。

UPDATE ステートメントまたは INSERT ステートメントの作成UPDATE ステートメントまたは INSERT ステートメントの作成は、次の手順で行います。

1 UPDATE ステートメントまたは INSERT ステートメントの文字列をユーザーに入力させ

るか、関連する配列型の列を含む新規行の挿入または既存行の更新を行う文字列を作成

します。次の文は、PROJ_DEPT_BUDGET テーブルの指定した行にある配列型の列 QUART_HEAD_CNT を更新します。部門番号と四半期ごとの人数は、実行時に入力さ

れるものとします。

char *upd_str =

"UPDATE PROJ_DEPT_BUDGET SET QUART_HEAD_CNT = ? WHERE ¥

YEAR = 1994 AND PROJ_ID = "MKTPR" AND DEPT_NO = ?";

次の INSERT ステートメントは、PROJ_DEPT_BUDGET テーブルに新規行を挿入します。

列データは実行時に入力されます。



char *upd_str =

"INSERT INTO PROJ_DEPT_BUDGET (YEAR, PROJ_ID, DEPT_NO, ¥

QUART_HEAD_CNT) VALUES (?, ?, ?, ?)";

これ以降のステップでは UPDATE ステートメントだけを取り上げて説明しますが、

INSERT ステートメントでも同様です。

2 UPDATE ステートメントの実行時にパラメータ値を入力するための、入力 XSQLDA を保持する変数を宣言します。次の宣言は、in_sqlda という XSQLDA を作成します。

XSQLDA *in_sqlda;

3 XSQLDA_LENGTH マクロを使って入力 XSQLDA のメモリを割り当てます。XSQLDAには、UPDATE ステートメントに渡すパラメータごとに、XSQLVAR 副構造体を 1 つず

つ設定しなければなりません。次の文は、2 つの XSQLVAR 副構造体を持つ入力 XSQLDA（in_sqlda）の格納スペースを割り当てます。





in_sqlda->sqln = 2;

5 XSQLDA に、渡すパラメータごとに XSQLVAR 構造体を 1 つずつ設定します。XSQLVAR構造体の設定には次のステップを使います。

a 項目のデータ型を指定します。

b コンパイル時に型がわかっているパラメータの場合は、XSQLVAR の sqldata フィールドを、渡すデータを含むローカル変数を示すように設定します。

c 実行時に型がわかっていないパラメータの場合は、XSQLVAR の sqldata フィールドが示すデータに対し、ローカルな格納スペースを割り当てます。

d データのバイト数を指定します。

配列型（および BLOB）の列のデータ格納は他の型の列とは異なるため、XSQLVAR の各フィールドも相応に設定しなければなりません。配列（および BLOB）以外の列の場

合は、sqldata が示すスペースから入力パラメータのデータが与えられます。配列型の

列の場合は、SQL_ARRAY（NULL が指定できる配列型の列の場合は、SQL_ARRAY + 1）というタイプに設定しなければなりません。sqldata のスペースには、配列データその

ものではなく、内部配列識別子に対応する格納スペースを設定しなければなりません。

配列の作成方法と修正方法、配列 ID を Sqldata のスペースに格納する方法、実際の配

列データを列と関連付ける方法については、以降の節を参照してください。

次のコードは、コンパイル時に列の型がわかっている 1 つの TEXT 列と 1 つの配列型の

列を割り当てる方法を示したものです。

#define NUMLEN 4

char dept_no[NUMLEN + 1];

ISC_QUAD array_id;

in_sqlda->sqlvar[0].sqldata = &array_id;

in_sqlda->sqlvar[0].sqltype = SQL_ARRAY + 1;



in_sqlda->sqlvar[0].sqllen = sizeof(ISC_QUAD);

in_sqlda->sqlvar[1].sqldata = dept_no;

in_sqlda->sqlvar[1].sqltype = SQL_TEXT;

in_sqlda->sqlvar[1].sqllen = 4;

dept_no 変数には、実行時に値を代入する必要があります。コンパイル時に値がわかっ

ている場合は不要です。array_id 変数は、以降の節で説明するように、新たに作成した

配列を参照するように設定する必要があります。

実行時にしか型がわからないデータの操作については、第 6 章「動的 SQL の操作」を参


isc_array_put_slice2() の呼び出し配列または配列スライスにデータを格納する手順は次のとおりです。

1 配列 ID を宣言します。

ISC_QUAD array_id; /* 配列 ID を宣言します */

2 配列 ID を初期化します。新規行に挿入する新規配列を作成する場合や、既存の配列を

置き換える場合は、配列 ID を NULL に初期化します。

array_id = NULL;/* ハンドルを使用する前に NULL に設定します */

既存の配列を修正する場合は、「配列からデータを読み取る」に記載されているステップ

に従って、既存の配列 ID を array_id に読み取ります。

3 isc_array_put_slice2() を呼び出します。この呼び出しでは、array_id 変数に保持されて

いる配列 ID（既存配列の場合は配列 ID、新規配列の場合は NULL）を渡します。また、

書き込むデータのバッファ、およびデータが所属する配列スライスを指定するデスクリ

プタも渡します。

既存配列の配列 ID を使って isc_array_put_slice2() を呼び出した場合は、指定した配列

と同じ特性を持つ新規配列が作成され、既存配列データが新規配列にコピーされます。

次に、配列デスクリプタで指定した範囲に基づき、配列バッファのデータが新規配列（ま

たは配列のスライス）に書き込まれ、新規配列の配列 ID が同じ array_id 変数に返され

ます。

NULL の配列 ID で isc_array_put_slice2() を呼び出した場合は、isc_array_put_slice2()に渡される配列デスクリプタに指定した列名とテーブル名の配列型の列と同じ特性を持

つ空の新規配列が作成されます。配列バッファのデータが新規配列（または配列のスラ

イス）に書き込まれ、新規配列の配列 ID が array_id 変数に返されます。

どちらの場合でも、新しい配列が作成され、その配列 ID が array_id 変数に返されます。

UPDATE または INSERT ステートメントを実行して特定の行の特定の列に関連付けられ

るまで、配列は一時的配列です。

isc_array_put_slice2() は、一回の呼び出しによって全データを一括して配列に書き込む

か、複数の呼び出しによって配列スライスにデータを個別に格納することができます。

後者の場合、2 回め以降の呼び出しでは、一時配列の配列 ID を受け渡す必要がありま

す。一時的な配列の配列 ID で isc_array_put_slice2() を呼び出すと、一時配列の指定し

たスライスに指定したデータがコピーされますが、新規配列は作成されません。

次のコードは、isc_array_put_slice2() を呼び出す例です。



isc_array_put_slice2(

status_vector,

&db_handle,

&trans,

&array_id,/* 配列 ID（NULL、または既存の配列の配列 ID） */

&desc, /* データを書き込む場所を示す配列デスクリプタ */

hcnt, /* 配列に書き込むデータを保持する配列バッファ */

&len /* 配列バッファの長さ */);

上の呼び出しは、新規配列を作成し、hcnt のデータを新規配列（または配列のスライ

ス）にコピーし、配列 ID を新規配列に割り当て、その配列 ID を示すように array_idを設定します。

重要 array_id は、更新する配列型の列を指定する、UPDATE ステートメントまたは INSERT ステートメントの入力パラメータの Sqldata フィールドが示す変数です。UPDATE ステートメ

ントまたは INSERT ステートメントを実行すると、この新規配列の配列 ID により、新規配

列を参照するように配列型の列が設定または更新されます。

新規配列を配列型の列と関連付けるUPDATE ステートメントを実行し、文が選択した行の配列型の列に新規配列を関連付けま

す。


status_vector,

&db_handle,

&trans,

0, /* 実行する文字列が NULL で終わることを示します */

upd_str, /* 実行する UPDATE ステートメント文字列 */


in_sqlda /* UPDATE ステートメントにパラメータを提供する XSQLDA */);

上の文は、UPDATE ステートメントで指定した行の配列型の列を、新規配列の配列 ID を含

めるように設定します。配列 ID は、配列型の列に対応する in_sqlda パラメータが示す

array_id 変数から与えられます。

UPDATE ステートメントを実行する前に、指定した行の配列型の列に異なる配列の配列 IDが含まれていた場合は、新規配列の ID を含むように列が修正され、以前に格納されていた

配列 ID の参照先となる配列は、次のガベージコレクションで削除されます。

配列の削除

配列を削除する方法は、次の 3 とおりあります。

1 配列を含む行を削除する。DSQL を使って DELETE ステートメントを実行できます。

2 上記の手順に従い、他の配列と置き換える。配列 ID を含んでいる配列型の列を修正し、

別の配列を参照するようにすると、以前に格納されていた配列 ID の参照先となる配列

は、次のガベージコレクションで削除されます。



3 配列を参照する列を NULL に再設定する。たとえば、以下のような文を実行する DSQLを使用します。LANGUAGE_REQ は、配列の列です。

"UPDATE JOB SET LANGUAGE_REQ = NULL ¥

WHERE JOB_CODE = "SA12" AND JOB_GRADE = 10"

以前に格納されていた配列 ID の参照先となる配列は、次のガベージコレクションで削

除されます。


第章

第 9 章データの変換

InterBase は、独自の内部記憶形式として TIMESTAMP、TIME、および DATE データ型を

使用しますが、そのフォーマットとホスト言語のデータ型との間で変換を行うために以下

の API 関数を提供しています。

• isc_decode_sql_date()。InterBase の内部日付形式を C の日付構造体に変換する

• isc_encode_sql_date()。C の日付構造体を InterBase の内部日付形式に変換する

• isc_decode_sql_time()。InterBase 内部時刻形式を C の time 構造体に変換する

• isc_encode_sql_time()。C の time 構造体を InterBase の内部時刻形式に変換する

• isc_decode_timestamp()。InterBase の内部タイムスタンプ形式を C の timestamp 構造体に

変換する（従来の isc_decode_date() 呼び出し）

• isc_encode_timestamp()。C の timestamp 構造体を InterBase の内部タイムスタンプ形式に

変換する（従来の isc_encode_date() 呼び出し）

これらの関数は、日付時刻データ（DATE、TIME、TIMESTAMP）のフォーマットを変換す

るだけで、日付時刻データ自体を読み取ったり、書き込んだりするわけではありません。日

付時刻データをデータベースに読み取ったり書き込んだりするには、isc_dsql で始まる

API で処理される DSQL 構文を使用します。

メモ InterBase 6 では、DATE データ型はダイアレクト 3 の日付情報だけを格納し、ダイアレク

ト 1 では、曖昧さを排除するために DATE データ型は使用できません。古いデータベース

をダイアレクト 1 に移行すると、DATE データ型であった列はすべて自動的に TIMESTAMP型に変換されます。移行後のデータをダイアレクト 3 の DATE 列に格納するには、ダイアレクト 3 で新しく DATE データ型の列を作成し、そこにデータを移動する必要があります。

InterBase では、データが失われる可能性があることから、ALTER COLUMN を使って

TIMESTAMP データ型を DATE データ型に変更することはできません。

InterBase では、データベースパラメータバッファやトランザクションパラメータバッファ

に入力する数値は、下位バイトを後とする汎用形式で表さなければなりません。符号付

き数値は、後のバイトに符号が付きます。上位バイトを後とする形式で数値を表すシ

ステムの場合は、API 関数の isc_portable_integer() を使用して、データベースパラメータ

第 9 章データの変換 9-1

I n t e r B a s e 形式から C 形式への日付と時刻の変換

バッファ（DPB）やトランザクションパラメータバッファ（TPB）に入力した数値のバイト

順を逆にしなければなりません。このようなシステムで返された数値は、

isc_portable_integer() を再度使ってバイト順を逆にする必要があります。

DSQL によるデータ読み取りと書き込みについては、第 6 章「動的 SQL の操作」を参照


InterBase 形式から C 形式への日付と時刻の変換

以下に、TIMESTAMP データ型を InterBase 形式から C 形式に変換する手順を示します。

API 呼び出しを前述の適切なものに置き換えることで、同じ手順で TIME データ型および

DATE データ型を変換することができます。InterBase 6 では、前バージョンで使用されて

いた DATE データ型は TIMESTAMP データ型に置き換えられています。

テーブルからタイムスタンプデータを選択して、C プログラムで使用できる形式に変換す

る手順は次のとおりです。

1 C の時刻構造体を表す変数を作成します。通常、C/C++ 開発システムの場合、C の時

刻構造体の型 tm は time.h で定義されています。次のコードでは、time.h をインク

ルードして、tm 型構造体の変数を宣言しています。

#include <time.h>

#include <ibase.h>

. . .

struct tm entry_time;

. . .

メモ C/C++ 以外の言語では、時刻構造体の作成方法が上記とは異なります。詳細については、

使用する言語のリファレンスマニュアルを参照してください。

2 ISC_TIMESTAMP 型の変数を宣言します。たとえば、記述は次のようになります。

ISC_TIMESTAMP entry_date;

ISC_TIMESTAMP 構造体は ibase.h で宣言されていますが、実際に使用する

ISC_TIMESTAMP 型のホスト言語変数を宣言しなければなりません。

3 テーブルから ISC_TIMESTAMP 変数にタイムスタンプを取り出します。

4 InterBase の isc_decode_timestamp() 関数を使用して、ISC_TIMESTAMP 変数を C 形式に変換します。この関数は ibase.h に宣言されています。

isc_decode_timestamp() では、ISC_TIMESTAMP 型変数（変換元）と tm 型変数（変換

先）を指定します。たとえば次のコードは、entry_date を entry_time に変換します。

isc_decode_timestamp(&entry_date, &entry_time);

9-2 A P I ガイド

C 形式から I n t e r B a s e 形式への日付と時刻の変換

C 形式から InterBase 形式への日付と時刻の変換

以下に、TIMESTAMP データ型を C 形式から InterBase 形式に変換する手順を示します。

API 呼び出しを 9-1 に示す適切なものに置き換えることで、同じ手順で TIME データ型お

よび DATE データ型を変換することができます。テーブルにタイムスタンプを挿入する場

合、ホスト言語の形式から InterBase の形式に変換してから格納する必要があります。Cプログラムでこの変換と挿入を行う手順は次のとおりです。

1 C の時刻構造体を表す変数を作成します。通常、C/C++ 開発システムの場合、C の時

刻構造体の型 tm は time.h で定義されています。次のコードでは、time.h をインク

ルードして、tm 型構造体の変数を宣言しています。

#include <time.h>;

. . .

struct tm entry_time;

. . .

C/C++ 以外の言語では、時刻構造体の作成方法が上記とは異なります。詳細について

は、使用する言語のリファレンスマニュアルを参照してください。

2 InterBase が使用する ISC_TIMESTAMP 型のホスト変数を宣言します。ホスト変数の宣

言は、たとえば次のようになります。

ISC_TIMESTAMP mytime;

ISC_TIMESTAMP 構造体は ibase.h で宣言されていますが、実際に使用する ISC_TIMESTAMP 型のホスト言語変数を宣言しなければなりません。

3 日付情報を entry_time に格納します。

4 InterBase の isc_encode_sql_date() 関数を使用して、entry_time のデータを InterBase 形式に変換し、そのデータを ISC_TIMESTAMP 型の変数（ここでは entry_date）に格納します。この関数も ibase.h で宣言されています。

isc_encode_timestamp() では、tm 型の変数（変換元）と ISC_TIMESTAMP 型の変数

（変換先）を指定します。たとえば次のコードは、entry_time を entry_date に変換しま

す。

isc_encode_timestamp(&entry_time, &entry_date);

5 データをテーブルに挿入します。

数値のバイト順の逆転 InterBase では、データベースパラメータバッファやトランザクションパラメータバッ

ファに入力する数値は、下位バイトを後とする汎用形式で表さなければなりません。符

号付き数値は、後のバイトに符号が付きます。上位バイトを後とする形式で数値を

表すシステムの場合は、API 関数 isc_portable_integer() を使用して、DPB や TPB に入力し

た数値のバイト順を逆にしなければなりません。このようなシステムで戻された数値は、

isc_portable_integer() を再度使ってバイト順を逆にする必要があります。

isc_portable_integer() の構文は次のとおりです。

ISC_LONG isc_portable_integer( char *buffer, short length);

第 9 章データの変換 9-3

数値のバイト順の逆転

buffer は、変換する整数を指す char 型のポインタです。length は、整数のサイズをバイト

単位で示します。有効な長さは、1（short）、2（int）、4（long）、および 8（INT64）です。

#include <ibase.h>

. . .

for(p = res_buffer; *p != isc_info_end;)

{

p++;

length = isc_portable_integer(p, 2);

}

9-4 A P I ガイド

第章

第 10 章エラー条件の処理

この章では、InterBase が実行時エラーの情報を格納するエラーステータスベクターを設

定する方法、およびエラーの処理や報告を行う API 関数の使い方について説明します。

以下の表は、エラーを処理する API 関数とその目的を要約したものです。

エラーステータスベクターの設定

ほとんどの API 関数は、正常に完了したかどうかを示すステータス情報を返します。返さ

れる情報は、InterBase がエラーステータスを報告する、エラーステータス配列の第 2 要素から取得できます。エラーステータスベクターは、20 個の long 整数の配列として、ア

プリケーションで次のように宣言されます。

#include <ibase.h>

. . .


ISC_STATUS は、プログラミング上の利便性とプラットフォームからの独立性のために、

ibase.h で #define によって定義されています。

表 10.1 エラー処理関数

関数用途

isc_interprete() InterBase のエラーメッセージを捕捉してバッファに入れる

isc_print_sqlerror() SQL のエラーメッセージを表示する

isc_print_status() InterBase のエラーメッセージを表示する

isc_sqlcode() SQLCODE の値を設定する

isc_sql_interprete() SQL のエラーメッセージを捕捉してバッファに入れる

第 1 0 章エラー条件の処理 10-1

ステータスベクターの情報を使う


InterBase は、API 呼び出しの間にエラーが発生した場合も発生しなかった場合も、エラー

ステータスベクターにステータス情報を格納します。この情報は、1 つ以上の InterBaseエラーコード、および特定のエラーに固有のエラーメッセージを作成するために使用でき

るエラー情報から構成されます。

アプリケーションでは、ほとんどの API 呼び出しの実行後にステータスベクターをチェッ

クして、正常に完了したかどうかを判定できます。エラー条件が報告された場合、アプリ

ケーションで以下の処理を行うことができます。

• isc_print_status() を使って InterBase エラーメッセージを表示する。

• isc_sqlcode() を使って InterBase エラーに対応する SQLCODE の値を設定し、

isc_print_sqlerror() を使って SQLCODE と SQL エラーメッセージを表示する。

• isc_interprete() を使って InterBase エラーメッセージをバッファ内に作成する。バッファ

はアプリケーションで作成しなければなりません。バッファを使うと、エラーログファイ

ルにメッセージを格納するなど、アプリケーションでメッセージに対する独自の処理を行

うことができます。この機能は、画面への直接書き込みできないウィンドウシステムで特

に役立ちます。

• isc_sql_interprete() を使って SQL エラーメッセージをバッファに取り込む。バッファはア

プリケーションで作成しなければなりません。

• ステータスベクターの InterBase エラーコードを解析して、以降の動作を行う。

ステータスベクターをチェックしてエラーの有無を判定する

ステータスベクターに情報を返す API 関数は、ISC_STATUS ポインタを返すものとして

ibase.h で宣言されています。たとえば isc_prepare_transaction() のプロトタイプは次のよ

うに宣言されています。

ISC_STATUS ISC_EXPORT isc_prepare_transaction(ISC_STATUS ISC_FAR *,isc_tr_handle ISC_FAR *);

関数の実行後にステータスベクターをチェックしてエラーの有無を判定するには、ステー

タスベクターの第 1 要素を調べます。1 に設定されている場合は、第 2 要素をチェックし、

0 かどうかを確認します。第 2 要素が 0 でない場合は、エラーが発生したことを示してい

ます。次の C コードは、ステータスベクターをチェックしてエラーの有無を判定していま

す。

#include <ibase.h>

. . .


. . .

/* ここで、ステータス情報を返す API を呼び出します */if (status_vector[0] == 1 && status_vector[1] > 0)

{

/* ここで、エラー条件を処理します */



;

}

エラーステータスが検出された場合は、エラー処理ルーチン内で API 関数を使い、エラー

メッセージの表示、エラーメッセージのバッファへの取り込み、および特定のエラーコー

ドに対応するステータスベクターの解析を行うことができます。

エラーメッセージの表示や取り込みは、エラー処理ルーチンのごく一部にすぎません。通

常、エラー処理ルーチンではトランザクションをロールバックし、場合によっては失敗し

た動作をもう一度実行します。

InterBase エラーメッセージの表示

InterBase エラーメッセージを画面に表示するには isc_print_status() を使用します。この

関数は、ステータスベクターを解析してエラーメッセージを作成し、C の printf() 関数を

使って画面にメッセージを書き込みます。isc_print_status() に必要なパラメータは、エラー

情報を保持するステータスベクターを指すポインタです。次のコードは、エラーが発生し

た場合は、isc_print_status() を呼び出し、トランザクションをロールバックします。

#include <ibase.h>

. . .



. . .

trans = 0L;

. . .

/* ここで、trans トランザクションを開始します */


{



}

重要 printf() を使って画面への書き込みが直接できないウィンドウシステムの場合は、isc_interprete()を使ってエラーメッセージをバッファに取り込んでください。

ヒント動的 SQL（DSQL）API 関数を使用するアプリケーションでは、SQL の規則に従ってエ

ラーを表示する必要があります。isc_print_status() ではなく、isc_sqlcode() および

isc_print_sqlerror() を使用してください。

InterBase エラーメッセージの取り込み

isc_interprete() を使うと、ステータスベクター内の情報からエラーメッセージを作成して

アプリケーションで定義したバッファに格納し、さらに操作することができます。バッファ

へのメッセージの取り込みは、次のような場合に利用できます。

• 画面に直接書き込むことができないウィンドウシステムでアプリケーションを実行する場

合



• メッセージの表示で、isc_print_status() の機能以外の制御を必要とする場合

• アプリケーションで、すべてのエラーメッセージをログファイルに保存する場合

• 表示するエラーメッセージの操作や書式化を行ったり、ウィンドウシステムの表示ルーチ

ンにエラーメッセージを渡す場合

isc_interprete() では、1 回の呼び出しで取り出され、書式化されるエラーメッセージは 1つです。プログラムで発生するエラーによっては、ステータスベクターに複数のエラーメッ

セージが格納されることもあります。してがって、関連するすべてのエラーメッセージを

取り出すには、isc_interprete() を繰り返し呼び出す必要があります。

バッファの場所とステータスベクターのアドレスの両方を isc_interprete() に指定すると、

ステータスベクターの情報からエラーメッセージを作成し、フォーマット済みの文字列を

バッファに格納してステータスベクターポインタをエラー情報の次クラスタの先頭に進め

ることができます。isc_interprete() には、2 つのパラメータが必要です。すなわち、フォー

マット済みメッセージの出力を保持するアプリケーションバッファのアドレス、およびス

テータスベクター配列を指すポインタです。

重要 isc_interprete() には、ステータスベクター配列を直接渡してはなりません。ステータスベ

クターのポインタは、isc_interprete() を呼び出すたびに、新しいメッセージ情報を格納す

る次の要素に進められます。isc_interprete() を呼び出す前に、ステータスベクターの先頭

アドレスにポインタを設定してください。

次のコードは、isc_interprete() を繰り返し呼び出し、バッファ内のステータスベクターか

らエラーメッセージを 1 つずつ抽出してログファイルに書き込めるようにするエラー処理

ルーチンを示します。

#include <ibase.h>

. . .



long *pvector;

char msg[512];

FILE *efile; /* このコードでは、開かれているファイルへのポインタであるとします */trans = 0L;

. . .

/* ここで、エラー処理ルーチンを開始します */

/* pvector は常に status_vector の先頭に設定されます */pvector = status_vector;

/* 初のメッセージを取得します */isc_interprete(msg, &pvector);

/* バッファからログファイルに初のメッセージを書き込みます */fprintf(efile, "%s¥n", msg);

msg[0] = '-'; /* 2 番めのメッセージの先頭にハイフンを追加します */

/* ループ内で他のメッセージを検索して処理します */

while(isc_interprete(msg + 1, &pvector)) /* まだあるか？ */

fprintf(efile, "%s¥n", msg); /* ある場合はログに書き込みます */fclose(efile); /* すべて完了したら、ログファイルを閉じます */isc_rollback(status_vector, &trans);


エラーに対する SQLCODE 値の設定

return(1);

. . .

メモこのコードは、エラーハンドラに制御が渡される前に、宣言済みのログファイルがアプリ

ケーションで開かれているものとしています。

ヒント動的 SQL（DSQL）API 関数を使用するアプリケーションでは、SQL の表記規則に従っ

てエラーをバッファに取り込む必要があります。isc_interprete() ではなく、isc_sqlcode()と isc_sql_interprete() を使用してください。


DSQL アプリケーションでは、エラーステータスを SQL 表記規則に基づいて算定する必

要があります。通常の SQL アプリケーションは、アプリケーションが宣言する SQLCODE変数を使ってエラーを報告します。InterBase エラーコードを SQLCODE 形式に変換する

には isc_sqlcode() を使用します。この関数はエラーステータスベクターをチェックし、SQLエラーコードに変換できる InterBase エラーコードを見つけて変換します。SQLCODE が設定されたら、API 関数 isc_print_sqlerror() および isc_sql_interprete() を呼び出して

SQL エラーを処理することができます。

isc_sqlcode() には、ステータスベクターを指すポインタをパラメータとして指定する必要

があります。これを実行すると、SQL エラーコードを含む、32 ビットの値が返されます。

次のコードは、この関数の使用例を示したものです。

#include <ibase.h>;

. . .

long SQLCODE; /* SQL エラーコード変数を宣言します */ISC_STATUS status_vector[20];

. . .

if (status_vector[0] == 1 && status_vector[1] > 0)

{


isc_print_sqlerror(SQLCODE, status_vector)

. . .

}

isc_sqlcode() は、正常に終了すると、ステータスベクターから解読した、初の有効な SQLエラーコードを返します。有効な SQL エラーコードが見つからない場合は -999 を返しま

す。

SQL エラーメッセージの表示

エンドユーザーに DSQL インターフェースを提供する API アプリケーションで、SQL エラーコードと対応するエラーメッセージを画面に表示するには isc_print_sqlerror() を使用

します。isc_print_sqlerror() には、SQL エラーコードとステータスベクターを指すポイン

タを含む変数 SQLCODE が渡されます。isc_print_sqlerror() は、ステータスベクターを



解読して SQL エラーメッセージを作成し、C の printf() 関数を使って SQLCODE の値と

メッセージを画面に書き込みます。次のコードは、エラーが発生した場合は、

isc_print_sqlerror() を呼び出し、トランザクションをロールバックします。

#include <ibase.h>

. . .



long SQLCODE;

. . .

trans = 0L;

. . .



{




}

重要 printf() で直接画面への書き込みができないウィンドウシステムの場合は、isc_sql_interprete()を使ってエラーメッセージをバッファに取り込んでください。

SQL エラーメッセージの取り込み

isc_sql_interprete() を使うと、特定の SQL エラーコードに基づいて SQL エラーメッセー

ジを作成し、アプリケーションで定義したバッファに格納することができます。このよう

なエラーメッセージの取り込みは、次のような場合に利用できます。

• 画面に直接書き込むことができないウィンドウシステムでアプリケーションを実行する場

合

• アプリケーションで、すべてのエラーメッセージをログファイルに保存する場合

• 表示するエラーメッセージの操作や書式化を行ったり、ウィンドウシステムの表示ルーチ

ンにエラーメッセージを渡す場合

isc_sql_interprete() ではパラメータとして、（通常は SQLCODE 変数として渡される）有

効な SQL エラーコード、メッセージを格納するバッファ、およびバッファのサイズが必要

です。次のコードは、この関数を呼び出してメッセージ文字列を作成し、ログファイルに

格納する方法を示したものです。

#include <ibase.h>

. . .



long SQLCODE;

char msg[512];

FILE *efile; /* このコードでは、開かれているファイルへのポインタであるとします */


ステータスベクターの解析

trans = 0L;

. . .


/* ここで、ステータス情報を返す API を呼び出します */. . .

/* ここで、エラー処理ルーチンを開始します */if (status_vector[0] == 1 && status_vector[1] > 0)

{


isc_sql_interprete(SQLCODE, msg, 512);

fprintf(efile, "%s¥n", msg);


return(1);

}

メモこのコードは、エラーハンドラに制御が渡される前に、宣言済みのログファイルがアプリ

ケーションで開かれているものとしています。


InterBase がステータスベクターに格納するエラー情報は、2 つまたは 3 つの long のクラスタとして格納されます。ステータスベクターの先頭クラスタは、常にエラーの主因を示

します。その後に続くクラスタには、エラーメッセージに対応する表示文字列や数値など、

エラーに関するサポート情報が格納されます。サポート情報が格納される実際のクラスタ

数は、エラーによって異なります。

多くの場合、ステータスベクターには追加のエラーも報告されます。追加のエラーがある

場合は、初のエラーとそれに関するサポート情報に続いて報告されます。追加エラーメッ

セージの先頭クラスタは、エラーの内容を識別するクラスタになります。後続のクラスタ

には、エラーに関するサポート情報が格納されます。

ステータスベクターの解析方法

InterBase エラー処理ルーチン isc_print_status() と isc_interprete() は、ステータスベク

ター内のエラーメッセージを自動的に解析するルーチンを使用するため、開発者はステー

タスベクターの構造について知る必要はありません。ただし、ステータスベクターを読み

取り、応答する独自のルーチンを作成する場合は、ステータスベクターを解釈する方法に

ついて知っていなければなりません。

ステータスベクターを解析する鍵は、ベクターの先頭クラスタから順に、各クラスタの先

頭の long 値の意味を解読することです。

クラスタの先頭の long 値の意味

各クラスタの先頭の long 値は数値のデスクリプタです。このデスクリプタを調べること

で、以下のことを判定できます。



• クラスタ内の long 値の総数

• 2 番め以降のクラスタに格納されている情報の種類

• ステータスベクターの次のクラスタの開始位置

ソースコードの先頭に ibase.h をインクルードすると、作成したステータスベクター解析

ルーチン内で、数値をハードコードするかわりに #define を使うことができます。#defineを使うと次の利点があります。

• コードの可読性が高まる。

• 数値デスクリプタのナンバリング方法が変更になっても、コードの保守が容易になる。

次の表に、数値デスクリプタとそれに対応する ibase.h の #define 文の一覧を示します。

表 10.2 ステータスベクタークラスタの先頭の long 値の解釈

値long 値の個数意味

0 — ステータスベクター内にあるエラー情報の後

1 2 2 番めの long は InterBase エラーコード

2 2 2 番めの long は InterBase エラーメッセージとして置き換え可能な文字列のアドレスを示す

3 3 2 番めの long はオペレーティングシステムが作成する可変長文字列（通常はファイル名）の長さをバイト単位で表したもの。3 番めの long は文字列のアドレス

4 2 2 番めの long は InterBase エラーメッセージの置き換え可能パラメータとして使用する数値を示す

5 2 2 番めの long はそれ以上処理せずに表示できる、エラーメッセージ文字列のアドレス

6 2 2 番めの long は VAX/VMS エラーコード

7 2 2 番めの long は UNIX エラーコード

8 2 2 番めの long は Apollo Domain エラーコード

9 2 2 番めの long は MS-DOS または OS/2 のエラーコード

10 2 2 番めの long は HP MPE/XL エラーコード

11 2 2 番めの long は HP MPE/XL IPC エラーコード

12 2 2 番めの long は NeXT/Mach エラーコード

注意： InterBase の動作するハードウェア / ソフトウェアプラットフォームが追加された場合、そのプラットフォームとオペレーティングシステムに固有のエラーコードに対応する数値デスクリプタは、このリストの末尾に追加されます。



これらの #define の使用例は、10-11 ページの「ステータスベクターの解析の例」を参照


クラスタの 2 番めの long 値の意味

クラスタの 2 番めの long 値は以下のいずれかを示します。

• InterBase エラーコード（先頭の long が 1 の場合）

• 文字列のアドレス（先頭の long が 2 か 5 の場合）

• 文字列の長さ（先頭の long が 3 の場合）

• 数値（先頭の long が 4 の場合）

• オペレーティングシステムのエラーコード（先頭の long > 5 の場合）

InterBase エラーコードInterBase エラーコードには 2 つの用途があります。1 つは、InterBase の関数が内部で使

用し、エラーメッセージを示す文字列を作成して表示することです。たとえば、InterBaseエラーコードを使用する別の関数を isc_interprete() で呼び出して、表示したりログファイ

ルに格納することができるエラーメッセージを作成するための、基本となるエラーメッ

セージを抽出します。

もう 1 つは、独自のエラー処理ルーチンを作成する際に、ステータスベクターを解析し、

特定の InterBase エラーコードを検出してそれに応答することです。

クラスタの 2 番めの long が InterBase エラーコードである場合、後続のクラスタには

InterBase エラーコードに関連した追加パラメータが保持されている場合があります。た

とえば、InterBase エラーメッセージには、エラーが発生したテーブルの名前に対応する

置き換え可能な文字列パラメータや、エラーステータスを検出したトリガーのコードに対

応する置き換え可能な数値パラメータが含まれています。

独自の解析ルーチンを作成する場合は、エラー情報を格納する上記の追加クラスタを

チェックして使用する必要があります。

表 10.3 ステータスベクターの数値デスクリプタの #define

値 #define 値 #define

0 isc_arg_end 8 isc_arg_domain

1 isc_arg_gds 9 isc_arg_dos

2 isc_arg_string 10 isc_arg_mpexl

3 isc_arg_cstring 11 isc_arg_mpexl_ipc

4 isc_arg_number 15 isc_arg_next_mach

5 isc_arg_interpreted 16 isc_arg_netware

6 isc_arg_vms 17 isc_arg_win32

7 isc_arg_unix



文字列のアドレス文字列のアドレスはエラーメッセージのテキストを指します。クラスタの先頭の long が 2（isc_arg_string）である場合、示されたアドレスには、エラーの影響を受けるデータベー

ス、テーブル、列の名前が含まれる場合があります。この場合、エラーメッセージ文字列

を作成する InterBase 関数は、InterBase エラーメッセージのパラメータをアドレスが示

す文字列に置き換えます。これ以外の場合は、データベーストリガー内にハードコードさ

れたエラーメッセージのアドレスになります。

クラスタの先頭の long が 5（isc_arg_interpreted）の場合は、抽出できるテキストメッセー

ジを指すアドレスになります。このメッセージは、InterBase によりハードコードされる

場合と、システムレベルのエラーメッセージである場合があります。

どの場合も、isc_print_status() や isc_interpreted() などの InterBase 関数がエラーメッ

セージのフォーマットを設定して表示します。

文字列長インジケータクラスタの先頭の long が 3（isc_arg_cstring）の場合は、クラスタの 3 番めの long にア

ドレスが格納されている、2 番めの long の数値によってメッセージ文字列の長さ（バイト

数）が指定されます。この文字列は、NULL 終端の標準の C 文字列に変換してから表示す

る必要があります。

数値数値の意味は、クラスタの先頭の long にある数値デスクリプタの値によって決まります。

先頭の long が 4（isc_arg_number）の場合は、メッセージを作成する InterBase 関数が、

InterBase エラーメッセージの数値パラメータを置き換えるのに使用します。たとえば、整

合性エラーが発生した場合、InterBase は、トラブルを検出したトリガーのコードを、数

値としてステータスベクターに格納します。isc_interpreted() などの InterBase 関数が、そ

のエラーのエラーメッセージ文字列を作成する際は、ステータスベクターの数値を、

InterBase 整合性エラーメッセージ文字列に挿入します。

オペレーティングシステムエラーコードクラスタの先頭の long が 5 より大きい場合、2 番めの long の数値は、特定のプラット

フォームまたはオペレーティングシステムに固有のエラーコードになります。プラット

フォームやオペレーティングシステムのエラーメッセージを抽出 / 表示するのに、

InterBase 関数は使用できません。このようなエラーの処理方法については、オペレーティ

ングシステムのマニュアルを参照してください。

クラスタの 3 番めの long の意味

クラスタの先頭の long が 3（isc_arg_cstring）の場合、クラスタの長さは long 3 つ分に

なります。3 番めの long には、NULL 終端の標準の C 文字列に変換してから表示できる

メッセージ文字列のアドレスが格納されます。この文字列は通常、ファイル名やパス名で

す。isc_interprete() などの InterBase 関数を使うと、文字列の変換が自動的に行われます。



ステータスベクターの解析の例

ステータスベクターのブルートフォース解析を行う C プログラムの例を示します。この

コードは、まず故意にエラー条件を生成します。次に、エラー処理ブロックがステータス

ベクター配列をクラスタごとに解析します。後に、クラスタの内容を解釈して出力しま

す。

#include <ibase.h>

. . .


main()

{

int done, v;/* 引数の終わり？、ベクターのインデックス */

int c, extra;/* クラスタカウント、3 つの long クラスタフラグ */static char *meaning[] = {"End of error information",

"n InterBase error code"," string address"," string length",

" numeric value"," system code"};

/* ここでは、データベースが接続され、トランザクションが開始されているものとする */

if (status_vector[0] == 1 && status_vector[1] > 0)

error_exit();

. . .

}

void error_exit(void)

{

done = v = 0;

c = 1;

while (!done)

{

extra = 0;

printf("Cluster %d:¥n", c);

printf("Status vector %d: %ld: ", v, status_vector[v]);

if (status_vector[v] != gds_arg_end)

printf("Next long is a");

switch (status_vector[v++])

{

case gds_arg_end:

printf("%s¥n", meaning[0]);

done = 1;

break;

case gds_arg_gds:


break;

case gds_arg_string:

case gds_arg_interpreted:




break;

case gds_arg_number:


break;

case gds_arg_cstring:


extra = 1;

break;

default:


break;

}

if (!done)

{

printf("Status vector %d: %ld", v, status_vector[v]);

v++;/* ベクターポインタを進めます */

c++;/* クラスタカウントを進めます */if (extra)

{

printf(": Next long is a %s¥n", meaning[2]);

printf("Status vector: %d: %ld¥n¥n", v,status_vector[v]);

v++;

}

else

printf("¥n¥n");

}

}


isc_detach_database(&db1);

return(1);

}

このプログラムの出力例を示します。

Cluster 1:

Status vector 0: 1: Next long is an InterBase error code

Status vector 1: 335544342

Cluster 2:

Status vector 2: 4: Next long is a numeric value

Status vector 3: 1

Cluster 3:

Status vector 4: 1: Next long is an InterBase error code


Cluster 4:

Status vector 6: 2: Next long is a string address




Cluster 5:

Status vector 8: 0: End of error information

この出力例は、2 つの InterBase エラーが発生したことを示しています。初のエラーコー

ドは 335544342 です。エラー出力ルーチン isc_print_status() と isc_interprete() は、

InterBase エラーコードを使用して、対応するエラーメッセージを抽出します。エラーメッ

セージにはプレースホルダが格納されています。ここでは、335544342 のエラーコードに

対応するエラーメッセージを抽出します。エラーメッセージ文字列は次のとおりです。

"action cancelled by trigger (%ld) to preserve data integrity"

このエラーメッセージは、置き換えられる数値パラメータとして %ld を使用します。

この場合、置き換えに使用する数値 1 は、第 2 クラスタの 2 番めの long に格納されてい

ます。エラー出力ルーチンにより、このパラメータがメッセージに挿入されると次のメッ

セージが表示されます。

action cancelled by trigger (1) to preserve data integrity

2 番めのエラーコードは 335544382 です。このコードに対応する基本メッセージは次のと

おりです。

"%s"

この場合、表示されるメッセージ全体が置き換え可能な文字列になります。第 4 クラスタ

の 2 番めの long には、置き換え可能な文字列のアドレス（156740）が格納されます。こ

れは、エラーの原因となったトリガーに定義されているエラーメッセージです。エラー出

力ルーチンにより、トリガーからのメッセージが挿入されると、次のメッセージが表示さ

れます。

-Department name is missing.

メモこの例では、ステータスベクターの構造と内容を示すことだけを目的としています。開発

中のプログラムにとって、このプログラムのエラー処理ルーチンは、デバッグツールとし

ての機能が限られているため、エンドユーザーに役立つ情報は得られないかもしれません。

通常、エラーの解釈、内容を説明するエラーメッセージの表示、および修正措置などは、ア

プリケーションのエラー処理ブロックで行う必要があります。

上のプログラム例では、エラー処理ルーチンが isc_print_status() を呼び出し、各コードに

関連したエラーメッセージを表示します。表示されるメッセージは以下のとおりです。

action cancelled by trigger (1) to preserve data integrity-Department name is missing.



第章

第 11 章イベントの操作

この章では、イベントの操作方法について説明します。イベントは、トリガーやストアド

プロシージャによって InterBase のイベントマネージャに渡されるメッセージです。通常

は、記録の挿入、修正、削除など、データベースでの変更を指します。また、イベントバッ

ファの設定方法、および同期 / 非同期のイベント呼び出しを行う API 関数についても説明

します。イベント操作に関連する関数を以下の表に示します。

非同期イベントについては、通知したイベントに応答する関数である非同期トラップ

（AST）を作成する方法も解説します。

InterBase のイベントメカニズム

InterBase のイベントメカニズムは、次の 4 つの部分から構成されます。

• InterBase エンジン（イベントマネージャ）：イベントキューを管理し、イベントが発生し

たときにアプリケーションに通知する。

• イベントパラメータバッファ：イベント発生の通知を受け取る場所としてアプリケーショ

ンが設定する。

表 11.1 API イベント関数

関数用途

isc_event_block() イベントパラメータバッファを割り当てる

isc_wait_for_event() 通知する同期イベントを待機する

isc_que_events() 非同期イベントを設定し、アプリケーションの処理に戻る

isc_event_counts() イベントパラメータバッファにある、イベントカウンタの値が変わったかどうかを判定する

isc_cancel_events() イベントの関連性を取り消す

第 1 1 章イベントの操作 11-1

I n t e r B a s e のイベントメカニズム

• アプリケーション：名前を指定して 1 つ以上のイベントを登録し、そのイベントの発生を

待機する（同期イベント）、または通知を処理する AST 関数にポインタを渡してアプリケー

ションが一定の時間処理を継続できるようにする（非同期イベント）。

• トリガーまたはストアドプロシージャ：名前を指定された特定のイベントが発生したこと

を通知する。通知することをポストするとも呼ぶ。

上記の要素が揃っていると、いずれかのアプリケーションでイベントを発生させるような

ストアドプロシージャ（またはトリガー）が実行された場合にそのイベントがイベントマ

ネージャに送られます。同時に、イベント発生するまで待機しているアプリケーションに

対して通知が送られ、通知を受けたアプリケーションで処理が行われます。

イベントを通知するトリガーやストアドプロシージャの作成方法については、『データ定義

ガイド』を参照してください。

イベントパラメータバッファ

イベントに関する通知をアプリケーションが受け取るには、isc_event_block() を使用して、

同一サイズのイベントパラメータバッファ（EPB）を 2 つ設定しなければなりません。1 つは、アプリケーションがイベントの関連性を登録する前に、イベントの発生回数を格納す

るバッファ event_buffer です。もう 1 つは、アプリケーションに関連のあるイベントが発

生すると同時に、イベントの発生回数を更新して入力するためのバッファ result_buffer です。API 関数 isc_event_counts() は、各バッファの項目別カウント数を比較し、イベント

の種類を判定します。

EPB の設定と使用の詳細については、11-3 ページの「isc_event_block( ) による EPBの作成」を参照してください。

同期イベントの通知

発生するイベントによって処理が異なるアプリケーションの場合は、同期イベントの通知

を使い、イベントが発生するまではアプリケーション自体の実行を中断する必要がありま

す。たとえば、特定の価格が変動したときに株式を売買する自動証券取引アプリケーショ

ンの場合は、EPB を設定して株式の関連性の登録 / 実行を行い、価格に変動があるまで実

行を中断しておきます。

アプリケーションの同期イベントを処理するには、isc_wait_for_event() 関数を使用しま

す。同期イベントの処理については、11-4 ページの「isc_wait_for_event() によるイベ

ントの待機」を参照してください。

非同期イベントの通知

特定のデータベースのイベントに応答し、イベント発生の有無にかかわらず作業を続行す

る必要があるアプリケーションの場合は、非同期トラップ（AST）関数を設定して非同期

イベントの通知を使用します。イベントの関連性を登録すると、アプリケーション自体の

実行を続行できるようになります。たとえば、証券ブローカー（仲介）アプリケーション


i s c _ e v e n t _ b l o c k ( ) による E P B の作成

では、証券データベースに絶えずアクセスし、ブローカーがいつでも株式の売買ができる

ようにしておく必要がありますが、それと同時に、特に重要な株価の変動や不安定な株価

の変動については、イベントを利用してブローカーに警告することも必要です。

アプリケーションの非同期イベントを処理するには、isc_que_events() 関数と AST 関数を

使用します。非同期イベントの処理については、11-5 ページの「isc_que_events() によ

る処理の続行」を参照してください。

トランザクションのイベント制御

イベントはトランザクションの制御下で発生するため、コミットやロールバックを行うこ

とができます。イベントを通知するトランザクションがコミットされるまでは、関連する

アプリケーションがイベントの通知を受け取ることはありません。通知後のイベントが

ロールバックされた場合も通知されません。

コミットする前は、同一のイベントを 1 つのトランザクションで何度も通知できますが、

イベントの通知においては、その回数にかかわらず、イベントの発生回数は 1 回と見なさ

れます。

isc_event_block( ) による EPB の作成アプリケーションでイベントの関連性を登録するには、2 つのイベントパラメータバッファ

（EPB）を設定して登録しなければなりません。1 つは関連する各イベントの発生カウント

の初期値を保持し、もう 1 つは変更された発生カウントを保持します。このバッファは、

複数の API イベント関数にパラメータとして渡されます。

C では、次のように、EPB は char ポインタとして宣言されます。


バッファを宣言したら、isc_event_block() を呼び出してバッファ領域を割り当て、初期値

を設定します。

isc_event_block() には、関連性を登録するイベントの数、およびイベント名を表す文字列

をパラメータとして指定する必要があります。isc_event_block() の 1 回の呼び出しで、

大 15 個のイベント名文字列を渡すことができます。イベント名は、ストアドプロシージャ

またはトリガーから通知されるイベント名と一致しなければなりません。

isc_event_block() は、指定したイベントを処理するのに十分な領域を各 EPB に割り当て、

バッファのサイズをバイト単位で返します。

isc_event_block() の構文は次のとおりです。

ISC_LONG isc_event_block(char **event_buffer,char **result_buffer,unsigned short id_count,. . . );

たとえば次のコードは、3 つのイベントについて EPB を設定します。

#include <ibase.h>;


i s c _ w a i t _ f o r _ e v e n t ( ) によるイベントの待機

. . .


long blength;

. . .

blength = isc_event_block(&event_buffer, &result_buffer, 3, "BORL", "INTEL", "SUN");

. . .

上のコードでは、"BORL"、"INTEL"、"SUN" という名前のイベントを通知するデータ

ベースにトリガーとストアドプロシージャが定義されているものとしています。

ヒントアプリケーションで応答するイベントが 15 種類より多い場合は、isc_event_block() を繰り返

し呼び出し、呼び出しごとに異なる EPB とイベント名を指定できます。

isc_event_block() の詳細については、15-98 ページの「isc_event_block()」を参照して

ください。

isc_wait_for_event() によるイベントの待機

isc_event_block() で EPB を設定し、関連するイベントを指定したら、isc_wait_for_event()を使ってイベントの関連性を登録し、いずれかのイベントが発生するまで実行を中断しま

す。

重要 isc_wait_for_event() は、Microsoft Windows アプリケーション、および処理の中断を許可しないオペレーティングシステムでは利用できません。そのようなプラットフォームで動作するアプリケーションは、非同期のイベント処理を使用しなければなりません。

isc_wait_for_event() の構文は次のとおりです。

ISC_STATUS isc_wait_for_event(ISC_STATUS *status_vector,isc_db_handle *db_handle,short length,char *event_buffer,char *result_buffer);

次のコードは 3 つのイベントの EPB を設定し、isc_wait_for_event() を使ってそれらのい

ずれかのイベントが発生するまで実行を中断します。

#include <ibase.h>;

. . .


long blength;


isc_db_handle db1;

. . .

/* ここで、データベース db1 が接続され、トランザクションが開始されているものとする */blength = isc_event_block(&event_buffer, &result_buffer, 3, "BORL", "INTEL", "SUN");


i s c _ q u e _ e v e n t s ( ) による処理の続行

isc_wait_for_event(status_vector, &db1, (short)blength,event_buffer, result_buffer);

/* イベントが発生するまで、アプリケーションの処理は一時停止される */. . .

isc_wait_for_event() を呼び出すと、要求したイベントが通知されるまでアプリケーション

の処理が中断します。イベントが発生すると、isc_wait_for_event() の呼び出しに続く次の

実行可能文と同時に、アプリケーションの処理が再開されます。複数のイベントを待機す

るアプリケーションは、isc_event_counts() を使用して、どのイベントが記録されたかを判

定しなければなりません。

メモ isc_wait_for_event() の 1 回の呼び出しで、大 15 個までのイベントに対して待機できま

す。それより多いイベントに対して待機するアプリケーションの場合は、さらに

isc_event_block() を呼び出す必要があります。

isc_wait_for_event() の詳細については、15-153 ページの「isc_wait_for_event()」を参


isc_que_events() による処理の続行引数として渡されるイベントバッファに指定されたイベントの非同期通知を要求するに

は、isc_que_events() を呼び出します。呼び出し後、イベントが通知される前に、呼び出し

を行ったアプリケーションに制御権が渡され、処理が続行できるようになります。

要求したイベントが発生すると、InterBase が非同期トラップ（AST）関数を呼び出しま

す。AST 関数は、イベントの通知を処理するために isc_que_events() に渡されるパラメー

タの 1 つです。AST は、呼び出しアプリケーション内の関数またはサブルーチンであり、

アプリケーションにかわってイベントの通知を行うことだけを目的とした関数です。

isc_que_events() の構文は以下のとおりです。

ISC_STATUS isc_que_events(ISC_STATUS *status_vector,isc_db_handle *db_handle,ISC_LONG *event_id,short length,char *event_buffer,isc_callback event_function,void *event_function_arg);

event_id は、その後の isc_cancel_events() の呼び出しでイベントの通知を終了する際にハ

ンドルとして使用する long 型のポインタです。初期化の必要はありません。length は、待

機するイベントの発生回数を格納する、event_buffer のサイズです。event_function は、

関連するイベントが記録されたときに InterBase が呼び出す AST 関数を指すポインタで

す。AST 関数が呼び出されたことをアプリケーションに通知するかどうかは、AST 関数の

内容によります。通知を行うには、何らかのグローバルフラグを使用します。

event_function_arg は、AST に渡す先頭パラメータを指すポインタです。

isc_que_events() および AST を呼び出す例は、11-6 ページの「isc_que_events() の例」




AST の作成

イベント関数 event_function は、次の 3 つの引数を指定して作成する必要があります。

1 isc_que_events() の呼び出しで指定する event_function_arg。通常は、更新後のイベン

トカウントを入力する、イベントパラメータバッファを指すポインタです。

2 後に続く events_list バッファの長さ。

3 更新後のイベントカウントを除き、isc_que_events() に渡されるイベントパラメータバッ

ファと同様の、events_list バッファを指すポインタ。

イベントが発生しても、結果バッファは自動的に更新されません。events_list バッファの

内容を、アプリケーションが使用するバッファにコピーするかどうかは、event_functionの内容によります。

event_function では、グローバルフラグを設定するなどにより、event_function が呼び出

されたことをアプリケーションに知らせる必要があります。

以下に、event_function の例を示します。

isc_callback event_function

(char *result, short length, char *updated)

{

/* グローバルなイベントフラグを設定します */event_flag++

/* 更新された一時バッファを結果バッファにコピーします */while (length--)

*result++ = *updated++;

return(0);

};

isc_que_events() の例

次のコードは、イベントの発生を非同期モードで待機する isc_que_events() を呼び出して

います。ループ内では、他の処理を行いながら、（指定したイベント関数が設定する）イベ

ントフラグをチェックして、いつイベントが通知されたかを調べます。イベントが通知さ

れると、まずイベントフラグをリセットし、次に isc_event_counts() を呼び出して通知さ

れたイベントを判定し、isc_que_events() を呼び出して新しい非同期待機を起動します。

#include <ibase.h>

#define number_of_stocks 3;

#define MAX_LOOP 10

char *event_names[] = {"DEC", "HP", "SUN"};



short length;

ISC_LONG event_id;

int i, counter;

int event_flag = 0;



length = (short)isc_event_block(

&event_buffer,

&result_buffer,

number_of_stocks,

"DEC", "HP", "SUN");

isc_que_events(

status_vector,

&database_handle, /* 先の isc_attach_database() で設定されます */&event_id,

length, /* isc_event_block() から返されます */event_buffer,

(isc_callback)event_function,

result_buffer);


{

isc_print_status(status_vector); /* エラーメッセージを表示します */ return(1);

};

counter = 0;

while (counter < MAX_LOOP)

{

counter++;

if (!event_flag)

{

/* 必要に応じて他の処理を行います */;

}

else

{ event_flag = 0;

isc_event_counts(

status_vector,

length,

event_buffer,

result_buffer);


{


};

for (i=0; i<number_of_stocks; i++)

if (status_vector[i])

{

/* イベントが通知されています。適切な処理を行ってください（注文品の購入や販売の開始など）。

メモ：event_names[i] は、status_vector[i] に対応するイベント名を通知します。*/


i s c _ e v e n t _ c o u n t s ( ) による発生イベントの判定

;

}

isc_que_events(

status_vector,

&database_handle,

&event_id,

length,

event_buffer,


result_buffer);


{


}

} /* else の終わり */

} /* while の終わり */

/* 非同期で待機する必要がなくなったことを InterBase に通知します */isc_cancel_events(

status_vector,

&database_handle,

&event_id);


{


}

isc_event_counts() による発生イベントの判定

複数イベントの関連性を登録してイベント発生の通知を受け取ったアプリケーションは、

isc_event_counts() を使用して、どのイベントが発生したかを判定しなければなりません。

isc_event_counts() は、result_buffer の値と event_buffer の値を比較して、イベントの関

連性を登録してから発生したイベントの回数を算出します。event_buffer と result_bufferは、アプリケーションで宣言される変数で、isc_event_block() で割り当てられ、初期化さ

れます。

各要素の差異は、isc_event_counts() に渡されるエラーステータス配列に返されます。発生

したイベントを判定するには、配列の各要素をアプリケーションがチェックし、0 以外の値

がないかどうかを確認しなければなりません。0 以外の値は、isc_event_block() が呼び出さ

れてから、isc_wait_for_event() または isc_que_events() を呼び出してから初のイベント

通知までに、イベントが通知された回数を示します。同一のデータベースにアクセスする

アプリケーションが複数ある場合は、イベントカウントが 1 の場合もあれば、複数の場合

もあります。


i s c _ e v e n t _ c o u n t s ( ) による発生イベントの判定

メモ isc_que_events() により、イベントをトラップする AST を設定したときは、InterBase が、

ステータスベクターの全カウントを 0 ではなく 1 に初期化します。カウントの値を取り消

すには、isc_event_counts() を使って再設定します。

isc_event_counts() は、どのイベントが発生したかを判定すると同時に、event_buffer 配列

を再び初期化し、isc_wait_for_event() または isc_que_events() を再び呼び出せるようにし

ます。event_buffer の値は、result_buffer の対応する値に設定されます。

isc_event_counts() の構文は次のとおりです。

void isc_event_counts(ISC_STATUS status_vector,short buffer_length,char *event_buffer,char *result_buffer);

次のコードは、3 つのイベントの関連性を宣言してイベントを待機し、

isc_event_counts() を使って発生したイベントを判定します。

#include <ibase.h>;

. . .


long blength;


isc_db_handle db1;

long count_array[3];

int i;

. . .

/* ここで、データベース db1 が接続され、トランザクションが開始されているものとする */blength = isc_event_block(&event_buffer, &result_buffer, 3, "BORL", "INTEL", "SUN");

isc_wait_for_event(status_vector, &db1, (short)blength,event_buffer, result_buffer);

/* イベントが発生するまで、アプリケーションの処理は一時停止される */isc_event_counts(status_vector, (short)blength, event_buffer,

result_buffer);

for (i = 0; i < 3; i++)

{


{

/* イベントを処理します */;

}

}

isc_event_counts() の詳細については、第 15 章「API 関数リファレンス」の 15-99 ページ

の「isc_event_counts()」を参照してください。


i s c _ c a n c e l _ e v e n t s ( ) による通知の取り消し

isc_cancel_events() による通知の取り消し isc_que_events() を使って非同期イベントの通知を要求したアプリケーションでは、

isc_cancel_events() を使ってその通知要求を取り消すことができます。構文は次のとおり

です。

ISC_STATUS isc_cancel_events(ISC_STATUS *status_vector,isc_db_handle *db_handle,ISC_LONG *event_id);

event_id は isc_que_events() を呼び出して設定されたイベントハンドルです。以下のコー

ドは event_id により識別されるイベントの関連性を取り消します。

include <ibase.h>;

. . .

/* この呼び出しまでのコード例については、

この章の前半の「isc_event_que() による処理の続行」

を参照してください */isc_cancel_events(status_vector, &db_handle, &event_id);


第章

第 12 章サービスの操作

この章では、InterBase のサービス API 関数について説明します。サービス API を使用す

ると、InterBase サーバーおよびデータベースの監視や制御を行うアプリケーションを作

成できます。この API を使用すると、以下のタスクを実行できます。

• データベースのバックアップと復元、シャットダウンと再起動、ガベージコレクション、

無効なデータ構造のスキャン等の、データベース保守操作を実行する。

• セキュリティデータベース内のユーザーエントリを作成、変更、削除する。

• ソフトウェアライセンスを管理する。

• データベースおよびサーバーの構成に関する情報を要求する。

サービス API の概要

この節では、サービス API の一般概念、サービスパラメータバッファの使い方、および

Services Manager との接続 / 接続解除方法について説明します。

一般情報

サービス API は、InterBase クライアントライブラリ（Windows では gds32.dll、UNIX/Linux では libgds.a）に含まれる関数の 1 つのグループです。サービス API で利用できる

機能には、コマンドラインツール gbak, gfix、gsec、gstat、および iblicense の機能も

含まれます（これらのツールについては、『操作ガイド』を参照してください）。また、サー

ビス API は、これらのツールでは提供されない機能も実行できます。

InterBase サーバーには、Services Manager と呼ばれる機能があります。クライアントア

プリケーションがサービス API を介して InterBase サーバーの Services Manager に要求

を出すと、Services Manager がそのタスクを実行します。サーバーは、ローカル（アプリ

第 1 2 章サービスの操作 12-1

サービス A P I の概要

ケーションと同じホスト上に存在する）であってもリモート（ネットワーク上の別のホス

ト上に存在する）であってもかまいません。サービス API は、接続先の InterBase サー

バーがローカルであってもリモートであっても同じ機能を提供します。

サービス API ファミリーは、次の 4 つの関数から構成されます。

• isc_service_attach()。指定された Services Manager への接続を開始する。

• isc_service_start( )。サービスタスクを起動する。

• isc_service_query( )。Services Manager に情報またはタスクの結果を要求する。

• isc_service_detach( )。Services Manager から切断する。

サービス API 関数の構文およびオプションの詳細については、15-136 ページの

「isc_service_attach()」、15-137 ページの「isc_service_detach()」、15-137 ページ

の「isc_service_query()」、および 15-139 ページの「isc_service_start()」のエント

リを参照してください。

サービスパラメータバッファの使い方

Services Manager への接続をカスタマイズするオプションを指定するには、サービスパ

ラメータバッファ（SPB）を作成して必要なプロパティをそこに格納し、SPB のアドレス

をサービス API グループの isc_service_attach() またはその他の関数に渡します。たとえ

ば、リモートサーバーに接続するためのユーザー名とパスワードを SPB に格納できます。

SPB は char 配列変数で、アプリケーション内で宣言します。SPB は、以下の要素を格納

します。

1 SPB 形式のバージョンを示すバイト。常にコンパイル時定数 isc_spb_version です。

2 バージョン番号を指定するバイト。InterBase は、InterBase 製品の各リリースに対す

る推奨 SPB バージョンとして定義されているマクロ isc_spb_current_version を提供し

ます。

3 これに続けて、それぞれ 1 つの引数を記述する、連続した 1 つ以上のバイトのクラス

タがあります。


4 各クラスタのパラメータタイプを示すバイト。すべてのパラメータタイプに対してコン

パイル時定数が定義されています（たとえば、isc_spb_user_name）。

5 クラスタ引数の残りの部分のバイト数を指定するバイト。固定長引数を使用するパラ

メータタイプには不要です。

6 データを含む、可変個のバイト（パラメータタイプによる）。

後続のクラスタは、SPB 配列の直後に続きます。

たとえば、次の C/C++ コードは、SPB バッファに SPB バージョンとユーザー名を示す 1つのクラスタを格納します。

Example 12.1サービスパラメータバッファに値を設定する C/C++ の例

1 char spb_buffer[128], *spb = spb_buffer;

2 *spb++ = isc_spb_version;



3 *spb++ = isc_spb_current_version;

4 *spb++ = isc_spb_user_name;

5 *spb++ = strlen("SYSDBA");

6 strcpy(spb, "SYSDBA");

7 spb += strlen("SYSDBA");

行 1 では、128 バイトの配列と、配列の初のエントリを指すように初期化されたポイン

タを宣言しています。

行 2 では、SPB バージョンの項目指定子を配列の初の要素に割り当てています。すべて

の SPB は、配列の先頭にこの項目を持たなければなりません。SPB 項目の長さは常に 1 バイトなので、長さ指定子は使いません。

行 3 では、SPB バージョン項目の値を割り当てています。

行 4 では、ユーザー名文字列のクラスタ識別子を配列の次の要素に割り当てています。

行 5 では、後続の文字列の長さを指定しています。この例では、文字列は "SYSDBA" で、

長さは 6 です。

行 6 では、文字列 "SYSDBA" を現在の要素で始まる配列にコピーしています。

行 7 では、文字列 "SYSDBA" を指していた SPB ポインタをインクリメントして、追加の

クラスタに位置付けます。

重要データベースパラメータバッファに格納される数値は、下位バイトが先頭にくる汎用フォー

マットで表さなければなりません。符号付き数値の場合は、後のバイトに符号が付きます。

API 関数 isc_portable_integer() を使用すると、数値のバイト順を逆転することができます。

isc_portable_integer() の詳細については、15-123 ページの「isc_portable_integer()」を参


isc_service_attach() による Services Manager への接続

サービス API 関数 isc_service_attach() は、接続アプリケーションからリモート InterBaseServices Manager への接続を開始するために使います。

ローカルまたはリモートサービス名を指定して、接続先のホストを指定しなければなりま

せん。この文字列は、クライアントアプリケーションをサーバーホスト上の ServicesManager に接続するためのネットワークプロトコルを構文で指定する点が InterBaseデータベース接続文字列と共通しています。

serverhost を InterBase データベースサーバーのホスト名に置き換えてください。すべて

のケースで、文字列 service_mgr はリテラル文字列です。

表 12.1 Services Manager 接続文字列の構文（プロトコル別）

プロトコル構文サポートされているサーバープラットフォーム

TCP/IP serverhost:service_mgr すべて

NetBEUI ¥¥serverhost¥service_mgr Windows NT または Windows 2000

ローカル service_mgr すべて



Services Manager に接続するためのユーザー ID は、要求に従って Services Manager がタスクを実行するときに使用するユーザー ID です。一部のサービスタスクは、ユーザー

ID が SYSDBA である場合にのみ実行できます。

Example 12.2C/C++ での Services Manager への接続

char *user = "SYSDBA",

*password = "masterkey", /* セキュリティのヒントを参照 */*service_name = "jupiter:service_mgr";

ISC_STATUS status[20];

isc_svc_handle *service_handle = NULL;

spb_buffer[128], *spb = spb_buffer;

unsigned short spb_length;

*spb++ = isc_spb_version;

*spb++ = isc_spb_current_version;

*spb++ = isc_spb_user_name;

*spb++ = strlen(user);

strcpy(spb, user);

spb += strlen(user);

*spb++ = isc_spb_password;

*spb++ = strlen(password)

strcpy(spb, password);

spb += strlen(password);

spb_length = spb - spb_buffer;

if (isc_service_attach(status, 0, service_name,

&service_handle, spb_length, spb_buffer))

{

isc_print_status(status);

exit(1);}

isc_service_detach() による Services Manager からの接続解除

isc_service_detach() は、サービス API を使ったタスクを完了した後で ServicesManager との接続を解除するために使います。以下に、接続を終了する C/C++ コード例

を示します。ここでは、isc_service_attach() から有効なサービスハンドルを取得している

と仮定しています。

Example 12.3C/C++ での Services Manager からの接続解除

isc_service_detach(status, &service_handle);


i s c _ s e r v i c e _ s t a r t ( ) によるサービスタスクの起動

isc_service_start() によるサービスタスクの起動

関数 isc_service_start() は、指定されたタスクを実行するように Services Manager に要

求するために使います。タスクは、サーバーホスト上で ibserver プロセスのスレッドとし

て実行されます。この節では、要求可能なタスクのタイプについて説明します。

Services Manager との接続において一度に実行できるタスクは 1 つだけです。タスクが

実行している間、isc_service_query() を使ってタスクからの出力を取得できます。ServicesManager への複数の接続を保持して、各接続においてタスクを実行することができます。

要求バッファの使用

サービス API では、isc_service_start() の SPB に似た構造を持つバッファを使用して、

Services Manager のタスクやオプションを指定します。このバッファは、要求バッファ

と呼ばれます。要求バッファには、パラメータと引数のクラスタを格納します。ServicesManager は、指定されたタスクを実行します。

タスク識別子の概要

次の表に、isc_service_start() を使って要求可能なタスクを、要求バッファクラスタ識別子

別に示します。

表 12.2 サービス API のタスク

タスク項目用途

isc_action_svc_backup データベースをファイルまたはテープデバイスにバックアップする。gbak -b に相当

isc_action_svc_restore データベースバックアップファイルを復元し、データベースを再作成する。gbak -c に相当

isc_action_svc_properties データベースのプロパティを設定する。オプションを指定したgfix に相当

isc_action_svc_repair データベースの整合性チェックと修正を実行する。-validate、-full、および -mend オプションを指定した gfix に相当

isc_action_svc_db_stats データベース統計情報をレポートする。gstat の出力に相当

isc_action_svc_get_ib_log サーバー上の interbase.log ファイルの内容をレポートする

isc_action_svc_display_users サーバー上のセキュリティデータベースのユーザーエントリを表示する。gsec -display に相当

isc_action_svc_add_user サーバー上のセキュリティデータベースにユーザーエントリを追加する。gsec -add に相当

isc_action_svc_delete_user サーバー上のセキュリティデータベースからユーザーエントリを削除する。gsec -delete に相当



タスクの説明やその呼び出し例については、以降の節を参照してください。

データベースのバックアップと復元

クラスタ識別子 isc_action_svc_backup は、Services Manager がバックアップ操作を行う

ように要求するために使います。これは、ibserver プロセスのスレッドとして gbak ツー

ルを起動するためのプログラム的な方法です。データベース一次ファイルのパスとバック

アップ出力ファイルのパスを指定する必要があります。

メモバックアップファイルのパスは、サーバーを基準にして指定します。Services Managerは、バックアップおよび復元タスクをサーバーホスト上で実行するので、バックアップファ

イルの読み込みや書き込みはサーバーホスト上で行われます。Services Manager は、サー

バーのコンテキスト内にもファイルを作成します。UNIX システムでは、サーバーをルー

トとして実行している場合、サーバーがファイルを作成したときに設定された保護のため

に、バックアップの復元に失敗することがります。

必要に応じて追加のオプションを指定できます。引数を必要とするオプションもあれば、オ

プションビットマスクのビットとして指定するオプションもあります。

次の表に、isc_action_svc_backup の引数を示します。

isc_action_svc_modify_user サーバー上のセキュリティデータベースのユーザーエントリを変更する。gsec -modify に相当

isc_action_svc_add_license ソフトウェアライセンスを ib_license.dat に追加する。SYSDBA だけがこのタスクを起動できる

isc_action_svc_remove_license ib_license.dat からソフトウェア起動証明書を削除する。SYSDBA だけがこのタスクを起動できる

表 12.2 サービス API のタスク

タスク項目用途

表 12.3 サービス API のデータベースのバックアップに関する引数

引数用途引数の長さ引数の値

isc_spb_dbname データベースの一次ファイルのパス。サーバーを基準とする

2 バイト + 文字列

文字列

isc_spb_verbose 指定した場合、Services Manager はisc_service_query() を介して返す出力を準備する。gbak -verbose に相当

— —

isc_spb_bkp_file バックアップ出力ファイルのパス。複数の出力ファイルを指定可能。gsplit 機能に相当


文字列

isc_spb_bkp_length バックアップ出力ファイルの長さ（バイト数）。後のファイルを除く各出力ファイルの長さ値を指定する必要がある。gsplit 機能に相当


文字列



Example 12.4C/C++ でのデータベースバックアップサービスの起動

char request[100],*x, *p = request;

/* クラスタを識別します */

*p++ = isc_action_svc_backup;

/* データベースファイル名のための引数 */*p++ = isc_spb_dbname;

ADD_SPB_LENGTH(p, strlen(argv[1]));

for (x = argv[1]; *x; ) *p++ = *x++;

isc_spb_bkp_factor テープデバイスブロッキング係数。gbak -factor に相当

4 バイト unsignedlong

isc_spb_options 次に続く値は下記の isc_spb_bkp_xxxx オプションのビットマスク

4 バイトビットマスク

isc_spb_bkp_ignore_checksums バックアップ中にチェックサムを無視する。gbak -ignore に相当

— ビット

isc_spb_bkp_ignore_limbo バックアップ中に limbo トランザクションを無視する。gbak -limbo に相当

— ビット

isc_spb_bkp_metadata_only 空のテーブルの場合にのみメタデータのバックアップファイルを出力する。gbak -metadata に相当

— ビット

isc_spb_bkp_no_garbage_collect バックアップ中に通常のガベージコレクションを抑止する。一部のデータベースではパフォーマンスが向上する。

gbak -garbage_collect に相当

— ビット

isc_spb_bkp_old_descriptions 4.0 以前の形式でメタデータを出力する。gbak -old_descriptionsに相当

— ビット

isc_spb_bkp_non_transportable 非 XDR データ形式でバックアップファイルを出力する。スペースとパフォーマンスがわずかに向上する。gbak -nt に相当

— ビット

isc_spb_bkp_convert 外部テーブルデータを内部テーブルに変換する。gbak -convert に相当

— ビット

表 12.3 サービス API のデータベースのバックアップに関する引数




/* バックアップ出力ファイル名のための引数 */*p++ = isc_spb_bkp_file;

ADD_SPB_LENGTH(p, strlen(argv[2]));

for (x = argv[2]; *x; ) *p++ = *x++;

/* 詳細出力を要求するための引数 */*p++ = isc_spb_verbose;

if (isc_service_start(status,

&service_handle,

NULL,

p - request,

request))

{


isc_service_detach(status, service_handle);

exit(1);

}

また、データベースバックアップファイルを復元して新しいデータベースファイルを作成

することもできます。次の表に、クラスタ識別子 isc_action_svc_restore の引数を示します。

表 12.4 サービス API のデータベースの復元に関する引数


isc_spb_bkp_file バックアップファイル名のパス 2 バイト + 文字列

文字列

isc_spb_dbname データベースの一次ファイルのパス。サーバーを基準とする。複数のデータベースファイルを指定可能


文字列

isc_spb_res_length 復元したデータベースファイルの長さ（ページ数）。2GB を超えてはならない。後のファイルを除く各データベースファイルの長さを指定する必要がある

4 バイト unsignedlong。データベースファイルのページ数

isc_spb_verbose 指定した場合、Services Manager は isc_service_query() を介して返す出力を準備する。gbak -verbose に相当

— —

isc_spb_res_buffers 復元したデータベースへの接続に対して設定するデフォルトのキャッシュバッファの数。gbak -buffers に相当

4 バイト unsignedlong。バッファ数

isc_spb_res_page_size 復元したデータベースのページサイズ。gbak -page_size に相当



isc_spb_res_access_mode データベースのアクセスモードを設定する。次に続くバイトは以下のどちらかでなければならない。

• isc_spb_prp_am_readonly• isc_spb_prp_am_readwrite

gbak -mode に相当

1 バイトバイト

isc_spb_options 次に続く値は下記の isc_spb_res_xxxx オプションのビットマスク


isc_spb_res_deactivate_idx 復元中にユーザーインデックスを作成しない。gbak -inactive に相当

— ビット

isc_spb_res_no_shadow 復元中にシャドウファイルを再作成しない。gbak -kill に相当

— ビット

isc_spb_res_no_validity 復元中に検査条件（たとえば NOT NULL）を強制しない。gbak -no_validity に相当

— ビット

isc_spb_res_one_at_a_time 各テーブルの復元が完了した後でコミットする。gbak -one_at_a_time に相当

— ビット

isc_spb_res_replace データベースが存在する場合は、そのデータベースを置き換える。gbak -replace に相当。復元時には、isc_spb_res_replace または isc_spb_res_create のいずれかを指定する必要がある

— ビット

isc_spb_res_create 既存のデータベースを上書きせずに復元する。gbak -create に相当。復元時には、isc_spb_res_replace または isc_spb_res_create のいずれかを指定する必要がある

— ビット

isc_spb_res_use_all_space 各データページの 20 パーセントを将来のレコードバージョン用に予約しない。読み取り専用データベースに対して使用する。gbak -use_all_space に相当

— ビット

表 12.4 サービス API のデータベースの復元に関する引数




Example 12.5C/C++ でのデータベース復元サービスの起動

char request[100], *x, *p = request;

unsigned long options;

/* クラスタを識別します */*p++ = isc_action_svc_restore;

/* バックアップファイル名のための引数 */for (i = 1; argc > 1; --argc; ++i)

{

*p++ = isc_spb_bkp_file;

ADD_SPB_LENGTH(p, strlen(argv[i]));

for (x = argv[i]; *x; ) *p++ = *x++;

}

/* データベースファイル名のための引数 */*p++ = isc_spb_db_name;

ADD_SPB_LENGTH(p, strlen(argv[i]));

for (x = argv[i]; *x; ) *p++ = *x++;

/* 詳細出力を要求するための引数 */*p++ = isc_spb_verbose;

/* 復元オプションを指定するための引数 */*p++ = isc_spb_options;

options = isc_spb_res_create;

ADD_SPB_NUMERIC(p, options);

if (isc_service_start(status,

&service_handle,

NULL,

p - request,

request))

{


isc_service_detach(status, service_handle);

exit(1);

}

データベースプロパティの設定

クラスタ識別子 isc_action_svc_properties を使用すると、ローカルデータベースまたはリ

モートデータベースのプロパティを設定できます。この機能は、gfix コマンドラインユー

ティリティのいくつかのオプションに対応します。



次の表に、isc_action_svc_properties の引数を示します。

表 12.5 サービス API のデータベースプロパティに関する引数




文字列

isc_spb_prp_page_buffers デフォルトのキャッシュバッファ数を指定された値に設定する。gfix -buffers に相当


isc_spb_prp_set_sql_dialect データベースヘッダーページの SQL ダイアレクトを指定の数値（1 または 3）に設定する


isc_spb_prp_sweep_interval スイープ間隔を指定された値に設定する。スイープを無効にするには、0 を指定する。gfix -housekeeping に相当


isc_spb_prp_shutdown_db 以下のときにデータベースをシャットダウンする。

• データベースへの接続がないとき、または

• 指定したタイムアウト期間が経過したとき

gfix -shut -force n に相当


isc_spb_prp_deny_new_transactions 指定されたタイムアウト期間が経過したときにアクティブなトランザクションがなければデータベースをシャットダウンする。このタイムアウト期間中は新しいトランザクションを拒否する。タイムアウト期間が経過したときにアクティブなトランザクションがあれば失敗する。gfix -shut -tran n に相当


isc_spb_prp_deny_new_attachments 指定されたタイムアウト期間が経過したときにアクティブなトランザクションがなければデータベースをシャットダウンする。このタイムアウト期間中は新しいデータベース接続を拒否する。タイムアウト期間が経過したときにアクティブなデータベース接続があれば失敗する。gfix -shut -attach n に相当




データベース保守の起動

この節では、isc_service_start() を使用して、データベースの検証、ガベージコレクション

のスイープ、および limbo トランザクションの解決を行う方法について説明します。これ

らのタスクは、gfix コマンドラインユーティリティのいくつかのオプションに対応します。

isc_spb_prp_reserve_space 新しいレコードを挿入するときにデータページをすべて埋めるようにデータベースを設定するか、または将来のレコードデルタのために各ページの 20% を予約する。次に続くバイトは以下のどちらかでなければならない。

• isc_spb_prp_res_use_full• isc_spb_prp_res

gfix -use に相当


isc_spb_prp_write_mode データベースの書き込みモードを設定する。次に続くバイトは以下のどちらかでなければならない。

• isc_spb_prp_wm_async• isc_spb_prp_wm_sync

gfix -write に相当


isc_spb_prp_access_mode データベースのアクセスモードを設定する。次に続くバイトは以下のどちらかでなければならない。

• isc_spb_prp_am_readonly• isc_spb_prp_am_readwrite

gfix -mode に相当


isc_spb_prp_set_sql_dialect データベースの SQL ダイアレクトを設定する。値は 1 または 3 でなければならない


isc_spb_options 次に続く値は下記の isc_spb_prp_xxxx オプションのビットマスク


isc_spb_prp_activate データベースとして使うシャドウファイルをアクティブにする。gfix -activate に相当

— ビット

isc_spb_prp_db_online シャットダウン状態のデータベースをオンラインにする。gfix -online に相当

— ビット

表 12.5 サービス API のデータベースプロパティに関する引数




データベース検証処理を起動するデータベース検証処理を要求するには、クラスタ識別子 isc_action_svc_repair を使用しま

す。データベース検証処理は、内部データ構造体をスキャンして特定のタイプの破損の有

無を調べます。場合によっては、検証処理で破損状態を修復できることがあります。

重要検証処理では、すべての破損状態を修復できるとは限りません。データベース検証処理は、

障害復旧ポリシーとして考えてはなりません。データベースは定期的にバックアップして

ください。

次の表に、データベースを検証するための isc_action_svc_repair の引数を示します。

データベーススイープ処理を起動するデータベーススイープ処理を要求するには、クラスタ識別子 isc_action_svc_repair を使用

します。スイープ処理は、データベースをスキャンして古いレコードバージョンを検出し、

それを空き領域としてマークします。次の表に、データベースをスイープするための

isc_action_svc_repair の引数を示します。

表 12.6 サービス API のデータベースの検証に関する引数




文字列

isc_spb_options 次に続く値は下記の isc_spb_rpr_xxxx オプションのビットマスク


isc_spb_rpr_check_db 問題の修正を行わずに、データベースの読み取りに関する検証処理だけを要求する。gfix -no_update に相当

— ビット

isc_spb_rpr_ignore_checksum チェックサムエラーをすべて無視する。gfix -ignore に相当

— ビット

isc_spb_rpr_kill_shadows 利用不可能なシャドウファイルの参照を削除する。gfix -kill に相当

— ビット

isc_spb_rpr_mend_db 破損レコードを使用不可としてマークして、以降の操作でそれらのレコードがスキップされるようにする。gfix -mend に相当

— ビット

isc_spb_rpr_validate_db 確保されているけれどもどのデータ構造体にも割り当てられていないページを検索して解放する。gfix -validate に相当

— ビット

isc_spb_rpr_full レコードおよびページ構造体をチェックして、割り当てられてないレコードを解放する。isc_spb_rpr_validate_db と一緒に使う。gfix -full に相当

— ビット



limbo トランザクションの解決limbo 状態のトランザクションをリストおよび修正するには、クラスタ識別子

isc_action_svc_repair を使用します。

limbo トランザクションは、InterBase の 2 相コミットを中断した結果として生成される

トランザクションです。BDE および ODBC を含むほとんどのクライアントインター

フェースは、InterBase の 2 相コミットまたは分散トランザクション機能を使用しません。

したがって、このようなクライアントインターフェースを使用しているアプリケーション

では、limbo トランザクションが生成されることはありません。

次の表に、limbo トランザクションを解決するための isc_action_svc_repair の引数を示し

ます。

表 12.7 サービス API のデータベースのスイープに関する引数




文字列

isc_spb_options 次に続く値は下記の isc_spb_rpr_xxxx オプションのビットマスク


isc_spb_rpr_sweep_db データベースのスイープを要求して古いレコードを空き領域としてマークする。gfix -sweep に相当

— ビット

表 12.8 サービス API の limbo トランザクションに関する引数




文字列

isc_spb_rpr_commit_trans 後続のトランザクションをコミットするように Services Manager に要求する

— —

isc_spb_rpr_rollback_trans 後続のトランザクションをロールバックするように Services Manager に要求する

— —

isc_spb_rpr_recover_two_phase 指定されたトランザクションに対して自動 2 相コミット復元処理を使用するように Services Manager に要求する

— —

isc_spb_tra_id トランザクション ID 番号の前に指定する




データベースとサーバーのステータスレポートの要求

この節では、データベース統計情報およびサーバーエラーログを要求する方法について説

明します。

データベースステータス情報の要求データベース統計情報を準備するように Service Manager に要求するには、クラスタ識別

子 isc_action_svc_db_stats を使用します。この機能は、gstat コマンドラインユーティリ

ティの機能に対応します。isc_service_query() を使用すると、あとでこの情報を取得する

ことができます（12-34 ページの「サービスタスクのクエリー」を参照）。次の表に、

isc_action_svc_db_stats の引数を示します。

サーバーログを要求するサーバーの interbase.log ファイルの内容を返すように Services Manager に要求するに

は、クラスタ識別子 isc_action_svc_get_ib_log を使用します。このクラスタは引数をとり

ません。

Server Manager が返すテキストを取得するには、isc_service_query() を使用します。

12-34 ページの「サービスタスクのクエリー」を参照してください。

表 12.9 サービス API のステータスレポートに関する引数




文字列

isc_spb_options 次に続く値は下記の isc_spb_sts_xxxx オプションのビットマスク


isc_spb_sts_data_pages ユーザーデータページの統計情報を要求する。gstat -data に相当

— ビット

isc_spb_sts_db_log データベースログページ内の情報だけを要求する。gstat -log に相当

— ビット

isc_spb_sts_hdr_pages データベースヘッダーページ内の情報だけを要求する。gstat -header に相当

— ビット

isc_spb_sts_idx_pages ユーザーインデックスページの統計情報を要求する。gstat -index に相当

— ビット

isc_spb_sts_sys_relations ユーザーテーブルとインデックスに加えて、システムテーブルおよびインデックスの統計情報を要求する。gstat -system に相当

— ビット



ユーザーの設定

サービス API を使用すると、ユーザーの表示、追加、削除、および変更を行うことができ

ます。この機能は、gsec コマンドラインツールの機能に対応します。

セキュリティデータベース内の有効なユーザーを一覧する次の表に、isc_action_svc_display_users の引数を示します。

InterBase セキュリティデータベース（デフォルトは admin.ib）内のすべてのユーザーの情報

を返すように Services Manager に要求するには、isc_spb_sec_username 引数を省略します。

Server Manager が返す情報を取得するには、isc_service_query() にクラスタ識別子

isc_info_svc_get_users を組み合わせます。12-27 ページの「サービス API を使ったクエ

リー：サーバー設定情報」を参照してください。

セキュリティデータベースへのユーザーの追加InterBase セキュリティデータベースに新しいユーザーを作成するには、クラスタ識別子

isc_action_svc_add_user を使用します。クラスタの先頭の引数は isc_spb_sec_usernameでなければなりません。次の表に、このクラスタの引数を示します。

表 12.10 サービス API のユーザーの表示に関する引数


isc_spb_sec_username 1 人のユーザーの名前を指定する。Services Manager はこのユーザーについての情報を返す


文字列

表 12.11 サービス API の isc_action_svc_add_user の引数


isc_spb_sec_username 作成するユーザー名。大 31 文字。必須の引数。先頭のパラメータにする必要がある

2 バイト長 +文字列

文字列

isc_spb_sec_password ユーザーのパスワード。大 31 文字。先頭 8 文字だけが有意。必須の引数


文字列

isc_spb_sec_firstname このユーザー名を使用するユーザーのファーストネーム（オプション）


文字列

isc_spb_sec_middlename このユーザー名を使用するユーザーのミドルネーム（オプション）


文字列

isc_spb_sec_lastname このユーザー名を使用するユーザーのラストネーム（オプション）


文字列

isc_spb_sec_userid ユーザーを登録するための /etc/passwd に定義されたユーザー ID番号（オプション）。将来の実装のために予約




セキュリティデータベースからのユーザーの削除InterBase セキュリティデータベース（デフォルトは admin.ib）からユーザーを削除する

には、クラスタ識別子 isc_action_svc_delete_user を使用します。次の表に、このクラスタ

の引数を示します。

InterBase セキュリティデータベース（デフォルトは admin.ib）からユーザーエントリを

削除した場合、その名前を使ってサーバー上のデータベースにログインすることはできな

くなります。その名前でデータベースにログインするには、isc_action_svc_add_user を使って新しいエントリを作成する必要があります。

セキュリティデータベース内のユーザーの変更クラスタ識別子の isc_action_svc_modify_user を使用して、InterBase セキュリティデー

タベース（デフォルトは admin.ib）内に新しいユーザーを作成できます。

このクラスタで使用できる引数は、isc_action_svc_add_user の引数と同じです。ユーザー

名を変更することはできません。変更できるのは、ユーザーエントリの関連プロパティだ

けです。指定したプロパティだけが変更されます。プロパティを削除するには、プロパティ

の長さとデータに 0 を指定します。クラスタの先頭の引数は isc_spb_sec_username でなけ

ればなりません。

isc_spb_sec_groupid ユーザーを登録するための /etc/group に定義されたグループ ID 番号（オプション）。将来の実装のために予約


isc_spb_sec_groupname ユーザーを登録するための /etc/group に定義されたグループ名（オプション）。将来の実装のために予約


文字列

isc_spb_sql_role_name ユーザーを管理するときに適用するSQL ロール（オプション）。将来のために予約


文字列

表 12.12 サービス API のユーザーの削除に関する引数


isc_spb_sec_username 削除するユーザーの名前。必須の引数。先頭のパラメータにする必要がある


文字列

isc_spb_sql_role_name ユーザーを管理するときに適用するSQL ロール（オプション）。将来のために予約


文字列

表 12.11 サービス API の isc_action_svc_add_user の引数 ( 続き )




古いユーザー関数の使用中止API 関数の isc_add_user()、isc_delete_user()、および isc_modify_user() は、新しく導入

された InterBase サービス API で置き換えられました。新しいサービス API 関数は、一

貫したサービスメカニズム、インターフェース、メッセージのセットを提供しており、古

いユーザー設定関数より優れています。古いユーザー設定関数のかわりに、この新しいサー

ビス API 関数を使用することをお勧めします。isc_xxxx_user() 関数は、下位互換性のた

めに InterBase に残されていますが、将来の製品リリースでは削除される予定です。

ソフトウェアライセンスの管理

サービス API を使用して、ソフトウェアライセンスをインストールしたり削除することができ

ます。それには、クラスタ識別子 isc_action_svc_add_license と isc_action_svc_remove_licenseを使用します。

次の表に、isc_action_svc_add_license と isc_action_svc_remove_license の引数を示しま

す。

ソフトウェアライセンスのリストソフトウェアライセンスをリストを取得するには、isc_service_query() で isc_info_get_licenseクラスタ識別子を使用します。

isc_service_query() を使ってライセンスを取得する例については、12-26 ページの「サービ

ス API を使ったクエリー：ソフトウェアライセンス」を参照してください。

ソフトウェアライセンスの追加ソフトウェアライセンスを追加するには、 Certification ID と Certification Key の両方

を isc_action_svc_add_license の適切な引数に指定する必要があります。

ソフトウェアライセンスの削除ソフトウェアライセンスを削除するには、Certification Key だけを

isc_action_svc_remove_license の適切な引数に指定する必要があります。

ライセンスの変更の有効化同時ユーザー数の変更は、即座に有効になります。

ライセンスに対するその他の変更を有効にするには、InterBase サービスをいったん停止

してから再起動する必要があります。現在の実装では、InterBase サービスを再起動する

サービス API メソッドは用意されていません。

表 12.13 サービス API のソフトウェアライセンスに関する引数


isc_spb_lic_key ソフトウェアライセンスを識別するキー文字列


文字列

isc_spb_lic_id ソフトウェアライセンスの ID 文字列（isc_action_svc_add_license のみ）


文字列


S e r v i c e s M a n a g e r に対するクエリー

Win32 API を使用すると、ローカル Windows NT/2000 ホスト上のサービスをプログラ

ムから停止 / 起動できます。サービスを停止または起動するには、Administrator か、

Power Users グループのメンバーでなければなりません。

次に例を示します。

Example 12.6Win32 API による Windows NT サービスの再起動

SC_HANDLE service;

if (!(service = OpenService(manager, "InterBaseGuardian",SERVICE_START|SERVICE_STOP)))

return 1;

if (!ControlService(service, SERVICE_CONTROL_STOP, NULL))

{

CloseServiceHandle(service);

return 1;

}

if (!StartService(service, 0, NULL))

{


return 1;

}


return 0;

上のコードは、Windows NT または Windows 2000 の InterBase サーバーが実行されて

いるホストでのみ動作します。Windows 98/ME では、InterBase はアプリケーションと

して実行され、ib_license.dat ファイルを読み込ませるには、手動で停止して再起動する

必要があります。

UNIX 版 InterBase の Superserver 実装では、ibmgr を使って ibserver をシャットダ

ウンして再起動する必要があります。従来の InterBase サーバーは、サーバーのインスタ

ンスが起動されるたびに ib_license.dat ファイルを読み取ります。

Services Manager に対するクエリー

サービス API 関数 isc_service_query() を使用すると、InterBase サーバー環境についての

情報を Services Manager に要求することができます。この節では、isc_service_query()を使って情報を要求する方法と、そのデータを解釈する方法について説明します。

タイムアウトのブロックと指定

isc_service_query() を使用すると、進行中のサービスタスクの出力を要求できます。

isc_service_query() 呼び出しは、要求が完了するかまたは結果バッファが満杯にならない

と復帰しません。サービスタスクが進行中であるために返されるべきデータがない場合、ク

エリーはタスクが完了するのを待ちます。isc_service_query() は、出力が利用可能になる

まで無制限にブロック状態になります。これにより、ポーリングの必要がなくなります。



isc_service_query() には、タスクからの出力が得られない場合でも isc_service_query() 呼び出

しが復帰すべき間隔を指定する SPB 項目を定義することができます。SPB には、SPB バー

ジョン情報に続けて、isc_info_svc_timeout クラスタ識別子、およびタイムアウトまでの秒

数を指定する 4 バイトの値を設定します。

現在の実装では、これは isc_service_query() の SPB クラスタに対してだけ使用することが

できます。

サービス API を使ったクエリーの例

この章では、完全な C/C++ コード例を示しながら isc_service_query() 関数の使い方を説

明します。コード例は、以降の節で説明するクエリー項目を示すためにいくつかの部分に

分かれています。この例では、Services Manager への接続が正常に行われていること

（12-3 ページの「isc_service_attach() による Services Manager への接続」を参照）、

および有効なサービスハンドルが取得されていることを想定しています。

例の初の部分では、結果バッファを設定する方法と isc_service_query() を呼び出す方法

を示します。

Example 12.7サービス API を使ったクエリー：クエリーの設定と起動

char spb_buffer[6], *spb = spb_buffer;

char request_buffer[] = {

isc_info_svc_server_version,

isc_info_svc_implementation,

isc_info_svc_get_licensed_users,

isc_info_svc_user_dbpath,

isc_info_svc_get_env,

isc_info_svc_get_env_lock,

isc_info_svc_get_env_msg,

isc_info_svc_get_license,

isc_info_svc_svr_db_info,

isc_info_svc_version,

isc_info_svc_get_config};

char result_buffer[1024], *p = result_buffer;

*spb++ = isc_info_svc_timeout;

ADD_SPB_NUMERIC(spb, 60); /* 1 分間のタイムアウト */

if (isc_service_query (status,&service_handle,NULL,spb - spb_buffer, spb_buffer,sizeof(request_buffer), request_buffer, sizeof(result_buffer), result_buffer))

{


isc_service_detach(status, &svc_handle);



return;

}

do

{

switch (*p++)

{

. . .

このコード例は次のコード例に続きます。

結果バッファの使用

サービス API は、isc_service_query() の SPB に似た構造を持つバッファを使用して、

Services Manager のタスクやオプションを指定します。このバッファは、要求バッファ

と呼ばれます。要求バッファには、パラメータと引数のクラスタを格納します。ServicesManager は、これらの引数で要求されたデータを返します。

isc_service_query() は、別の構造付きバッファを使用して、要求されたデータを返します。

このバッファは、結果バッファと呼ばれます。Services Manager は、結果バッファにデー

タを格納します。アプリケーションでは、isc_service_query() が復帰した後でバッファを

スキャンし、そのデータを各クラスタの先頭部分にある 1 バイトの項目タイプに基づいて

解釈するコードを書きます。

要求バッファ内のデータを要求する場合と、結果バッファに返されたデータのクラスタを

識別する場合の両方において、クラスタ識別子を使用します。これらの識別子を要求バッ

ファに追加するときは、引数の識別子ではなく、識別子名だけを要求バッファに指定しま

す。Services Manager は、引数の識別子およびデータを結果バッファに返します。

結果バッファ内の識別子を解釈する場合、クラスタには関連データが含まれています。ク

ラスタ識別子に続くデータは、クラスタタイプに固有のデータです。一部のクラスタは、識

別子に続いて固定長の値を持ちます。たとえば、数値は常に 4 バイトの long 整数として

返されます。後続の文字列の長さを指定する 2 バイトの short 整数が続くクラスタ識別子

もあります。また、固定長または可変長のデータを持つ一連の引数識別子が続くクラスタ

識別子もあります。

Server Manager が返すデータが、指定した結果バッファのサイズを超える場合、

isc_service_query() はバッファに可能な限りのデータを入れ、isc_info_truncated を後の

クラスタ識別子として含めます。これは、結果バッファが小さすぎてサービスクエリーの

結果出力すべてを格納できないことを意味します。バッファの内容すべてを受け取るには、

大きなバッファを指定して isc_service_query() を再度呼び出す必要があります。ServicesManager は、出力の初から処理をやり直します。このとき、全出力を格納するのに十分

な大きさのバッファを指定しなければなりません。

Example 12.8サービス API を使ったクエリー：切り捨てられた結果の処理

. . .

case isc_info_truncated:

printf ("Buffer Truncated¥n");

/* バッファサイズを増やしてクエリーをやり直します */



break;

. . .

データベースのバックアップタスクのように一般に非常に大きな出力の場合、ServicesManager は大量のテキストデータを返さなければなりません。要求項目 isc_info_svc_lineを使用すると、テキスト結果の連続する行を要求できます。また、isc_info_svc_to_eof を使用すると、1 つのクエリーでテキスト出力全体を要求できます。12-34 ページの「サービ

スタスクのクエリー」を参照してください。

サーバー設定のクエリー

isc_service_query() と一緒に次の項目を使用すると、InterBase サーバー設定に関する情報

を要求することができます。

表 12.14 サービス API のサーバー設定に関するクエリー項目

サーバー設定項目用途戻り値の長さ戻り値

isc_info_svc_version Services Manager のバージョン 4 バイト u n s i g n e dlong

isc_info_svc_server_version InterBase サーバーのバージョン 2 バイト +文字列

文字列

isc_info_svc_implementation サーバーの実装文字列またはプラットフォーム。例：InterBase/Sun4

2 バイト +文字列

文字列

isc_info_svc_get_license サーバー上で現在有効なすべてのCertification ID および CertificationKey

以下を参照以下を参照

isc_info_svc_get_license_mask サーバー上で現在有効なソフトウェアライセンスオプションを表すビットマスク。将来の実装のために予約


isc_info_svc_capabilities サーバー上で現在有効な機能を表すビットマスク。将来の実装のために予約


isc_info_svc_get_config サーバー上の ibconfig ファイルで定義されているパラメータと値


isc_info_svc_get_env サーバー上の InterBase ルートディレクトリの位置。これは、$INTERBASE システム環境変数の値、またはレジストリキーの内容


文字列

isc_info_svc_get_env_lock サーバー上の InterBase ロックマネージャファイルの位置。これは、$INTERBASE_LCK システム環境変数の値。デフォルトは $INTERBASE/serverhostname.lck


文字列



Example 12.9サービス API を使ったクエリー：Services Manager バージョン

. . .

case isc_info_svc_version:

{

unsigned long svcversion;

p += sizeof (unsigned short);

svcversion = (unsigned long) isc_portable_integer (p, sizeof(unsigned long));

printf ("Service Manager Version: %d¥n", svcversion);

p += sizeof (unsigned long);

break;

}

. . .

Example 12.10サービス API を使ったクエリー：サーバーバージョン

. . .

case isc_info_svc_server_version:

{

path_length = (unsigned short) isc_portable_integer (p, sizeof(unsigned short));


buffer = (char*) malloc (path_length);

strncpy (buffer, p, path_length);

buffer [path_length] = '¥0';

printf ("Server version: %s¥n", buffer);

p += path_length;

break;

}

. . .

Example 12.11サービス API を使ったクエリー：サーバー実装

. . .

case isc_info_svc_implementation:

{



isc_info_svc_get_env_msg サーバー上の InterBase メッセージファイルの位置。これは、$INTERBASE_MSG システム環境変数の値。デフォルトは $INTERBASE/interbase.msg


文字列

表 12.14 サービス API のサーバー設定に関するクエリー項目 ( 続き )

サーバー設定項目用途戻り値の長さ戻り値






printf ("Server implementation: %s¥n", buffer);

p += path_length;

break;

}

. . .

Example 12.12サービス API を使ったクエリー：ライセンスマスク

. . .

case isc_info_svc_get_license_mask:

{

unsigned long mask;

printf ("License Information:¥n");


mask = (unsigned long) isc_vax_integer (p, sizeof(unsigned long));

if (mask & LIC_S)

printf ("¥tRemote Server Enabled¥n");


break;

}

. . .

Example 12.13サービス API を使ったクエリー：サーバーの機能

. . .

case isc_info_svc_capabilities:

{

unsigned long capabilities;

printf ("Server Capabilities:¥n");


capabilities = (unsigned long) isc_vax_integer (p, sizeof(unsigned long));

if (capabilities & MULTI_CLIENT_SUPPORT)

printf ("¥tSupports multiple clients¥n");


break;

}

. . .

Example 12.14サービス API を使ったクエリー：サーバーのルートディレクトリの位置

. . .

case isc_info_svc_get_env:

{








printf ("Value of $INTERBASE: %s¥n", buffer);

free(buffer);

p += path_length;

break;

}

. . .

Example 12.15サービス API を使ったクエリー：サーバーのロックファイルの位置

. . .

case isc_info_svc_get_env_lock:

{






printf ("Path to <hostname>.lck: %s¥n", buffer);

free(buffer);

p += path_length;

break;

}

. . .

Example 12.16サービス API を使ったクエリー：メッセージファイルの位置

. . .

case isc_info_svc_get_env_msg:

{






printf ("Path to INTERBASE.MSG: %s¥n", buffer);

p += path_length;

break;

}

. . .



サーバーの設定に関連するデータ

ソフトウェアライセンスisc_info_svc_get_license 結果バッファ項目は、複数のデータのセットを引数として返しま

す。サーバー上の ib_license.dat ファイルに含まれるソフトウェアライセンスのそれぞれに

対して、このクラスタは Certification ID および Certification Key 文字列を返します。

サーバー上に複数のライセンスがインストールされている場合、戻りバッファは、ID とキー文字列の複数のペアを格納します。バッファ内容の末尾は、クラスタの

isc_info_flag_end 値によって示されます。次の表に、ライセンス情報に関するクラスタ識

別子を示します。

Example 12.17サービス API を使ったクエリー：ソフトウェアライセンス

. . .

case isc_info_svc_get_license:

{

printf ("Software activation certificates:¥n");

do {

switch (*p++)

{

case isc_spb_lic_key:

{






printf ("¥tLicense Key: %s¥n", buffer);

free(buffer);

p += path_length;

break;

}

case isc_spb_lic_id:

{

表 12.15 サービス API のソフトウェアライセンスに関する引数

引数用途戻り値の長さ戻り値

isc_spb_lic_id ソフトウェアライセンスの Certification ID 文字列 2 バイト +文字列

文字列

isc_spb_lic_key ソフトウェアライセンスの対応する CertificationKey 文字列


文字列

isc_info_flag_end 引数の終わりを isc_info_svc_get_license に通知する — —








printf ("¥tLicense ID: %s¥n", buffer);

free(buffer);

p += path_length;

break;

}

}

} while (*p != isc_info_flag_end);

break;

}

. . .

サーバー設定プロパティServices Manager に対してサーバー上の InterBase 設定ファイルの内容をレポートする

ように要求することができます。このファイルは InterBase のインストールディレクトリ

にあり、すべてのプラットフォームで ibconfig というファイル名になります。

結果バッファのクラスタは、isc_info_svc_get_config 識別子とそれに続く 2 バイトの数値

データから構成されます。後続のデータは、1 バイトの設定エントリ識別子と 4 バイトの

値のペアです。文字列値を持つ設定エントリ（たとえば TMP_DIRECTORY）は、このクラ

スタでは現在サポートされていません。

設定項目のいくつかは、特定のプラットフォームにのみ対応します。Services Managerは、Services Manager を実行している対応サーバープラットフォームに関係する設定

データだけを返します。

Services Manager は、デフォルト値に設定されている設定項目の値は返しません。

Example 12.18サービス API を使ったクエリー：サーバー設定情報

. . .

case isc_info_svc_get_config:

{

unsigned short chTmp = 0, key;

unsigned long len = 0, ulConfigInfo;

printf ("Configuration Settings:¥n");

len = (unsigned short)isc_portable_integer(p, sizeof(unsigned short));

p += sizeof(unsigned short);

for (chTmp = 0; chTmp < len; chTmp++)

{

key = p[chTmp];



ulConfigInfo = (unsigned long)isc_portable_integer(p+ chTmp + 2, p[chTmp+1]);

switch (key)

{

case ISCCFG_LOCKMEM_KEY:

printf ("¥tLock mem: %d¥n", ulConfigInfo);

break;

case ISCCFG_LOCKSEM_KEY:

printf ("¥tLock Semaphores: %d¥n", ulConfigInfo);

break;

case ISCCFG_LOCKSIG_KEY:

printf ("¥tLock sig: %d¥n", ulConfigInfo);

break;

case ISCCFG_EVNTMEM_KEY:

printf ("¥tEvent mem: %d¥n", ulConfigInfo);

break;

case ISCCFG_PRIORITY_KEY:

printf ("¥tPriority: %d¥n", ulConfigInfo);

break;

case ISCCFG_MEMMIN_KEY:

printf ("¥tMin memory: %d¥n", ulConfigInfo);

break;

case ISCCFG_MEMMAX_KEY:

printf ("¥tMax Memory: %d¥n", ulConfigInfo);

break;

case ISCCFG_LOCKORDER_KEY:

printf ("¥tLock order: %d¥n", ulConfigInfo);

break;

case ISCCFG_ANYLOCKMEM_KEY:

printf ("¥tAny lock mem: %d¥n", ulConfigInfo);

break;

case ISCCFG_ANYLOCKSEM_KEY:

printf ("¥tAny lock semaphore: %d¥n",ulConfigInfo);

break;

case ISCCFG_ANYLOCKSIG_KEY:

printf ("¥tany lock sig: %d¥n", ulConfigInfo);

break;

case ISCCFG_ANYEVNTMEM_KEY:

printf ("¥tany event mem: %d¥n", ulConfigInfo);

break;

case ISCCFG_LOCKHASH_KEY:

printf ("¥tLock hash: %d¥n", ulConfigInfo);

break;

case ISCCFG_DEADLOCK_KEY:

printf ("¥tDeadlock: %d¥n", ulConfigInfo);



break;

case ISCCFG_LOCKSPIN_KEY:

printf ("¥tLock spin: %d¥n", ulConfigInfo);

break;

case ISCCFG_CONN_TIMEOUT_KEY:

printf ("¥tConn timeout: %d¥n", ulConfigInfo);

break;

case ISCCFG_DUMMY_INTRVL_KEY:

printf ("¥tDummy interval: %d¥n", ulConfigInfo);

break;

case ISCCFG_IPCMAP_KEY:

printf ("¥tMap size: %d¥n", ulConfigInfo);

break;

case ISCCFG_DBCACHE_KEY:

printf ("¥tCache size: %d¥n", ulConfigInfo);

break;

}

chTmp += p[chTmp+1] + 1;

}

break;

}

. . .

セキュリティ設定のクエリー

isc_service_query() と一緒に次の項目を使用すると、InterBase サーバーのセキュリティお

よびユーザーアクセスに関する情報を要求することができます。

Example 12.19サービス API を使ったクエリー：ライセンスが与えられているユーザーの数

. . .

表 12.16 サービス API のセキュリティ設定に関するクエリー項目

セキュリティ設定項目用途戻り値の長さ

戻り値

isc_info_svc_get_licensed_users サーバーによって許可されているユーザー数

4 バイト u n s i g n e dlong

isc_info_svc_user_dbpath サーバー上のセキュリティデータベースのパス。例：/usr/interbase/admin.ib


文字列

isc_info_svc_get_users セキュリティデータベースからのユーザー情報


isc_info_svc_svr_db_info データベース接続の数およびサーバー上で現在アクティブなデータベースの数




case isc_info_svc_get_licensed_users:

{

unsigned long nUsers;

p+= sizeof (unsigned short);

nUsers = (unsigned long)isc_portable_integer(p, sizeof (unsigned long));

printf ("Number of licensed users: %d¥n", nUsers);

p += sizeof(unsigned long);

break;

}

. . .

Example 12.20サービス API を使ったクエリー：セキュリティデータベースの位置

. . .

case isc_info_svc_user_dbpath:

{






printf ("Path to admin.ib: %s¥n", buffer);

p += path_length;

break;

}

. . .

セキュリティ情報に関連するデータisc_info_svc_get_users 結果項目は、複数のデータのセットを返します。複数のユーザーが

レポートされる場合は、結果バッファは複数のクラスタを格納します。バッファ内容の末

尾は、クラスタの isc_info_flag_end 値によって示されます。次の表に、ユーザー情報に関

するクラスタ識別子を示します。

表 12.17 サービス API のユーザー情報に関する引数


isc_spb_username InterBase セキュリティデータベース（デフォルトは admin.ib）からのユーザー ID


文字列

isc_spb_firstname ユーザー ID に関連付けられているファーストネーム


文字列

isc_spb_middlename ユーザー ID に関連付けられているミドルネーム


文字列

isc_spb_lastname ユーザー ID に関連付けられているラストネーム


文字列



Example 12.21サービス API を使ったクエリー：サーバー上で設定されているユーザー

. . .

case isc_info_svc_get_users:

{

ISC_USHORT len, loop;

ISC_ULONG id;

char buffer[50], *buf = buffer;

loop = (ISC_USHORT) isc_portable_integer (p, sizeof (ISC_USHORT));

p += sizeof (ISC_USHORT);

while (*p != isc_info_end)

{

switch (*p++)

{

case isc_spb_sec_username:

len = (ISC_USHORT) isc_portable_integer(p, sizeof(ISC_USHORT));


strncpy (buf, p, len);

p += len;

buffer[len] = 0;

printf ("Username: %s¥n", buffer);

loop -= (len + sizeof(ISC_USHORT)+1);

break;

case isc_spb_sec_firstname:



isc_spb_userid ユーザーを登録するための /etc/passwd に定義されたユーザー ID 番号。UNIX または Linux サーバーでのみ該当

4 バイト uns ignedlong

isc_spb_groupid ユーザーを登録するための /etc/group に定義されたグループ ID 番号。UNIX または Linux サーバーでのみ該当

4 バイト uns ignedlong

isc_info_flag_end 引数の終わりを isc_info_svc_get_users に通知する

— —

表 12.17 サービス API のユーザー情報に関する引数





p += len;

buffer[len] = 0;

printf ("Firstname: %s¥n", buffer);


break;

case isc_spb_sec_middlename:




p += len;

buffer[len] = 0;

printf ("Middlename: %s¥n", buffer);


break;

case isc_spb_sec_lastname:




p += len;

buffer[len] = 0;

printf ("Lastname: %s¥n", buffer);


break;

case isc_spb_sec_groupid:

id = isc_portable_integer (p, sizeof (ISC_ULONG));

p += sizeof (ISC_ULONG);

printf ("Group ID: %d¥n", id);

loop -= (len + sizeof(ISC_ULONG)+1);

break;

case isc_spb_sec_userid:

id = isc_portable_integer (p, sizeof (ISC_ULONG));

p += sizeof (ISC_ULONG);

printf ("User ID: %d¥n", id);

loop -= (len + sizeof(ISC_ULONG)+1);

break;

default:

*x = *p;

break;



} /* switch の終わり */

} /* while の終わり */break;

}

. . .

isc_info_svc_svr_db_info 結果項目は、複数のデータのセットを返します。複数のアクティ

ブデータベースがレポートされる場合は、結果バッファは複数のクラスタを格納します。

バッファ内容の末尾は、クラスタの isc_info_flag_end 値によって示されます。次の表に、

データベース接続情報に関するクラスタ識別子を示します。

Example 12.22サービス API を使ったクエリー：データベース接続

. . .

case isc_info_svc_svr_db_info:

{

printf ("Database information:¥n");

do {

switch (*p++)

{

case isc_spb_dbname:

{

/* 使用しているデータベース名 */path_length = (unsigned short)

isc_portable_integer(p, sizeof(unsigned short));





printf ("Database in use: %s¥n", buffer);

p += path_length;

break;

}

表 12.18 サービス API のデータベース接続情報に関する引数


isc_spb_num_att サーバー上で現在使用されている接続の数 4 バイト unsignedlong

isc_spb_num_db サーバー上で現在使用されているデータベースの数


isc_spb_dbname サーバー上で現在使用されているデータベースの名前。この項目は、使用されているデータベースごとに発生する


文字列

isc_info_flag_end 引数の終わりを isc_info_svc_svr_db_info に通知する

— —



case isc_spb_num_att:

{

/* 接続数 */unsigned long nAttachments;


nAttachments = (unsigned long)isc_portable_integer(p, sizeof (unsigned long));

printf ("¥tNumber of attachments: %d¥n", nAttachments);


break;

}

case isc_spb_num_db:

{

/* データベース数 */unsigned long nDatabases;


nDatabases = (unsigned long)isc_portable_integer(p, sizeof(unsigned long));

printf ("¥tNumber of databases: %d¥n",nDatabases);


break;

}

}

} while (*p != isc_info_flag_end);

break;

}

. . .

Example 12.23サービス API を使ったクエリー：例の終わり

. . .

}

} while (*p);

isc_service_detach(status, &service_handle);

}

サービスタスクのクエリー

いくつかのサービスタスクはテキスト出力を返します。isc_service_query() と一緒に次の

項目を使用すると、サービスタスクの出力を要求することができます。出力を生成するタ

スクは、サービス API タスク項目 isc_action_svc_backup、isc_action_svc_restore、isc_action_svc_repair、isc_action_svc_db_stats、isc_action_svc_get_ib_log、および

isc_action_get_users に対応するタスクです。



タスクの結果に関連するデータisc_info_svc_limbo_trans 結果項目は、複数のデータのセットを返します。レポートする

limbo トランザクションが複数ある場合、結果バッファは複数のクラスタを含みます。バッ

ファ内容の末尾は、クラスタの isc_info_flag_end 値によって示されます。次の表に、limboトランザクション情報に関するクラスタ識別子を示します。

表 12.19 サービス API のタスクに関するクエリー項目

タスク結果項目用途戻り値の長さ戻り値

isc_info_svc_line サービスタスクからの 1 行出力 2 バイト +文字列

テキストの行

isc_info_svc_to_eof 大で結果バッファのサイズまでの、サービスタスクからの複数行出力


テキストのバッファ

isc_info_svc_running サービスタスクがサーバー上ですでに実行されている場合は TRUE を返す。進行中のタスクの非ブロッキングチェックに使用する

4 バイト unsignedlong、1 または 0

isc_info_svc_get_users 参照：12-30 ページの「セキュリティ情報に関連するデータ」

q.v. q.v.

isc_info_svc_limbo_trans 未解決の分散トランザクションのlimbo トランザクション情報




isc_dpb_single_tra_id 単独データベース limbo トランザクション ID を指定する


isc_spb_multi_tra_id マルチデータベース limbo トランザクション ID を指定する


isc_spb_tra_host_site トランザクションを開始したクライアントホストのホスト名。マルチデータベーストランザクションの場合のみ


文字列

isc_spb_tra_advise limbo トランザクションを解決するためにサーバーが推奨する処理。次のいずれかの値

• isc_spb_tra_advise_commit• isc_spb_tra_advise_rollback• isc_spb_tra_advise_unknown


isc_spb_tra_remote_site トランザクションが limbo 状態になっているサーバーのホスト名


文字列


D e l p h i および C + + B u i l d e r でのサービス A P I の使用

Delphi および C++Builder でのサービス API の使用

InterBase Express™ コンポーネント製品は、ビジュアル開発ツールである Delphi および

C++Builder のためのデータアクセスコンポーネントを提供します。このパッケージには、

この章で説明したサービス API のコンポーネントインターフェースが含まれています。

InterBase Express™ のサービスコンポーネントについては、『開発者ガイド』を参照して

ください。

isc_spb_tra_db_path トランザクションが limbo 状態になっているデータベースの一次ファイルのパス


文字列

isc_spb_tra_state limbo トランザクションの状態を指定するバイトを示す。次のいずれかの値

• isc_spb_tra_state_limbo• isc_spb_tra_state_commit• isc_spb_tra_state_rollback

• isc_spb_tra_state_unknown（この状態になることはない）


isc_info_flag_end 引数の終わりを isc_info_svc_limbo_trans に通知する

— —




第章

第 13 章インストール API とライセンスAPI

この章では、アプリケーションインストールの一部として InterBase のインストール APIの関数を使用する方法について説明します。以下の内容が含まれます。

• インストール API とその内容の説明

• API を使ってインストールプログラムを記述する方法の概要

• ライセンス API の説明

• 標準的なインストールのためのサンプルコード

ライセンス関数とインストール関数のリファレンスについては、API ガイドの「API 関数

リファレンス」の章を参照してください。API 関数リファレンスの各章は、HTML 形式

（<ib_home>/HtmlRef/ApiFunctionRef.html）でもご覧になれます。

第 1 3 章インストール A P I とライセンス A P I 13-1

I n t e r B a s e のインストール A P I について

InterBase のインストール API について

InterBase は、Win32 プラットフォームでのアプリケーションインストールの一部として

InterBase をインストールするプロセスを大幅に簡略化するリソースを提供しています。

これは、完全に自動化されたインストールのメカニズムを提供します。また、これによっ

て必要に応じてユーザーと対話して、ユーザーから情報を取得し、進捗レポートやメッセー

ジをユーザーに示すことができます。

ibinstall.dll に含まれる API 関数を使うと、独自の製品のインストールプログラムに、

InterBase の埋め込みコピーの配布を統合することができます。インストールの InterBase部分はサイレントになり、ビルボードは表示されず、エンドユーザーによる操作も必要あ

りません。

インストール API のファイル

API は以下のファイルで構成されます。

以上のファイルは、すべて InterBase CD-ROM に格納されています。また、これらのファ

イルは、インストール時に IBDEV オプションが選択された場合に、InterBase インストー

ルの一部としてコピーされます。

表 13.1 InterBase インストールの作成に必要なインストール API ファイル

ファイル説明

ibinstall.dll 関数のライブラリ（インストールエンジン）： • 10 個の関数と InterBase のエラーと警告のメッセージのテキストを含む API• どの InterBase オプションをインストールする場合でもインストールされる

ibinstall.h C プログラム用：

• 関数および関連する値の宣言、エラーと警告メッセージとその番号のリストを含むヘッダーファイル

• IBDEV オプションの場合にインストールされる

ibinstall.lib Borland C++Builder プログラム用：

• ibinstall.dll 内の関数のリストを含むライブラリファイル


ibinstall_ms.lib Microsoft Visual C プログラム用：

• 関数および関連する値の宣言、エラーと警告メッセージとその番号のリストを含むヘッダーファイル


ibinstall.pas Delphi プログラム用：

• 関数宣言と関連する値を含む Object Pascal ソースファイル




インストール API が行うこと

InterBase インストール API の関数は、これまでは開発者の責任であった数多くの処理を

行います。

• インストール前のチェック：有効なオペレーティングシステムかどうか、ユーザーのアク

セス許可は適切か、既存の InterBase のコピー、ディスクの空き容量、インストール元と

インストール先のディレクトリ

• ib_install.log ファイルへのすべての処理の記録

• 必要（かつ可能）な場合は、インストール先ディレクトリの作成

• オプションの依存関係のチェック

• すべてのファイルのコピー。新しいバージョンへの上書きを防ぐバージョンチェックを行

う

• 必要なレジストリエントリの作成と、共有ファイルの参照カウントのインクリメント

• Windows NT/2000 の場合、InterBase サーバーと InterBase Guardian を、自動的に起

動するサービスとしてインストールする。Windows 98 の場合、レジストリの Run セク

ションに Guardian を追加する

• 必要であれば、TCP/IP Services ファイルの変更

• 選択されたファイルのアンインストールファイルへの書き込み

インストール API が行わないことInterBase インストール API は、インストール後のサーバーの起動、およびショートカッ

トの作成を行う機能は提供していません。ライセンスに関する機能は、ライセンス API で処理します。

インストール API 関数

InterBase インストール API（ibinstall.dll）は、開発者の独自のアプリケーションの一部

として InterBase をインストールおよび配布するプロセスを簡略化する関数のライブラリ

です。表 13.2「ibinstall.dll のエントリポイント」は、ibinstall.dll の各エントリポイント

と簡単な説明を一覧します。

各関数の詳細なリファレンスについては、API ガイドの 15-105 ～ 15-150 ページを参照し

てください。この情報は、HTML 形式（<ib_home>/HtmlRef/ApiFunctionRef.html）でも

ご覧になれます。



インストールハンドル

各インストールインスタンスには、それぞれを識別するための一意のハンドルがあります。

このハンドルは OPTION_HANDLE 型（13-6 ページの「インストール API 用に定義されて

いるデータ型」を参照）の変数で、プログラムで InterBase インストールの開始時に 0 に初期化します。この章では、この変数を handle として言及し、そのアドレスを phandle とします。isc_install_set_option() に渡すと、この変数は現在のインストールのすべてのオプ

ションが格納されているデータ領域を参照します。handle を直接逆参照する必要はなく、

またしてはなりません。インストールデータは、インストールエンジンによって保守され

ます。必要なことは、呼び出す関数の構文に従って、handle または handle へのポインタを

渡すだけです。

isc_install_set_option() は handle の値が 0 でないと受け付けないので、他の関数に渡す前

に、初に handle を isc_install_set_option() に渡さなければなりません。0 以外の場合は

エラーになります。

表 13.2 ibinstall.dll のエントリポイント

関数説明

isc_install_clear_options() isc_install_set_option() によって設定されたオプションをすべてクリアします。

isc_install_execute() 実際のインストールを実行します。これには、ファイルのコピー、レジストリの登録、アンインストールオプションの保存、また必要であれば Services ファイルの変更が含まれます。

isc_install_get_info() 要求された情報（推奨されるインストールディレクトリ、必要なディスク空き容量、オプションの名前、またはオプションの説明）を人が読める形式で返します。

isc_install_get_message() 要求されたエラーまたは警告メッセージ番号のテキストを返します。

isc_install_load_external_text() 指定されたメッセージファイルからメッセージをロードします。

isc_install_precheck() インストール環境について、既存のサーバー、ディスク容量とアクセス、ユーザーのアクセス権限、オプションの依存関係などの必要なチェックを行います。

isc_install_set_option() 選択されたインストールオプションのリストのハンドルを作成します。各オプションごとに 1 回呼び出す必要があります。

isc_install_unset_option() isc_install_set_option() によって取得された、選択されているオプションのリストから 1 つのオプションを削除します。

isc_uninstall_execute() インストールされている InterBase ファイルを削除し、レジストリを更新し、参照カウントが 1 より小さい共有ファイルを削除し、InterBase Guardian および Server サービスをアンインストールします。

isc_uninstall_precheck() サーバーが実行中かどうか、ユーザーの権限が正しいかどうか、およびアンインストールファイルが有効かどうかをチェックします。



エラー処理

InterBase インストール API の各関数は、次のようにメッセージ番号を返します。

• 関数の実行が成功した場合は、0（isc_install_success）を返します。

• 処理は完了したが警告がある場合は、各警告メッセージに対応する負の数を返します。

• エラーが発生した場合は、各エラーメッセージに対応する正の値を返します。

関数を呼び出すときは、常に戻り値をチェックする必要があります。戻り値が 0 以外の場

合は、isc_install_get_message() を呼び出してエラーまたは警告メッセージのテキストを取

得します。例を示します。

error = isc_install_precheck(handle, source_path, dest_path) if(error)

isc_install_get_message(error, message, length(message))

「手順の概要」の手順では、この点については明示的に示していません。必要に応じてチェッ

クが行われることを想定しています。

コールバック関数

isc_install_execute() 関数と isc_uninstall_execute() 関数では、プログラマが作成したエ

ラー処理関数およびステータス関数にポインタを渡すことができます。

• エラー処理関数を使用して、エラーまたは警告に対する応答を指定し、メッセージテキス

トをエンドユーザーに表示することができます。

• ステータス関数では、エンドユーザーにステータス情報を渡し、エンドユーザーからの「取

り消し」要求を受け取ることができます。

これらの関数のプロトタイプは次のとおりです。

fp_status()int (*fp_status)(int status, void *status_arg, const TEXT* act_desc)

fp_status() は、開発者が作成するコールバック関数です。インストール / アンインストー

ルの進捗のパーセンテージを示す整数（status）を受け取ります。isc_install_execute() または isc_uninstall_execute() に fp_status() へのポインタを渡すと、fp_status() が一定間隔

で呼び出され、進捗のパーセンテージを示す数値が渡されるので、それを使ってステータ

スバーや他のインジケータをエンドユーザーに表示することができます。

fp_status() は、実行中の処理を示すテキスト（たとえばサーバーファイルのコピーなど）

を返すこともできます。



戻り値 fp_status() 関数は、isc_install_fp_continue または isc_install_fp_abort を返さなければ

なりません。

fp_error()int (*fp_error)(MSG_NO msg_no, void *error_arg, const TEXT* context)

fp_error() は、開発者が作成するコールバック関数です。この関数へのポインタが

isc_install_execute() または isc_uninstall_execute() にパラメータとして渡された場合に、

エラー番号（msg_no）を受け取ります。

戻り値 fp_error() は、エラーメッセージを処理して、isc_install_fp_retry、isc_install_fp_continue、isc_install_fp_abort のいずれか値を返します。

重要これらのコールバック関数では、isc_install_get_message() だけを呼び出すことができま

す。コールバック関数が他のインストール API 関数を呼び出した場合の結果は不定です。

インストール API 用に定義されているデータ型

インストール API 用に次のデータ型が定義されています。


status INT isc_install_execute() または isc_uninstall_execute() から、0 から 100 までの整数を受け取ります。渡された整数は、インストール / アンインストールの進捗のパーセンテージを示します。

status_arg VOID* isc_install_execute() または isc_uninstall_execute() に渡される、オプションのユーザー定義データへのポインタ。

act_desc TEXT* 進捗インジケータの一部として表示できるテキスト。


msg_no MSG_NO isc_install_execute() または isc_uninstall_execute() からエラー番号を受け取ります。

error_arg VOID* isc_install_execute() または isc_uninstall_execute() に渡される、オプションのユーザー定義データへのポインタ。

context TEXT* エラーの性質についてユーザーに示すことができる追加情報を提供します。

fp_error() の戻り値関数呼び出しへの影響

isc_install_ fp_abort 動作に失敗し、関数呼び出しは同じエラーを返す

isc_install_ fp_retry 動作は再試行されるが、ユーザー側の何らかの操作がなければおそらく同じように失敗する

isc_install_ fp_continue 関数はエラーを無視し、エラーが発生した位置から処理を継続する


I n t e r B a s e インストールの記述

InterBase インストールの記述

どのような手順をとるかは、自動インストールを行うか対話型インストールを行うかに

よって異なります。手順の一部のステップは、必須ではなく単なる推奨です。たとえば、イ

ンストールの他の部分に進む前に isc_clear_options を呼び出すことなどがこれに当たりま

す。他のステップは、アンインストールプログラムの記述や、アイコンの作成、承認コー

ドの追加、サーバーの起動などのタスクも実行するかどうかによって異なります。

重要 1 台のマシンごとに InterBase サーバーは 1 つだけでなければなりません。特に重要なの

は、InterBase の SuperServer バージョン（Windows プラットフォームの V4.2 以降）

を、Classic サーバーがインストールされたままのマシンに配置しないことです。

手順の概要

1 InterBase を IB_DEV オプションを指定して開発システムにインストールしている場

合、アプリケーションの開発とコンパイルに必要なファイルは

<interbase_home>¥SDK¥ ディレクトリにあります。また、InterBase CDROM の¥SDK ディレクトリのいくつかのサブディレクトリにも格納されています。次に示す

ファイルを揃えてください。

• C/C++ プログラムの場合： ibinstall.dll、ibinstall.lib、ibinstall.h

• Delphi プログラムの場合： ibinstall.dll、ibinstall.pas

ibinstall.dll を、コンパイルした実行形式ファイルを格納するディレクトリに配置しま

す。他のファイルは、コンパイラが参照できる場所に配置します。

2 handle 用に OPTIONS_HANDLE 型の変数を宣言し、内容を 0（long int）に初期化

します。対応するアンインストールプログラムも記述する場合は、アンインストールプ

ログラムのファイル名用にテキストバッファを割り当てます。

表 13.3 インストール API 用に定義されているデータ型

データ型定義

OPTIONS_HANDLE void*

TEXT char

MSG_NO long

OPT unsigned long

FP_STATUS 次の型の関数ポインタ int (*fp_status)(int status, void *status_arg, const TEXT*description)

FP_ERROR 次の型の関数ポインタ int (*fp_error)(MSG_NO msg_no, void *status_arg, const TEXT*description)


I n t e r B a s e インストールの記述

3 メッセージに英語以外の言語を使う場合は、isc_load_external_text() を呼び出してエ

ラーと警告のメッセージをロードします。

4 対話型インストールの場合のみ：次のステップは、オペレーティングシステムが有効か

どうか、Classic サーバーが存在しないか、および InterBase サーバーが実行中でない

かをチェックするために、一時的にオプションのグループを選択します。これにより、

エンドユーザーがいくつかの質問に答えた後で、OS が有効でなかったり Classic サー

バーがあるためにインストールが実行できなくなるケースを回避します。

a isc_install_set_option() を次のパラメータで呼び出します。

isc_install_set_option(handle, INTERBASE)

サーバーではなくクライアントをインストールする場合は、INTERBASE を IB_CLIENT に置き換えてください。

b isc_install_precheck(handle, NULL, NULL) を呼び出します。

c isc_install_clear_options() を呼び出します。

5 対話型インストールでは、ユーザーにインストール先と他の必要なオプションを問い合

わせます。

6 インストールのオプションごとに isc_install_set_option() を 1 回呼び出します。これ

は、ユーザー入力を処理するメカニズムです。

7 isc_install_precheck() をもう一度呼び出します。今度は、インストール元とインストー

ル先のパス、および選択されたオプションを提供します。isc_install_precheck() は、イ

ンストール先のディレクトリが存在し、書き込み可能かどうかをチェックします。指定

されたディレクトリが存在せず、作成もできない場合、関数はエラーで終了します。ま

た、選択されたオプションの依存関係もチェックし、選択内容に矛盾がある場合、また

は必要なオプションが選択されていない場合は、警告を発します。

8 isc_install_execute() に、handle、ソースパス、およびデスティネーションパスを渡して

呼び出します。エラー処理とステータス表示の関数を書いた場合は、その関数へのポイ

ンタを渡し、オプションとしてコンテキストデータへのポインタも渡します。後のパ

ラメータはオプションで、アンインストールプログラムのファイル名を格納するバッ

ファへのポインタです。対応するアンインストールプログラムを提供する場合は、アン

インストールファイルの名前のためのテキストバッファを宣言して、そのバッファへの

ポインタを関数の後のパラメータとして渡さなければなりません。これで、

isc_install_execute() は実際のインストールを実行します。

以下のステップはすべてオプションです。

9 インストールが完了したら、ライセンス API（iblicense.dll）の関数を呼び出し、CertificationID と Certification Key を提供することにより、製品のライセンス許可された機能を有

効にすることができます。これを行わない場合は、サーバーを起動する前にエンドユー

ザーが Certification ID と Certification Key のペア（認証コード）を入力しなければ

なりません。

10［スタート］メニューにショートカットを作成します。

11 InterBase Guardian を起動します。これは、有効な Certification ID と KEY を提供

した後でしか行うことができません。


ライセンス A P I の使い方

実環境のサンプル

InterBase setup.exe のソースコードは、ib_install_dir¥examples¥install にあります。この

コードは InterBase インストール API を使用しており、これらの関数の使ってインストー

ルプログラムを記述する例として活用できます。

ライセンス API の使い方

InterBase サーバーの機能は、Borland から提供される認証コードをインストールするこ

とによって有効にしなければなりません。各認証コードは、 Certification ID と

Certification Key から構成されます。InterBase ライセンス API で提供される関数を使

用して、インストールの一部としてサーバーを有効にすることができます。インストール

の一部としてサーバーを有効にしない場合、ユーザーが IBConsole または iblicense.exeユーティリティを使って認証コードを入力するまで、サーバーは有効になりません。

InterBase ライセンス API（iblicense.dll）は、 Certification ID と Certification Key のペア（認証コード）のチェック、追加、削除、および表示を行うことができる 5 つの関数

を提供します。5 つ目の関数は、他の 4 つの関数から返される値に対応するメッセージを

取り出して表示します。

ライセンス API のロード

インストール処理中に、iblicense.dll を静的にロードすることはできません。ライセンス

API が必要になったときに、Windows の LoadLibrary() API の呼び出しか、他の言語で

同様な機能を使って動的に呼び出し、使用が終わったらすぐにライブラリを解放します。

通常、対象の Certification ID と Key のペアが実際に追加できるかどうかをチェックする

ために、インストールの開始時にライセンス API をロードします。isc_license_check() を呼び出してから、ライブラリを解放します。そして、インストール部分が完了して、認証

コードを追加できる状態になったときに、iblicense.dll をもう一度ロードして認証コードを

追加します。この順序によって、インストールが完了したときに、何らかの理由で認証コー

ドが追加できないためにアンインストールしなければならないという事態が回避されま

す。

ib_license.dat ファイルの用意

InterBase の認証コードは、InterBase のルートディレクトリにある ib_license.dat ファイル

に格納されています。このファイルには、以前のインストールからの認証コードが含まれて

います。InterBase の旧バージョンの認証コードは現在のバージョンでは機能しませんが、

古いバージョンが必要となった場合のために保持しておく必要があります。このファイルを

削除した場合、InterBase はコードを置き換えることができません。

InterBase CD-ROM には、現在のクライアントバージョン用のクライアント有効化コード

が含まれる ib_license.dat ファイルも入っています。このセクションの以下の手順では、

新のクライアント認証コードが使用されており、前の認証コードが失われていないことを

確認します。


ライセンス A P I の使い方

• InterBase インストールディレクトリに ib_license.dat が存在するかどうかをチェックしま

す。

• ファイルが見つかった場合、それを CD-ROM 内の ib_license.dat に結合して、現在のクラ

イアントの機能を追加します。

• ファイルが見つからない場合は、CD-ROM 内から ib_license.dat を InterBase インストー

ルディレクトリにコピーします。

以上のステップによって、ライセンスが承認されている既存のサーバー機能を維持し、

新のクライアントの機能を提供することができます。

サーバーについて有効化される機能は、各行で有効化される機能を合わせたものになりま

す。

サーバー機能の追加

ib_license.dll には、認証コードの操作に使用できる関数が 5 つあります。

各関数の詳細なリファレンスについては、API ガイドの 15-115 ～ 15-118 ページを参照し

てください。この情報は、HTML 形式（<ib_home>/HtmlRef/ApiFunctionRef.html）でも

ご覧になれます。

• isc_license_add() は、ib_license.dat に行を追加します。Borland から配布コードとして提

供された認証コードだけを使用してください。

• isc_license_check() は、認証コードを ib_license.dat に追加できるかどうかを調べます。この

関数は、ib_license.dat を実際には変更しないことを除けば、isc_license_add() と同じ働きを

します。

• isc_license_remove() は、ib_license.dat から行を削除します。

• isc_license_display() は、ib_license.dat に現在ある認証コードを表示します。

• isc_license_get_msg() は、他の 4 つのライセンス関数が返したエラーコードに対応するエ

ラーメッセージのテキストを返します。

isc_license_add() は、次のエラーを生成します。

表 13.4 isc_license_add() が返すエラーコード

戻り値説明

isc_license_msg_restart 認証コードは正しく追加された。

isc_license_msg_writefailed 認証コードを書き込めなかった。

isc_license_msg_dupid 同じ認証コードがライセンスファイル内にすでにあるため、認証コードは追加できない。

isc_license_msg_convertfailed ID とキーの組み合わせが無効である。


標準的なインストールのためのサンプルコード


以下のコードは、インストールプログラムの記述で一般にとられるステップを示していま

す。インストール API 関数の呼び出しと、それに関連する特有のコードは太字で示してあ

ります。

begin OPTIONS_HANDLEhandle; boolean done = false; LANG_TYPE language;

/* 必要ならばユーザー設定を取得します（別のディレクトリに * 変換した ibinstall.msg ファイルを作成した場合） */

language = get_language_choice(); if (language <> english) isc_install_load_external_text(lang_dirs[language]);

/* すべての有効なオプション名についてインストールを問い合わせます */ while(not all options) begin isc_install_get_info(isc_install_info_opname, option, opname buffer, ISC_INSTALL_MAX_MESSAGE_LEN); isc_install_get_info(isc_install_info_opdescription, option, opdesc buffer, ISC_INSTALL_MAX_MESSAGE_LEN); isc_install_get_info(isc_install_info_opspace, option, opspace buffer, sizeof(unsigned long)); end;

/* 推奨されるインストール先のディレクトリを取得します */ isc_install_get_info(isc_install_info_destination, 0, dest_buffer, ISC_INSTALL_MAX_PATH);

/* ユーザーに選択させて対話させます */ interact_with_user();

/* ユーザーが対話したとき、またはユーザーが［インストール］ボタンを押した後で* isc_install_set_option と isc_install_unset_option のいずれかを使用します * ここで初めてハンドルを 0 にします */

handle = 0L; while (not all options) begin

if(option is selected) isc_install_set_option(&handle, option); // エラーをチェックします

end;

/* source_dir と dest_dir をチェックできます。この例では、 * ディレクトリでチェックは実行されません。また、source_dir または dest_dir が存在しない場合は、 * dest_path ですべてのチェックが実行されるわけではありません */

error = isc_install_precheck(handle, source_path, dest_path); if (error > isc_install_success) then

begin /* Classic サーバーがインストールされているか、任意のサーバーが実行されている場合は、 * エラーを出力して終了します */

isc_install_get_message(error, message, length(message)); user_choice = display(message); do_user_choice();/* たとえば、終了して、オプションの

選択画面に戻ります */end



else if (error < isc_install_success) then begin

/* いくつか警告が発生しました。それらを表示して続行します */ isc_install_get_message(error, message, length(message)) display(message)

end

display_file(install.txt) display_file(license.txt)

/* コールバック関数を提供できますが、お勧めしません。* エラーが発生するとインストールが中止されるためです。エラーによっては無視されるものもあります。* インストール後に手動で解決できる問題もあります。コールバックを使用しない場合は、* ユーザーのステータスを判定できなくなります */

error = isc_install_execute(&handle, source_path, dest_path, NULL, NULL, NULL, NULL, NULL) if (error < 0) then

begin isc_install_get_message(error, message, length(message))

display(message) exit() end else

if (error > 0) then begin

isc_install_get_message(error, message, length(message)) display(message)

end display_file(readme.txt)

/* これは必須です。オプションをクリアしないと、メモリリークが起こります */isc_install_clear_options(&handle) display_done() end


第章

第 14 章 XML のエクスポート

InterBase API を使った XML の生成

InterBase には、InterBase テーブルから直接 XML ドキュメントを生成するための 3 つの

API 呼び出し（isc_dsql_xml_fetch()、isc_dsql_xml_fetch_all()、 isc_dsql_xml_buffer_fetch()）が用意されています。

これらの関数は、ibxml.dll（Windows）または ibxml.so（Solaris および Linux）という

名前の新しいクライアント側ライブラリに含まれます。

• これらの関数のために、ibxml.h ヘッダーファイルでいくつかの構造体が定義されていま

す。

• プロトタイプ定義は ibxml_proto.h ファイルにあります。このヘッダーファイル内で ibxml.hもインクルードされています。

これらの関数を使用するには、このライブラリをリンクパスに追加し、コンパイラのインクルードファイルに新しいヘッダーファイルを追加する必要があります。

新しい関数プロトタイプは次のとおりです。

• isc_dsql_xml_buffer_fetch() は、指定されたバッファに XML 形式のテキストを返します。

int isc_dsql_xml_fetch


isc_stmt_handle *stmt_handle,

unsigned short da_version,

char *buffer

int buffer_size

XSQLDA *xsqlda,

IB_XMLDA *ib_xmlda);

isc_dsql_xml_buffer_fetch() を使用するには、少なくとも 1024 文字のバッファを割り当

て、これを buffer 引数で関数に渡す必要があります。buffer_size 引数には、渡したバッファ

のサイズを指定します。この関数は、バッファに書き込まれた文字のサイズ（終端の NULL

第 1 4 章 X M L のエクスポート 14-1

I n t e r B a s e A P I を使った X M L の生成

を除く）を返します。続行できるだけの十分なメモリがない場合は -1 を返し、ヘッダーと

フッターを完全に格納するだけのバッファサイズがない場合は -2 を返します。この関数が

不完全なヘッダー、フッター、またはレコードを返すことはありません。再度呼び出しを

行って完全な XML バッファを取得する必要がある場合は、xmlda_more_data が設定され

ます。

Delphi でこの呼び出しを使用するには、通常の POINTER 型を使用して、IBXMLDA 構造

体に FILE * 型のスペースを確保します。

• isc_dsql_xml_fetch() は、取得したデータを XML 形式のファイルに追加し、このデータを

XSQLDA に返します。

int isc_dsql_xml_fetch(




XSQLDA *xsqlda,


• isc_dsql_xml_fetch_all() は、前もって作成されて実行されたステートメントハンドルを

使って XML 形式のファイルを作成します。

int isc_dsql_xml_fetch(ISC_STATUS *status_vector, isc_stmt_handle *stmt_handle, unsigned short da_version, XSQLDA *xsqlda, IB_XMLDA *ib_xmlda);

これらの関数は、isc_dsql_prepare() で準備され、isc_dsql_execute() で実行された文を使用

します。ib_xmlda は、初期化された XML デスクリプタエリア（IB_XMLDA）へのポイン

タです。

isc_dsql_xml_fetch() は、XSQLDA を使用して、カーソルでの連続したデータアクセスを許

可します。

Blob と配列はサポートされていません。

IB_XMLDA 構造体

IB_XMLDA 構造体は ibxml.h ファイルに含まれており、定義は次のとおりです。

typedef struct ib_xmlda

{

char ISC_FAR *xmlda_file_name; /* ファイル名を保持する char 文字列へのポインタ。

xml_fetch() によって使用される。

バッファ関数では無視される */

char ISC_FAR *xmlda_header_tag; /* header タグとして出力される

文字列へのポインタ */


I n t e r B a s e A P I を使った X M L の生成

char ISC_FAR *xmlda_database_tag; /* xml ファイルに database タグとして出力される


char ISC_FAR *xmlda_table_tag; /* xml ファイルに tablename タグとして出力される


char ISC_FAR *xmlda_row_tag; /* xml ファイルに rowname タグとして出力される


FILE *xmlda_file_ptr; /* ファイルポインタを保持するために

API によって内部的に使用される。 C、C++ 以外のプログラムでは POINTER 型 */

char ISC_FAR **xmlda_temp_buffer; /* 内部使用のみ。fetch() から返される

String 配列を格納するために使用される */

ISC_STATUS xmlda_fetch_stat; /* この要素は、isc_dsql_fetch() 呼び出しの戻り値を保持し、すべてのレコードを受け取ったか、エラーが発生したかを示す */

ULONG xmlda_flags; /* フラグ（後で説明） */

ULONG xmlda_more_data; /* バッファ呼び出しよって使用され、

後のレコードの状態を維持する。

これ以上データがない場合は 0、

さらにデータが取り出されてもバッファ

に格納されない場合は 1 を返す */ULONG xmlda_temp_size; /* 内部使用のみ。後のレコードの

サイズを格納するために使用される */

USHORT xmlda_status; /* 内部状態は、初に呼び出す際に

ユーザーが 0 に設定する必要がある */

USHORT xmlda_more; /* このフラグは、バッファモードで使用される。さらに XML データがある場合にこのフラグを設定する */

USHORT xmlda_version; /* XMLDA のバージョン */

USHORT xmlda_array_size; /* 内部使用のみ */

SLONG xmlda_reserved; /* 将来の使用のために予約 */} IB_XMLDA;

IB_XMLDA 構造体の必須の要素3 つの XML 関数のいずれかを呼び出す前に、次の IB_XMLDA 構造体の要素を設定する


1 xmlda_file_name：XML 出力が書き込まれるファイルのフルパスを含む名前です。この名

前は、isc_dsql_xml_fetch() と isc_dsql_xml_fetch_all() で必要です。

2 xmlda_version：1 に設定する必要があります。これは、パーサーが SQLDA デスクリプ

タエリアではなく、XSQLDA デスクリプタエリアを使用することを指定します。


X M L 生成の例

3 xmlda_status：isc_dsql_xml_fetch() を初めて呼び出すときに 0 に設定する必要がありま

す。isc_dsql_fetch_all() では何の効果もありませんが、0 に設定することをお勧めしま

す。これは、状態を保持するために XML 関数によって内部的に使用されます。

IB_XMLDA 構造体のオプションの要素1 xmlda_header_tag：XML ヘッダーとして使用される文字列へのポインタです。NULL に

設定すると、デフォルトのヘッダー <?xml version="1.0"> が出力されます。

2 xmlda_database_tag：Database タグのかわりに使用できる文字列へのポインタですこの

後の XML ドキュメントの例を参照してください。NULL に設定すると、この XML タグはデフォルトの “Database” になります。

3 xmlda_table_tag：Tablename タグのかわりに使用できる文字列へのポインタですこの後

の XML ドキュメントの例を参照してください。NULL に設定すると、この XML タグ

はデフォルトの “Tablename” になります。

4 xmlda_row_tag：Row タグのかわりに使用できる文字列へのポインタですこの後の XMLドキュメントの例を参照してください。NULL に設定すると、この XML タグはデフォ

ルトの “Row” になります。

5 xmlda_flags：現在、次の 2 つの値を設定できます。

• XMLDA_ATTRIBUTE_FLAG は、XML ドキュメントをタグではなく属性として生成

します。

• XMLDA_NO_NULL_DISPLAY_FLAG は、NULL データとそれらに関連するタグを表

示しません。

定義ibxml.h には次の 3 つの定義があります。

• XMLDA_ATTRIBUTE_FLAG：1 に設定すると、データを属性として出力します。

#define XMLDA_ATTRIBUTE_FLAG 0x01

• XMLDA_NO_NULL_DISPLAY_FLAG：NULL データを表示しません。

#define XMLDA_NO_NULL_DISPLAY_FLAG 0x02

• XMLDA_NO_HEADER_FLAG：追加のヘッダーを表示しません。

#define XMLDA_NO_HEADER_FLAG 0x04

XMLDA_ATTRIBUTE_FLAG は、出力を要素ではなく属性として生成します。このフラグは、

InterBase によって生成された実際のデータだけに影響し、ユーザーは目的の属性をタグ

として挿入することでその他のすべてのタグを制御できます。

XMLDA_NULL_NO_DISPLAY_FLAG を設定すると、API は、NULL のデータの行の生成を

スキップします。デフォルトの動作では、空文字列が生成されます。

XML 生成の例

ここでは、InterBase テーブルから XML を生成する方法の完全な例を示します。


X M L 生成の例

XML 出力構造体

生成される XML の一般的な形式は次のとおりです。

<?xml version="1.0">

<Database>

<Tablename>

<Row>

<ColumnAlias1>Data</ColumnAlias1>


</Row>

<Row>



</Row>

…

</Tablename>

</Database>

C プログラム

次の C コードは、データベースサンプルの employee.gdb を使って InterBase XML API を呼び出し、emp.xml XML ファイルを生成する方法を示します。

#include <stdlib.h>

#include <string.h>

#include <stdio.h>

#include <ibase.h>

#include <ibxml_proto.h>

#define ERREXIT(status, rc) {isc_print_status(status); return rc;}

#define LASTLEN 20

#define FIRSTLEN 15

#define EXTLEN 4

/* このマクロは、SQL VARCHAR 型を表す構造体の宣言に使用されます */

#define SQL_VARCHAR(len) struct {short vary_length; char vary_string[(len)+1];}

int main (ARG(int, argc), ARG(char **, argv))

ARGLIST(int argc)

ARGLIST(char **argv)

{

char last_name[LASTLEN+2];

char first_name[FIRSTLEN+2];

char file_name [1024];

char phone_ext[EXTLEN + 2];

short flag0 = 0, flag1 = 0;

short flag2 = 0;


X M L 生成の例

isc_stmt_handle stmt = NULL; /* ステートメントハンドル */

isc_db_handle DB = NULL; /* データベースハンドル */

isc_tr_handle trans = NULL; /* トランザクションハンドル */

long status[20]; /* ステータスベクター */XSQLDA ISC_FAR * sqlda;

long fetch_stat;

char empdb[128];

char *sel_str =

"SELECT last_name, first_name, phone_ext FROM phone_list ¥

WHERE location = 'Monterey' ORDER BY last_name, first_name;";

IB_XMLDA xmlda;

char version[] = "<?xml version = ¥"1.0¥"?>¥n

¥n";

char employeedb[] = "Employee_DB";

char tbname[] = "PhoneList";

char rowname[] = "Employee";

FILE *xmlfptr;

xmlda.xmlda_status = 0;

xmlda.xmlda_version = 1;

xmlda.xmlda_header_tag = version;

xmlda.xmlda_database_tag = employeedb;

xmlda.xmlda_table_tag = tbname;

xmlda.xmlda_row_tag = rowname;

if (argc > 1)

strcpy(empdb, argv[1]);

else

strcpy(empdb, "D:¥¥smistry¥¥work¥¥IB6.5¥¥XML¥¥XML¥¥employee.gdb");

if (isc_attach_database(status, 0, empdb, &DB, 0, NULL))


if (isc_start_transaction(status, &trans, 1, &DB, 0, NULL))

{

ERREXIT(status, 1)

}

/* 出力 SQLDA を割り当てます */sqlda = (XSQLDA ISC_FAR *) malloc(XSQLDA_LENGTH(3));

sqlda->sqln = 3;

sqlda->sqld = 3;

sqlda->version = 1;

/* ステートメントハンドルを割り当てます */if (isc_dsql_allocate_statement(status, &DB, &stmt))

{

ERREXIT(status, 1)

}

/* 文を作成します */if (isc_dsql_prepare(status, &trans, &stmt, 0, sel_str, 1, sqlda))


X M L 生成の例

{

ERREXIT(status, 1)

}

/*

* 選択された 3 つの列の型は varchar ですが、

* 3 番めのフィールドは TEXT 型に変更されて出力されます*/

sqlda->sqlvar[0].sqldata = (char *)&last_name;

sqlda->sqlvar[0].sqltype = SQL_TEXT + 1;

sqlda->sqlvar[0].sqlind = &flag0;

sqlda->sqlvar[1].sqldata = (char *)&first_name;



sqlda->sqlvar[2].sqldata = (char ISC_FAR *) phone_ext;



printf("¥n%-20s %-15s %-10s¥n¥n", "LAST NAME", "FIRST NAME", "EXTENSION");

/* 文を実行します */if (isc_dsql_execute(status, &trans, &stmt, 1, NULL))

{

ERREXIT(status, 1)

}

/* レコードを取り出して出力します

* 後の行が取り出された後の状態は 100 です */

/* XML 用のファイルを開きます */

/* バッファ呼び出しを使用する場合はここから置き換えます */

strcpy (file_name, "D:¥¥smistry¥¥work¥¥IB6.5¥¥XML¥¥XML¥¥emp.xml");

xmlda.xmlda_file_name = file_name;

while ((fetch_stat = isc_dsql_xml_fetch(status, &stmt, 1, sqlda, &xmlda)) == 0)/* 呼び出し側はまだ sqlda 変数にアクセスできます */

/* 呼び出し側はまだ sqlda 変数にアクセスできます */

{

printf("%-s", last_name);

printf("%-s", first_name);

printf("%s¥n", phone_ext);

}

/* バッファ呼び出しの置き換えはここまで */if (fetch_stat != 100L)

{

ERREXIT(status, 1)

}

/* ステートメントハンドルを解放します */if (isc_dsql_free_statement(status, &stmt, DSQL_close))

{

ERREXIT(status, 1)


X M L 生成の例

}

if (isc_commit_transaction(status, &trans))

{

ERREXIT(status, 1)

}

if (isc_detach_database(status, &DB))

{

ERREXIT(status, 1)

}

free( sqlda);

return 0;

}

XML 出力上のコードは、次の XML ファイルを生成します。

<?xml version="1.0"?>



<Employee_DB>

<PhoneList>

<Employee>

<LAST_NAME>Bender</LAST_NAME>

<FIRST_NAME>Oliver H.</FIRST_NAME>

<PHONE_EXT>255</PHONE_EXT>

</Employee>

<Employee>

<LAST_NAME>Bishop</LAST_NAME>

<FIRST_NAME>Dana</FIRST_NAME>


</Employee>

<Employee>

<LAST_NAME>Brown</LAST_NAME>

<FIRST_NAME>Kelly</FIRST_NAME>


</Employee>

<Employee>

<LAST_NAME>Burbank</LAST_NAME>

<FIRST_NAME>Jennifer M.</FIRST_NAME>


</Employee>

<Employee>

<LAST_NAME>De Souza</LAST_NAME>

<FIRST_NAME>Roger</FIRST_NAME>


</Employee>

…


X M L 生成の例

…

<Employee>

<LAST_NAME>Young</LAST_NAME>

<FIRST_NAME>Katherine</FIRST_NAME>


</Employee>

</PhoneList>

</Employee_DB>

xmlda_flags の使い方

次の例は、XMLDA_ATTRIBUTE_FLAG と XMLDA_NO_HEADER の使い方を示します。

XMLDA_ATTRIBUTE_FLAGXMLDA_ATTRIBUTE_FLAG を設定すると、データが要素ではなく属性として出力されます。

このフラグは、InterBase から生成された実際のデータだけに影響します。目的の属性を

タグとして入力することでその他のすべてのタグを制御できます。このフラグを設定する

と、次のような XML ファイルが生成されます。

<?xml version="1.0"?>



<Employee_DB>

<PhoneList>

<Employee>

<LAST_NAME="Bender">

<FIRST_NAME="Oliver H.">

<PHONE_EXT="255">

</Employee>

<Employee>

<LAST_NAME="Bishop">

<FIRST_NAME="Dana">

<PHONE_EXT="290">

</Employee>

…

…

<Employee>

<LAST_NAME="Young">

<FIRST_NAME="Katherine">

<PHONE_EXT="231">

</Employee>

</PhoneList>

</Employee_DB>


X M L 生成の例

XMLDA_NO_HEADER XMLDA_NO_HEADER フラグを設定すると、ヘッダーが表示されなくなります。この例で

は、次のような XML ファイルが生成されます。

<Employee>

<LAST_NAME>Bender</LAST_NAME>

<FIRST_NAME>Oliver H.</FIRST_NAME>


</Employee>

<Employee>

<LAST_NAME>Bishop</LAST_NAME>

<FIRST_NAME>Dana</FIRST_NAME>


</Employee>

…

…

<Employee>

<LAST_NAME>Young</LAST_NAME>

<FIRST_NAME>Katherine</FIRST_NAME>


</Employee>

}


第章

第 15 章 API 関数リファレンス

この章は、InterBase API 関数のアルファベット順のリファレンスです。初に関数が行

うタスクによって分類したカテゴリ別の表を示し、その後に各関数について、構文、引数、

使用例、および関連関数を含む詳細な解説をアルファベット順に記載しています。

この章は、HTML 形式（<ib_home>/HtmlRef/ApiFunctionRef.html）でもご覧になれます。

関数のカテゴリ

InterBase API 関数は、以下の 12 のクラスに分類されます。

• 配列関数：データの配列を扱う

• BLOB 関数： InterBase の BLOB データ型を扱う

• データベース関数：データベースに対する要求を処理する

• 変換関数： InterBase の日付形式と C 言語の tm 構造体形式間のデータの変換、および整

数のバイト順の反転を行う

• DSQL 関数：実行時にユーザーが入力する SQL ステートメントを処理する

• エラー処理関数

• イベント関数：アプリケーション内でトリガーおよびストアドプロシージャが通知したイ

ベントを登録し、イベントキューを処理する

• 情報関数：データベース、トランザクション、BLOB データ、およびイベントに関する情

報を取得する

• インストール関数： InterBase の自動埋め込みインストールを記述する

• セキュリティ関数：パスワードデータベース内のユーザーレコードの追加、削除、および

変更を行う

• サービス関数：サーバーおよびデータベースのプロパティを管理する

• トランザクション関数：アプリケーション内のトランザクションを処理する

第 1 5 章 A P I 関数リファレンス 15-1


情報の取り出しなど、複数のクラスに存在する関数もあります。

配列関数

アプリケーションで配列の処理に使用できる InterBase API 関数は次のとおりです。

BLOB 関数

アプリケーションで BLOB データの処理に使用できる InterBase API 関数は次のとおり

です。

表 15.1 配列関数

関数名用途

isc_array_get_slice2() 配列フィールドの指定の部分を取り出す

isc_array_lookup_bounds2() 配列フィールドの次元を指定する

isc_array_lookup_desc2() 配列の記述を取り出す

isc_array_put_slice2() 配列フィールドの指定の部分を書き込む

isc_array_set_desc2() 配列の記述を設定する

表 15.2 BLOB 関数

関数名用途

isc_blob_default_desc2() 動的アクセス用に BLOB のデフォルト記述を設定する

isc_blob_gen_bpb2() 動的アクセス用に BLOB パラメータバッファ（BPB）を生成する

isc_blob_info() BLOB フィールドに関する情報を取得する

isc_blob_lookup_desc2() BLOB デスクリプタを取得する

isc_blob_set_desc2() BLOB デスクリプタを設定する

isc_cancel_blob() BLOB を破棄する

isc_close_blob() BLOB を閉じる

isc_create_blob2() 新しい BLOB を作成する

isc_get_segment() BLOB データのセグメントを取得する

isc_open_blob2() 読み取りアクセス用に BLOB を開く

isc_put_segment() BLOB データのセグメントを書き込む



データベース関数

アプリケーションでデータベースへの要求の処理に使用できる InterBase API 関数は次の

とおりです。

変換関数

InterBase の DATE、TIME、および TIMESTAMP 形式と C 言語の日付時刻形式間のデータ

の変換、および整数のバイト順の反転に使用できる InterBase API 関数は次のとおりです。

メモ下位互換性を保つ目的で、isc_encode_date() 関数および isc_decode_date() 関数はこのバージョ

ンでも残されています。これらの関数は、isc_encode_timestamp() および isc_decode_timestamp()と同じ機能を持ちます。

表 15.3 データベース関数

関数名用途

isc_attach_database() 既存のデータベースに接続する

isc_database_info() 接続しているデータベースに関する情報を取得する

isc_detach_database() データベースから切断する

isc_drop_database() 接続しているデータベースとその関連ファイルを削除する

isc_expand_dpb() データベースパラメータバッファ（DPB）を動的に構築する

isc_version() データベースの実装番号と、オンディスク構造体（ODS）のメジャーおよびマイナーバージョン番号を取得する

表 15.4 日付時刻および変換関数

関数名用途

isc_decode_sql_date() 日付を InterBase 形式から C の tm 構造体形式に変換する

isc_encode_sql_date() 日付を C の tm 構造体形式から InterBase 形式に変換する

isc_decode_sql_time() 時刻を InterBase 形式から C の tm 構造体形式に変換する

isc_encode_sql_time() 時刻を C の tm 構造体形式から InterBase 形式に変換する

isc_decode_timestamp() 日付および時刻を C の tm 構造体形式から InterBase 形式に変換する

isc_encode_timestamp() 日付および時刻を C の tm 構造体形式から InterBase 形式に変換する

isc_portable_integer() 整数のバイト順を反転する



DSQL 関数

実行時にユーザーが入力する DSQL ステートメントの処理に使用できる InterBase API関数は次のとおりです。

表 15.5 DSQL 関数

関数名用途

isc_dsql_allocate_statement() ステートメントハンドルを割り当てる

isc_dsql_alloc_statement2() データベースのデタッチの際に自動的に解放されるステートメントハンドルを割り当てる

isc_dsql_describe() DSQL ステートメントが返した値に関する情報を XSQLDA に入れる

isc_dsql_describe_bind() DSQL ステートメントの入力パラメータに関する情報をXSQLDA に入れる

isc_dsql_execute() 作成済みの DSQL ステートメントを実行する

isc_dsql_execute2() 値のセット 1 つを返す作成済みの DSQL ステートメントを実行する

isc_dsql_execute_immediate() 1 回だけ使用する、戻り値のない DSQL ステートメントを作成して実行する

isc_dsql_exec_immed2() 1 回だけ使用する、戻り値のセットを 1 つ返す DSQL ステートメントを作成して実行する

isc_dsql_fetch() 前に作成して実行した DSQL ステートメントが返した値を取得する

isc_dsql_free_statement() ステートメントを解放する、またはステートメントハンドルに関連付けられているカーソルを閉じる

isc_dsql_prepare() 実行する DSQL ステートメントを作成する

isc_dsql_set_cursor_name() カーソル名を定義し、ステートメントハンドルに関連付ける

isc_dsql_sql_info() 作成済みの DSQL ステートメントに関する情報を取得する



エラー処理関数

アプリケーションのエラー条件の処理に使用できる InterBase API 関数は次のとおりで

す。

イベント関数

アプリケーション内のイベントの処理に使用できる InterBase API 関数は次のとおりで

す。

情報関数

データベース、トランザクション、BLOB データに関する情報を、要求したクライアント

アプリケーションに報告するために使用できる InterBase API 関数は次のとおりです。

表 15.6 エラー処理関数

関数名用途

isc_interprete() InterBase のエラーメッセージを捕捉してバッファに入れる

isc_print_sqlerror() SQL のエラーメッセージを表示する

isc_print_status() InterBase のエラーメッセージを表示する

isc_sqlcode() SQLCODE の値を設定する

isc_sql_interprete() SQL のエラーメッセージを捕捉してバッファに入れる

表 15.7 イベント関数

関数名用途

isc_cancel_events() イベントの関連性を取り消す

isc_event_block() イベントパラメータバッファを割り当てる

isc_event_counts() イベント配列内のイベントカウンタの値の変化を取得する

isc_que_events() イベントがポストされるまで非同期で待機する

isc_wait_for_event() イベントがポストされるまで同期して待機する

表 15.8 情報関数

関数名用途

isc_blob_info() BLOB フィールドに関する情報を取得する

isc_database_info() 接続しているデータベースに関する情報を取得する



インストール関数

アプリケーションのインストールルーチンの作成に使用できる InterBase API 関数は次の

とおりです。

ライセンス関数

次の表は、 Certification ID と Certification Key のペア（認証コード）を追加、削除、お

よび表示するために使用できる InterBase API 関数です。5 番めの関数は、他の 4 つの関

数から返される値に対応するメッセージを取り出して表示します。

isc_dsql_sql_info() 作成済みの DSQL ステートメントに関する情報を取得する

isc_transaction_info() 指定されたトランザクションに関する情報を取得する

isc_version() データベースの実装番号と、オンディスク構造体（ODS）のメジャーおよびマイナーバージョン番号を取得する

表 15.9 インストール関数

関数名用途

isc_install_clear_options() isc_install_set_option() によって設定されたオプションをすべてクリアする

isc_install_execute() インストールを実行する

isc_install_get_info() 要求された情報を返す

isc_install_get_message() 要求されたエラーまたは警告メッセージのテキストを返す

isc_install_load_external_text() 指定されたファイルからメッセージをロードする

isc_install_precheck() インストール環境に関するチェックを行う

isc_install_set_option() 選択されたインストールオプションのリストのハンドルを作成する

isc_install_unset_option() 選択されたオプションのリストからオプションを削除する

isc_uninstall_execute() 以前にインストールされたファイルを削除する

isc_uninstall_precheck() 現在のシステムとアンインストールファイルの有効性をチェックする

表 15.8 情報関数 ( 続き )

関数名用途



サービス関数

サーバーおよびデータベース管理タスクのプログラム制御に使用できる InterBase API 関数は次のとおりです。

トランザクション制御関数

アプリケーション内のトランザクションの制御に使用できる InterBase API 関数は次のと

おりです。

表 15.10 ライセンス関数

関数名用途

isc_license_add() InterBase ライセンスファイルに Certification ID とCertification Keyのペアを追加する

isc_license_check() 提供された ID とキーのペアが有効であるかどうかをチェックする

isc_license_remove() InterBase ライセンスファイルから指定された行を削除する

isc_license_display() InterBase ライセンスファイルから ID と Key のペアをバッファにコピーする

isc_license_get_msg() エラーコードのテキストを返す

表 15.11 サービス関数

関数名用途

isc_service_attach() InterBase Services Manager 機能に接続する。InterBase サービスを使用する前に必要

isc_service_detach() InterBase Services Manager への接続を終了する

isc_service_query() クライアントが接続している InterBase サーバーに関する情報を要求して取得する

isc_service_start() クライアントが接続している InterBase サーバー上でサービスタスクを実行する

表 15.12 トランザクション制御関数

関数名用途

isc_commit_retaining() トランザクションをコミットし、元のトランザクションのコンテキストを使って新しいトランザクションを開始する

isc_commit_transaction() トランザクションをコミットし、トランザクションを終了する

isc_prepare_transaction() 2 相コミットの第 1 フェーズを実行する

isc_prepare_transaction2() 2 相コミットの第 2 フェーズを実行する


関数リファレンスの表記

関数リファレンスの表記

この章の各関数の定義では、下記の項目があります。

isc_add_user()

InterBase セキュリティデータベース（デフォルトは admin.ib）にユーザーレコードを追

加します。

メモこの関数は使用しないでください。かわりに、機能の完備したサービス API を使用してくだ

さい。12-1 ページの第 12 章「サービスの操作」および 15-139 ページの「isc_service_start()」のリファレンス項目を参照してください。

isc_rollback_transaction() トランザクションをロールバックし、トランザクションを終了する

isc_rollback_retaining() トランザクションをロールバックし、元のトランザクションのコンテキストを使って新しいトランザクションを開始する

isc_start_multiple() 新しいトランザクションを開始する（可変個の入力引数をサポートしないシステムで使用する）

isc_start_transaction() 新しいトランザクションを開始する

isc_transaction_info() 指定されたトランザクションに関する情報を取得する

表 15.12 トランザクション制御関数 ( 続き )

関数名用途

表 15.13 関数の説明の形式

要素説明

タイトル関数名

定義関数の主な用途

構文関数とパラメータの呼び出し形式

パラメータ各パラメータの説明

説明関数の使い方に関する詳細な情報

例関数を使用したプログラム例

戻り値（もしあれば）ステータスベクターに返される値の説明

参照他の関連する関数


i s c _ a d d _ u s e r ( )

構文 ISC_STATUS isc_add_user(

ISC_STATUS *status

USER_SEC_DATA *user_sec_data);

説明 3 つのセキュリティ関数 isc_add_user()、isc_delete_user()、および isc_modify_user() によっ

て、gsec コマンドラインユーティリティと同等の機能が提供されます。isc_add_user() は、

InterBase セキュリティデータベース（デフォルトは admin.ib）にレコードを追加します。

少なくともユーザー名とパスワードを指定しなければなりません。サーバーがローカルで

ない場合は、サーバー名とプロトコルも指定する必要があります。プロトコルフィールド

の有効な値は、sec_protocol_tcpip、sec_protocol_netbeui、および sec_protocol_local のい

ずれかです。

DBA のユーザー名とパスワードが与えられていない場合、InterBase は環境変数

ISC_USER と ISC_PASSWORD の設定を読み取ります。

USER_SEC_DATA 構造体は ibase.h で次のように定義されています。

typedef struct {

short sec_flags; /* 指定するフィールド */

int uid; /* ユーザー ID */

int gid; /* ユーザーのグループ ID */

int protocol; /* 接続に使用するプロトコル */

char *server; /* 管理するサーバー */

char *user_name; /* ユーザー名 */

char *password; /* ユーザーのパスワード */char *group_name; /* グループ名 */

char *first_name; /* ユーザーの名 */

char *middle_name; /* ユーザーのミドルネーム */

char *last_name; /* ユーザーの姓 */

char *dba_user_name; /* DBA のユーザー名 */

char *dba_password; /* DBA のパスワード */} USER_SEC_DATA;

この構造体をセキュリティ関数に渡すときには、ibase.h で定義されている以下の値のビッ

トごとの論理和（OR）を使用して、どのフィールドが指定されているかを示すことができ

ます。

sec_uid_spec 0x01

sec_gid_spec 0x02

sec_server_spec 0x04

sec_password_spec 0x08

sec_group_name_spec 0x10

sec_first_name_spec 0x20


status vector ISC_STATUS * エラーステータスベクターへのポインタ

user_sec_data USER_SEC_DATA * ibase.h で定義されている構造体へのポインタ


i s c _ a d d _ u s e r ( )

sec_middle_name_spec 0x40

sec_last_name_spec 0x80

sec_dba_user_name_spec 0x100

sec_dba_password_spec 0x200

ユーザー名とパスワードは必ず指定しなければならないので、対応するビット値はありま

せん。

この関数については、次のエラーメッセージが生じる可能性があります。

表 15.14 isc_adduser() のエラーメッセージ

コード値説明

isc_usrname_too_long 335544747 The user name passed in is greater than 31bytes（ユーザー名が長すぎます。大長は 31 バイトです）

isc_password_too_long 335544748 The password passed in is longer than 8bytes（パスワードが長すぎます。大長は 8 バイトです）

isc_usrname_required 335544749 The operation requires a user name（この操作にはユーザー名が必要です）

isc_password_required 335544750 The operation requires a password（この操作にはパスワードが必要です）

isc_bad_protocol 335544751 The protocol specified is invalid（無効なネットワークプロトコルが指定されました）

isc_dup_usrname_found 335544752 The user name being added already existsin the security database（セキュリティデータベース内でユーザー名が重複しています）

isc_usrname_not_found 335544753 The user name was not found in thesecurity database（セキュリティデータベース内に、指定されたユーザー名が見つかりませんでした）

isc_error_adding_sec_record 335544754 An unknown error occurred whileadding a user（ユーザーの追加時にエラーが発生しました）


i s c _ a d d _ u s e r ( )

例次の例では、ビットごとの論理和を使って USER_SEC_DATA 構造体内の値を渡して、パ

スワードデータベースにユーザー（"Socks"）を追加します。

{


USER_SEC_DATA sec;

sec.server = "kennel";

sec.dba_user_name= "sysdba";

sec.dba_password = "masterkey";

sec.protocol = sec_protocol_tcpip;

sec.first_name = "Socks";

sec.last_name = "Clinton";

sec.user_name = "socks";

sec.password = "2meow!"; /* メモ：パスワードはハードコードしないでください */sec.sec_flags = sec_server_spec

| sec_password_spec

| sec_dba_user_name_spec

| sec_dba_password_spec

| sec_first_name_spec

| sec_last_name_spec;

isc_add_user(status, &sec);

/* エラーがないかどうかステータスをチェックします */if (status[0] == 1 && status[1])

{

switch (status[1]) {

case isc_usrname_too_long:

printf("Security database cannot accept long user names¥n");

break;

...

}

}

isc_error_deleting_sec_record 335544755 An unknown error occurred whileadding a user（ユーザーの追加時にエラーが発生しました）

isc_error_modifying_sec_record 335544756 An unknown error occurred whiledeleting a user（ユーザーレコードの変更時にエラーが発生しました）

isc_error_updating_sec_db 335544757 An unknown error occurred whileupdating the security database（セキュリティデータベースの更新時にエラーが発生しました）

表 15.14 isc_adduser() のエラーメッセージ

コード値説明


i s c _ a r r a y _ g e t _ s l i c e ( )

}

戻り値 isc_add_user() は、ステータスベクターの第 2 要素を返します。0 の場合は、正常に終了し

たことを示します。0 以外の場合は、エラーが発生したことを示します。ステータスベク

ターの値を調べる方法については、第 10 章「エラー条件の処理」を参照してください。

参照 isc_delete_user()

isc_array_get_slice()

非推奨。isc_array_get_slice2() と機能は同じですが、32 バイトより長いメタデータ名をサ

ポートしません。

isc_array_get_slice2()

SELECT から返された行の配列型の列からデータを抽出します。

構文 ISC_STATUS isc_array_get_slice2(


isc_db_handle *db_handle,


ISC_QUAD *array_id,

ISC_ARRAY_DESC_V2 *desc,

void *dest_array,ISC_LONG *slice_length);


status_vector ISC_STATUS * エラーステータスベクターへのポインタ

db_handle isc_db_handle * isc_attach_database() の呼び出しで前もって設定されているデータベースハンドルへのポインタ。このハンドルは、配列型の列が含まれるデータベースを識別する。

db_handle が NULL の場合は status_vector にエラーが返される

trans_handle isc_tr_handle * isc_start_transaction() の呼び出しで前もって設定されているトランザクションハンドルを指すポインタ。trans_handle が NULL の場合はエラーが返される

array_id ISC_QUAD * 配列の内部 ID。配列 ID は、API DSQL 関数によって前もって抽出されていなければならない。


i s c _ a r r a y _ g e t _ s l i c e 2 ( )

isc_array_get_slice2() は、テーブルの行の配列型の列から配列 ID に基づいてデータを抽

出します。指定した列のすべての配列要素、または連続した配列要素（スライス）を抽出

することができます。desc 構造体の上限値と下限値によって、抽出する要素を指定します。

InterBase は、slice_length で指定されたサイズのバッファ dest_array に要素をコピーしま

す。バッファのサイズは、抽出される要素の予想される長さ以上でなければなりません。

InterBase は、実際にコピーしたバイト数を slice_length に設定して、isc_array_get_slice2()から復帰します。

isc_array_get_slice2() を呼び出す前に、配列デスクリプタ desc の値を設定し、適切な内部

配列識別子 array_id を指定し、アクセスする配列型の列を含む行を取り出しておく必要が

あります。配列デスクリプタを設定して配列情報を抽出する手順については、第 8 章「配

列データの操作」を参照してください。

メモ単一の要素を取り出す場合以外は、配列型の列のデータに直接アクセスしようとする DSQLステートメントを実行してはなりません。配列型列データにアクセスする方法は、

isc_array_get_slice2() または isc_array_put_slice2() の呼び出し以外にはありません。DSQLステートメントでサポートされている配列参照は、配列型の列全体（つまり列名）を指定し

て配列の内部識別子を取得することだけで、これは isc_array_get_slice2() と

isc_array_put_slice2()、および単一要素の参照で必要になります。

例次のプログラムは、テーブル PROJ_DEPT_BUDGET に対して動作します。このテーブルに

は、会社の各部門で実施するプロジェクトに割り当てられた、四半期ごとの人数が保持さ

れています。テーブルの各行は、特定の部門とプロジェクトに対応します。四半期ごとの

人数は、配列型の列 QUARTERLY_HEAD_CNT に保持されています。この列の各行には 4 つの要素があります。配列の各要素は long 型の数値になります。

このプログラムは、VBASE という名前のプロジェクトに関する 1994 年の情報を保持して

いる行を選択します。その各行について、部門番号と配列型の列のデータ（四半期ごとの

人数）を抽出して出力します。

また、このプログラム例は、isc_array_lookup_bounds2() と isc_array_get_slice2() の使い

方、およびデータ構造体の初期化方法および DSQL 関数の呼び出し方法を示しています。

DSQL 関数は SELECT ステートメントを作成して実行し、isc_array_get_slice2() に必要な

array_id を取得して、選択した行を 1 行ずつ取り出します。

#include <ibase.h>

#define Return_if_Error(stat) if (stat[0] == 1 && stat[1]) ¥

{ ¥

isc_print_status(stat); ¥

return(1); ¥

desc ISC_ARRAY_DESC _V2* 抽出する配列スライス（配列の全体または一部）を定義するデスクリプタ。

dest_array void * isc_array_get_slice() 関数によってコピーされる配列スライスのコピー先となる、長さ slice_length のバッファへのポインタ。

slice_length ISC_LONG * dest_array バッファの長さ（バイト数）。




}

char *sel_str =

"SELECT dept_no, quarterly_head_cnt FROM proj_dept_budget ¥

WHERE year = 1994 AND proj_id = 'VBASE'";

char dept_no[6];

long hcnt[4], tr_handle, database_handle, SQLCODE;

short len, i, flag0, flag1;

ISC_QUAD array_id;


ISC_STATUS status_vector[20], fetch_stat;

isc_stmt_handle stmt = NULL;

XSQLDA *osqlda;

tr_handle = database_handle = 0L;

/* ここでデータベースに接続します。コードは省略します */

/* ここでトランザクションを開始します。コードは省略します */

/* SELECT ステートメントを設定します */

/* 配列データを保持するための出力 XSQLDA を割り当てます */osqlda = (XSQLDA *)malloc(XSQLDA_LENGTH(2));

osqlda->sqln = 2;

osqlda->version = 1;

/* ステートメントハンドルを割り当てます */isc_dsql_allocate_statement(

status_vector,

&database_handle,

&stmt);

Return_if_Error(status_vector);

/* クエリーの実行を準備します */isc_dsql_prepare(

status_vector,

&tr_handle,

&stmt,

0,

sel_str,

1,

osqlda);


/* XSQLVAR を設定して、取得する各項目の領域を

割り当てます */osqlda->sqlvar[0].sqldata = (char *) dept_no;

osqlda->sqlvar[0].sqltype = SQL_TEXT + 1;

osqlda->sqlvar[0].sqlind = &flag0;

osqlda->sqlvar[1].sqldata = (char *) &array_id;

osqlda->sqlvar[1].sqltype = SQL_ARRAY + 1;


/* SELECT ステートメントを実行します */



isc_dsql_execute(

status_vector,

&tr_handle,

&stmt,

1,

NULL);


/* 配列デスクリプタを設定します */isc_array_lookup_bounds2(

status_vector,

&database_handle, /* 先の isc_attach_database() 呼び出しで設定されます */


"PROJ_DEPT_BUDGET", /* テーブル名 */

"QUARTERLY_HEAD_CNT", /* 配列型の列の名前 */&desc);


/* 各部門の四半期ごとに人数を取り出します */while ((fetch_stat = isc_dsql_fetch(

status_vector,

&stmt,

1,

osqlda)) == 0)

{

if (!flag1)

{

/* 配列データがあります。現在の値を取得します */len = sizeof(hcnt);

/* 配列型の列からデータを取り出し、hcnt 配列に格納します */isc_array_get_slice2(

status_vector,

&database_handle,

&tr_handle,

&array_id,

&desc,

hcnt,

&len);


/* 部門番号と人数を出力します */dept_no[osqlda->sqlvar[0].sqllen] = '¥0';

printf("Department #: %s¥n¥n", dept_no);

printf("¥tCurrent counts: %d %d %d %d¥n",

hcnt[0], hcnt[1], hcnt[2], hcnt[3]);

};


i s c _ a r r a y _ l o o k u p _ b o u n d s ( )

}


{



return(1);

}

戻り値 isc_array_get_slice2() は、ステータスベクターの第 2 要素を返します。0 の場合は正常に

終了したことを示します。0 以外の場合は、エラーが発生したことを示します。InterBaseエラーの場合は、ステータスベクターの第 1 要素が 1 に設定され、第 2 要素は、

isc_bad_stmt_handle、isc_bad_trans_handle、または他の InterBase エラーコードに設定

されます。

InterBase エラーの有無を判定するには、ステータスベクターの先頭の 2 つの要素を直接

チェックします。ステータスベクターの値を調べる方法については、第 10 章「エラー条

件の処理」を参照してください。

参照 isc_array_lookup_bounds2()、isc_array_lookup_desc2()、isc_array_put_slice2()、isc_array_set_desc2()、isc_dsql_fetch()、isc_dsql_prepare()

isc_array_lookup_bounds()

非推奨。isc_array_lookup_bounds2() と機能は同じですが、32 バイトより長いメタデータ

名をサポートしません。

isc_array_lookup_bounds2()

指定されたテーブルの指定された配列型の列の、データ型、長さ、小数点以下の桁数、次

元、配列の範囲を判定します。

構文 ISC_STATUS isc_array_lookup_bounds2(




char *table_name,

char *column_name,

ISC_ARRAY_DESC_V2 *desc);


i s c _ a r r a y _ l o o k u p _ b o u n d s 2 ( )

説明 isc_array_lookup_bounds2() は、テーブル table_name の配列型の列 column_name の各要

素について、データ型、長さ、小数点以下の桁数、次元、配列の範囲を判定し、その情報

を配列デスクリプタ desc に格納します。

isc_array_lookup_bounds2() は、デスクリプタ内のフラグを 0 に設定します。これは、そ

の後の関数呼び出しで行を基準に配列データにアクセスすることを指定します。列を基準

に配列データにアクセスする場合は、フラグを 1 に設定してください。

配列デスクリプタは、以降の isc_array_get_slice2() または isc_array_put_slice2() の呼び

出しで使用されます。

配列デスクリプタの詳細については、第 8 章「配列データの操作」を参照してください。

メモ isc_array_lookup_bounds2() 呼び出しを使わずに、配列デスクリプタを入力する以下のよ

うな方法もあります。

• isc_array_lookup_desc2() を呼び出します。この関数の機能は、各次元の上限と下限に関す

る情報を入力しないという点を除いて、isc_array_lookup_bounds2() の機能と同じです。

• isc_array_set_desc2() を呼び出して、データベースのメタデータにアクセスせずに、呼び出

しに使用するパラメータに基づいて配列デスクリプタを初期化します。

• デスクリプタの各項目を直接設定します。array_desc_dtype は下の表に示すデータ型のい

ずれかとして表現されていなければならず、またパラメータ array_desc_field_name および

array_desc_relation_name はNULL で終了していなければなりません。






table_name char * 配列型の列 column_name を含むテーブルの名前。NULL で終わっていても空白で終わっていてもよい。

column_name char * 配列型の列の名前。NULL または空白のいずれかで終わる。

desc ISC_ARRAY_DESC_V2 * この関数によって入力される配列のデスクリプタへのポインタ。


i s c _ a r r a y _ l o o k u p _ b o u n d s 2 ( )

例 isc_array_lookup_bounds2() を呼び出す例を示します。配列にアクセスする例については、

isc_array_get_slice2() と isc_array_put_slice2() の例を参照してください。

#include <ibase.h>



char *str1 = "PROJ_DEPT_BUDGET";

char *str2 = "QUARTERLY_HEAD_CNT";


status_vector,


&tr_handle, /* 先の isc_start_transaction() 呼び出しで設定されます */str1,

str2,

&desc);


{

表 15.15 配列デスクリプタフィールドのデータ型

array_desc_dtype 対応する InterBase のデータ型


blr_text CHAR

blr_text2 CHAR

blr_short SMALLINT

blr_long INTEGER


blr_float FLOAT


blr_sql_date DATE

blr_sql_time TIME


blr_varying VARCHAR






i s c _ a r r a y _ l o o k u p _ d e s c ( )


return(1);

}

戻り値 isc_array_lookup_bounds2() は、ステータスベクターの第 2 要素を返します。0 の場合は

正常に終了したことを示します。0 以外の場合は、エラーが発生したことを示します。

InterBase エラーの場合は、ステータスベクターの第 1 要素が 1 に設定され、第 2 要素は、

isc_bad_stmt_handle、isc_bad_trans_handle、isc_fld_not_def、または他の InterBase エラーコードに設定されます。




参照 isc_array_get_slice2()、isc_array_lookup_desc2()、isc_array_put_slice2()、isc_array_set_desc2()

isc_array_lookup_desc()

非推奨。isc_array_lookup_desc2() と機能は同じですが、32 バイトより長いメタデータ名

をサポートしません。

isc_array_lookup_desc2()

指定されたテーブルの指定された配列型のすべての列の、データ型、長さ、小数点以下の

桁数、次元、配列の範囲を判定します。

構文 ISC_STATUS isc_array_lookup_desc2(




char *table_name,

char *column_name,



i s c _ a r r a y _ l o o k u p _ d e s c 2 ( )

説明 isc_array_lookup_desc2() は、テーブル table_name の配列型の列 column_name につい

て、データ型、長さ、小数点以下の桁数、次元を判定し、配列デスクリプタ desc に格納し

ます。

isc_array_lookup_desc() は、デスクリプタ内のフラグを 0 に設定します。これは、関数

呼び出しで行を基準に配列データにアクセスする（デフォルト）ことを示します。列を基

準にアクセスする場合は、フラグを 1 に設定します。




メモ isc_array_lookup_desc2() 呼び出しを使わずに、配列デスクリプタを入力する以下のような

方法もあります。

• isc_array_lookup_bounds2() を呼び出します。この関数の機能は、各次元の上限と下限に関

する情報も入力するという点を除き、isc_array_lookup_desc2() の機能と同じです。

• isc_array_set_desc2() を呼び出して、データベースのメタデータにアクセスせずに、呼び出

しに使用するパラメータに基づいて配列デスクリプタを初期化します。

• デスクリプタの各項目を直接設定します。array_desc_dtype は下の表に示すデータ型のい

ずれかとして表現されていなければならず、またパラメータ array_desc_field_name および

array_desc_relation_name は NULL で終了していなければなりません。






table_name char * 配列型の列 column_name を含むテーブルの名前。NULL で終わっていても空白で終わっていてもよい

column_name char * 配列型の列の名前。NULL または空白のいずれかで終わる。

desc ISC_ARRAY_DESC_V2 * この関数によって入力される配列のデスクリプタへのポインタ


i s c _ a r r a y _ l o o k u p _ d e s c 2 ( )

例 isc_array_lookup_desc2() を呼び出す例を示します。配列にアクセスする例については、


#include <ibase.h>



char str1 = "PROJ_DEPT_BUDGET";

char str2 = "QUARTERLY_HEAD_CNT";

isc_array_lookup_desc2(

status_vector,


&tr_handle, /* 先の isc_start_transaction() 呼び出しで設定されます */str1,

str2,

&desc);


{

/* 処理エラー */




blr_text CHAR

blr_text2 CHAR

blr_short SMALLINT

blr_long INTEGER


blr_float FLOAT


blr_sql_date DATE

blr_sql_time TIME


blr_varying VARCHAR






i s c _ a r r a y _ p u t _ s l i c e ( )


return(1);

};

戻り値 isc_array_lookup_desc2() は、ステータスベクターの第 2 要素を返します。0 の場合は正常

に終了したことを示します。0 以外の場合は、エラーが発生したことを示します。InterBaseエラーの場合は、ステータスベクターの第 1 要素が 1 に設定され、第 2 要素は、

isc_bad_stmt_handle、isc_bad_trans_handle、isc_fld_not_def、または他の InterBase エラーコードに設定されます。




参照 isc_array_get_slice2()、isc_array_lookup_bounds2()、isc_array_put_slice2()、isc_array_set_desc2()

isc_array_put_slice()

非推奨。isc_array_put_slice2() と機能は同じですが、32 バイトより長いメタデータ名をサ


isc_array_put_slice2()

配列型の列にデータを書き込みます。

構文 ISC_STATUS isc_array_put_slice2(




ISC_QUAD *array_id,

ISC_ARRAY_DESC_V2 *desc,

void *source_array,

ISC_LONG *slice_length);


i s c _ a r r a y _ p u t _ s l i c e 2 ( )

説明 isc_array_put_slice2() は、配列型の列にデータを書き込みます。指定した列のすべての配

列要素を格納するか、連続した配列要素の一部（スライス）を格納します。どの要素に格

納するかは、関数に渡される配列デスクリプタ desc 内の範囲で指定します。

InterBase は、slice_length で指定したサイズのバッファ source_array から要素をコピーし

ます。

isc_array_put_slice2() の呼び出しによって配列を新規に作成する場合は、配列識別子（配

列 ID）array_id を、NULL として受け渡す必要があります。既存の配列を修正する場合は、

修正する配列の識別子に array_id を設定しなければなりません。これは、DSQL 関数呼び

出しによって前もって特定しておかなければなりません。

既存の配列の配列 ID を使って isc_array_put_slice2() が呼び出された場合は、次のように

処理を行います。

1 指定された配列と次元や範囲が同じ新しい配列を作成し、既存の配列のデータを新しい

配列にコピーします。

2 配列バッファ source_array のデータを新しい配列（またはそのスライス）に、配列デ

スクリプタ desc に指定された範囲の分だけ書き込みます。

3 同じ array_id 変数に新しい配列の配列 ID を返します。






array_id ISC_QUAD * 入力時は NULL（配列を新規に作成する場合）、修正の場合は配列の内部識別子。内部識別子は、DSQL 関数によって前もって特定しておかなければならない。

この関数は array_id を、作成または修正する配列の識別子に変更する（下記参照）

desc ISC_ARRAY_DESC _V2* 書き込み先の配列スライス（配列全体またはその一部）を定義するデスクリプタ

source_array void * この関数によって書き込み先配列にコピーされるデータスライスを格納している、長さ slice_lengthのバッファへのポインタ

slice_length ISC_LONG * source_array バッファの長さ（バイト単位）



配列 ID として NULL を使って呼び出された場合、isc_array_put_slice2() は次のような処

理を行います。

1 配列デスクリプタ desc で名前とテーブル名を指定された配列型の列として宣言された

とおりの新しい空の配列を作成します。

2 配列バッファ source_array のデータを新しい配列（またはそのスライス）に書き込み

ます。

3 array_id 変数に新しい配列の配列 ID を返します。

どちらの場合でも、新しい配列が作成され、その配列 ID が array_id 変数に返されます。

UPDATE または INSERT ステートメントを実行して特定の行の特定の列に関連付けられる

まで、配列は一時的配列です。

isc_array_put_slice2() の 1 回の呼び出しで、必要なデータをすべて配列に書き込むことが

できます。isc_array_put_slice2() を複数回呼び出して、配列のさまざまなスライスにデータ

を格納することもできます。複数回呼び出す場合、2 回め以降の isc_array_put_slice2() の各呼び出しでは、一時的配列の配列 ID を渡す必要があります。一時的配列の配列 ID を使っ

て呼び出された場合、isc_array_put_slice2() は（新しい配列を作成せずに）一時的配列の指

定されたスライスに指定されたデータをコピーし、array_id は変更しません。

isc_array_put_slice2() を呼び出す前に、配列デスクリプタ desc の値を設定し、適切な内部

配列識別子 array_id を指定し、アクセスする配列型の列を含む行を取り出しておく必要が

あります。

配列デスクリプタを設定して配列情報を書き込む手順については、第 8 章「配列データの

操作」を参照してください。

メモ配列型の列のデータに直接アクセスしようとする DSQL ステートメントを実行してはな

りません。配列型列データにアクセスする方法は、isc_array_get_slice2() または

isc_array_put_slice2() の呼び出し以外にはありません。DSQL ステートメントでサポート

されている配列参照は、配列型の列全体（つまり列名）を指定して配列の内部識別子を取

得することだけで、これは isc_array_get_slice2() と isc_array_put_slice2() で必要になり

ます。

例次のプログラムは、テーブル PROJ_DEPT_BUDGET に対して動作します。このテーブルに

は、会社の各部門で実施するプロジェクトに割り当てられた、四半期ごとの人数が保持さ

れています。テーブルの各行は、特定の部門とプロジェクトに対応します。四半期ごとの

人数は、配列型の列 QUARTERLY_HEAD_CNT に格納されています。この列の各行には 4 つの要素があります。配列の各要素は long 型の数値になります。

このプログラムは、VBASE という名前のプロジェクトに関する 1994 年の情報を格納して

いる行を選択します。各行について、isc_array_get_slice2 を呼び出し、後の 2 つの四半

期の人数を保持する配列スライスを抽出します。さらに、各四半期の値を更新し、

isc_array_put_slice2() を呼び出して更新後の値を格納します。

このプログラムは、isc_array_lookup_desc2()、isc_array_get_slice2()、isc_array_put_slice2() の使い方、およびデータ構造体の初期化と DSQL 関数の呼び出し

の方法を示しています。DSQL 関数は、SELECT ステートメントと UPDATE ステートメン

トの作成と実行、isc_array_get_slice2() と isc_array_put_slice2() に必要な array_id の取

得、選択した行の 1 行ずつの取り出し、および配列 ID の更新を行います。

#include <ibase.h>



#define Return_if_Error(stat) if (stat[0] == 1 && stat[1]) ¥

{ ¥

isc_print_status(stat); ¥

return(1); ¥

}

char *sel_str =

"SELECT dept_no, quarterly_head_cnt FROM proj_dept_budget ¥

WHERE year = 1994 AND proj_id = 'VBASE'";

char *upd_str =

"UPDATE proj_dept_budget SET quarterly_head_count = ? ¥

WHERE CURRENT OF S";

char dept_no[6];

long fetch_stat, SQLCODE, hcnt[2];

short len, i, flag0, flag1, flag2;

ISC_QUAD array_id;



isc_stmt_handle stmt = NULL;

isc_stmt_handle ustmt = NULL;

char *cursor = "S";

XSQLDA *osqlda, *isqlda;

/* SELECT ステートメントを設定します */

/* 配列データを保持するための出力 XSQLDA を割り当てます */osqlda = (XSQLDA *)malloc(XSQLDA_LENGTH(2));

osqlda->sqln = 2;

osqlda->version = SQLDA_CURRENT_VERSION;

/* SELECT ステートメントにステートメントハンドルを割り当てます */isc_dsql_allocate_statement(

status_vector, &database_handle, &stmt);


/* クエリーの実行を準備します */isc_dsql_prepare(

status_vector,

&tr_handle,

&stmt,

0,

sel_str,

1,



osqlda);


/* XSQLVAR を設定して、取得する各項目の領域を

割り当てます */

osqlda->sqlvar[0].sqldata = (char *) dept_no;

osqlda->sqlvar[0].sqltype = SQL_TEXT + 1;


osqlda->sqlvar[1].sqldata = (char *) &array_id;

osqlda->sqlvar[1].sqltype = SQL_ARRAY + 1;


/* SELECT ステートメントを実行します */isc_dsql_execute(

status_vector,

&tr_handle,

&stmt,

1,

NULL);


/* カーソルを宣言します */isc_dsql_set_cursor_name(

status_vector, &stmt, cursor, 0);


/* UPDATE ステートメントを設定します */

/* UPDATE ステートメントにステートメントハンドルを割り当てます */isc_dsql_allocate_statement(

status_vector, &database_handle, &ustmt);


/* 入力 XSQLDA を割り当てます */isqlda = (XSQLDA *)malloc(XSQLDA_LENGTH(2));

isqlda->sqln = 1;

1sqlda->version = SQLDA_CURRENT_VERSION;

/* 実行する UPDATE ステートメントを準備します */isc_dsql_prepare(

status_vector,

&tr_handle,

&ustmt,



0,

upd_str,

1,

NULL);


/* 入力 XSQLDA を初期化します */isc_dsql_describe_bind(

status_vector, &ustmt, 1, isqlda);


/* 入力 sqldata フィールドと sqlind フィールドを設定します */isqlda->sqlvar[0].sqldata = (char *) &array_id;

isqlda->sqlvar[0].sqlind = &flag2;

/* 配列デスクリプタを設定します */isc_array_lookup_desc2(

status_vector,



"PROJ_DEPT_BUDGET", /* テーブル名 */

"QUARTERLY_HEAD_CNT", /* 配列型の列の名前 */&desc);


/* デスクリプタの範囲を、更新するスライスの範囲（後の 2 つの要素の範囲）に設定します。ここで、この配列の列は 4 つの要素を含み、下限の添字が 1、上限が 4 で、後の 2 つの要素の添字が 3 と 4 であるように定義されているとします */desc->array_desc_bounds[0].array_bound_lower = 3;

desc->array_desc_bounds[0].array_bound_upper = 4;

/* 目的の行を取り出して処理します */while ((fetch_stat = isc_dsql_fetch(

status_vector, &stmt, 1, osqlda)) == 0)

{

if (!flag1)

{

/* 配列データがあります。後の 2 四半期の値を取得します */len = sizeof(hcnt);

/* データを配列スライスから hcnt 配列に取り出します */isc_array_get_slice2(

status_vector,

&database_handle,

&tr_handle,

&array_id,

&desc,



hcnt,

&len);


/* カウントごとに 1 を追加します */for (i = 0; i < 2; i++)

hcnt[i] = hcnt[i] + 1;

/* 新しい値を保存します */isc_array_put_slice2(

status_vector,

&database_handle,

&tr_handle,

&array_id,

&desc,

hcnt,

&len);


/* 配列 ID を更新します */isc_dsql_execute(

status_vector, &tr_handle, &ustmt, 1, isqlda);


};

};


{



return(1);

}

戻り値 isc_array_put_slice2() は、ステータスベクターの第 2 要素を返します。0 の場合は正常に

終了したことを示します。0 以外の場合はエラーが発生したことを示します。InterBase エラーの場合は、ステータスベクターの第 1 要素が 1 に設定され、第 2 要素は、


されます。




参照 isc_array_get_slice2()、isc_array_lookup_bounds2()、isc_array_lookup_desc2()、isc_array_set_desc2()、isc_dsql_allocate_statement()、isc_dsql_describe_bind()、isc_dsql_execute()、isc_dsql_fetch()、isc_dsql_prepare()、isc_dsql_set_cursor_name()


i s c _ a r r a y _ s e t _ d e s c ( )

isc_array_set_desc()

非推奨。isc_array_set_desc2() と機能は同じですが、32 バイトより長いメタデータ名をサ


isc_array_set_desc2()

配列デスクリプタを初期化します。

構文 ISC_STATUS isc_array_set_desc2(


char *table_name,

char *column_name,

short *sql_dtype,

short *sql_length,

short *dimensions,


説明 isc_array_set_desc2() は、table_name、column_name、sql_dtype、sql_length、dimensionsの各関数パラメータを使って配列デスクリプタ desc を初期化します。

isc_array_set_desc2() は、デスクリプタ内のフラグを 0 に設定します。これは、関数呼び

出しで行を基準に配列データにアクセスする（デフォルト）ことを示します。列を基準に

アクセスする場合は、フラグを 1 に設定します。

table_name および column_name は、NULL または空白で終わる文字列です。デスクリプ

タに格納される名前は NULL で終わる文字列です。

sql_dtype は、SQL マクロ定数として与えなければなりません。





table_name char * 配列型の列 column_name を保持する、空白または NULL で終わるテーブルの名前。

column_name char * 配列型の列の名前。NULL や空白で終わっていてもよい。

sql_dtype short * 配列要素の SQL データ型を指すポインタ。

sql_length short * 配列要素の長さを指すポインタ。

dimensions short * 配列の次元数を指すポインタ。

desc ISC_ARRAY_DESC_V2 * この関数によって入力される配列デスクリプタ。


i s c _ a r r a y _ s e t _ d e s c 2 ( )


メモ isc_array_set_desc2() 呼び出しを使わずに、配列デスクリプタを入力する以下のような方

法もあります。

• isc_array_lookup_bounds2() を呼び出します。この関数の機能は、各次元の上限と下限に関

する情報を入力するという点を除いて isc_array_lookup_desc2() と同じです。

• isc_array_lookup_desc2() を呼び出します。これは、各次元の上限と下限に関する情報を入

力しないという点を除き、isc_array_lookup_bounds2() の機能と同じです。

• デスクリプタの各フィールドを直接設定します。

• array_desc_version を ARR_DESC_CURRENT_VERSION に設定する必要があります。

• array_desc_field_name と array_desc_relation_name パラメータは、NULL で終わる


• array_desc_dtype は、次の表内のデータ型の 1 つとして指定する必要があります。

例 isc_array_set_desc2() を呼び出す例を示します。配列にアクセスする例については、


#include <ibase.h>




blr_text CHAR

blr_text2 CHAR

blr_short SMALLINT

blr_long INTEGER


blr_float FLOAT


blr_sql_date DATE

blr_sql_time TIME


blr_varying VARCHAR






i s c _ a t t a c h _ d a t a b a s e ( )



short dtype = SQL_TEXT;

short len = 8;

short dims = 1;

isc_array_set_desc2(

status_vector,

"TABLE1",

"CHAR_ARRAY",

&dtype,

&len,

&dims,

&desc);


{


return(1);

}

戻り値 isc_array_set_desc2() は、ステータスベクターの第 2 要素を返します。0 の場合は正常に

終了したことを示します。0 以外の場合は、エラーが発生したことを示します。InterBaseエラーの場合は、ステータスベクターの第 1 要素が 1 に設定され、第 2 要素は InterBaseエラーコードに設定されます。




参照 isc_array_get_slice2()、isc_array_lookup_bounds2()、isc_array_lookup_desc2()、isc_array_put_slice2()

isc_attach_database()

既存のデータベースに接続します。

構文 ISC_STATUS isc_attach_database(


short db_name_length,

char *db_name,


short parm_buffer_length,

char *parm_buffer);


i s c _ a t t a c h _ d a t a b a s e ( )

説明 isc_attach_database() 関数は、既存のデータベースに接続し、プログラムからアクセスで

きるようにします。リモートサーバーからデータベースにアクセスするためのユーザー名

とパスワード、および使用するデータベースキャッシュバッファの数などもオプションで

指定できます。これらのオプションは、呼び出しプログラムが作成して登録するデータベー

スパラメータバッファ（DPB）に渡されます。

プログラムは、接続先のデータベースファイル名を db_name に渡さなければなりません。

C 以外の言語で書かれたプログラムの場合は、db_name の長さ（バイト単位）を

db_name_length パラメータで渡さなければなりません。C プログラムでは、このパラメー

タには長さ 0 を渡す必要があります。

実行が正常に完了すると、isc_attach_database() は db_handle に一意の ID を割り当てま

す。以降の API 関数では、このハンドルが操作対象となるデータベースの識別に使用され

ます。

データベースへのアクセスが終了したら、isc_detach_database() で接続を解除します。

例以下のコードは、データベース employee.db に接続して、ユーザー名とパスワードをパラ

メータバッファに指定します。ユーザー名とパスワードはそれぞれ char * 変数 user_nameと user_password で与えられます。



isc_db_handle handle = NULL;

short dpb_length;

/* データベースパラメータバッファを作成します */dpb = dpb_buffer;


*dpb++ = isc_dpb_user_name;

*dpb++ = strlen(user_name);

for (p = user_name; *p;)



db_name_length short 文字列 db_name のバイト数。0 の場合は、文字列が NULL で終わっているものと見なされる

db_name char * データベース名

db_handle isc_db_handle * この関数によって設定されるデータベースハンドルへのポインタ。

isc_attach_database() に渡すときには、db_handle はNULL に設定しておくのが望ましい。

parm_buffer_length short データベースパラメータバッファ（DPB）のバイト数

parm_buffer char * DPB のアドレス


i s c _ b l o b _ d e f a u l t _ d e s c ( )

*dpb++ = *p++;

*dpb++ = isc_dpb_password;

*dpb++ = strlen(user_password);

for (p = user_password; *p;)

*dpb++ = *p++;

/* 別の作成方法として、isc_expand_dpb() を呼び出す方法があります */


isc_attach_database(

status_vector,

0,

"employee.db",

&handle,

dpb_length,

dpb_buffer);


{

/* エラーが発生しました */isc_print_status (status_vector);

return(1);

}

戻り値 isc_attach_database() は、ステータスベクターの第 2 要素を返します。0 の場合は正常に終

了したことを示します。0 以外の場合は、エラーが発生したことを示します。InterBase エラーの場合は、ステータスベクターの第 1 要素が 1 に設定され、第 2 要素は InterBase エラーコードに設定されます。




参照 isc_detach_database()、isc_expand_dpb()

DPB の作成と値の設定については、4-3 ページの「DPB の作成と値の設定」を参照して

ください。データベースへの接続については、4-2 ページの「データベースへの接続」を参


isc_blob_default_desc()

非推奨。isc_blob_default_desc2() と機能は同じですが、32 バイトより長いメタデータ名を

サポートしません。


i s c _ b l o b _ d e f a u l t _ d e s c 2 ( )

isc_blob_default_desc2()

BLOB のサブタイプ、キャラクタセット、セグメントサイズを含むデフォルト情報を、デー

タ構造体に読み込みます。

構文 void isc_blob_default_desc2(

ISC_BLOB_DESC_V2 *desc,

unsigned char *table_name,

unsigned char *column_name);

説明 isc_blob_default_desc2() は、isc_blob_gen_bpb2() を呼び出す前に、指定された table_nameと column_name、および BLOB に関する以下のデフォルトの情報を使って BLOB デスク

リプタ desc をロードし、アクセスする BLOB 列の BLOB パラメータバッファ（BPB）を

作成します。

• サブタイプを TEXT に設定します。

• キャラクタセットを、プロセスまたはデータベースに対応するデフォルトのキャラクタ

セットに設定します。

• セグメントサイズを 80 バイトに設定します。

• ISC_BLOB_DESC_V2 は、長さ METADATALENGTH の長いメタデータ名をサポートします。

古い ISC_BLOB_DESC 構造体は、32 バイト以下のメタデータ名しかサポートしません。

isc_blob_default_desc2() および関連する 3 つの関数 isc_blob_gen_bpb2()、isc_blob_lookup_desc2()、isc_blob_set_desc2() によって、BLOB 情報への動的なアクセスが可能になります。これら

の関数を使うと、特にテキスト型の BLOB データに関するキャラクタセット情報、テキス

ト型やテキスト型以外に関するサブタイプ情報など、フィルタリングの対象となる BLOBの情報を定義してアクセスすることができます。

次の表に、desc 構造体のフィールドを示します。


desc ISC_BLOB_DESC_V2 * BLOB デスクリプタへのポインタ

table_name unsigned char * テーブルの名前

column_name unsigned char * BLOB 列の名前

表 15.18 BLOB デスクリプタフィールド


blob_desc_version short BLOB_DESC_CURRENT_VERSION に設定する

blob_desc_subtype short BLOB フィルタのサブタイプ

blob_desc_charset short 使用されているキャラクタセット


i s c _ b l o b _ g e n _ b p b ( )

例次のコードは、デフォルトの情報を使って BLOB デスクリプタをロードします。

typedef struct

{

short blob_desc_version

short blob_desc_subtype;

short blob_desc_charset;

short blob_desc_segment_size;

unsigned char blob_desc_field_name[METADATALENGTH];

unsigned char blob_desc_relation_name[METADATALENGTH];

} ISC_BLOB_DESC2;

isc_blob_default_desc2(&desc, &relation, &field);

戻り値ありません。

参照 isc_blob_gen_bpb2()、isc_blob_lookup_desc2()、isc_blob_set_desc2()

BLOB デスクリプタの詳細については、第 7 章「BLOB データの操作」を参照してくだ

さい。

isc_blob_gen_bpb()

非推奨。isc_blob_gen_bpb2() と機能は同じですが、32 バイトより長いメタデータ名をサ


isc_blob_gen_bpb2()

BLOB パラメータバッファ（BPB）を作成して、BLOB のサブタイプとキャラクタセット

の情報に動的にアクセスできるようにします。

構文 ISC_STATUS isc_blob_gen_bpb2(


ISC_BLOB_DESC_V2 *to_desc,

ISC_BLOB_DESC_V2 *from_desc,

unsigned short bpb_buffer_length,

unsigned char *bpb_buffer,

unsigned short *bpb_length);

blob_desc_segment_size short BLOB のセグメントサイズ

blob_desc_field_name[METADATALENGTH]

char BLOB 列の名前を保持する配列

blob_desc_relation_name[METADATALENGTH]

char BLOB が格納されているテーブルの名前を保持する配列

表 15.18 BLOB デスクリプタフィールド ( 続き )



i s c _ b l o b _ g e n _ b p b 2 ( )

説明 isc_blob_gen_bpb2() は、ソース BLOB デスクリプタ from_desc と、ターゲット（変換先）

BLOB デスクリプタ to_desc に格納されたサブタイプとキャラクタセットの情報に基づい

て BLOB パラメータバッファ（BPB）を作成します。

BPB は、BLOB 列の書き込みまたは読み取りに使用されるフィルタで必要になります。フィ

ルタリングには、フィルタのソースデータを記述するデスクリプタ from_desc と、ターゲッ

トを記述するデスクリプタ to_desc の 2 つの BLOB デスクリプタが必要です。2 つの BLOBデスクリプタは、直接作成するか、isc_blob_default_desc2()、isc_blob_lookup_desc2()、isc_blob_set_desc2() のいずれかを呼び出して前もって作成しておかなければなりません。

isc_blob_gen_bpb2() によって作成される BPB は、以降呼び出される isc_open_blob2() やisc_create_blob2() でフィルタリングが使用されるときに必要になります。BPB の詳細につ

いては、第 7 章「BLOB データの操作」を参照してください。

重要 to_desc と from_desc で渡される 2 つの ISC_BLOB_DESC_V2 構造体では、blob_desc_versionフィールドを BLB_DESC_CURRENT_VERSION に設定する必要があります。ISC_BLOB_DESC_V2は、長さ METADATALENGTH の長いメタデータ名をサポートします。古い ISC_BLOB_DESC構造体は、32 バイト以下のメタデータ名しかサポートしません。

例次のコードは BLOB デスクリプタを作成します。

isc_blob_gen_bpb2(status, &to_desc, &from_desc, bpb_length, &buffer, &buf_length);

戻り値 isc_blob_gen_bpb2() は、ステータスベクターの第 2 要素を返します。0 の場合は正常に終



チェックします。

ステータスベクターの値を調べる方法については、第 10 章「エラー条件の処理」を参照


参照 isc_blob_default_desc2()、isc_blob_lookup_desc2()、isc_blob_set_desc2()、isc_create_blob2()、isc_open_blob2()



to_desc ISC_BLOB_DESC_V2 * ターゲット BLOB デスクリプタバッファへのポインタ

from_desc ISC_BLOB_DESC_V2 * ソース BLOB デスクリプタバッファへのポインタ

bpb_buffer_length unsigned short BLOB パラメータバッファ bpb_buffer の長さ

bpb_buffer unsigned char * BPB へのポインタ

bpb_length unsigned short * BPB に格納されるデータの長さへのポインタ


i s c _ b l o b _ i n f o ( )

isc_blob_info()

開いている BLOB に関する情報を返します。

構文 ISC_STATUS isc_blob_info(


isc_blob_handle *blob_handle,

short item_list_buffer_length,char *item_list_buffer,

short result_buffer_length,

char *result_buffer);

説明 isc_blob_info() は、blob_handle で指定された既存の BLOB に関する情報を返します。項

目リストバッファは構造を持たないバイトベクターで、必要な情報の項目を指定します。

InterBase は結果バッファに、要求された項目ごとに連続したクラスタを 1 つずつ返しま

す。各クラスタは以下の 3 つの部分から構成されます。

1 1 バイトの項目タイプ：それぞれ、項目リストバッファ内の項目タイプの 1 つに一致し

ます。

2 2 バイトの数字：項目タイプの後に続く、クラスタの構成バイト数を指定します。

3 可変数バイトに格納される値：項目のタイプに応じて解釈されます。

結果バッファの内容を解釈し、必要に応じて各クラスタの暗号を解読する作業は、呼び出

しプログラム側で行う必要があります。

要求および返される項目の一覧については、第 7 章「BLOB データの操作」を参照してく

ださい。

例次の例は、現在開いている BLOB に関する情報を抽出します。

static char blob_items[] = {

isc_info_blob_max_segment,

isc_info_blob_num_segments,

isc_info_blob_type};



blob_handle isc_blob_handle * BLOB ハンドルへのポインタ

item_list_buffer_length short 情報を要求する項目を指定する項目リストバッファの長さ

item_list_buffer char * 項目リストバッファへのポインタ

result_buffer_length short 要求された情報を InterBase が返す結果バッファの長さ

result_buffer char * 結果バッファへのポインタ


i s c _ b l o b _ l o o k u p _ d e s c ( )

CHAR blob_info[32];

isc_open_blob2(status_vector, &db, &tr_handle, &blob_handle, &blob_id, blength, baddr)


{


return(1);

}

isc_blob_info(status_vector, &blob_handle, sizeof(blob_items),blob_items, sizeof(blob_info), blob_info));

戻り値 isc_blob_info() は、ステータスベクターの第 2 要素を返します。0 の場合は正常に終了した

ことを示します。0 以外の場合は、エラーが発生したことを示します。InterBase エラーの

場合は、ステータスベクターの第 1 要素が 1 に設定され、第 2 要素は InterBase エラー

コードに設定されます。


チェックします。

ステータスベクターの値を調べる方法については、第 10 章「エラー条件の処理」を参照


参照 isc_create_blob2()、isc_open_blob2()

isc_blob_lookup_desc()

非推奨。isc_blob_lokup_desc2() と機能は同じですが、32 バイトより長いメタデータ名を

サポートしません。

isc_blob_lookup_desc2()

テーブル名と BLOB 列名で指定された BLOB のサブタイプ、キャラクタセット、セグメ

ントサイズを判定します。

構文 ISC_STATUS isc_blob_lookup_desc(


isc_db_handle **db_handle,

isc_tr_handle **trans_handle,


unsigned char *column_name,

ISC_BLOB_DESC_V2 *desc,

unsigned char *global);


i s c _ b l o b _ l o o k u p _ d e s c 2 ( )

説明 isc_blob_lookup_desc2() は、データベースのシステムテーブルを使用して、テーブル名と

BLOB 列名で指定された BLOB のサブタイプ、キャラクタセット、セグメントサイズを判

定します。

isc_blob_lookup_desc2()、および関連する 3 つの関数 isc_blob_default_desc2()、isc_blob_gen_bpb2()、isc_blob_set_desc2() によって BLOB 情報への動的なアクセスが可能になります。これらの

関数を使うと、特にテキスト型の BLOB データに関するキャラクタセット情報、テキスト

型やテキスト型以外に関するサブタイプ情報など、フィルタリングの対象となる BLOB の情報を定義してアクセスすることができます。

メモ ISC_BLOB_DESC_V2 構造体は、長さ METADATALENGTH の長いメタデータ名をサポート

します。古い ISC_BLOB_DESC 構造体は、32 バイト以下のメタデータ名しかサポートしま

せん。

isc_blob_lookup_desc2() は、BLOB に関する要求情報を BLOB デスクリプタ desc から読

み込みます。次の表に、desc 構造体のフィールドを示します。



db_handle isc_db_handle ** isc_attach_database() の呼び出しによって前もって設定されているデータベースハンドルへのポインタ


trans_handle isc_tr_handle ** isc_start_transaction() の呼び出しで前もって設定されているトランザクションハンドルを指すポインタ。trans_handle が NULL の場合はエラーが返される

table_name unsigned char * BLOB 列を含むテーブルの名前

column_name unsigned char * BLOB 列の名前

desc ISC_BLOB_DESC_V2 * この関数が情報を返す BLOB デスクリプタへのポインタ

global unsigned char * この関数が返すグローバルな列名

表 15.19 BLOB デスクリプタフィールド


blob_desc_version short BLOB_DESC_CURRENT_VERSION に設定する

blob_desc_subtype short BLOB フィルタのサブタイプ

blob_desc_charset short 使用されているキャラクタセット


i s c _ b l o b _ s e t _ d e s c ( )

blob_desc_version フィールドは、isc_blob_default_desc2()、isc_blob_lookup_desc2()、および

isc_blob_set_desc2() によって BLB_DESC_CURRENT_VERSION に設定されます。isc_blob_gen_bpb2()では、ユーザーが blob_desc_version を BLB_DESC_CURRENT_VERSION に明示的に設定する必

要があります。

例次のコードは、BLOB デスクリプタに情報を抽出します。

isc_blob_lookup_desc2(status, &db_handle, &tr_handle, &relation_name, f&field_name, &desc, &global);

戻り値 isc_blob_lookup_desc2() は、ステータスベクターの第 2 要素を返します。0 の場合は正常

に終了したことを示します。0 以外の場合は、エラーが発生したことを示します。InterBaseエラーの場合は、ステータスベクターの第 1 要素が 1 に設定され、第 2 要素は InterBaseエラーコードに設定されます。InterBase エラーの有無を判定するには、ステータスベク

ターの先頭の 2 つの要素を直接チェックします。ステータスベクターの値を調べる方法に

ついては、第 10 章「エラー条件の処理」を参照してください。

参照 isc_blob_default_desc2()、isc_blob_gen_bpb2()、isc_blob_set_desc2()


さい。

isc_blob_set_desc()

非推奨。isc_blob_set_desc2() と機能は同じですが、32 バイトより長いメタデータ名をサ


blob_desc_segment_size short BLOB のセグメントサイズ

blob_desc_field_name[METADATALENGTH]

char BLOB 列の名前を保持する配列

blob_desc_relation_name[METADATALENGTH]

char BLOB が格納されているテーブルの名前を保持する配列

表 15.19 BLOB デスクリプタフィールド ( 続き )



i s c _ b l o b _ s e t _ d e s c 2 ( )

isc_blob_set_desc2()

BLOB のサブタイプとキャラクタセットを設定します。

構文 ISC_STATUS isc_blob_set_desc2(



unsigned char *column_name,short subtype,

short charset,

short segment_size,

ISC_BLOB_DESC_V2 *desc);

説明 isc_blob_set_desc2() は、BLOB 列の名前、テーブル名、サブタイプ、キャラクタセット、

セグメントサイズを、アプリケーションで指定された値に設定します。各値を InterBaseのデフォルトに設定するには isc_blob_default_desc2() を使用します。

isc_blob_set_desc2() と関連する 3 つの関数 isc_blob_default_des2c()、isc_blob_gen_bpb2()、isc_blob_lookup_desc2() によって BLOB 情報への動的なアクセスが可能になります。これ

らの関数を使うと、特にテキスト型の BLOB データに関するキャラクタセット情報、テキ

スト型やテキスト型以外に関するサブタイプ情報など、フィルタリングの対象となる

BLOB の情報を定義してアクセスすることができます。

isc_blob_set_desc2() を呼び出すことで、TEXT サブタイプについて、サブタイプとキャラ

クタセットの情報を BLOB デスクリプタに独自に設定することができます。アプリケー

ション内で、サブタイプ、キャラクタセット、セグメントサイズを BLOB デスクリプタに

渡します。

isc_blob_set_desc2() を使うと、システムテーブルに対する情報のクエリーを行わずに、

BLOB デスクリプタの内容を設定できます。アプリケーションで独自のフィルタリング動

作用のキャラクタセットとサブタイプを指定することもできます。



table_name unsigned char * BLOB 列を含むテーブルの名前

column_name unsigned char * テーブル内の BLOB 列の名前

subtype short BLOB のサブタイプを指定する値：

• InterBase 定義のサブタイプ値： 0 または 1（TEXT）

• ユーザー定義のサブタイプ：-1 ~ -32768

charset short BLOB のキャラクタセット

segment_size short BLOB のセグメントサイズ

desc ISC_BLOB_DESC * 情報を格納する BLOB デスクリプタへのポインタ


i s c _ c a n c e l _ b l o b ( )

メモ ISC_BLOB_DESC_V2 構造体は、長さ METADATALENGTH の長いメタデータ名をサポート

します。古い ISC_BLOB_DESC 構造体は、32 バイト以下のメタデータ名しかサポートしま

せん。

メモ V3.x のデータベースに対する操作では、この関数を呼び出さないでください。

例次のコードは、サブタイプ、キャラクタセット、セグメントサイズを含む、ツアーガイド

アプリケーションのデフォルト値を設定します。

isc_blob_set_desc2(status, "TOURISM", "GUIDEBOOK", 1, 2, 80, &desc);

戻り値 isc_blob_set_desc2() は、ステータスベクターの第 2 要素を返します。0 の場合は正常に終





参照 isc_blob_default_desc2()、isc_blob_gen_bpb2()、isc_blob_lookup_desc2()


さい。

isc_cancel_blob()

BLOB を破棄し、その BLOB が使用していた内部記憶域を解放し、BLOB ハンドルを

NULL に設定します。

構文 ISC_STATUS isc_cancel_blob(


isc_blob_handle *blob_handle);

説明 InterBase は作成処理中に、BLOB データを一時的にデータベースに格納します。何らか

の理由で BLOB を閉じることができなかった場合は、データベースに一時的な格納領域が

割り当てられたままになり、ハンドルは NULL に設定されません。このようなデータベー

スの一時格納領域を解放し、blob_handle を NULL に設定するには isc_cancel_blob() を呼

び出します。アプリケーションの通常の処理手順で BLOB を閉じる場合は、isc_close_blob()の呼び出しと同時に InterBase がシステムリソースを解放するので、この作業は不要です。

メモハンドルが NULL の場合でも、この関数の呼び出しではエラーは生成されません。このた

め、BLOB を作成するか開く前に isc_cancel_blob() を呼び出して既存の BLOB 動作を取り

消しておくとよいでしょう。



blob_handle isc_blob_handle * 破棄する BLOB のハンドルへのポインタ。ハンドルがすでに NULL の場合でも、ハンドルを 0 に設定して正常終了の結果を返す


i s c _ c a n c e l _ e v e n t s ( )

例次のコードは、BLOB を新規に作成する前に、開いている BLOB を破棄します。

isc_cancel_blob(status_vector, &blob_handle);


{


return(1);

}

isc_create_blob(status_vector, &DB, &trans, &blob_handle, &blob_id)

戻り値 isc_cancel_blob() は、ステータスベクターの第 2 要素を返します。0 の場合は正常に終了

したことを示します。0 以外の場合は、エラーが発生したことを示します。InterBase エラーの場合は、ステータスベクターの第 1 要素が 1 に設定され、第 2 要素は InterBase エラーコードに設定されます。




参照 isc_close_blob()

isc_cancel_events()

指定されたイベントグループのイベントに関するアプリケーションの非同期の通知を取り

消します。

構文 ISC_STATUS isc_cancel_events(



ISC_LONG *event_id);

説明 isc_cancel_events() は、指定されたイベントリストについて、アプリケーションプログラ

ムの非同期待機を取り消します。このイベントは、isc_que_events() 呼び出しの結果とし

て、event_id とすでに関連付けられているものです。



db_handle isc_db_handle * isc_attach_database() の呼び出しによって前もって設定されているデータベースハンドルへのポインタ。このハンドルは、監視を取り消すイベントの対象となるデータベースを識別する。


event_id ISC_LONG * 取り消すイベントへのポインタ。isc_que_events() の呼び出しによって前もって設定されている必要がある。


i s c _ c l o s e _ b l o b ( )

例次の呼び出しは、event_id に関連付けられたイベントについて、プログラムの非同期待機

を取り消します。event_id は、isc_que_events() の以前の呼び出しで返された ID です。

isc_cancel_events(status_vector, &database_handle, &event_id);

イベントの完全な例については、isc_que_events() の説明を参照してください。

戻り値 isc_cancel_events() は、ステータスベクターの第 2 要素を返します。0 の場合は正常に終





参照 isc_que_events()

isc_close_blob()

開いている BLOB の残っているセグメントをフラッシュし、BLOB の更新または取り出し

処理に関連付けられていたシステムリソースを解放し、BLOB ハンドルを 0 に設定して、

BLOB を閉じます。

構文 ISC_STATUS isc_close_blob(


isc_blob_handle *blob_handle);

説明 isc_close_blob() は、BLOB をデータベースに格納し、BLOB 操作の後処理を行います。読

み取りや書き込みが終了した BLOB は閉じる必要があります。何らかの理由でアプリケー

ションで BLOB を閉じないと、データが消失することがあります。アプリケーションで閉

じていない BLOB を開く可能性がある場合は、isc_cancel_blob() を呼び出して、開いたま

まになっている BLOB を開けないようにする必要があります。

blob_handle は、isc_create_blob2() または isc_open_blob2() の呼び出しで設定されます。

例次のコードは、BLOB を閉じてシステムリソースを解放します。

if (status_vector[1] == isc_segstr_eof)

isc_close_blob(status_vector, &blob_handle)

戻り値 isc_close_blob() は、ステータスベクターの第 2 要素を返します。0 の場合は正常に終了し

たことを示します。0 以外の場合は、エラーが発生したことを示します。InterBase エラー

の場合は、ステータスベクターの第 1 要素が 1 に設定され、第 2 要素は InterBase エラー




blob_handle isc_blob_handle * 閉じる BLOB のハンドルへのポインタ


i s c _ c o m m i t _ r e t a i n i n g ( )




参照 isc_cancel_blob()、isc_create_blob2()、isc_open_blob2()

isc_commit_retaining()

アクティブなトランザクションをコミットし、コミット後のトランザクションのコンテキ

ストを保持します。

構文 ISC_STATUS isc_commit_retaining(

ISC_STATUS *status_vector,isc_tr_handle *trans_handle);

説明 isc_commit_retaining() は、アクティブなトランザクションをコミットしてクローンを作成

します。つまり、トランザクション名、トランザクションに関連したシステムリソース、ト

ランザクション内で開いているカーソルの状態を維持します。実際には新規のトランザク

ションを開始しますが、アクティブなトランザクションハンドルが新規のトランザクショ

ンに割り当てられることにより、次のコミットまでの間もトランザクションは開いたまま

になります。これによって新規のトランザクションを開始する負荷を小にすることがで

き、処理効率が向上します。isc_commit_retaining() を使うと、カーソルを開いたままで更

新をコミットすることができます。

アクティブトランザクション内ではロールバックを実行できますが、ロールバックが有効

なのはコミットされていない更新に対してだけです。言い換えると、トランザクションの

コンテキストがクローンに渡された後でもロールバックは違法ではありませんが、ロール

バックされるのはコミット以降にデータベースに対して行われた更新に限られます。

この関数の呼び出しによって行われたコミットを検査するには、ステータスベクターの第

1 要素を調べて呼び出しが成功したかどうかを確認します。第 1 要素が 0 の場合は呼び出

しは成功です。

isc_commit_transaction() または isc_rollback_transaction() を呼び出して、コンテキスト

の保持機能を使用せずにコミットまたはロールバックを行うと、トランザクションは終了

します。

例次の C/C++ コードは、トランザクションをコミットしてメッセージを出力し、同じ要求

内の同じハンドルを使って新規のトランザクションを開始します。

if (!isc_commit_retaining(status, &retained_trans))

{



trans_handle isc_tr_handle * isc_start_transaction() の呼び出しで前もって設定されているトランザクションハンドルを指すポインタ。trans_handleが NULL の場合はエラーが返される


i s c _ c o m m i t _ t r a n s a c t i o n ( )

fprintf(stderr, "Committed and retained¥n");


}

次のコードは、トランザクションをコミットして確認メッセージを出力し、同じ要求内の

同じハンドルを使って新規のトランザクションを開始します。コミットが失敗した場合は、

エラーメッセージを出力してロールバックします。

isc_commit_retaining(status, &retained_trans);

if (status[0] == 1 && status[1])

{

fprintf(stderr, "Error during commit, rolling back.¥n");

rb_status = isc_rollback_transaction(status, &retained_trans);

}

else

{

fprintf(stderr, "Commit successful.¥n");

tr_count++; /* リサイクルの数をインクリメントします */}

戻り値 isc_commit_retaining() は、ステータスベクターの第 2 要素を返します。0 の場合は正常に





参照 isc_commit_transaction()、isc_rollback_transaction()、isc_start_transaction()

isc_commit_transaction()

指定されたアクティブなトランザクションをコミットします。

構文 ISC_STATUS isc_commit_transaction(



説明 isc_commit_transaction() は、指定したトランザクションのレコードストリームを閉じ、シ

ステムリソースを解放し、トランザクションハンドルを 0 に設定します。





i s c _ c r e a t e _ b l o b 2 ( )

この関数を呼び出して複数のデータベースに対してコミット操作を実行する場合、InterBaseは初に isc_prepare_transaction() を実行します。isc_prepare_transaction() は、2 相コミットの

第 1 段階を実行します。これにより、トランザクションは limbo 状態になり、コミットする準

備が整います。InterBase は、対象となるすべてのデータベースにポーリングし、コミットを

受け入れる準備が整っていることを確認します。また isc_commit_transaction() は、BLOB メッ

セージをシステムテーブル RDB$TRANSACTION の列 RDB$TRANSACTION_DESCRIPTION に書

き込みます。このメッセージは、コミット中にシステム障害が発生した場合の再接続に必要な

詳細情報です。

isc_commit_transaction() は、すべてのデータベースからコミットの受け入れ準備が整って

いるという確認を受信するとともに、2 相コミットの第 2 段階を実行します。

isc_commit_transaction() は RDB$TRANSACTION の取り消しも行います。

例次のコードは、トランザクションをコミットしてメッセージを出力します。

isc_commit_transaction(status, &trans);


{

fprintf(stderr, "Error on write¥n");


}

戻り値 isc_commit_transaction() は、ステータスベクターの第 2 要素を返します。0 の場合は正常

に終了したことを示します。0 以外の場合は、エラーが発生したことを示します。InterBaseエラーの場合は、ステータスベクターの第 1 要素が 1 に設定され、第 2 要素は InterBaseエラーコードに設定されます。




参照 isc_commit_retaining()、isc_prepare_transaction()

isc_create_blob2()

書き込みアクセス用に BLOB を作成して開き、オプションで BLOB サブタイプを変換す

るフィルタを指定します。

構文 ISC_STATUS isc_create_blob2(





ISC_QUAD *blob_id,

short bpb_length,

char *bpb_address);


i s c _ c r e a t e _ b l o b 2 ( )

説明 isc_create_blob2() は、BLOB を格納するためのコンテキストを作成して書き込みアクセス

用に BLOB を開き、必要に応じて BLOB サブタイプの変換に使用するフィルタを指定し

ます。isc_put_segment() を呼び出すと、この BLOB にアプリケーションバッファのデー

タが書き込まれます。

BLOB フィルタを使用する場合は、BLOB に書き込むセグメントごとにフィルタを呼び出

します。InterBase は、bpb_address が指す BLOB パラメータバッファ（BPB）に前もっ

て指定されているソースサブタイプとターゲットサブタイプに基づいて、使用するフィル

タを選択します。

BLOB フィルタが不要または利用不能な場合は、BPB は不要であり、bpb_length に 0 を、

bpb_address に NULL を渡します。

isc_create_blob2() を呼び出すときには、blob_handle が指す BLOB ハンドルは 0 でなけれ

ばなりません。blob_handle を再利用するには、isc_close_blob() を呼び出して BLOB を閉

じて、ハンドルを 0 に設定してから isc_create_blob2() を呼び出します。

動作に成功すると、isc_create_blob2() は blob_handle に一意な ID を割り当て、blob_id にBLOB 識別子を割り当てます。以降の API 呼び出しでは、操作の対象となる BLOB を識

別するために、これらの一方または両方が必要になります。

BLOB が作成されると、isc_put_segment() の一連の呼び出しによってデータを書き込むこ

とができます。BLOB への書き込みが終了したら、isc_close_blob() を呼び出して BLOB を閉じます。

BLOB を作成する場合、blob_id にテーブルの特定の行の特定の列を割り当てるまでは

BLOB は「どこにも所属していない」状態になります。「所属を決める」には、BLOB を閉じてから DSQL を使用して、BLOB（および他の必要な列）を含む新しい行を挿入する

INSERT ステートメントを実行するか、既存の BLOB を新しい BLOB に置き換える

UPDATE ステートメントを実行します。



db_handle isc_db_handle * isc_attach_database() の呼び出しによって前もって設定されているデータベースハンドルへのポインタ


trans_handle isc_tr_handle * BLOB の作成先となるトランザクションハンドルへのポインタ

blob_handle isc_blob_handle * BLOB ハンドルへのポインタ

blob_id ISC_QUAD * システム定義の 64 ビットの BLOB ID を指すポインタ。BLOB ID はテーブル内の項目に格納され、BLOB の先頭セグメント、または BLOB の一部を指すポインタを格納するページのアドレスを示す

bpb_length short BLOB パラメータバッファ（BPB）の長さ

bpb_address char * BPB へのポインタ


i s c _ c r e a t e _ b l o b 2 ( )

BPB と BLOB フィルタの詳細については、第 7 章「BLOB データの操作」を参照してく

ださい。

例次のコードは、BPB を宣言し、フィルタ情報を登録してから、BLOB を作成して BPB を渡します。

isc_blob_handle blob_handle; /* 先頭で宣言します */

ISC_QUAD blob_id; /* 先頭で宣言します */char bpb[] = {

isc_bpb_version1,

isc_bpb_target_type,

1, /* ターゲットのサブタイプを指定する、後に続くバイト数 */

1, /* ターゲットのサブタイプ（TEXT） */isc_bpb_source_type,

1, /* ソースのサブタイプを指定する、後に続くバイト数 */

-4, /* ソースのサブタイプ */};

. . .

isc_create_blob2(

status_vector,

&db_handle,

&tr_handle,

&blob_handle, /* この関数によって入力されます */

&blob_id, /* この関数によって入力されます */

actual_bpb_length, /* BPB データの長さ */

&bpb /* BLOB パラメータバッファ */)

戻り値 isc_create_blob2() は、ステータスベクターの第 2 要素を返します。0 の場合は正常に終了





参照 isc_blob_gen_bpb2()、isc_open_blob2()、isc_put_segment()


i s c _ c r e a t e _ d a t a b a s e ( )

isc_create_database()

isc_create_database() メソッドは、ユーザーアプリケーションでの使用は現在サポートされ

ていません。このメソッドは内部使用専用です。有効なデータベースハンドルを持つデー

タベースを作成するには、isc_dsql_execute_immediate() を使います。

isc_database_info()

すでに接続しているデータベースについて要求された情報を返します。

構文 ISC_STATUS isc_database_info(



short item_list_buffer_length,

char *item_list_buffer,



説明 isc_database_info() は、接続したデータベースに関する情報を返します。通常は以下の場合

に isc_database_info() を呼び出します。

• ページキャッシュに使用される領域のサイズを調べる。キャッシュ領域のサイズはバッ

ファ数とページサイズの積であり、isc_database_info() の呼び出しで項目リストオプション

isc_info_num_buffers と isc_info_page_size を使って判定します。

• パフォーマンスの監視。たとえば、ソートしたストリームの更新やソートしないストリー

ムの更新のように、更新方法の違いによる効率の差異について調べます。

プログラムは、プログラム側で用意した項目リストバッファを通じて要求する情報を指定

し、InterBase はプログラム側が用意した結果バッファに要求された情報を返します。

例次のコードは、ページサイズとバッファ数についての情報を要求し、結果バッファを調べ

て InterBase エンジンが返した値を取得します。





item_list_buffer_length short 項目リストバッファのバイト数

item_list_buffer char * 項目リストバッファのアドレス

result_buffer_length short 結果バッファのバイト数

result_buffer char * 結果バッファのアドレス


i s c _ d a t a b a s e _ i n f o ( )

char db_items[] = {

isc_info_page_size, isc_info_num_buffers,

isc_info_end};


int length;

SLONG page_size = 0L, num_buffers = 0L;


isc_database_info(

status_vector,

&handle,/* 先の isc_attach_database() 呼び出しで設定されます */sizeof(db_items),

db_items,

sizeof(res_buffer),

res_buffer);


{


return(1);

};

/* 結果バッファに返された値を抽出します */for (p = res_buffer; *p != isc_info_end ;)

{

item = *p++;

length = isc_portable_integer (p, 2);

p += 2;

switch (item)

{

case isc_info_page_size:

page_size = isc_portable_integer (p, length);

break;

case isc_info_num_buffers:

num_buffers = isc_portable_integer (p, length);

break;

default:

break;

}

p += length;

};

戻り値 isc_database_info() は、ステータスベクターの第 2 要素を返します。0 の場合は正常に終了



i s c _ d e c o d e _ s q l _ d a t e ( )




参照 isc_attach_database()、isc_detach_database()

データベース接続情報の要求の詳細については、4-10 ページの「接続に関する情報の要求」


isc_decode_sql_date()

InterBase の ISC_DATE 形式の日付を C の tm 構造体形式に変換します。

構文 void isc_decode_sql_date(

ISC_DATE *ib_date,

void *tm_date);

説明 isc_decode_sql_date() は、テーブルから取得して ISC_DATE 変数 ib_date に格納した日付を

C プログラムで使用できる時刻構造体に変換します。ib_date と tm_date は、どちらも使用

前に宣言して初期化しておかなければなりません。

変換を行う前に InterBase の DATE 型データをテーブルから抽出して ISC_DATE 構造体に

格納するには、isc_dsql ファミリーの API 呼び出しを使用します。

メモ InterBase 6 以降では、DATE データ型はダイアレクト 3 でのみ使用することができます。

DATE データ型は、時刻情報を含まずに日付情報だけを格納します。バージョン 6 のダイ

アレクト 1 では、TIMESTAMP データ型は日付情報と時刻情報の両方を格納します。これ

は、前バージョンの InterBase で用意されていた DATE データ型と同じものです。

例次のコードは、時刻構造体を宣言して isc_decode_sql_date() を呼び出し、InterBase の日

付形式を C の時刻形式に変換します。

#include <time.h>

#include <ibase.h>

. . .

struct tm hire_time;

ISC_DATE hire_date;

. . .

/* ここで、テーブルから DATE データを取得します */. . .

isc_decode_sql_date(&hire_date, &hire_time);



ib_date ISC_DATE * InterBase 形式の日付が格納される 8 バイトのISC_DATE 構造体へのポインタ

tm_date void * C の tm 構造体へのポインタ


i s c _ d e c o d e _ s q l _ t i m e ( )

参照 isc_decode_sql_time()、isc_decode_timestamp()、isc_encode_sql_date()

isc_decode_sql_time()

InterBase の ISC_TIME 形式の時刻を C の tm 構造体形式に変換します。

構文 void isc_decode_sql_time(

ISC_TIME *ib_time,

void *tm_date);

説明 isc_decode_sql_time() は、テーブルから取得して ISC_TIME 変数 ib_time に格納した時刻を

C プログラムで使用できる時刻構造体に変換します。ib_time と tm_date は、どちらも使

用前に宣言して初期化しておかなければなりません。

変換を行う前に InterBase の TIME 型データをテーブルから抽出して ISC_TIME 構造体に

格納するには、isc_dsql ファミリーの API 呼び出しを使用します。

メモ isc_decode_sql_time() はミリ秒をサポートしません。これは、エンコード / デコード関数

が、秒の小数部をサポートしない time.h の tm 構造体を使用しているためです。

例次のコードは、時刻構造体を宣言して isc_decode_sql_time() を呼び出し、InterBase の日

付形式を C の時刻形式に変換します。

#include <time.h>

#include <ibase.h>

. . .


ISC_TIME hire_date;

. . .

/* ここで、テーブルから TIME データを取得します */. . .

isc_decode_sql_time(&hire_date, &hire_time);


参照 isc_decode_sql_date()、isc_decode_sql_time()、isc_encode_sql_date()


ib_time ISC_TIME * InterBase 形式の時刻を格納する 4 バイトのISC_TIME 構造体へのポインタ



i s c _ d e c o d e _ t i m e s t a m p ( )

isc_decode_timestamp()

InterBase の ISC_TIMESTAMP 形式の日付および時刻を C の tm 構造体形式に変換します。

構文 void isc_decode_timestamp(

ISC_TIMESTAMP *ib_date,

void *tm_date);

説明 isc_decode_timestamp() は、テーブルから取得して ISC_TIMESTAMP 変数 ib_timestamp に格納した日付を C プログラムで使用できる時刻構造体に変換します。ib_timestamp とtm_date は、どちらも使用前に宣言して初期化しておかなければなりません。

isc_decode_timestamp() は、バージョン 6.0 以前の InterBase に用意されていた

isc_decode_date() 関数と同じ機能を持ちます。

変換を行う前に InterBase の TIMESTAMP 型データをテーブルから抽出して ISC_TIMESTAMP構造体に格納するには、isc_dsql ファミリーの API 呼び出しを使用します。

メモ isc_decode_timestamp() はミリ秒をサポートしません。これは、エンコード / デコード関

数が、秒の小数部をサポートしない time.h の tm 構造体を使用しているためです。

例次のコードは、時刻構造体を宣言して isc_decode_sql_timestamp() を呼び出し、InterBaseの日付形式を C の時刻形式に変換します。

#include <time.h>

#include <ibase.h>

. . .


ISC_TIMESTAMP hire_date;

. . .

/* ここで、テーブルから TIMESTAMP データを取得します */. . .

isc_decode_timestamp(&hire_date, &hire_time);


参照 isc_decode_sql_date()、isc_decode_sql_time()、isc_encode_sql_date()

isc_delete_user()

InterBase セキュリティデータベース（デフォルトは admin.ib）からユーザーレコードを

削除します。


ib_timestamp ISC_TIMESTAMP * InterBase 形式の日付および時刻を格納する 8 バイトのISC_TIMESTAMP 構造体へのポインタ



i s c _ d e l e t e _ u s e r ( )


さい。第 12 章「サービスの操作」および 15-139 ページの「isc_service_start()」のリファ

レンス項目を参照してください。

構文 ISC_STATUS isc_delete_user(

ISC_STATUS *status



て、gsec コマンドラインユーティリティと同等の機能が提供されます。isc_delete_user()は、InterBase セキュリティデータベースからレコードを削除します。

少なくともユーザー名とパスワードを指定しなければなりません。サーバーがローカルで

ない場合は、サーバー名とプロトコルも指定する必要があります。プロトコルフィールド

の有効な値は、sec_protocol_tcpip、sec_protocol_netbeui、および sec_protocol_local です。




typedef struct {





char *server; /* 管理するサーバー */

char *user_name; /* ユーザー名 */

char *password; /* ユーザーのパスワード */

char *group_name;/* グループ名 */

char *first_name;/* ユーザーの名 */

char *middle_name;/* ユーザーのミドルネーム */


char *dba_user_name;/* DBA のユーザー名 */

char *dba_password;/* DBA のパスワード */} USER_SEC_DATA;



ます。

sec_uid_spec 0x01

sec_gid_spec 0x02







i s c _ d e l e t e _ u s e r ( )








せん。


表 15.20 isc_deleteuser() のエラーメッセージ

コード値説明

isc_usrname_too_long 335544747 The user name passed in is greater than 31 bytes（ユーザー名が長すぎます。大長は 31 バイトです）

isc_password_too_long 335544748 The password passed in is longer than 8 bytes（パスワードが長すぎます。大長は 8 バイトです）




isc_dup_usrname_found 335544752 The user name being added already exists in thesecurity database（セキュリティデータベース内でユーザー名が重複しています）

isc_usrname_not_found 335544753 The user name was not found in the securitydatabase（セキュリティデータベース内に、指定されたユーザー名が見つかりませんでした）

isc_error_adding_sec_record 335544754 An unknown error occurred while adding auser（ユーザーの追加時にエラーが発生しました）

isc_error_deleting_sec_record 335544755 An unknown error occurred while adding auser（ユーザーの追加時にエラーが発生しました）

isc_error_modifying_sec_record 335544756 An unknown error occurred while deleting auser（ユーザーレコードの変更時にエラーが発生しました）

isc_error_updating_sec_db 335544757 An unknown error occurred while updating thesecurity database（セキュリティデータベースの更新時にエラーが発生しました）


i s c _ d e l e t e _ u s e r ( )

例次の例では、ビットごとの論理和を使って USER_SEC_DATA 構造体内の値を渡して、パス

ワードデータベースからユーザー "Socks" を削除します。

{


USER_SEC_DATA sec;



sec.dba_password = "masterkey";



sec.sec_flags = sec_server_spec


| sec_dba_password_name_spec;

isc_delete_user(status, &sec);


{




break;

...

}

}

}

戻り値 isc_delete_user() は、ステータスベクターの第 2 要素を返します。0 の場合は、正常に終了

したことを示します。0 以外の場合は、エラーが発生したことを示します。エラーコードに

ついては、この関数の「説明」を参照してください。ステータスベクターの値を調べる方

法については、第 10 章「エラー条件の処理」を参照してください。

参照 isc_add_user()、isc_modify_user()


i s c _ d e t a c h _ d a t a b a s e ( )

isc_detach_database()

isc_attach_database() によって接続されたデータベースの接続を解除します。

構文 ISC_STATUS isc_detach_database(


isc_db_handle *db_handle);

説明 isc_detach_database() は、接続中のデータベースとの接続を解除します。この関数は、デー

タベースを使い終わった場合や、異なる接続パラメータを使って同じデータベースに接続

する場合にシステムリソースを解放するために呼び出します。isc_detach_database() は、

データベースが格納されているクライアントやリモートサーバー上のリモートインター

フェースを制御する、バッファおよび構造体を解放します。

isc_detach_database() を呼び出す場合は、解除の対象となるデータベースに影響するトラ

ンザクションをコミットまたはロールバックしておかなければなりません。

例次のコードは、データベースとの接続を解除します。

if (handle)

isc_detach_database(status_vector, &handle);

ここでは、handle が有効で接続しているデータベースを指しているものとします。この文

が実行されると、指定されたデータベースの接続が解除されます。

戻り値 isc_detach_database() は、ステータスベクターの第 2 要素を返します。0 の場合は正常に





参照 isc_attach_database()






i s c _ d r o p _ d a t a b a s e ( )

isc_drop_database()

現在接続しているデータベースおよびそのサポートファイル（2 次データベースファイル、

WAL ファイル、シャドウファイルなど）をすべて削除します。

構文 ISC_STATUS isc_drop_database(


isc_db_handle *db_handle);

説明 isc_drop_database() は、接続しているデータベースおよびそのサポートファイルをすべて

削除します。このルーチンは、データベースを使う必要がなくなった場合に呼び出します

（たとえば、すべてのデータを別のデータベースに移動したり、一時的に使用していたデー

タベースが不要になった場合などです）。isc_drop_database() が正常に終了するのは、削

除するデータベースに接続しているプロセスが残っていない場合だけです。

例次の条件文はデータベースを削除します。

if (handle)

isc_drop_database(status_vector, &handle);

ここでは、handle が有効で接続しているデータベースを指しているものとします。この文

が実行されると、指定されたデータベースの接続が解除されます。

戻り値 isc_drop_database() は、ステータスベクターの第 2 要素を返します。0 の場合は正常に終











i s c _ d s q l _ a l l o c a t e _ s t a t e m e n t ( )

isc_dsql_allocate_statement()

以降の動的 SQL（DSQL）の API 呼び出しで使用するステートメントハンドルを割り当

てます。

構文 ISC_STATUS isc_dsql_allocate_statement(



isc_stmt_handle *stmt_handle);

説明 isc_dsql_allocate_statement() は、ステートメントハンドルを割り当て、ステートメントハンド

ルのポインタを stmt_handle に返します。このポインタは isc_dsql_prepare() に渡され、処理

する DSQL ステートメントとステートメントハンドルを関連付けます。

1 つの DSQL ステートメントを複数回実行する場合や、出力値（ストアドプロシージャか

ら得られた結果を除く）を返す DSQL ステートメントを実行する場合は、前もって

isc_dsql_allocate_statement() または isc_dsql_alloc_statement2() を呼び出してステートメ

ントハンドルを割り当ててから、

isc_dsql_prepare() と isc_dsql_execute() で文の作成と実行を行わなければなりません。

メモ isc_dsql_allocate_statement() 関数は、isc_dsql_alloc_statement2() に似ていますが、

isc_dsql_allocate_statement() で割り当てたステートメントハンドルは、対象となるデータ

ベースの接続が解除されても、自動的に NULL に再設定されることはありません。ステー

トメントハンドルを自動的に NULL に再設定するには、isc_dsql_alloc_statement2() を使

用してください。

文の処理が完了した後は、isc_dsql_free_statement() または isc_detach_database() を呼び

出してステートメントハンドルを解放します。

例次のコードは、データベースハンドル database_handle によって参照されるデータベース

にアクセスする SQL ステートメントにステートメントハンドルを割り当てます。


isc_stmt_handle statement_handle;

statement_handle = NULL; /* ハンドルを割り当てる前に NULL に設定します */isc_dsql_allocate_statement(





stmt_handle isc_stmt_handle * この関数で割り当てたステートメントハンドルを指すポインタ。この関数の呼び出し時にはハンドルは NULL でなければならない。NULL 以外の場合は、status_vector にエラーが返される


i s c _ d s q l _ a l l o c _ s t a t e m e n t 2 ( )

status_vector,

&database_handle, /* 先の isc_attach_database() 呼び出しで設定されます */&statement_handle);


{

isc_print_status(status_vector); /* エラーメッセージを表示します */

return(1); /* ここで戻ります */}

/* 特定の SQL ステートメントにステートメントハンドルを関連付けたり、

* DSQL ステートメントを作成して実行するために必要なその他の操作を実行するために、

* 他の関数を呼び出します。不要になったステートメントハンドルは解放します */

戻り値 isc_dsql_allocate_statement() は、ステータスベクターの第 2 要素を返します。0 の場合は



isc_bad_stmt_handle、isc_bad_db_handle、または他の InterBase エラーコードに設定さ

れます。




参照 isc_dsql_alloc_statement2()、isc_dsql_execute()、isc_dsql_free_statement()、isc_dsql_prepare()

isc_dsql_alloc_statement2()

以降の動的 SQL（DSQL）の API 呼び出しで使用するステートメントハンドルを割り当

てます。

構文 ISC_STATUS isc_dsql_alloc_statement2(



isc_stmt_handle *stmt_handle);





stmt_handle isc_stmt_handle * この関数で割り当てたステートメントハンドルを指すポインタ。この関数の呼び出し時にはハンドルは NULL でなければならない。NULL 以外の場合は、status_vectorにエラーが返される


i s c _ d s q l _ a l l o c _ s t a t e m e n t 2 ( )

説明 isc_dsql_alloc_statement2() はステートメントハンドルを割り当て、ステートメントハンド

ルのポインタを stmt_handle に返します。このポインタは isc_dsql_prepare() に渡され、処

理する DSQL ステートメントとステートメントハンドルを関連付けます。

1 つの DSQL ステートメントを複数回実行する場合や、出力値（ストアドプロシージャか

ら得られた結果を除く）を返す DSQL ステートメントを実行する場合は、前もって

isc_dsql_allocate_statement() または isc_dsql_alloc_statement2() を呼び出してステートメン

トハンドルを割り当ててから、isc_dsql_prepare() と isc_dsql_execute() によって文の作成と

実行を行わなければなりません。

メモ isc_dsql_allocate_statement2() 関数は isc_dsql_alloc_statement() 関数に似ていますが、

isc_dsql_allocate_statement2() で割り当てたステートメントハンドルは、対象となるデー

タベースの接続が解除されると、自動的に NULL に再設定されます。

isc_dsql_alloc_statement() ではハンドルは再設定されません。

例次のコードは、データベースハンドル database_handle によって参照されるデータベース

にアクセスする SQL ステートメントにステートメントハンドルを割り当てます。


isc_stmt_handle statement_handle;

isc_dsql_alloc_statement2(

status_vector,

&database_handle, /* 先の isc_attach_database() 呼び出しで設定されます */&statement_handle);


{

isc_print_status(status_vector); /* Display an error message. */

return(1); /* ここで戻ります */}

;

/* 特定の SQL ステートメントにステートメントハンドルを関連付けたり、

* DSQL ステートメントを作成して SQL ステートメント実行するために

* 必要なその他の操作を実行するために、他の関数を呼び出します。*/

戻り値 isc_dsql_alloc_statement2() は、ステータスベクターの第 2 要素を返します。0 の場合は正

常に終了したことを示します。0 以外の場合は、エラーが発生したことを示します。


isc_bad_stmt_handle、isc_bad_db_handle、または他の InterBase エラーコードに設定さ

れます。




参照 isc_dsql_allocate_statement()、isc_dsql_execute()、isc_dsql_free_statement()、isc_dsql_prepare()


i s c _ d s q l _ d e s c r i b e ( )

isc_dsql_describe()

DSQL の SELECT ステートメントまたは EXECUTE PROCEDURE ステートメントの実行に

よって抽出された列に関する情報を返します。

構文 ISC_STATUS isc_dsql_describe(




XSQLDA *xsqlda);

説明 isc_dsql_describe() は、SELECT ステートメントから返される行を構成する列の記述、また

は EXECUTE PROCEDURE ステートメントから返される情報を XSQLDA に格納します。

isc_dsql_describe() を呼び出すには、isc_dsql_prepare() を呼び出して、各文を実行可能な

状態に作成しておかなければなりません。

メモ isc_dsql_describe() 関数を呼び出した結果、実行する DSQL の戻り値を格納できるだけの

領域が出力 XSQLDA にないことが判明した場合は、isc_dsql_describe() を使用する必要

はありません。

例次のコードは順に、XSQLDA を割り当て、文を作成し、XSQLVAR が適切な数だけ割り当

てられているかをチェックし、必要であれば状況を修正します。

#include <ibase.h>


XSQLDA *osqlda;

int n;

char *query = "SELECT * FROM CITIES WHERE STATE = 'NY' ORDER BY CITY DESCENDING";

osqlda = (XSQLDA *)malloc(XSQLDA_LENGTH(3);


osqlda->sqln = 3;

isc_dsql_prepare(



stmt_handle isc_stmt_handle * isc_dsql_allocate_statement() または isc_dsql_alloc_statement2()の呼び出しで前もって設定されているステートメントハンドルを指すポインタ。ハンドルが NULL の場合は、status_vector にエラーが返される

da_version unsigned short SQLDA ではなく、XSQLDA デスクリプタを使用するように指定する。この値は 1 に設定する

xsqlda XSQLDA * 前もって割り当てた出力 XSQLDA へのポインタ


i s c _ d s q l _ d e s c r i b e ( )

status_vector,

&tr_handle, /* 先の isc_start_transaction() 呼び出しで設定されます */&stmt_handle,

/* isc_dsql_allocate_statement() または isc_dsql_alloc_statement2() の

呼び出しによって前もって割り当てられます */0,

query,

1,

osqlda);


{


return(1);

}

if (osqlda->sqld > osqlda->sqln) /* さらに多くの XSQLVARS が必要です */{

n = osqlda->sqld;

free(osqlda);

osqlda = (XSQLDA *)malloc(XSQLDA_LENGTH(n);

osqlda->sqln = n;


isc_dsql_describe(

status_vector,

&stmt_handle,

1,

osqlda);


{


return(1);

}

}

戻り値 isc_dsql_describe() は、ステータスベクターの第 2 要素を返します。0 の場合は正常に終了

したことを示します。0 以外の場合は、エラーが発生したことを示します。InterBase エラーの場合は、ステータスベクターの第 1 要素が 1 に設定され、第 2 要素は、

isc_bad_stmt_handle または他の InterBase エラーコードに設定されます。




参照 isc_dsql_describe_bind()、isc_dsql_execute()、isc_dsql_execute2()、isc_dsql_prepare()


i s c _ d s q l _ d e s c r i b e _ b i n d ( )

値を返す DSQL ステートメントの準備については、6-16 ページの「DSQL のプログラミ

ング手法」を参照してください。XSQLDA の作成と値の設定については、6-6 ページの

「XSQLDA」を参照してください。

isc_dsql_describe_bind()

すでに作成されている DSQL ステートメントに必要な動的入力パラメータに関する情報

を返します。

構文 ISC_STATUS isc_dsql_describe_bind(




XSQLDA *xsqlda);

説明 isc_dsql_describe_bind() は、isc_dsql_prepare() で作成した DSQL ステートメントに必要

な動的入力パラメータの情報を、入力 XSQLDA の xsqlda に格納します。

入力パラメータを持つ文をアプリケーションで実行するには、パラメータの値を入力

XSQLDA 構造体に割り当てておく必要があります。必要なパラメータの数とデータ型が正

確にわかっている場合は、isc_dsql_describe_bind() を呼び出さずに XSQLDA を直接設定

できます。InterBase に文を解析させ、パラメータ数やデータ型などの情報を算出させる

場合は、isc_dsql_describe_bind() を呼び出さなければなりません。

例次のコードは順に、入力 XSQLDA を割り当て、DSQL UPDATE ステートメントを作成し、

isc_dsql_describe_bind() 関数を呼び出し、XSQLVAR が適切な数だけ割り当てられているかを

チェックし、必要であれば状況を修正します。

#include <ibase.h>


XSQLDA *isqlda

int n;

char *str = "UPDATE DEPARTMENT SET BUDGET = ?, LOCATION = ?";

isc_dsql_prepare(





xsqlda XSQLDA * 前もって割り当てた入力 XSQLDA へのポインタ


i s c _ d s q l _ d e s c r i b e _ b i n d ( )

status_vector,




str,

1,

NULL);


{


return(1);

}

/* 入力 XSQLDA を割り当てます */isqlda = (XSQLDA *)malloc(XSQLDA_LENGTH(1);

isqlda->version = SQLDA_CURRENT_VERSION;

isqlda->sqln = 1;

isc_dsql_describe_bind(

status_vector,

&stmt_handle,



isqlda);


{

/* 処理エラー */ isc_print_status(status_vector);

return(1);

}

if (isqlda->sqld > isqlda->sqln) /* さらに多くの XSQLVAR が必要です */{

n = isqlda->sqld;

free(isqlda);

isqlda = (XSQLDA *)malloc(XSQLDA_LENGTH(n);

isqlda->sqln = n;


isc_dsql_describe_bind(

status_vector,

&stmt_handle,

1,

isqlda);



i s c _ d s q l _ e x e c u t e ( )

{


return(1);

}

}

戻り値 isc_dsql_describe_bind() は、ステータスベクターの第 2 要素を返します。0 の場合は正常






参照 isc_dsql_describe()、isc_dsql_execute()、isc_dsql_execute2()、isc_dsql_prepare()

値を返す DSQL ステートメントの準備については、6-16 ページの「DSQL のプログラミ

ング手法」を参照してください。XSQLDA の作成と値の設定については、6-6 ページの


isc_dsql_execute()

前もって作成されている DSQL ステートメントを実行します。

構文 ISC_STATUS isc_dsql_execute(





XSQLDA *xsqlda);




stmt_handle isc_stmt_handle * isc_dsql_allocate_statement() またはisc_dsql_alloc_statement2() の呼び出しで前もって設定されているステートメントハンドルを指すポインタ。ハンドルが NULL の場合は status_vector にエラーが返される


xsqlda XSQLDA * 前もって割り当てた入力 XSQLDA へのポインタ



説明 isc_dsql_execute() は、isc_dsql_prepare() で前もって作成した DSQL ステートメントを実

行します。isc_dsql_execute() では次の 2 種類の DSQL ステートメントを実行できます。

• 複数の行のデータを返す DSQL ステートメント

• 複数回実行する必要がある DSQL ステートメント

入力パラメータを持つ DSQL ステートメントを実行する場合は、各パラメータを記述する

入力 XSQLDA を isc_dsql_execute() に指定する必要があります。出力 XSQLDA は作成さ

れません。SELECT ステートメントを実行する isc_dsql_execute() を呼び出すと、結果の行

データを格納したリストが作成されます。データ行にアクセスするには、ループ構造内で

isc_dsql_fetch() を呼び出します。呼び出すたびにその選択リストから次の行が取り出され

ます。

入力パラメータの値を必要とする DSQL ステートメント、つまりパラメータのマーカを含

む DSQL ステートメントを実行する場合は、isc_dsql_execute() を呼び出す前に、入力

XSQLDA の xsqlda に値を設定しなければなりません。

メモ EXECUTE PROCEDURE ステートメントのように、入力パラメータと戻り値の両方を持つ

DSQL ステートメントを繰り返し実行する場合は、入力と出力両方の XSQLDA を必要と

する isc_dsql_execute2() を使用します。

戻り値がない DSQL ステートメントを一度だけ実行する場合は、isc_dsql_prepare() とisc_dsql_execute() ではなく、isc_dsql_execute_immediate() を使用します。入力パラメータと

出力パラメータの両方を持つ DSQL ステートメントを一度だけ実行する場合は、

isc_dsql_exec_immed2() を使用します。

メモ isc_dsql_execute() および isc_dsql_execute2() は、CREATE DATABASE ステートメントと SETTRANSACTION ステートメントの実行には使用できません。これらの DSQL ステートメント

には、

isc_dsql_execute_immediate() を使用してください。

例次のコードは isc_dsql_execute() と isc_dsql_fetch() を呼び出しています。入力 XSQLDA と出力 XSQLDA の割り当て、SELECT ステートメントの作成と実行、行単位の取り出しと処

理を行います。

#include <ibase.h>


XSQLDA *isqlda, *osqlda;

XSQLVAR *ivar, *ovar;

char *str = "SELECT CITY, POPULATION FROM CITIES WHERE STATE = ?";

char *state = "CA";

/* 出力 XSQLDA osqlda を割り当てます */osqlda = (XSQLDA *)malloc(XSQLDA_LENGTH(2);


osqlda->sqln = 2;

/* 文を作成します。この文から返される選択リスト項目に関する情報を osqlda に設定します */isc_dsql_prepare(

status_vector,






str,

1,

osqlda);


{


return(1);

}

/* 出力 XSQLDA に十分な XSQLVARS が割り当てられているかどうかをチェックします。割り当てられていない場合は修正します（isc_dsql_describe() を参照） */

/* 入力 XSQLDA を割り当てて入力します。この例では、入力パラメータの数（1）など、値を提供するために必要な情報がすべてわかっているものとします。わかっていない場合は、isc_dsql_describe_bind() を呼び出す必要があります */isqlda = (XSQLDA *)malloc(XSQLDA_LENGTH(1));


isqlda->sqln = 1;

isqlda->sqld = 1;

ivar = isqlda->sqlvar[0];

ivar->sqltype = SQL_TEXT;

ivar->sqllen = sizeof(state);

ivar->sqldata = state;

/* 文を実行します */isc_dsql_execute(

status_vector,




isqlda);


{


return(1);

}

/* XSQLVAR 構造体を設定し、返される各項目の領域を割り当てます */for (i=0, ovar = osqlda->sqlvar; i < osqlda->sqld; i++, ovar++)



{

dtype = (ovar->sqltype & ~1) /* NULL ビットを削除します */switch(dtype)

{

case SQL_TEXT:

ovar->sqldata = (char *)malloc(sizeof(char) * ovar->sqllen);

break;

case SQL_LONG:

ovar->sqldata = (char *)malloc(sizeof(long));

/* 残りの型を処理します */. . .

}

if (ovar->sqltype & 1)

{

/* NULL ステータスを保持するための変数を割り当てます */ovar->sqlind = (short *)malloc(sizeof(short));

}


/* 選択リストの行を 1 行ずつ取り出して処理します */while ((fetch_stat = isc_dsql_fetch(

status_vector,

&stmt_handle,

1,

osqlda)) == 0)

{

for (i=0; i < osqlda->sqld; i++)

{

/* 記述した関数を呼び出して、返された選択リストの各項目を処理します */process_column(osqlda->sqlvar[i]);

}

}

戻り値 isc_dsql_execute() は、ステータスベクターの第 2 要素を返します。0 の場合は正常に終了



されます。




参照 isc_dsql_describe_bind()、isc_dsql_exec_immed2()、isc_dsql_execute_immediate()、isc_dsql_execute2()、isc_dsql_fetch()、isc_dsql_prepare()


i s c _ d s q l _ e x e c u t e 2 ( )

XSQLDA の作成と値の設定については、6-6 ページの「XSQLDA」を参照してください。

isc_dsql_execute2()

前もって作成されている DSQL ステートメントを実行します。

構文 ISC_STATUS isc_dsql_execute2(





XSQLDA *in_xsqlda,

XSQLDA *out_xsqlda);

説明 isc_dsql_execute2() は、EXECUTE PROCEDURE ステートメントや SELECT ステートメント

のように、入力パラメータと戻り値の両方を持つ作成済みの DSQL ステートメントを実行

します。

入力パラメータの値を必要とする文、つまりパラメータマーカを含む DSQL ステートメン

トを実行する場合は、isc_dsql_execute2() を呼び出す前に、入力 XSQLSQL ステートメント

DA（in_xsqlda）に値を設定しなければなりません。

実行した DSQL ステートメントから返される値は、指定した出力 XSQLDA（out_xsqlda）に格納されます。出力 XSQLDA に NULL を指定した場合、戻り値は結果セットに格納さ

れます。戻り値にアクセスするには、isc_dsql_fetch() を呼び出します。

ヒント 1 つのデータグループだけを返す DSQL ステートメントを一度だけ実行する場合は、

isc_dsql_prepare() と isc_dsql_execute2() ではなく、isc_dsql_exec_immed2() を使用しま

す。






in_xsqlda XSQLDA * （オプション）前もって割り当てた入力 XSQLDA へのポインタ。入力パラメータがない場合、この値は NULL に設定する

out_xsqlda XSQLDA * （オプション）前もって割り当てた出力 XSQLDA へのポインタ。必要がない場合、この値は NULL に設定する


i s c _ d s q l _ e x e c u t e 2 ( )

戻り値がない DSQL ステートメントを実行する場合は、isc_dsql_prepare() とisc_dsql_execute2() ではなく、isc_dsql_execute_immediate() を使用します。

メモ isc_dsql_execute() および isc_dsql_execute2() は、CREATE DATABASE ステートメントと SETTRANSACTION ステートメントの実行には使用できません。これらの DSQL ステートメント

には、

isc_dsql_execute_immediate() を使用してください。

例次のプログラムは順に、入力 XSQLDA を割り当ててそこに値を設定し、出力 XSQLDA を割り当て、EXECUTE PROCEDURE ステートメントを作成し、呼び出しによって抽出された

各行の各列用の領域を出力 XSQLDA に割り当て、後に作成した DSQL ステートメント

を実行して戻り値を出力 XSQLDA に格納します。

#include <ibase.h>


XSQLDA *isqlda, *osqlda;

XSQLVAR *ivar, *ovar;

short null_flag;

char *str = "EXECUTE PROCEDURE P1";

char *state = "CA";

/* 出力 XSQLDA osqlda を割り当てます。この例では、P1 が 1 つの値を返すことがわかっているとします */osqlda = (XSQLDA *)malloc(XSQLDA_LENGTH(1);


osqlda->sqln = 1;

/* 文を作成します。この文（プロシージャ）から返される項目に関する情報を osqlda に設定します */isc_dsql_prepare(

status_vector,




str,

1,

osqlda);


{


return(1);

}

/* 戻り値のための領域を割り当てるために出力 XSQLVAR 構造体を設定します。この例でも、P1 が 1 つだけ値を返すことがわかっているとします。これがわからない場合の例については、isc_dsql_describe() を参照してください。複数の戻り値のための領域を割り


i s c _ d s q l _ e x e c u t e 2 ( )

当てるために出力 XSQLVAR 構造体を設定する例については、isc_dsql_execute() のサンプルプログラムを参照してください。*/ovar = osqlda->sqlvar[0];

dtype = (ovar->sqltype & ~1); /* NULL ビットを削除します */switch(dtype)

{

case SQL_TEXT:

ovar->sqldata = (char *)malloc(sizeof(char) * ovar->sqllen);

break;

case SQL_LONG:

ovar->sqldata = (char *)malloc(sizeof(long));

/* 残りの型を処理します */. . .

}

if (ovar->sqltype & 1)

{

/* NULL ステータスを保持するための変数を割り当てます */ovar->sqlind = &null_flag;

}

/* 入力 XSQLDA を割り当てて入力します。この例では、入力パラメータの数（1）など、値を提供するために必要な情報がすべてわかっているものとします。わかっていない場合は、isc_dsql_describe_bind() を呼び出す必要があります */isqlda = (XSQLDA *)malloc(XSQLDA_LENGTH(1);


isqlda->sqln = 1;

isqlda->sqld = 1;

ivar = isqlda->sqlvar[0];

ivar->sqltype = SQL_TEXT;

ivar->sqllen = sizeof(state);

ivar->sqldata = state;

/* 文を実行します */isc_dsql_execute2(

status_vector,




isqlda,

osqlda);


{


return(1);


i s c _ d s q l _ e x e c u t e _ i m m e d i a t e ( )

}

/* ここで、osqlda->sqlvar[0] に返される値を処理します */. . .

戻り値 isc_dsql_execute2() は、ステータスベクターの第 2 要素を返します。0 の場合は正常に終

了したことを示します。0 以外の場合は、エラーが発生したことを示します。InterBase エラーの場合は、ステータスベクターの第 1 要素が 1 に設定され、第 2 要素は、


されます。




参照 isc_dsql_exec_immed2(), isc_dsql_execute_immediate()、isc_dsql_execute()、isc_dsql_fetch()、isc_dsql_prepare()


isc_dsql_execute_immediate()

データを返さない DSQL ステートメントを作成して実行します。データベースを作成する

ための isc_dsql_execute_immediate() の特殊なケースがあります。

構文 ISC_STATUS isc_dsql_execute_immediate(




unsigned short length,

char *statement,

unsigned short dialect,

XSQLDA *xsqlda);

メモ CREATE DATABASE ステートメントを使用している特殊なケースではトランザクションが発

生しないので、db_handle および trans_handle は、値が NULL のハンドルを指すポインタで

なければなりません。isc_dsql_execute_immediate() が復帰すると、db_handle は、

isc_attach_database() 呼び出しを行ったかのように有効なハンドルを指します。



説明 isc_dsql_execute_immediate() は、statement に指定された DSQL ステートメントを作成し

て実行し、後に廃棄します。SELECT ステートメントや EXECUTE PROCEDURE ステート

メントのように、値を返す DSQL ステートメントは使用できません。

statement が入力パラメータの値を必要とする場合、つまりパラメータマーカを含む文を実

行する場合は、入力 XSQLDA の xsqlda に値を設定しなければなりません。

isc_dsql_execute_immediate() を使ってデータベースを作成するには、CREATE DATABASEステートメントで db_handle および trans_handle が NULL 値を持つハンドルを指し示す

ようにします。

ヒント statement がデータを返す場合、または 2 回以上実行される場合は、isc_dsql_execute_immediate()を使用しません。その場合、isc_dsql_prepare() と isc_dsql_execute()（または isc_dsql_execute2()）を使用します。



db_handle isc_db_handle * • statement が CREATE DATABASE でない場合は、isc_attach_database() の呼び出しで前もって設定されているデータベースハンドルを指すポインタ。NULL の場合、db_handle は status_vector にエラーを返す

• statement が CREATE DATABASE の場合は、値が NULL のデータベースハンドルを指し示さなければならない

trans_handle isc_tr_handle * • statement が CREATE DATABASE でない場合は、isc_start_transaction() の呼び出しで前もって設定されているトランザクションハンドルを指すポインタ。NULL の場合、db_handle はエラーを返す

• statement が CREATE DATABASE または SETTRANSACTION の場合は、値が NULL のトランザクションハンドルを指さなければならない

length unsigned short DSQL ステートメントの長さ（バイト数）。C の場合は 0 に設定して、NULL で終わる文字列であることを示す

statement char * 実行する DSQL 文字列

dialect unsigned short • 文の SQL ダイアレクトを示す

• クライアントの SQL ダイアレクトに等しいか小さい値でなければならない

xsqlda XSQLDA * 前もって割り当てた入力 XSQLDA へのポインタ（オプション）。入力パラメータがない場合は、この値をNULL に設定する



メモ CREATE DATABASE または SET TRANSACTION ステートメントの場合は、

isc_dsql_prepare() や isc_dsql_execute() ではなく isc_dsql_execute_immediate() を呼び出

す必要があります。トランザクションを開始する場合には、isc_start_transaction() を使用

することもできます。

例次のコードは isc_dsql_execute_immediate() を呼び出して挿入を行います。

#include <ibase.h>


char *insert_stmt =

"INSERT INTO CUSTOMER(CUSTNAME, BAL, CUSTNO)

VALUES("John Smith", 299.0, 5050)";


status_vector,


&tr_handle, /* 先の isc_start_transaction() 呼び出しで設定されます */0,

insert_stmt,

1,

NULL);


{


return(1);

}

次の C/C++ コードは、isc_dsql_execute_immediate() を使ってデータベースを作成し、新

しいデータベースのハンドルを返します。

#include <ibase.h>


char *statement =

"CREATE DATABASE 'C:/INVENTORY.IB' PAGE_SIZE 4096 ¥

USER 'SYSDBA' PASSWORD 'masterkey'";

isc_db_handle db_handle = NULL;

isc_tr_handle dummy_handle = NULL;


status_vector,

&db_handle,

&dummy_handle,

0,

statement,

1,

NULL);



i s c _ d s q l _ e x e c _ i m m e d 2 ( )

{


return(1);

}

戻り値 isc_dsql_execute_immediate() は、ステータスベクターの第 2 要素を返します。0 の場合は



isc_bad_db_handle、isc_bad_trans_handle、または他の InterBase エラーコードに設定さ

れます。




参照 isc_dsql_exec_immed2()、isc_dsql_execute(), isc_dsql_prepare()





isc_dsql_exec_immed2()

1 行のデータだけを返す DSQL ステートメントを作成して 1 回だけ実行します。

構文 ISC_STATUS isc_dsql_exec_immed2(





char *statement,


XSQLDA *in_xsqlda,

XSQLDA *out_xsqlda);





trans_handle isc_tr_handle * isc_start_transaction() の呼び出しで前もって設定されているトランザクションハンドルを指すポインタ。trans_handle がNULL の場合はエラーが返される


i s c _ d s q l _ e x e c _ i m m e d 2 ( )

説明 isc_dsql_exec_immed2() は、statement で指定された DSQL ステートメントを作成し、1回実行して廃棄します。statement は、EXECUTE PROCEDURE ステートメントや単一行

SELECT ステートメントのように、1 セットの値を出力 XSQLDA に返すことができます。

statement が入力パラメータの値を必要とする場合、つまりパラメータマーカを持つ場合、

その値を入力 XSQLDA の in_xsqlda に設定しなければなりません。

複数行のデータを返す DSQL ステートメントを実行する場合は、isc_dsql_prepare()、isc_dsql_execute2()、および isc_dsql_fetch() を併用します。

例次のプログラムは isc_dsql_exec_immed2() を呼び出します。


XSQLDA *in_xsqlda, *out_xsqlda;

char *execute_p1 = "EXECUTE PROCEDURE P1 ?";

/* ここで、入力および出力 XSQLDA 構造体を設定します */. . .

isc_dsql_exec_immed2(

status_vector,


&tr_handle, /* 先の isc_start_transaction() 呼び出しで設定されます */0,

execute_p1,

1,

in_xsqlda,

out_xsqlda);

if (status_vector[0] == 1 && status_vector[1]) {


return(1);

}



dialect unsigned short • statement の SQL ダイアレクトを示す


in_xsqlda XSQLDA * （オプション）前もって割り当てた入力 XSQLDA へのポインタ。入力パラメータがない場合、この値は NULL に設定する

out_xsqlda XSQLDA * （オプション）前もって割り当てた、実行された文の結果を返す先となる XSQLDA へのポインタ。必要がない場合、この値は NULL に設定する



i s c _ d s q l _ f e t c h ( )

戻り値 isc_dsql_exec_immed2() は、ステータスベクターの第 2 要素を返します。0 の場合は正常


isc_bad_db_handle、isc_bad_trans_handle、または他の InterBase エラーコードに設定さ

れます。





参照 isc_dsql_execute2()、isc_dsql_prepare()

isc_dsql_fetch()

すでに作成され実行された DSQL ステートメントが返したデータを取り出します。

構文 ISC_STATUS isc_dsql_fetch(




XSQLDA *xsqlda);

説明 isc_dsql_fetch() は、1 回の呼び出しでデータを 1 行ずつ抽出して xsqlda に格納します。複

数行のデータをカーソルに返す DSQL ステートメントの場合は、ループの中で

isc_dsql_fetch() を使って抽出と処理を繰り返します。

カーソルは、DSQL ステートメントによって抽出された順序付きの行セットに対する一方

向のポインタです。カーソルが必要となるのは、オプションの FOR UPDATE OF 句を指定

した SELECT ステートメントを isc_dsql_fetch() で実行し、抽出された行に対して位置指定

付きの UPDATE ステートメントや DELETE ステートメントを実行する場合だけです。

ループ構造でデータを取り出すかどうかは、アプリケーションで指定します。



stmt_handle isc_stmt_handle * isc_dsql_allocate_statement() または isc_dsql_alloc_statement2()の呼び出しで前もって設定されているステートメントハンドルを指すポインタ。ハンドルが NULL の場合は status_vector にエラーが返される


xsqlda XSQLDA * （オプション）前もって割り当てた、実行された文の結果を返す先となる XSQLDA へのポインタ


i s c _ d s q l _ f e t c h ( )

isc_dsql_fetch() を呼び出す前に、isc_dsql_prepare() を呼び出して DSQL ステートメント

を作成し、isc_dsql_execute() を（または xsqlda 引数を NULL にして isc_dsql_execute2()を）呼び出して DSQL ステートメントを実行しておかなければなりません。DSQL ステー

トメントを実行すると、戻り値を格納した結果セットが出力されます。isc_dsql_fetch() を呼び出すたびに、結果セットから次の行データが抽出され、xsqlda に格納されます。

例次のプログラムは、出力 XSQLDA を割り当て、実行する DSQL ステートメントを作成し、

抽出される各データ列用に XSQLDA 内に XSQLVAR 構造体を割り当て、DSQL ステート

メントを実行して、戻り値のセレクトリストを出力し、ループ内で 1 行ずつ取り出して処

理します。

#include <ibase.h>

#define LASTLEN 20

#define FIRSTLEN 15

#define EXTLEN 4

typedef struct vary {

short vary_length;

char vary_string[1];

} VARY;

ISC_STATUS status_vector[20], retcode;

long SQLCODE;

XSQLDA *osqlda;

XSQLVAR *ovar;

short flag0, flag1, flag2;

char *str =

"SELECT last_name, first_name, phone_ext FROM phone_list

WHERE location = "Monterey" ORDER BY last_name, first_name";

char last_name[LASTLEN + 2];

char first_name[FIRSTLEN + 2];

char phone_ext[EXTLEN + 2];

VARY *vary;

/* 出力 XSQLDA osqlda を割り当てます */osqlda = (XSQLDA *)malloc(XSQLDA_LENGTH(3);


osqlda->sqln = 3;

/* 文を作成します */isc_dsql_prepare(

status_vector,




str,

1,

osqlda);



i s c _ d s q l _ f e t c h ( )

{


return(1);

}

/* XSQLVAR 構造体を設定し、返される各項目の領域を割り当てます */osqlda->sqlvar[0].sqldata = last_name;

osqlda->sqlvar[0].sqltype = SQL_VARYING + 1;


osqlda->sqlvar[1].sqldata = first_name;



osqlda->sqlvar[2].sqldata = phone_ext;



/* 文を実行します */isc_dsql_execute(

status_vector,




NULL);


{


return(1);

}

printf("¥n%-20s %-15s %-10s¥n¥n", "LAST NAME", "FIRST NAME", "EXTENSION");

/* 選択リスト内のレコードを 1 つずつ取り出して出力します */while ((retcode = isc_dsql_fetch(

status_vector,

&stmt_handle,

1,

osqlda)) == 0)

{

vary = (VARY *)last_name;

printf("%-20.*s ", vary->vary_length, vary->vary_string);

vary = (VARY *)first_name;


vary = (VARY *)phone_ext;



i s c _ d s q l _ f r e e _ s t a t e m e n t ( )

}

if (retcode != 100L)

{



return(1);

}

戻り値 isc_dsql_fetch() は、ステータスベクターの第 2 要素を返します。0 の場合は正常に終了し


の場合は、ステータスベクターの第 1 要素が 1 に設定され、第 2 要素は、isc_bad_stmt_handleまたは他の InterBase エラーコードに設定されます。




参照 isc_dsql_execute()、isc_dsql_execute2(), isc_dsql_prepare()

isc_dsql_free_statement()

次の 3 つのアクションの 1 つを実行します。

• ステートメントハンドルとそれに割り当てられているすべてのリソースを解放します。

• ステートメントハンドルによって参照される文に関連付けられているカーソルを閉じ

ます。

• サーバーでの文の実行を取り消します。

構文 ISC_STATUS isc_dsql_free_statement(



unsigned short option);



stmt_handle isc_stmt_handle * isc_dsql_allocate_statement() またはisc_dsql_alloc_statement2() の呼び出しで前もって設定されているステートメントハンドルを指すポインタ。ハンドルが NULL の場合は、status_vector にエラーが返される

option unsigned short 次の中の 1 つDSQL_closeDSQL_dropDSQL_cancel


i s c _ d s q l _ f r e e _ s t a t e m e n t ( )

説明 isc_dsql_free_statement() は、option = DSQL_drop の場合はステートメントハンドルと

ステートメントハンドルに割り当てられていたすべてのリソースを解放し、option =DSQL_close の場合は DSQL ステートメントに関連付けられていたカーソルを閉じるか、

option = DSQL_cancel の場合は文の実行を取り消します。

メモ DSQL_drop、DSQL_clos、または DSQL_cancel 以外のオプションを指定した場合、

isc_dsql_free_statement() は何もしません。

DSQL_closeDSQL_close は、カーソルが不要になった場合、つまりクエリーの実行の結果として得ら

れたすべての行の取り出しと処理が完了した場合にカーソルを閉じます。

isc_dsql_set_cursor_name() を使って stmt_handle に関連付けて開いたカーソルは、この

方法で閉じる必要があります。

DSQL_close でカーソルを閉じても、関連付けられていた DSQL ステートメントはそのま

ま以降の実行に使用できます。

クエリーから返された行をカーソルを使って更新または削除した後、異なる入力パラメー

タを使って同じ DSQL ステートメントを再実行して、行の更新や削除を行いたい場合は、

次の手順に従います。

1 isc_dsql_free_statement() を呼び出してカーソルを閉じます。

2 isc_dsql_set_cursor_name() を使ってカーソルを再び開きます。

3 必要に応じて、DSQL ステートメントに渡す入力パラメータを変更します。

4 DSQL ステートメントを再実行し、新しいセレクトリストを使って抽出します。

5 isc_dsql_fetch() を使って各行を抽出し、isc_dsql_execute_immediate() を使って処理し

ます。

DSQL_dropisc_dsql_allocate_statement() 使って割り当てたステートメントハンドルが不要になった

場合は、DSQL_drop オプションを指定した isc_dsql_free_statement() を呼び出して解放し

なければなりません。ステートメントハンドルに結び付けられたすべてのリソースが解放

され、開いているカーソルが閉じます。

例次のプログラムは、2 とおりの isc_dsql_free_statement() を呼び出しています。stmt_handle1および stmt_handle2 は、isc_dsql_allocate_statement() または isc_dsql_alloc_statement2()を呼び出して前もって割り当てたステートメントハンドルです。stmt_handle1 が参照する

DSQL ステートメントには、カーソルも結び付けられています。

#include <ibase.h>


. . .

/* stmt_handle1 に関連付けられているカーソルを解放します */isc_dsql_free_statement(

status_vector,

&stmt_handle1,

DSQL_close);


{


i s c _ d s q l _ p r e p a r e ( )


return(1);

}

/* stmt_handle2 を解放します */isc_dsql_free_statement(

status_vector,

&stmt_handle2,

DSQL_drop);


{


return(1);

}

DSQL_cancelDSQL_cancel オプションを使用すると、文の実行を非同期に取り消すことができます。文

を実行していたクライアントは、isc_cancelled のステータスコードを受け取ります。文が

取り消されると、その後で文を実行しても、その文は再開されずに初から開始されます。

戻り値 isc_dsql_free_statement() は、ステータスベクターの第 2 要素を返します。0 の場合は、正


InterBase エラーの場合は、ステータスベクターの第 1 要素が 1 に設定され、第 2 要素は

isc_bad_stmt_handle などの InterBase エラーコードに設定されます。InterBase エラーの

有無を判定するには、ステータスベクターの先頭の 2 つの要素を直接チェックします。ス

テータスベクターの値を調べる方法については、第 10 章「エラー条件の処理」を参照し

てください。

参照 isc_dsql_allocate_statement()、isc_dsql_alloc_statement2()、isc_dsql_set_cursor_name()

isc_dsql_prepare()

繰り返して実行する DSQL ステートメントを作成します。

構文 ISC_STATUS isc_dsql_prepare(





char *statement,


XSQLDA *xsqlda);



説明 isc_dsql_prepare() は、statement に指定された DSQL ステートメントに構文エラーがない

かをチェックし、効率よく実行できる形式に解析して繰り返し実行できるようにします。

SELECT ステートメントは、必ず isc_dsql_prepare() で作成しておかなければなりません。

作成が完了した DSQL ステートメントは、現行セッション内で繰り返し実行できます。繰

り返して実行できるように DSQL ステートメントを作成するのは、

isc_dsql_execute_immediate() または

isc_dsql_exec_immed2() を何度も呼び出して DSQL ステートメントをそのつど作成して

実行するより高い効率が得られます。

作成する文がデータを返さない場合は、出力 XSQLDA を NULL に設定します。データを返

す場合は、isc_dsql_prepare() を呼び出す前に出力 XSQLDA を割り当てておかなければな

りません。XSQLDA は、ibase.h で定義されている XSQLDA_LENGTH マクロを使って次の

ように割り当てます。

xsqlda = (XSQLDA *)malloc(XSQLDA_LENGTH(n));

XSQLDA_LENGTH は、DSQL ステートメントが返す n 個の列を格納するのに必要なバイ

ト数を算出し、格納に必要な領域を割り当てます。

XSQLDA（xsqlda）を割り当てた後は、xsqlda->version を SQLDA_CURRENT_VERSIONに設定し、xsqlda->sqln を XSQLVAR 構造体の割り当て数に設定します。

isc_dsql_prepare() を呼び出し、XSQLDA の残りのフィールドと XSQLVAR の全フィール

ドにデータを入力します。作成する文のセレクトリスト項目に対応するデータ型、長さ、項

目名などの情報を入力します。xsqlda->sqld には、実際に返されるセレクトリスト項目の

数が格納されます。xsqlda->sqld の値が xsqlda->sqln の値より大きい場合は、次の手順に

従って XSQLDA のサイズを変更してください。

1 xsqlda->sqld の値を記録する。




stmt_handle isc_stmt_handle * isc_dsql_allocate_statement() または isc_dsql_alloc_statement2()の呼び出しで前もって設定されているステートメントハンドルを指すポインタ。ハンドルが NULL の場合はstatus_vector にエラーが返される



dialect unsigned short • statement の SQL ダイアレクトを示す





2 xsqlda に割り当てた格納領域を解放する。

3 XSQLDA_LENGTH の引数で設定した値（ステップ 1 の値）を正しく指定し、xsqlda の格納領域を割り当て直す。

4 xsqlda->sqld および xsqlda->version を再設定する。

5 isc_dsql_describe() を実行して xsqlda のフィールドを入力する。

メモ作成する DSQL ステートメントに入力パラメータが必要な場合は、isc_dsql_execute() や

isc_dsql_execute2() を呼び出す前に入力 XSQLDA を割り当て、値を設定しておく必要があり

ます。入力 XSQLDA を割り当てて各フィールドを直接設定するか、まず割り当ててから

isc_dsql_describe_bind() を呼び出してパラメータの数と型を判定し、適切な値を設定する

ことができます。

例次のプログラムは、出力 XSQLDA を割り当て、isc_dsql_prepare() を呼び出しています。

#include <ibase.h>


XSQLDA *osqlda;

char *query = "SELECT CITY, STATE, POPULATION FROM CITIES ¥

WHERE STATE = "NY" ORDER BY CITY DESCENDING";

osqlda = (XSQLDA *)malloc(XSQLDA_LENGTH(3);


osqlda->sqln = 3;

isc_dsql_prepare(

status_vector,




query,

1,

osqlda);


{


return(1);

}

これ以降の実行とデータの取り出しについては、isc_dsql_execute()、isc_dsql_execute2()、および isc_dsql_fetch() のプログラム例を参照してください。

戻り値 isc_dsql_prepare() は、ステータスベクターの第 2 要素を返します。0 の場合は正常に終了



されます。


i s c _ d s q l _ s e t _ c u r s o r _ n a m e ( )




XSQLDA の作成と値の設定については、第 6 章「動的 SQL の操作」の 6-6 ページの


参照 isc_dsql_describe(), isc_dsql_describe_bind()、isc_dsql_execute()、isc_dsql_execute2()、isc_dsql_fetch()

isc_dsql_set_cursor_name()

カーソルの名前を定義し、DSQL ステートメントに関連付けます。

構文 ISC_STATUS isc_dsql_set_cursor_name(



char *cursor_name,

unsigned short type);

説明 isc_dsql_set_cursor_name() は、SELECT ステートメントのように複数にわたる行のデータ

を返す DSQL ステートメントについて、カーソル名を定義して DSQL ステートメントハンドルに結び付け、データアクセスに使用するカーソルをすばやく開けるようにします。

カーソルは、DSQL ステートメントによって抽出された順序付きの行セットに対する一方

向のポインタです。カーソルが必要となるのは、オプションの FOR UPDATE OF 句を指定

した SELECT ステートメントを isc_dsql_fetch() で実行し、抽出された行に対して位置指定

付きの UPDATE ステートメントや DELETE ステートメントを実行する場合だけです。

メモ UPDATE や DELETE ステートメントでは、カーソル名をパラメータマーカ "?" として指定

することはできません。

カーソルが不要になった場合は、isc_dsql_free_statement() で DSQL_close オプションを

指定して閉じます。

例次のコードは、isc_dsql_set_cursor_name() で名前を設定して開いたカーソルを使用して、

WHERE CURRENT OF 句を指定した UPDATE ステートメントまたは DELETE ステートメン

トを実行します。




cursor_name char * カーソル名の文字列

type unsigned short 将来用に予約。NULL に設定する


i s c _ d s q l _ s e t _ c u r s o r _ n a m e ( )

#include <ibase.h>


isc_stmt_handle st_handle = NULL;

char *cursor = "S";

/* ステートメントハンドル st_handle を割り当てます */isc_dsql_allocate_statement(

status_vector,

&db, /* isc_attach_database() 呼び出しによって設定されるデータベースハンドル */

&st_handle);


{


return(1);

}

/* ここで、出力 XSQLDA osqlda を設定します */

/* isc_dsql_prepare() を呼び出して SELECT ステートメントを作成します */

/* 必要に応じて、SELECT ステートメントのための入力 XSQLDA を設定します */

/* isc_dsql_execute() を呼び出して SELECT ステートメントを実行します */

/* 必要に応じて、UPDATE ステートメントまたは DELETE ステートメントのための入力 XSQLDA を設定します */

/* カーソル名を宣言し、それを st_handle に関連付けます */isc_dsql_set_cursor_name(

status_vector,

&st_handle,

cursor, 0);


{


return(1);

}

/* 取り出す行にカーソルを置き、1 行ずつ行を取り出します。UPDATE ステートメントまたは DELETE ステートメントを実行して、カーソルで示された行を更新または削除します */

while ((fetch_stat = isc_dsql_fetch(

status_vector, &st_handle, 1, osqlda)) == 0)

{

. . .

/* "UPDATE ...WHERE CURRENT OF S" ステートメントまたは "DELETE ... WHERE CURRENT OF S" ステートメントを実行して、現在の行を更新または削除します。ここで "S" は、isc_dsql_set_cursor_name() で宣言されたカーソルの名前です */

}


i s c _ d s q l _ s q l _ i n f o ( )

戻り値 isc_dsql_set_cursor_name() は、ステータスベクターの第 2 要素を返します。0 の場合は正







参照 isc_dsql_fetch()、isc_dsql_free_statement()

isc_dsql_sql_info()

作成済みの DSQL ステートメントについて要求された情報を返します。

構文 ISC_STATUS isc_dsql_sql_info(



unsigned short item_length,

char *items,

unsigned short buffer_length,

char *buffer);

説明 isc_dsql_sql_info() は、isc_dsql_prepare() 呼び出して作成した DSQL ステートメントに関

する情報を返します。実行時にユーザーが入力した DSQL ステートメントなど、未知の

DSQL ステートメントのタイプを判定します。

要求できる情報は次のとおりです。

• DSQL ステートメントのタイプ

• DSQL ステートメントが必要とする入力パラメータの数

• DSQL ステートメントが返す出力値の数




item_length unsigned short items 内の情報項目の文字列のバイト数

items char * 要求された情報項目の文字列

buffer_length unsigned short 結果バッファ buffer のバイト数

buffer char * 返されたデータを格納するユーザー定義のバッファ。要求した情報の格納に必要な大きさでなければならない


i s c _ d s q l _ s q l _ i n f o ( )

• データ型、小数点以下の桁数、長さなど、各入力パラメータまたは出力値に関する情報

• オプティマイザによって作成されたクエリープラン

例次のプログラムは、isc_dsql_sql_info() を呼び出して、stmt が参照するステートメントハンドルを持つ文のタイプを判定します。

int statement_type;

int length;

char type_item[] = {isc_info_sql_stmt_type};

char res_buffer[8];

isc_dsql_sql_info(

status_vector,

&stmt,

/* isc_dsql_allocate_statement() 呼び出しまたは isc_dsql_alloc_statement2() 呼び出しによって前もって割り当てられます */

sizeof(type_item),

type_item,

sizeof(res_buffer),

res_buffer);

if (res_buffer[0] == isc_info_sql_stmt_type)

{

length = isc_portable_integer(buffer[1], 2);

statement_type = isc_portable_integer(buffer[3], length);

}

戻り値 isc_dsql_sql_info() は、ステータスベクターの第 2 要素を返します。0 の場合は正常に終了





実行時における未知の文のタイプの判定については、第 6 章「動的 SQL の操作」の 6-32ページの「未知の文タイプを実行時に判定する」を参照してください。

参照 isc_dsql_describe_bind()、isc_dsql_describe()、isc_vax_integer()


i s c _ d s q l _ x m l _ b u f f e r _ f e t c h ( )

isc_dsql_xml_buffer_fetch()

指定されたバッファに XML 形式のテキストを返します。

構文 int isc_dsql_xml_buffer_fetch(



unsigned short da_version, char *buffer

int buffer_size

XSQLDA *xsqlda,


説明 isc_dsql_buffer_fetch() は、buffer に XML 形式のテキストを返します。バッファにデータ

を保持できるだけの十分なサイズがない場合、ファイルの処理を完了するには、これを 2回以上呼び出す必要があります。データを 1 行ずつ参照する場合は、isc_dsql_xml_fetch()を使用します。

isc_dsql_xml_buffer_fetch() を使用するには、少なくとも 1024 バイト長の文字配列 bufferを割り当てる必要があります。buffer_size 引数には、渡したバッファのサイズを指定しま

す。この関数が不完全なヘッダー、フッター、またはレコードを返すことはありません。再

度呼び出しを行って完全な XML バッファを取得する必要がある場合は、

xmlda_more_data が設定されます。

例次の例は、前もって作成して実行したステートメントハンドルからデータを取得し、XMLを stdout に出力します。

int buff_size = 2048;

. . .

while (!done){

char *buffer = malloc (buff_size);



stmt_handle isc_stmt_handle * isc_dsql_execute_statement() またはisc_dsql_alloc_execute2() の呼び出しで前もって実行されているステートメントハンドルを指すポインタ


buffer char * 返される XML を保持する文字バッファへのポインタ

buffer_size int buffer のサイズ


ib_xmlda IB_XMLDA* 初期化される XML デスクリプタエリア IB_XMLDA へのポインタ


i s c _ d s q l _ x m l _ f e t c h ( )

int size;

/* バッファのモード ... */size = isc_dsql_xml_buffer_fetch(

status, &stmt, buffer, buff_size, 1, sqlda, &xmlda);

if (size == -2)

/* バッファのサイズを増やす必要があります */{buff_size = buff_size + 1024;

done = 0;

}

else if (size == -1)

/* メモリが不十分です */{printf ("out of memory /n");

free (buffer);

break;

}

else

{printf ("%s", buffer);

if (xmlda.xmlda_more_data)

done = 0;

else

done = 1;

}

free (buffer);

}

InterBase テーブルから XML を生成する完全な例については、第 14 章「XML のエクス

ポート」を参照してください。

戻り値この関数は、（NULL で終わらない）バッファに書き込まれた文字数を返します。続行で

きるだけの十分なメモリがない場合は –1 を返し、バッファが小さすぎる場合は –2 を返し

ます。

参照 isc_dsql_xml_fetch(), isc_dsql_xml_fetch_all()

isc_dsql_xml_fetch()

取得したデータを XML 形式のファイルに追加し、このデータを XSQLDA に返します。

構文 int isc_dsql_xml_fetch(




XSQLDA *xsqlda,



i s c _ d s q l _ x m l _ f e t c h ( )

説明 isc_dsql_xml_fetch() は、前もって作成されて実行された文に対して機能し、呼び出される

たびに xmlda_file_name ファイルに 1 行のデータを返します。ループ内で呼び出されるた

びに、1 行のデータを取得して処理します。isc_dsql_fetch() と同じように使用されます。

データを取り出すためのループ構造は、アプリケーションコードで提供します。

ib_xmlda デスクリプタエリアについては、このマニュアルの「XML のエクスポート」の

章の 14-2 ページで詳しく説明しています。

isc_dsql_xml_fetch() を呼び出す前に、isc_dsql_prepare() を呼び出して文を作成し、

isc_dsql_execute() を呼び出して文を実行しておく必要があります。文を実行すると、返さ

れた行を含む結果セットが生成されます。isc_dsql_xml_fetch() を呼び出すたびに、

stmt_handle を使って InterBase データベースから次にある行データが取得され、2 つの可

能な出力が生成されます。これは、XSQLDA に取り込まれ、ib_xmlda デスクリプタの

xmlda_file_name で指定された XML ファイルに追加されます。

isc_dsql_xml_fetch() を呼び出した後でも、XSQLDA を使ってカーソル内のデータにアクセ

スできます。

例

fetch_stat = isc_dsql_xml_fetch(status_vector, &stmt_handle, 1, sqlda, &xmlda) == 0



参照 isc_dsql_xml_buffer_fetch(), isc_dsql_xml_fetch_all()




da_version unsigned short SQLDA ではなく、XSQLDA を使用するように指定する。この値は 1 に設定する




i s c _ d s q l _ x m l _ f e t c h _ a l l ( )

isc_dsql_xml_fetch_all()

前もって作成されて実行されたステートメントハンドルを使って XML 形式のファイルを

作成します。

構文 int isc_dsql_xml_fetch(




XSQLDA *xsqlda,


説明 isc_dsql_xml_fetch_all() は、クエリーの XML 形式の結果セットを作成します。完全な

XML ファイルを作成するが、1 行ずつデータを参照する必要がない場合は、この関数を使

用します。isc_dsql_xml_fetch() とは異なり、この関数は一度だけ呼び出す必要があります。

データを 1 行ずつ参照する場合は、isc_dsql_xml_fetch() を使用します。



参照 isc_dsql_xml_buffer_fetch()、isc_dsql_xml_fetch()








i s c _ e n c o d e _ s q l _ d a t e ( )

isc_encode_sql_date()

テーブルの DATE 型値の挿入または更新に先だって、C の tm 構造体形式を InterBase のISC_DATE 形式に変換します。

構文 void isc_encode_sql_date(

void *tm_date,

ISC_DATE *ib_date);

説明 isc_encode_sql_date() は、C の tm 構造体の日付を InterBase 内部で使用される ISC_DATE形式に変換します。この関数は、テーブルに DATE 型データを書き込む前に日付を

InterBase で認識できる形式にするために使います。

テーブルの ISC_DATE 構造体に対して DATE 型データの挿入や更新を行うには、isc_dsqlファミリーの API 呼び出しを使用します。

メモ InterBase 6 以降では、DATE データ型はダイアレクト 3 でのみ使用することができます。

DATE データ型は、時刻情報を含まずに日付情報だけを格納します。バージョン 6 のダイ

アレクト 1 では、TIMESTAMP データ型は日付情報と時刻情報の両方を格納します。これ

は、前バージョンの InterBase で用意されていた DATE データ型と同じものです。

例次のコードは、テーブルの挿入や更新を行う前に tm 構造体を宣言して isc_encode_sql_date()を呼び出し、C の tm 構造体形式を InterBase の日付形式に変換します。

#include <time.h>

#include <ibase.h>

. . .


ISC_DATE hire_date;

. . .

/* ここで、tm 構造体に日付情報を格納します */. . .

isc_encode_sql_date(&hire_time, &hire_date);

/* ここで、DSQL の INSERT ステートメントまたは UPDATE ステートメントを使用して、日付を DATE 列に移動します */


参照 isc_decode_sql_date()、isc_encode_sql_time()、isc_encode_timestamp()



ib_date ISC_DATE * InterBase 形式の日付が格納される 8 バイトの ISC_DATE 構造体へのポインタ


i s c _ e n c o d e _ s q l _ t i m e ( )

isc_encode_sql_time()

テーブルの TIME 型値の挿入または更新に先だって、C の tm 構造体形式を InterBase のISC_SQL_TIME 形式に変換します。

構文 void isc_encode_sql_time(

void *tm_date,

ISC_TIME *ib_time);

説明 isc_encode_sql_time() は、C の tm 構造体の時刻を InterBase 内部で使用される ISC_TIME形式に変換します。この関数は、テーブルに TIME 型データを書き込む前に時刻を

InterBase で認識できる形式にするために使います。

テーブルの ISC_TIME 構造体に対して TIME 型データの挿入や更新を行うには、isc_dsqlファミリーの API 呼び出しを使用します。

メモ isc_encode_sql time() はミリ秒をサポートしません。これは、エンコード / デコード関数

が、秒の小数部をサポートしない time.h の struct tm を使用しているためです。

例次のコードは、tm 構造体を宣言し、isc_encode_sql_time() を呼び出します。C の tm 構造

体形式を InterBase の時刻形式に変換して、挿入や更新ができるようにします。

#include <time.h>

#include <ibase.h>

. . .


ISC_TIME hire_date;

. . .

/* ここで、tm 構造体に時刻情報を格納します */. . .

isc_encode_sql_time(&hire_time, &hire_date);

/* ここで、DSQL の INSERT ステートメントまたは UPDATE ステートメントを使用して、* 日付を TIME 列に移動します */


参照 isc_decode_sql_time()、isc_encode_sql_date()、isc_encode_timestamp()



ib_time ISC_TIME * InterBase 形式の時刻を格納する 4 バイトの ISC_TIME 構造体へのポインタ


i s c _ e n c o d e _ t i m e s t a m p ( )

isc_encode_timestamp()

テーブルの TIMESTAMP 型値の挿入または更新に先だって、C の tm 構造体形式を

InterBase の ISC_TIMESTAMP 形式に変換します。

構文 void isc_encode_timestamp(

void *tm_date,

ISC_TIMESTAMP *ib_timestamp);

説明 isc_encode_timestamp() は、C の tm 構造体の日付を InterBase 内部で使用される

ISC_TIMESTAMP 形式に変換します。この関数は、テーブルに TIMESTAMP 型データを書き

込む前に日付および時刻を InterBase で認識できる形式にするために使います。この関数

は、このバージョンでも下位互換性を保つ目的で用意されている従来の isc_encode_date()と同じ機能を持ちます。

テーブルの ISC_TIMESTAMP 構造体に対して TIMESTAMP 型データの挿入や更新を行うに

は、isc_dsql ファミリーの API 呼び出しを使用します。

メモ isc_encode_timestamp() はミリ秒をサポートしません。これは、エンコード / デコード関

数が、秒の小数部をサポートしない time.h の struct tm を使用しているためです。

例次のコードは、テーブルの挿入や更新を行う前に tm 構造体を宣言して isc_encode_timestamp()を呼び出し、C の tm 構造体形式を InterBase の日付形式に変換します。

#include <time.h>

#include <ibase.h>

. . .


ISC_TIMESTAMP hire_date;

. . .

/* ここで、tm 構造体に日時情報を格納します */. . .

isc_encode_timestamp (&hire_time, &hire_date);

/* ここで、DSQL の INSERT ステートメントまたは UPDATE ステートメントを使用して、日付を TIMESTAMP 列に移動します */


参照 isc_decode_timestamp()、isc_encode_sql_date()、isc_encode_sql_time()



ib_timestamp ISC_TIMESTAMP * InterBase 形式の日付および時刻を格納する 8 バイトのISC_TIMESTAMP 構造体へのポインタ


i s c _ e v e n t _ b l o c k ( )

isc_event_block()

以降の API イベント呼び出しで使用する 2 つのイベントパラメータバッファ（EPB）を割

り当てます。

構文 long isc_event_block(

char **event_buffer,

char **result_buffer,

unsigned short id_count,

. . .);

説明 isc_event_block() は、他のイベント関数を呼び出す前に呼び出さなければなりません。

isc_event_block() は以下のことを行います。

• 同じサイズのイベントパラメータバッファを 2 つ割り当て、event_buffer と result_buffer でアドレスを指定された char ポインタに各バッファのアドレスを格納します。

• event_buffer が参照するバッファに、指定したイベントの名前とイベントの発生回数を格納

します。イベント名は、isc_event_block() の終引数として指定します。イベントカウント

は 0 に初期化され、イベント発生の待機を設定するまでに記録されたイベント数を示しま

す。

• バッファの長さ（バイト数）を返します。

バッファの名前と長さは、isc_wait_for_event()、isc_que_events()、および

isc_event_counts() の呼び出しで使用されます。event_buffer は関連するイベントを示した

り、イベントカウントを保持します。イベントが通知されると、event_buffer と同じ内容

が result_buffer に入力されますが、result_buffer のイベントカウントは更新されます。そ

の後で isc_event_counts() を呼び出し、event_buffer にカウントを設定したときから、

result_buffer のカウントを設定したときまでに、どのイベントが通知されたかを判定しま

す。

例次のコードは、isc_event_block() を呼び出しています。




event_buffer char ** char ポインタのアドレス。この関数は、イベントパラメータバッファを割り当てて初期化し、バッファのアドレスを charポインタに格納する

result_buffer char ** char ポインタのアドレス。この関数は、イベントパラメータバッファを割り当て、バッファのアドレスを char ポインタに格納する

id_count unsigned short イベント識別子の文字列の数

… char * 大 15 文字で NULL で終わるカンマ区切りの文字列。それぞれがイベント名を表す


i s c _ e v e n t _ c o u n t s ( )

long length;

length = isc_event_block(

&event_buffer,

&result_buffer,

number_of_stocks,


戻り値 isc_event_block() は、割り当てたイベントパラメータバッファのサイズをバイト単位で返

します。

参照 isc_event_counts()、isc_que_events()、isc_wait_for_event()

isc_event_counts()

2 つのイベントパラメータバッファ（EPB）を比較して通知されたイベントカウントを調

べ、以降に isc_que_events() または isc_wait_for_event() を呼び出せるようにイベントパラ

メータバッファを設定します。

構文 void isc_event_counts(


short buffer_length,

char *event_buffer,


説明 isc_event_counts() は、イベントパラメータバッファ event_buffer と result_buffer のイベ

ントカウントを比較し、status_array の先頭から 15 個の要素をセットアップしてカウント

の差を格納します。次に、result_buffer のカウントに等しくなるように event_buffer のカ

ウントを修正して、isc_wait_for_event() または isc_que_events() を再び呼び出せるように

します。

event_buffer のカウントは、前回 isc_event_wait() または isc_que_events() を呼び出した後

で、各イベントが通知された回数を示します。result_buffer のカウントは、現行の

isc_event_wait() または isc_que_events() の呼び出し後にイベントが通知された回数を、

event_buffer のカウントに加算した値です。いずれかの関数呼び出し後にイベントが通知

された場合、そのイベントに関する result_buffer のカウントは、event_buffer のカウント


status_vector long * ステータスベクターへのポインタ。イベントごとに、event_buffer とresult_buffer の対応するイベントカウントの差が格納される。

buffer_length short イベントパラメータバッファの長さ。割り当てを行ったisc_event_block() から返される。

event_buffer char * isc_wait_for_event() または isc_que_events() の呼び出し後のイベントカウントを示すイベントパラメータバッファを指すポインタ

result_buffer char * イベントが通知されると入力されるイベントパラメータバッファを指すポインタ


i s c _ e v e n t _ c o u n t s ( )

より大きくなります。上記の関数の呼び出し中に通知されたイベントが他にもあれば、そ

のイベントのカウントも大きくなります。event_buffer と result_buffer の値の差は

status_vector に格納されます。すべてのカウントを比較するこの機構によって、通知イベ

ントが失われることがなくなります。

例次のコードは、"DEC", "HP", "SUN" という名前のイベントを設定して待機し、

isc_event_counts() を呼び出して、どのイベントが通知されたかを判定します。

#include <ibase.h>





long length;

int i;

length = isc_event_block(

&event_buffer,

&result_buffer,

number_of_stocks,


isc_wait_for_event(

status_vector,

&database_handle, /* 先の isc_attach_database() で設定されます */


result_buffer);


{


}

isc_event_counts(

status_vector,

(short) length,

event_buffer,

result_buffer);



{

/* イベントが通知されました。売買注文を初期化するなどの適切な処理を行います */;

15-100 A P I ガイド

i s c _ e x p a n d _ d p b ( )

}


参照 isc_que_events()、isc_wait_for_event()

isc_expand_dpb()

データベースパラメータを格納するデータベースパラメータバッファを動的に構築または

拡張します。

構文 void isc_expand_dpb(

char **dpb,

unsigned short *dpb_size,

. . .);

説明 isc_expand_dpb() は、DPB を動的に構築または拡張します。主な用途は、isc_attach_database()を呼び出す前の DPB の構築を簡略化することと、エンドユーザーが実行時にユーザー名と

パスワードを入力できるようにすることです。多くの場合 DPB はプログラムによって構築

しますが、isc_expand_dpb() を使うと、ユーザー名、パスワード、メッセージファイル、

キャラクタセットなどのパラメータをアプリケーションから関数に渡し、既存の DPB に追

加することができます。

isc_expand_dpb() には、初期化した割り当て済みの DPB を指すポインタ、および呼び出

し時に DPB で使用している領域のサイズを格納した変数を指すポインタを渡さなければ

なりません。isc_expand_dpb() は、新しい DPB の領域を割り当て、現在の内容を保持し

て、新しいパラメータを追加します。

適切なメモリ管理を行うには、isc_expand_dpb() を呼び出すアプリケーションは free() を呼び出して割り当てメモリを解放する必要があります。

例次のコードは、isc_expand_dpb() を呼び出して DPB を構築し、作成した DPB を使って

データベースに接続します。ここでは、ユーザーに名前とパスワードを入力させるなどし

て、user_name と user_password にすでに値が割り当てられているものとしています。

#include <ibase.h>

char *dpb;


isc_db_handle handle = NULL;

short dpb_length;

/* データベースパラメータバッファを構築します */


dpb char ** 既存の DPB へのポインタ

dpb_size unsigned short * DPB のサイズ（バイト数）へのポインタ

… char * 拡張した DPB に挿入する項目へのポインタ


i s c _ g e t _ c l i e n t _ v e r s i o n ( )

dpb = (char *) malloc(50);

dpb_length = 0;

isc_expand_dpb(&dpb, &dpb_length, isc_dpb_user_name, user_name, isc_dpb_password, user_password, NULL);

isc_attach_database(

status_vector,

0,

"employee.db",

&handle,

dpb_length,

dpb_buffer);


{


return(1);

}



isc_get_client_version()

クライアントバージョン文字列を返します。

構文 void isc_get_client_version(char *version)

説明 isc_get_client_version() は、バージョン文字列を使ってバージョンを作成します。通常の

形式は次のとおりです。

XX-dM.N.n.b

この形式内の要素は次のとおりです。

15-102 A P I ガイド

i s c _ g e t _ c l i e n t _ m a j o r _ v e r s i o n ( )

この関数には、少なくとも 20 文字の文字バッファを渡す必要があります。バッファが短す

ぎる場合は、チェックが実行されません。

戻り値 isc_get_client_version() は、version によって示される文字列に、上で説明した形式でバー

ジョンを返します。

isc_get_client_major_version()

クライアントライブラリのメジャーバージョン番号を返します。

構文 int isc_get_client_major_version()

isc_get_client_minor_version()

クライアントライブラリのマイナーバージョン番号を返します。

構文 int isc_get_client_minor_version ()

isc_get_segment()

開いている BLOB からセグメントを読み取ります。

要素説明

XX 2 文字（大文字）のハードウェア / ソフトウェアプラットフォームコード： • WI = Windows/Intel• SO = Solaris/Sparc• LI = Linux/Intel

d 配布状態

• B = ベータ

• T = テスト

• V = 検証済み

• I = 内部

M メジャーバージョン番号

N マイナーバージョン番号

n マイナーマイナーバージョン番号

b ビルド番号


i s c _ g e t _ s e g m e n t ( )

構文 ISC_STATUS isc_get_segment(



unsigned short *actual_seg_length,

unsigned short seg_buffer_length,

char *seg_buffer);

説明 isc_get_segment() は、すでに開いている BLOB から BLOB セグメントを読み取ります。

seg_buffer_length パラメータは、BLOB データの型に応じて、適切なサイズに設定するこ

とができます。たとえば、テキストファイルから BLOB データを読み取る場合は、一般的

なテキストファイルの文字行長である 72 ～ 80 に合わせて、セグメントバッファの長さを

80 に設定するとよいでしょう。ループ内で実際のセグメント長を 1 回ごとにチェックすれ

ば、行の終わりやファイルの終わりを判定することができます。

BLOB を読み取るには、isc_open_blob2() によって BLOB を開いておかなければなりませ

ん。isc_get_segment() の動作は、直前の呼び出しによって異なります。isc_open_blob2()を呼び出した直後に isc_get_segment() を呼び出した場合は、BLOB の先頭セグメントが

読み取られます。isc_get_segment() の直後に isc_get_segment() を呼び出した場合は、次

のセグメントが読み取られます。

BLOB フィルタを指定して BLOB を開いた場合は、isc_get_segment() による読み取り時

に、各セグメントがフィルタにかけられます。

ビットマップなどのバイナリファイルは、形式変換（TIF から JPEG など）を行う必要がな

い限り、フィルタリングを使わずに直接読み取ることができます。JPG（JPEG）、BMP（Windows 固有のビットマップ）、GIF（CompuServe のグラフィック交換形式）などの

形式を使うと、圧縮したビットマップをデータベースに直接格納することもできます。フィ

ルタリングは不要です。

データベースへのビットマップの格納は、行優先または列優先の順序で行うことができま

す。

バッファが小さいために現在のセグメント全体を格納できない場合、isc_get_segment() はバッファサイズ分だけを読み取って isc_segment を返し、次の isc_get_segment() の呼び出

しでは、次のセグメントではなく同じセグメントの残りの部分を読み取ります。

BLOB の後のセグメントを読み取ると、isc_get_segment() はコード isc_segstr_eof を返

します。



blob_handle isc_blob_handle * 読み取る BLOB のハンドルへのポインタ

actual_seg_length unsigned short * InterBase がバッファから読み取る実際のセグメント長を指すポインタ。セグメント長がバッファ長より短い場合に有用

seg_buffer_length unsigned short セグメントバッファの長さ

seg_buffer char * セグメントバッファへのポインタ

15-104 A P I ガイド

i s c _ i n s t a l l _ c l e a r _ o p t i o n s ( )

BLOB からのデータの読み取りの詳細については、第 7 章「BLOB データの操作」を参


例次のコードは、BLOB からセグメントを抽出して別の BLOB に書き込みます。

get_status = isc_get_segment(status, &from_blob, &seg_len, 80, buffer);


{


return(1);

}

if (get_status != isc_segstr_eof)

write_status = isc_put_segment(status, &to_blob, seg_len, buffer);


{


return(1);

}

戻り値 isc_get_segment() は、ステータスベクターの第 2 要素を返します。0 の場合は正常に終了

したことを示します。isc_segment の場合は、バッファのサイズが不十分なために、セグメ

ント全体を格納できないことを示します。次に isc_get_segment() を呼び出したときは、次

のセグメントではなく、同じセグメントの残りの部分が抽出されます。isc_segstr_eof の場

合は、BLOB の終セグメントが読み取られたことを示します。他の 0 以外の値は、エラー

が発生したことを示します。InterBase エラーの場合は、ステータスベクターの第 1 要素

が 1 に設定され、第 2 要素は、InterBase エラーコードに設定されます。




参照 isc_create_blob2()、isc_open_blob2()、isc_put_segment()

isc_install_clear_options()

isc_install_set_option() によって設定されたすべてのオプションをクリアします。

構文 MSG_NO isc_install_clear_options(OPTIONS_HANDLE *phandle)


phandle OPTIONS_HANDLE* • 現在のインストールのオプションのリストのハンドルを指すポインタ

• 初めて使用する前に 0 に初期化しなければならない

• ハンドルはインストールエンジンによって保守され、プログラムでハンドルを逆参照する必要はなく、また逆参照してはならない


i s c _ i n s t a l l _ e x e c u t e ( )

説明 isc_install_clear_options() は、handle に格納されているオプションと他のデータすべて消

去し、handle を 0 に設定します。handle がすでに 0 であった場合は、警告を返します。

この関数をインストールの初と後に呼び出して、リソースをすべて解放することをお

勧めします。isc_install_clear_options() を呼び出した後は、他のインストール関数に handleを渡す前に、少なくとも 1 回 isc_install_set_option() に handle を渡さなければなりませ

ん。

戻り値成功した場合、isc_install_clear_options() は isc_install_success を返します。処理は完了

したけれども警告が生じた場合は、isc_install_success より小さい値を返します。致命的な

エラーが発生した場合は、isc_install_clear_options() は isc_install_success より大きい値

を返します。

戻り値が isc_install_success 以外の場合は、isc_install_get_message() を呼び出してエラー

メッセージを取得できます。

isc_install_execute()

実際のインストール処理を行います。これには、必要に応じてファイルのコピー、レジス

トリエントリの作成 / 変更、アンインストールオプションの保存、およびサービスファイ

ルの変更が含まれます。

構文 MSG_NO isc_install_execute(OPTIONS_HANDLE handle, TEXT *source_path,

TEXT *dest_path, FP_STATUS *fp_status, void *status_arg, FP_ERROR *fp_error, void *error_arg, TEXT *uninst_file_name)


handle OPTIONS_HANDLE isc_install_set_option() によって作成されたオプションのリストのハンドル。handle の値が NULLまたは 0 の場合はエラーを返す

source_path TEXT* インストールされるファイルが格納されているパス（通常は CD-ROM 上）。source_path が NULLまたは空文字列の場合、関数はエラーを返す

dest_path TEXT* インストール先となるパス。dest_path が NULL または空文字列の場合、関数はエラーを返す

fp_status FP_STATUS* 0 ～ 100 の整数を受け取るコールバック関数へのポインタ。ユーザーがステータス情報を要求しない場合は NULL であってもよい

status_arg void* fp_status() に渡されるユーザー定義データ。多くの場合 NULL

15-106 A P I ガイド

i s c _ i n s t a l l _ e x e c u t e ( )

説明 isc_install_execute() は、以下の処理を含む実際のインストールを行います。

• isc_install_precheck() を呼び出してインストールが実行可能か確認し、isc_install_precheck()がエラーを返した場合はインストールを中止する

• すべての処理を一時ファイル ib_install.log に記録する

• デスティネーションディレクトリが存在しない場合は作成する

• 正しいバージョンのチェックと、（必要であれば）遅延コピー方式を使ってファイルをコ

ピーする

• 必要なレジストリエントリを作成する

• 共有ファイルについてレジストリの UseCount エントリをインクリメントする

• Windows NT/2000/XP では、Guardian と Server をサービスとしてインストールする。

Windows 98 では、レジストリの Run セクションに Guardian を追加する

• 必要であれば、gds_db を Services ファイルに追加する

• 選択されたオプションを、アンインストール時に使用するために ib_uninst.nnn（nnn はシーケンス番号）に書き込む

• メモリからオプションリストを解放する

• 完了時に、ib_install.log をインストールディレクトリに移動します。

• 一定の間隔で fp_status() を呼び出し、インストールの進捗状況（完了したパーセンテージ）

についての情報を渡す

• ユーザーまたはエラーによってインストールが取り消された場合は、クリーンアップを試

みる

ステータスの表示とエラー処理のための関数を作成する場合は、それらの関数へのポイン

タを、fp_status および fp_error のパラメータとして渡します。また、これらの関数にコン

テキスト情報およびデータを status_arg および error_arg の値として渡すこともできます

（この 2 つのパラメータは、通常は NULL を指定します）。

戻り値実行に成功した場合は 0 を返します。エラーが発生した場合は正の数値を、実行は完了し

たが警告がある場合は負の数値を返します。

戻り値が 0 以外の場合は、isc_install_get_message() を呼び出してエラーメッセージを取得

できます。

fp_error FP_ERROR* エラー番号を受け取り、isc_install_execute() が中止、継続、再試行のいずれを行うかを指定するニーモニックを返すコールバック関数へのポインタ

error_arg void* fp_error() に渡されるユーザー定義データ。多くの場合 NULL

uninst_file_name TEXT* アンインストールファイルの名前が入ったバッファへのポインタ。NULL に設定することもできる



i s c _ i n s t a l l _ g e t _ i n f o ( )

isc_install_get_info()

要求された情報を人が読める形式で返します。要求できる情報は、推奨されるインストー

ルディレクトリ、必要なディスク容量、オプション名、およびオプションの説明です。

構文 MSG_NO isc_install_get_info(OPT option, int info_type, void *info_buf,

unsigned int buf_len)

説明 isc_install_get_info() は、info_type によって要求された情報を info_buf に返す。info_bufおよび buf_len パラメータは NULL であってはならない

戻り値関数の実行に成功した場合は 0 を返します。エラーが発生した場合は正の値を返し、関数

が警告を伴って完了した場合は負の値を返します。

戻り値が 0 以外の場合は、isc_install_get_message() を呼び出してエラーメッセージを取得

できます。

isc_install_get_message() が 0 以外を返した場合は info_buf の内容は不定となるので、呼

び出し側ではこの関数の戻り値を常にチェックする必要があります。


option OPT info_type が 2 ～ 4 の場合は、要求される情報についてのオプション。option が次のトークンの 1 つでない場合はエラーを返す

• IB_CONNECTIVITY_SERVER• IB_CLIENT• IB_CMD_TOOLS• IB_DEV• IB_DOC• IB_EXAMPLES• IB_EXAMPLE_API

• IB_EXAMPLE_DB• IB_GUI_TOOLS• IB_JDBC • IB_JDBC_CLIENT• IB_JDBC_DOCS• IB_SERVER

各オプションについては、isc_install_set_option() を参照してください。

info_type int 要求される情報の種類を指定する。以下の値を指定できる

• isc_install_info_destination：推奨されるデスティネーションを返す。option に渡された値は無視される

• isc_install_info_opspace：特定のオプションのインストールに必要なディスク容量を返す。option には有効な値が必要

• isc_install_info_opname：指定されたオプションの名前を人が読める形式で返す。option には有効な値が必要

• isc_install_info_opdescription：指定されたオプションの説明を人が読める形式で返す。option には有効な値が必要

info_buf void* isc_install_get_info() は、要求された情報をこのバッファに書き込む。info_buf が NULL の場合はエラーが返される。ディスク容量の情報が要求された場合、結果は unsigned long になる

buf_len unsigned int info_buf の長さを示すバイト数。buf_len が NULL の場合はエラーが返される。この値は、少なくとも isc_install_max_message_len バイトでなければならない。推奨デスティネーションが要求される場合の推奨バッファサイズは isc_install_max_path

15-108 A P I ガイド

i s c _ i n s t a l l _ g e t _ m e s s a g e ( )

isc_install_get_message()

要求されたエラーまたは警告メッセージ番号に対応するテキストを返します。

構文 MSG_NO isc_install_get_message(MSG_NO msg_no, TEXT *msg, int msg_len)

説明 isc_install_get message() は、msg_no に格納されているエラー値または警告値を変換して、

対応するメッセージテキストを開発者に返します。

戻り値関数の実行に成功した場合は 0 を返します。エラーが発生した場合は正の値を返し、関数が警告

を伴って完了した場合は負の値を返します。戻り値が 0 以外の場合は、isc_install_get_message()を呼び出してエラーメッセージを取得できます。

isc_install_load_external_text()

指定されたメッセージファイルからメッセージをロードします。

構文 MSG_NO isc_install_load_external_text(TEXT *external_path)

説明 isc_install_load_external_text() は、指定されたパスからメッセージファイルをロードしま

す。このファイルには、インストールのエラーおよび警告メッセージとともに、オプショ

ンの名前と説明、処理のテキスト、説明、およびステータスメッセージを入れることがで

きます。

戻り値関数の実行に成功した場合は 0 を返します。エラーが発生した場合は正の値を返し、関数

が警告を伴って完了した場合は負の値を返します。


msg_no MSG_NO テキストを要求するメッセージ番号。メッセージ番号は、インストール API のすべての関数の戻り値となる

msg TEXT* 返されるメッセージが入るバッファへのポインタ。メッセージは常に NULL で終わる

msg_len int メッセージの長さを示すバイト数。この値は、少なくともisc_install_max_message_len でなければならない


external_path TEXT* 英語以外のエラーおよび警告メッセージのファイルのフルパスとファイル名が入っているバッファへのポインタ


i s c _ i n s t a l l _ p r e c h e c k ( )

isc_install_precheck()

インストール環境について、既存のサーバー、ディスク容量とアクセス、ユーザーのアク

セス権限、オプションの依存関係などの状態をチェックします。

構文 MSG_NO isc_install_precheck(OPTIONS_HANDLE handle, TEXT *source_path,

TEXT *dest_path)

説明 isc_install_precheck() は、インストールが可能かどうかを確認するために多くのチェック

を行います。特に、次のチェックを行います。

• オペレーティングシステムが有効かどうか（現在は、有効なすべての Windows プラット

フォームをチェックします）。

• InterBase Classic サーバー（バージョン 4.1 以前）が存在していないかどうか。InterBaseサーバー（SuperServer）はマルチスレッドアーキテクチャであり、Classic サーバーと共

存できません。

• source_path が存在し、ユーザーから読み出せるディレクトリであるかどうか。source_pathが NULL または空文字列の場合はチェックされません。

• dest_path がユーザーから書き込めるディレクトリであり、選択されたコンポーネントをイ

ンストールできる空き領域がドライブにあるかどうか。dest_path が NULL または空文字

列の場合はチェックされません。

• IB_SERVER オプションの指定されている場合、既存の SuperServer の新しいバージョン

または古いバージョンが実行中でないかをチェックします。

• Windows NT/2000/XP の場合、IB_SERVER オプションが指定された場合、インストー

ルを行っているユーザーが管理者特権を持っているかどうかをチェックします。


handle OPTIONS_HANDLE isc_install_set_option() によって作成されたオプションのリストのハンドル。handle の値が NULL または 0 の場合はエラーを返す

source_path TEXT* インストールするファイルが格納されているパス（通常はCD-ROM 上）。source_path が NULL の場合、このチェックはスキップされる

dest_path TEXT* インストール先となるパス。dest_path が NULL の場合、ディスク容量のチェックはスキップされる

15-110 A P I ガイド

i s c _ i n s t a l l _ p r e c h e c k ( )

• 指定されたオプションおよび必要なオプションの依存関係。オプションの依存関係は次の

とおりです。

例次の呼び出しは、デスティネーションディレクトリを作成し、それをチェックします。

strcpy(dest, dest_path);

if(access(dest, 0) == -1)

{

len = strlen(dest);

if(dest[len - 1] == ‘¥¥’ || dest[len - 1] == ‘/’)

dest[len - 1] = ‘¥0’;

status = UTIL_make_directory(dest);

if(status > isc_install_success)

return status;

}

status = isc_install_precheck(handle, source_path, dest);

if(status > isc_install_success)

return status;

戻り値関数の実行に成功した場合は isc_install_success を返します。エラーが発生した場合は

isc_install_success より大きい値を返し、関数が警告を伴って完了した場合は

isc_install_success より小さい値を返します。戻り値が isc_install_success 以外の場合は、

isc_install_get_message() を呼び出してエラーメッセージを取得できます。

isc_install_precheck() は、オプションの依存関係を除くチェックのいずれかが失敗した場

合にエラーを返します。必要なオプションが指定されていなかった場合には警告を返しま

す。

このオプションが指定された場合このオプションもインストールされなければならない

IB_CMD_TOOLS, IB_GUI_TOOLS,IB_DEV, IB_JDBC,IB_JDBC_CLIENT,IB_CONNECTIVITY

IB_CLIENT

IB_EXAMPLES IB_SERVER、IB_CLIENT、および IB_DEV

IB_EXAMPLE_AP13 IB_CLIENT および IB_DEV

IB_EXAMPLE_DB IB_DEV


i s c _ i n s t a l l _ s e t _ o p t i o n ( )

isc_install_set_option()

選択されているインストールオプションのリストのハンドルを作成します。各オプション

ごとに必ず 1 回呼び出さなければなりません。

構文 MSG_NO isc_install_set_option(OPTIONS_HANDLE *phandle,

OPT option)


phandle OPTIONS_HANDLE 現在のインストールのオプションのリストのハンドルを指すポインタ。初めて使用する前に必ず 0 に初期化しなければならない。handle はインストールエンジンによって保守され、プログラムでハンドルを逆参照する必要はなく、また逆参照してはならない

option OPT option に指定できる値は次のとおり：

• IB_SERVER：InterBase の Server コンポーネント（サーバー、メッセージファイル、Guardian、サーバー環境設定ツール、gstat、UDF ライブラリ、gds_lock_print/iblockpr、国際キャラクタセットライブラリ、およびヘルプファイル）をインストールする。IB_SERVER は、レジストリに必要なエントリをすべて追加し、NT/2000/XP 上では InterBase サービスを作成する（必要であれば Services ファイルに gds_db を追加する）

• IB_CLIENT：InterBase クライアント（クライアントライブラリおよびメッセージファイルを含む）をインストールする。Windows レジストリを変更し、NT/2000/XP 上では（必要であれば）gds_db サービスを追加する

• IB_CMD_TOOLS：Widnows プラットフォーム上に InterBase のすべてのコマンドラインツール（gbak、gfix、gsec、gstat、iblockpr、isql）をインストールする。IB_CLIENT が指定されていない場合は警告を出す

• IB_GUI_TOOLS：IBConsole と関連ヘルプファイルをインストールする。IB_CLIENT が指定されていない場合は警告を出す

• IB_JDBC：関連するドキュメントと新の InterClient JDBC ドライバをインストールする

• IB_JDBC_CLIENT：ドキュメントなしで新の InterClient JDBC ドライバをインストールする

• IB_JDBC_DOCS：InterClient のドキュメントだけをインストールする

• IB_DOC：InterBase のドキュメントをインストールする

• IB_EXAMPLES：InterBase のすべてのサンプルをインストールする（IB_EXAMPLE_API または IB_EXAMPLE_DB の指定と同じ）。IB_SERVER、IB_CLIENT、および IB_DEV が指定されていない場合は警告を出す

• IB_EXAMPLE_API：API、SQL、DSQL、および ESQL サンプルファイルをインストールする。IB_CLIENT および IB_DEV が指定されていない場合は警告を出す

• IB_EXAMPLE_DB：すべてのサンプルデータベースをインストールする。IB_SERVER が指定されていない場合は警告を出す

• IB_DEV：gpre、インポートライブラリ、およびヘッダーファイルをインストールする

15-112 A P I ガイド

i s c _ i n s t a l l _ u n s e t _ o p t i o n ( )

説明 isc_install_set_option() は、要求されたオプション値のリストのハンドルを作成し保守しま

す。インストールする各オプションごとに isc_install_set_option() を 1 回呼び出さなけれ

ばなりません。対話形式のインストールでは、通常この関数はチェックボックスでのマウ

スクリックによって呼び出されます。

初めて isc_install_set_option() を呼び出す前に、handle を 0 に初期化しておかなければな

りません。


isc_install_success より大きい値を返し、関数が警告を伴って完了した場合は

isc_install_success より小さい値を返します。戻り値が isc_install_success 以外の場合は、

isc_install_get_message() を呼び出してエラーメッセージを取得できます。

isc_install_unset_option()

isc_install_set_option() から取得された選択オプションのリストからオプションを削除し

ます。

構文 MSG_NO isc_install_unset_option(OPTIONS_HANDLE *phandle, OPT option)

説明 isc_install_unset_option() は、handle が保守するリストから、option によって指定される

オプションを削除します。削除する各オプションごとに、この関数を 1 回呼び出さなけれ

ばなりません。呼び出されたときに handle が 0 であった場合は、この関数は警告を生成し

ます。


isc_install_success より大きい値を返し、関数が警告を伴って完了した場合は isc_install_successより小さい値を返します。戻り値が isc_install_success 以外の場合は、isc_install_get_message()を呼び出してエラーメッセージを取得できます。


phandle OPTIONS_HANDLE 現在のインストールのオプションのリストのハンドルを指すポインタ。初めて使用する前に必ず 0 に初期化しなければならない。handle はインストールエンジンによって保守され、プログラムでハンドルを逆参照する必要はなく、また逆参照してはならない

option OPT option に指定できるのは、isc_install_set_option() の説明の表に示されている値。option リスト内の後のメンバーの場合、handle は 0 に設定される


i s c _ i n t e r p r e t e ( )

isc_interprete()

エラーステータスベクターからユーザー定義のバッファに InterBase エラーメッセージの

テキストを抽出します。

構文 ISC_STATUS isc_interprete(

char *buffer,

ISC_STATUS **status_vector);

説明プログラムで割り当てた格納バッファの位置とステータスベクターのアドレスが与えられ

ると、isc_interprete() は、ステータスベクターの内容を示すエラーメッセージを作成し、

プログラムで操作できるバッファに形式済みの文字列を格納し、ステータスベクターのポ

インタをエラーメッセージ情報の次のクラスタの先頭に進めます。たとえば、エラー文字

列バッファを宣言し、isc_interprete() を呼び出して先頭のエラーメッセージを抽出して

バッファに入れ、バッファの内容をログファイルに書き込み、次クラスタをチェックして

エラー情報が残っていないかを確認することができます。

isc_interprete() は、1 回の呼び出しでメッセージを 1 つ抽出して書式化します。エラーが

発生すると、通常は複数のエラーメッセージがステータスベクターに格納されます。関連

するすべてのエラーメッセージを抽出するには、エラーメッセージが返されなくなるまで

isc_interprete() を繰り返し呼び出す必要があります。

メモステータスベクターのアドレスを直接渡してはなりません。isc_interprete() は、呼び出さ

れるたびにステータスベクターを指すポインタを修正し、次のメッセージの開始位置に進

めるからです。

すべてのエラーメッセージを、バッファに読み取るのではなく、画面に表示する場合は、

isc_print_status() を使用します。

例次のコードは、メッセージバッファ、ステータスベクター、ステータスベクターへのポイ

ンタを宣言し、isc_interprete() を繰り返し呼び出してすべてのメッセージをバッファに格

納します。

#include <ibase.h>

char msg[512];


long *pvector; /* ステータスベクターへのポインタのポインタ */

FILE *efile; /* ここでは、開いているファイルを示しているとします */. . .

pvector = status_vector; /* ステータスベクターの先頭に（再）設定します */

isc_interprete(msg, &pvector); /* 初のメッセージを取得します */fprintf(efile, "%s¥n", msg); /* バッファの内容をログファイルに書き込みます */

msg[0] = '-'; /* 2 番めのメッセージの先頭にハイフンを追加します */


buffer char * InterBase エラーメッセージを格納先するアプリケーションバッファ

status_vector ISC_STATUS ** エラーステータスベクターへのポインタへのポインタ

15-114 A P I ガイド

i s c _ l i c e n s e _ a d d ( )

while(isc_interprete(msg + 1,&pvector)) /* まだメッセージがあるか？ */{

fprintf(efile, "%s¥n", msg); /* あれば、それらも書き込みます */}

fclose(efile);

. . .

戻り値 isc_interprete() は、正常に終了した場合は、buffer に格納するエラーメッセージの長さを

返し、ステータスベクターのポインタをエラーメッセージ情報の次クラスタの先頭に進め

ます。

ステータスベクターにメッセージが残っていない場合、または isc_interprete() が次のメッ

セージを解釈できない場合は 0 を返します。

参照 isc_print_sqlerror()、isc_print_status()、isc_sqlcode()、isc_sql_interprete()

isc_license_add()

InterBase ライセンスファイルに Certification ID と Certification Key のペアを追加し

ます。

構文 int isc_license_add(char *cert_id, char *cert_key)

説明指定された Certification ID と KEY のペアを含む行を、InterBase インストールディレ

クトリにある ib_license.dat ファイルに追加します。この ID と KEY のペアは、Borlandから取得した有効な認証コードでなければなりません。InterBase の実行には複数の認証

コードを必要とする場合があり、追加する必要がある ID と KEY のペアごとにこの関数を

呼び出さなければなりません。

戻り値認証コードの追加に成功した場合、isc_license_add() は isc_license_msg_restart を返しま

す。エラーが返された場合は、その戻り値を isc_license_get_msg() に渡して正確なエラー

メッセージを取得します。戻り値は次のいずれかです。


cert_id char * 追加する Certification ID を含む NULL で終わる文字バッファへのポインタ。

cert_key char * 追加する Certification KEY を含む NULL で終わる文字バッファへのポインタ。

表 15.21 isc_license_add() が返すエラーコード

戻り値説明

isc_license_msg_restart 認証コードは正しく追加された。

isc_license_msg_writefailed 認証コードを書き込めなかった。


isc_license_msg_convertfailed ID と Key の組み合わせが無効である。


i s c _ l i c e n s e _ c h e c k ( )

isc_license_check()

提供された ID と Key のペアが有効であるかどうかをチェックします。

構文 int isc_license_check(char *cert_id, char *cert_key)

説明指定された ID と Key のペアが有効であり、ib_license.dat に追加可能かどうかをチェック

します。この関数を呼び出しても、ライセンスファイル自体には何も追加されません。

戻り値認証コードの追加が可能と判断された場合、isc_license_check() は isc_license_success を返

します。エラーが返された場合は、その戻り値を isc_license_get_msg() に渡して正確なエ

ラーメッセージを取得します。戻り値は次のいずれかです。

isc_license_remove()

InterBase ライセンスファイルから指定された行を削除します。

構文 int isc_license_remove(char *cert_key)

説明 cert_key によって指定される行を ib_license.dat から削除します。

戻り値 isc_license_remove() の戻り値は次のいずれかです。


cert_id char * チェックする Certification ID を含む NULL で終わる文字バッファへのポインタ。

cert_key char * チェックする Certification Key キーを含む NULL で終わる文字バッファへのポインタ。

表 15.22 isc_license_check() が返すエラーコード

戻り値説明

isc_license_success 認証コードは追加可能である。


isc_license_msg_convertfailed ID とキーの組み合わせが無効である。


cert_key char チェックする証明書キーを含む NULL で終わる文字バッファへのポインタ。

15-116 A P I ガイド

i s c _ l i c e n s e _ d i s p l a y ( )

isc_license_display()

InterBase ライセンスファイルから ID と KEY のペアをバッファにコピーします。

構文 unsigned short isc_license_display(char *buf, unsigned short buf_len)

説明現在 ib_license.dat にあるすべての Certification ID と KEY のペアを buf に入れます。ペ

ア間はカンマで区切られ、後は NULL で終わります。

戻り値成功した場合は 0 を返します。成功しなかった場合は、メッセージテキストの格納に必要

な buf の長さを返し、buf 自体には NULL が入ります。

表 15.23 isc_license_remove() が返す戻り値

戻り値説明

isc_license_msg_restart 認証コードは正しく削除された。

isc_license_msg_notremoved 認証コードは削除できなかった。次の理由が考えられる。

• cert_key によって指定されたキーが ib_license.dat に存在しない。

• cert_key は評価版ライセンスを示している。


buf char * • 結果を格納する文字バッファ。

• プログラム側で割り当てなければなりません。

• buf の長さが足りない場合、isc_license_get_msg はエラーを返します。

• NULL で終わっていなければなりません。

buf_len short • buf の長さ。


i s c _ l i c e n s e _ g e t _ m s g ( )

isc_license_get_msg()

エラーコードのテキストを返します。

構文 unsigned short isc_get_msg(short msg_no, char *msg,

unsigned short msg_len)

説明ライセンス API の他の 4 つの関数からのエラーコードが渡されると、isc_license_get_msg()は対応するエラーメッセージのテキストを msg バッファに返します。

戻り値成功した場合、isc_license_get_msg() は 0 を返します。成功しなかった場合は、メッセー

ジテキストの格納に必要な msg の長さを返します。

isc_modify_user()

InterBase セキュリティデータベース（デフォルトは admin.ib）のユーザーレコードを変

更します。


さい。第 12 章「サービスの操作」および 15-139 ページの「isc_service_start()」のリファ

レンス項目を参照してください。

構文 ISC_STATUS isc_modify_user(

ISC_STATUS *status



て、gsec コマンドラインユーティリティと同等の機能が提供されます。isc_modify_user() は、

InterBase セキュリティデータベースのレコードを変更します。

少なくともユーザー名を指定しなければなりません。名字や名前、パスワードなどの追加

のユーザー情報を指定すると、セキュリティデータベースに格納されていた情報に上書き

されます。


msg_no short 他の isc_license_*() 関数が返したメッセージ番号。

msg char * • msg_no に対応するメッセージ用の文字バッファ。

• プログラム側で割り当てなければなりません。

• ISC_LICENSE_MAX_MESSAGE_LEN の長さが推奨されます。

msg_len short msg の長さ。




15-118 A P I ガイド

i s c _ m o d i f y _ u s e r ( )

サーバーがローカルでない場合は、サーバー名とプロトコルも指定する必要があります。プ

ロトコルフィールドの有効な値は、sec_protocol_tcpip、sec_protocol_netbeui、および

sec_protocol_local です。




typedef struct {





char *server; /* 管理するサーバー */char *user_name; /* ユーザー名 */

char *password; /* ユーザーのパスワード */

char *group_name;/* グループ名 */

char *first_name;/* ユーザーの名 */

char *middle_name;/* ユーザーのミドルネーム */


char *dba_user_name;/* DBA のユーザー名 */

char *dba_password;/* DBA のパスワード */} USER_SEC_DATA;



ます。

sec_uid_spec 0x01

sec_gid_spec 0x02










せん。



i s c _ m o d i f y _ u s e r ( )

例次の例では、ビットごとの論理和を使って USER_SEC_DATA 構造体内の値を渡して、InterBaseセキュリティデータベースのユーザー "Socks" のパスワードを変更し、ます。

{


USER_SEC_DATA sec;

表 15.24 isc_modifyuser() のエラーメッセージ

コード値説明

isc_usrname_too_long 335544747 The user name passed in is greater than 31bytes（ユーザー名が長すぎます。大長は 31 バイトです）

isc_password_too_long 335544748 The password passed in is longer than 8bytes（パスワードが長すぎます。大長は 8 バイトです）




isc_dup_usrname_found 335544752 The user name being added already existsin the security database（セキュリティデータベース内でユーザー名が重複しています）

isc_usrname_not_found 335544753 The user name was not found in thesecurity database（セキュリティデータベース内に、指定されたユーザー名が見つかりませんでした）

isc_error_adding_sec_record 335544754 An unknown error occurred while adding auser（ユーザーの追加時にエラーが発生しました）

isc_error_deleting_sec_record 335544755 An unknown error occurred while adding auser（ユーザーの追加時にエラーが発生しました）

isc_error_modifying_sec_record 335544756 An unknown error occurred while deletinga user（ユーザーレコードの変更時にエラーが発生しました）

isc_error_updating_sec_db 335544757 An unknown error occurred whileupdating the security database（セキュリティデータベースの更新時にエラーが発生しました）

15-120 A P I ガイド

i s c _ o p e n _ b l o b 2 ( )



sec.dba_password= "masterkey";



sec.password = "feed_me!"; /* メモ：パスワードはハードコードしないでください */

sec.sec_flags = sec_server_spec

| sec_password_spec


| sec_dba_password_spec;

isc_add_user(status, &sec);


{




break;

...

}

}

}

戻り値 isc_modify_user() は、ステータスベクターの第 2 要素を返します。0 の場合は、正常に終

了したことを示します。0 以外の場合は、エラーが発生したことを示します。エラーコード

については、この関数の「説明」を参照してください。ステータスベクターの値を調べる

方法については、第 10 章「エラー条件の処理」を参照してください。

参照 isc_add_user()、isc_delete_user()

isc_open_blob2()

抽出とフィルタリング（オプション）を行うために、既存の BLOB を開きます。

構文 ISC_STATUS isc_open_blob2(




isc_blob_handle *blob_handle,ISC_QUAD *blob_id,

short bpb_length,

char *bpb_address);


i s c _ o p e n _ b l o b 2 ( )

説明 isc_open_blob2() は、抽出用に既存の BLOB を開き、必要に応じて BLOB のサブタイプを

変換するフィルタを指定します。

isc_open_blob2() には、入力 BLOB フィルタと出力 BLOB フィルタのタイプがサブタイプ

情報として、bpb_address が示す値設定済みの BPB で渡されます。この情報は、BLOBフィルタが不要または使用不可能な場合は、BPB は不要であり、bpb_length には 0 を、

bpb_address には NULL を渡します。

blob_id は、どの BLOB を開くのかを指定します。blob_id は一連の DSQL 関数呼び出し

によって設定されます。

動作に成功した場合、isc_open_blob2() は blob_handle に一意の ID を割り当てます。以降

の API 呼び出しでは、操作対象の BLOB を識別するためにこのハンドルを使用します。

BLOB が開くと、isc_get_segment() を順次呼び出してデータを読み取ることができます。

BLOB へのアクセスが終了したら、isc_close_blob() を使って閉じます。

BLOB からのデータの読み取りとフィルタリングの詳細については、第 7 章「BLOB デー

タの操作」を参照してください。

例次のコードは、サンプルファイル api9.c の一部です。このプログラムは、フィルタを通し

て渡された作業明細を表示します。

while ((fetch_stat = isc_dsql_fetch(status, &stmt, 1, sqlda)) == 0)

{

printf("¥nJOB CODE: %5s GRADE: %d", job_code, job_grade);

printf(" COUNTRY: %-20s¥n¥n", job_country);

/* 取り出した blob_id を使って blob を開きます */isc_open_blob2(status, &DB, &trans, &blob_handle, &blob_id, 9, bpb);






blob_handle isc_blob_handle * BLOB ハンドルへのポインタ。呼び出し時は NULL でなければならない

blob_id ISC_QUAD * システム定義の 64 ビットの BLOB ID を指すポインタ。BLOB ID はテーブル内の項目に格納され、BLOB の先頭セグメント、または BLOB の一部を指すポインタを格納するページのアドレスを示す

bpb_length short BLOB パラメータバッファ（BPB）の長さ

bpb_address char * BPB へのポインタ

15-122 A P I ガイド

i s c _ p o r t a b l e _ i n t e g e r ( )


{


return(1);

}

}

戻り値 isc_open_blob2() は、ステータスベクターの第 2 要素を返します。0 の場合は正常に終了し







参照 isc_close_blob()

isc_portable_integer()

整数のバイト順を逆転します。この関数は INT64（8 バイト整数）値をサポートします。

LONG（4 バイト）値だけをサポートする isc_vax_integer() のスーパーセットです。

構文 ISC_INT64 isc_portable_integer(

char *buffer,

short length);

説明 isc_portable_integer() は、buffer に指定された整数のバイト順を逆転し、その結果の値を

返します。

この関数の代表的な用途は、データベースパラメータバッファに渡される整数を、下位

バイトが先頭にあり、上位バイトが後にある形式に変換することです。整数値は、

InterBase では DPB などの入力パラメータバッファ内で表さなければならず、下位バイ

トが先頭にあり、上位バイトが後にある一般形式で結果バッファに返されます。

isc_portable_integer() は、整数をこの形式に変換するために使用されます。

例次のコード例は、isc_database_info() などの関数から返される結果バッファである文字バッ

ファに格納されている 2 バイト値を変換します。

#include <ibase.h>

char *p;

. . .



buffer char * 変換する整数へのポインタ

length short 変換する整数の長さ（バイト数）有効な長さは、1、2、4、8 バイト


i s c _ p r e p a r e _ t r a n s a c t i o n ( )

{

/* 結果バッファの次のクラスタの項目型を読み取ります */item = *p++;

/* 結果バッファの次の値の長さを読み取り、変換します */len = isc_portable_integer(p, 2);

p += len;

/* ここで、len バイトサイズの実際のデータを処理します */. . .

}

戻り値 isc_portable_integer() は、常にバイト順を逆転した INT64（8 バイト）値を返します。

参照 isc_attach_database()、isc_database_info()

isc_prepare_transaction()

複数のデータベースに対する 2 相コミットの第 1 段階を実行します。

構文 ISC_STATUS isc_prepare_transaction(



説明 isc_prepare_transaction() は、2 相コミットの第 1 段階を実行します。この報告を受信した

InterBase は、関連するすべてのデータベースにポーリングして応答を待ちます。

isc_prepare_transaction() 関数は、トランザクションを limbo 状態にします。

isc_prepare_transaction() を呼び出すと、コミットの全段階を制御することになるため、

isc_commit_transaction() 関数を明示的に呼び出して 2 相コミットの第 2 段階を完了させ

なければなりません。

isc_prepare_transaction() の呼び出しが失敗した場合は、アプリケーションで

isc_rollback_transaction() 関数を呼び出してトランザクションをロールバックする必要が

あります。

メモ 2 相コミットを InterBase に自動的に実行させる場合は、isc_prepare_transaction() を使わず

に isc_commit_transaction() を呼び出します。

例次のコードは、2 相コミットの第 1 段階を実行し、失敗した場合はロールバックします。

isc_prepare_transaction(status_vector, &trans);


rb_status = isc_rollback_transaction(status_vector, &trans)

else




15-124 A P I ガイド

i s c _ p r e p a r e _ t r a n s a c t i o n 2 ( )

{

isc_commit_transaction(status_vector, &trans);

if (!(status_vector[0] == 1 && status_vector[1]))

fprintf(stderr, "Commit successful.¥n");

}

戻り値 isc_prepare_transaction() は、ステータスベクターの第 2 要素を返します。0 の場合は正常





参照 isc_commit_transaction()、isc_prepare_transaction2()、isc_rollback_transaction()

isc_prepare_transaction2()

複数のデータベースに対する 2 相コミットの第 1 段階を実行します。

構文 ISC_STATUS isc_prepare_transaction2(



unsigned short msg_length,

char *message);

説明 isc_prepare_transaction2() は、isc_prepare_transaction() と同様に、2 相コミットの第 1 段階を実行します。ただし、以下の引数を指定する必要があります。

• コミットするトランザクションを記述したシステムテーブル RDB$TRANSACTIONS の列

RDB$TRANSACTION_DESCRIPTION に書き込む情報メッセージ。これにより、コミット中

にシステムクラッシュが発生しても復旧できるようになります。

• 情報メッセージの長さ（バイト数）




msg_length unsigned short メッセージの長さ（バイト数）

message char * トランザクション記述バッファ


i s c _ p r i n t _ s q l e r r o r ( )

isc_prepare_transaction2() を選択すると、2 相コミットが持っている自動復旧機能は無効になり

ます。2 相コミットが失敗した場合の復旧を処理するのは、アプリケーションプログラム側の責

任になります。コミット中にシステムクラッシュが発生した場合、InterBase は再接続のために

必要な情報を、システムテーブル RDB$TRANSACTIONS の列 RDB$TRANSACTION_DESCRIPTIONに書き込みます。isc_prepare_transaction2() の message パラメータを使うと、RDB$TRANSACTIONSにメッセージ文字列を書き込むことができます。

アプリケーションでコミットを行うたびに生じる余分な処理の負荷が大きすぎると判断さ

れる場合、RDB$TRANSACTION にメッセージを書き込むのをまったく止めてしまいたいと

考えられるかもしれませんが、そうするとシステムクラッシュ時の復旧ができなくなる危

険があります。

例次のコードは、2 相コミットの第 1 段階を実行し、失敗した場合はロールバックします。

isc_prepare_transaction2(status_vector, &trans, msg_len, msg);


rb_status = isc_rollback_transaction(status_vector, &trans);

戻り値 isc_prepare_transaction2() は、ステータスベクターの第 2 要素を返します。0 の場合は正


InterBase エラーの場合は、ステータスベクターの第 1 要素が 1 に設定され、第 2 要素は

InterBase エラーコードに設定されます。




参照 isc_commit_transaction()、isc_prepare_transaction()、isc_rollback_transaction()

isc_print_sqlerror()

SQL エラーメッセージに対応する SQLCODE の値、およびエラーステータスベクターの

InterBase エラーメッセージを表示します。

構文 void isc_print_sqlerror(

short SQLCODE,

ISC_STATUS *status_vector);


SQLCODE short SQLCODE 値を格納する変数


15-126 A P I ガイド

i s c _ p r i n t _ s t a t u s ( )

説明 DSQL API 関数を呼び出しているときには、SQL エラーが発生することがあります。通

常、SQL エラーは SQLCODE 変数に報告されます。DSQL 呼び出しでは、他の API 関数と同様に、ユーザー定義のエラーステータスベクターにエラー情報を戻します。

isc_print_sqlerror() は、エラーステータスを SQL エラーメッセージに変換して画面に直接

表示します。isc_print_sqlerror() を使うには、SQL エラー番号を格納する変数

SQLCODE、および InterBase エラー情報を格納するエラーステータスベクターをアプリ

ケーション内で宣言しなければなりません。isc_print_sqlerror() は、SQL エラーメッセー

ジに対応する SQLCODE の値、および追加の InterBase エラーメッセージをステータス

配列に表示します。

メモ画面への直接書き込みができないウィンドウシステムもあります。このような環境でアプリ

ケーションを開発する場合は、isc_print_sqlerror() は使用しないでください。isc_sql_interprete()または isc_interprete() を使用して、表示するメッセージをバッファに取り込んでください。

例次のコードは、エラーの発生時に isc_print_sqlerror() を呼び出します。

#include <ibase.h>

long SQLCODE;


. . .


{



}


参照 isc_interprete()、isc_print_status()、isc_sql_interprete()、isc_sqlcode()

isc_print_status()

InterBase エラーステータスベクターの内容に基づくエラーメッセージを作成して表示し

ます。

構文 ISC_STATUS isc_print_status(ISC_STATUS *status_vector);

説明 isc_print_status() は、エラーステータスベクターの内容に基づいてエラーメッセージを作

成して、画面に表示します。status_vector は、要素数 20 の配列としてプログラムで宣言

しておかなければなりません。

例次のコードは、処理中にエラーが発生した場合にエラーメッセージを表示します。

#include <ibase.h>





i s c _ p u t _ s e g m e n t ( )

. . .


{


return(1);

}

戻り値 isc_print_status() は、ステータスベクターの第 2 要素を返します。0 の場合は正常に終了





参照 isc_interprete()、isc_print_sqlerror()、isc_sqlcode()、isc_sql_interprete()

isc_put_segment()

BLOB セグメントを書き込みます。

構文 ISC_STATUS isc_put_segment(



unsigned short seg_buffer_length,

char *seg_buffer);

説明 isc_put_segment() は、isc_create_blob2() で作成した BLOB に seg_buffer_address で示さ

れる BLOB セグメントを書き込みます。

BLOB フィルタを指定して BLOB を作成した場合は、BLOB への格納と同時に各セグメ

ントがフィルタにかけられます。

isc_put_segment() の動作は、その前にどの関数が呼び出されたかによって異なります。

isc_create_blob() または isc_create_blob2() を呼び出した直後に isc_put_segment() を呼

び出した場合は、BLOB の先頭セグメントが書き込まれます。isc_put_segment() の直後に

isc_put_segment() を呼び出した場合は、次のセグメントが書き込まれます。



blob_handle isc_blob_handle * 書き込み先となる BLOB ハンドルを指すポインタ。ハンドルの値は isc_create_blob2() で設定する

seg_buffer_length unsigned short BLOB セグメントバッファの長さ

seg_buffer_address char * 書き込むデータを格納する BLOB セグメントバッファを指すポインタ

15-128 A P I ガイド

i s c _ p u t _ s e g m e n t ( )

ビットマップなどのバイナリファイルは、形式変換（GEM から BMP など）を行う場合を

除き、フィルタリングを使わずに直接書き込むことができます。JPG（JPEG）、BMP（Windows 固有のビットマップ）、GIF（CompuServe のグラフィック交換形式）などの

形式を使うと、圧縮したビットマップをデータベースに直接格納することもできます。

データベースへのビットマップの格納は、行優先または列優先の順序で行うことができま

す。

BLOB を直接更新することはできません。BLOB データを修正するには、以下の操作を行

う必要があります。

• 新規 BLOB を作成する。

• 編集や修正を行うためのバッファに既存の BLOB データを読み取る。

• 修正後のデータを新規 BLOB に書き込む。

• 既存 BLOB の BLOB ID を新規 BLOB の BLOB ID と置き換えるように BLOB 列を変更

する UPDATE ステートメントを作成して実行する。

BLOB データの作成と書き込みの詳細については、第 7 章「BLOB データの操作」を参


メモ isc_put_segment() で書き込んだセグメントを読み取るには、isc_close_blob() を使って

BLOB をいったん閉じてから、isc_open_blob2() で開く必要があります。

例次のコードは、BLOB からセグメントを読み取り、別の BLOB に書き込みます。

get_status = isc_get_segment(status, &from_blob, &seg_len, 80, buffer);


{


return(1);

}

if (get_status != isc_segstr_eof)

write_status = isc_put_segment(status, &to_blob, seg_len, buffer);


{


return(1);

}

戻り値 isc_put_segment() は、ステータスベクターの第 2 要素を返します。0 の場合は正常に終了





参照 isc_close_blob()、isc_get_segment()、isc_open_blob2()


i s c _ q u e _ e v e n t s ( )

isc_que_events()

指定されたイベントグループのイベントの非同期通知を要求します。

構文 ISC_STATUS isc_que_events(



ISC_LONG *event_id,short length,

char *event_buffer,

isc_callback event_function,

void *event_function_arg);

説明 isc_que_events() は、event_buffer に指定したイベントの非同期通知を要求するときに呼び

出します。呼び出し後、イベントが通知される前に、呼び出しを行ったアプリケーション

に制御権が戻され、処理が続行できるようになります。要求したイベントが通知されると、

InterBase は event_function に指定された関数を呼び出してイベントを処理します。

指定したイベントの非同期待機を新たに起動するには、event_function を呼び出した後で

isc_que_events() を再び呼び出さなければなりません。

メモ event_function の中から isc_que_events() を呼び出すことはできません。

非同期イベント通知を要求する isc_que_events() を取り消す場合には、isc_cancel_events()を呼び出します。



db_handle isc_db_handle * isc_attach_database() で前もって設定したデータベースハンドルを指すポインタ。このハンドルは、通知するイベントの対象となるデータベースを識別する。


event_id ISC_LONG * 設定するイベント識別子を指すポインタ

length short イベントパラメータバッファ（EPB）の長さ。割り当てを行った isc_event_block() から返される

event_buffer char * 待機中のイベントの発生回数を格納するイベントパラメータバッファを指すポインタ。このバッファは、isc_event_block() を呼び出して割り当てておく必要がある

event_function isc_callback イベントの通知を受信する関数のアドレスを指すポインタ

event_function_arg void * event_function に渡す先頭の引数。通常は、更新後のイベントカウントの入力先となるイベントパラメータバッファを指すポインタ

15-130 A P I ガイド

i s c _ q u e _ e v e n t s ( )

メモ同期通知を要求するには isc_wait_for_event() を呼び出します。

例次のコードは、イベントの発生を非同期モードで待機する isc_que_events() を呼び出して

います。ループ内では、他の処理を行いながら、（指定したイベント関数が設定する）イベ

ントフラグをチェックして、いつイベントが通知されたかを調べます。イベントが通知さ

れると、まずイベントフラグをリセットし、次に isc_event_counts() を呼び出して通知さ

れたイベントを判定し、isc_que_events() を呼び出して新しい非同期待機を起動します。

#include <ibase.h>


#define MAX_LOOP 10



ISC_STATUS count_array[number_of_stocks];

short length;

ISC_LONG event_id;

int i, counter;

int event_flag = 0;


&event_buffer,

&result_buffer,

number_of_stocks,


isc_que_events(

status_vector,

&database_handle, /* 先の isc_attach_database() で設定されます */&event_id,



result_buffer);


{


};

counter = 0;

while (counter < MAX_LOOP)

{

counter++;

if (!event_flag)

{


i s c _ q u e _ e v e n t s ( )

/* 必要に応じて他の処理を行います */;

}

else

{ event_flag = 0;

isc_event_counts(

count_array,

length,

event_buffer,

result_buffer);


{


}


if (count_array[i])

{

/* イベントがポストされました。ここで適切な処理を行います。たとえば、買注文または売注文を初期化します

メモ：event_names[i] は、count_array[i] に対応するイベントの名前を示します */

;

}

isc_que_events(

status_vector,

&database_handle,

&event_id,

length,

event_buffer,


result_buffer);


{


}

} /* else の終わり */

} /* while の終わり */

/* 非同期で待機する必要がなくなったことを InterBase に通知します */isc_cancel_events(

status_vector,

&database_handle,

15-132 A P I ガイド

i s c _ r o l l b a c k _ r e t a i n i n g ( )

&event_id);


{


}

戻り値 isc_que_events() は、ステータスベクターの第 2 要素を返します。0 の場合は正常に終了し







参照 isc_cancel_events()、isc_event_block()、isc_event_counts()、isc_wait_for_event()

非同期イベントトラップ（AST）関数の詳細については、第 11 章「イベントの操作」を


isc_rollback_retaining()

トランザクションによる変更を取り消し、ロールバック後のトランザクションのコンテキ

ストを保持します。

構文 ISC_STATUS isc_rollback_retaining(



説明 isc_rollback_retaining() は、アクティブなトランザクションをロールバックした直後に自

分自身のクローンを作成します。つまり、この関数は、トランザクション名、トランザク

ションに関連したシステムリソース、トランザクション内で開いているカーソルの現在の

状態を維持します。実際には関数は新規のトランザクションを開始しますが、既存のトラ

ンザクションハンドルを新規のトランザクションに割り当てることにより、ロールバック

後もトランザクションは開いたままになります。これによってアプリケーションは新規の

トランザクションを開始するオーバーヘッドを小にすることができ、処理効率が向上し

ます。isc_rollback_retaining() を使うと、カーソルを開いたままで更新をロールバックす

ることができます。



trans_handle isc_tr_handle * isc_start_transaction() の呼び出しによってすでに値が設定されているトランザクションハンドルへのポインタ。trans_handle が NULL の場合はエラーが返される


i s c _ r o l l b a c k _ r e t a i n i n g ( )

アクティブトランザクション内ではロールバックを実行できますが、ロールバックが有効

なのはコミットされていない更新に対してだけです。言い換えると、トランザクションの

コンテキストがクローントランザクションに渡された後でもロールバックは違法ではあり

ませんが、ロールバックされるのは前回のコミットまたはロールバック以降にデータベー

スに加えられた更新に限られます。

この関数の呼び出しによって行われたロールバックを検査するには、ステータスベクター

の第 1 要素を調べて呼び出しが成功したかどうかを確認します。第 1 要素が 0 の場合は呼

び出しは成功です。

isc_commit_transaction() または isc_rollback_transaction() を呼び出して、コンテキスト

の保持機能を使用せずにコミットまたはロールバックを行うと、トランザクションは終了

します。

ロールバックの原因となるエラーはトランザクションコンテキスト内にあることが多く、

その場合に isc_rollback_retaining() を呼び出すと元のエラーが繰り返されることになりま

す。このような場合のためにエラー検出コードを組み込んでいないと、脱出不可能なコー

ドループを生成してしまうことになります。

例次の C/C++ コードは、トランザクションをロールバックしてメッセージを出力し、同じ

要求内で同じハンドルを使って新規のトランザクションを開始します。

if (!isc_rollback_retaining(status, &retained_trans))

{

fprintf(stderr, "Rolled back and retained¥n");


}

次の C/C++ コードは、トランザクションをロールバックして確認メッセージを出力し、

同じ要求内で同じハンドルを使って新規のトランザクションを開始します。ロールバック

が失敗した場合は、エラーメッセージを出力してロールバックします。

isc_rollback_retaining(status, &retained_trans);


{

fprintf(stderr, "Error retaining; rolling back instead.¥n");

rb_status = isc_rollback_transaction(status, &retained_trans);

}

else

{

fprintf(stderr, "Rollback retaining successful.¥n");

tr_count++; /* リサイクルの数をインクリメントします */}

戻り値 isc_rollback_retaining() は、ステータスベクターの第 2 要素を返します。0 の場合は正常

に終了したことを示します。0 以外の値は、エラーが発生したことを示します。InterBaseエラーが発生した場合は、ステータスベクターの第 1 要素が 1 に設定され、第 2 要素が





15-134 A P I ガイド

i s c _ r o l l b a c k _ t r a n s a c t i o n ( )

参照 isc_commit_retaining()、isc_commit_transaction()、isc_rollback_transaction()、isc_start_transaction()

isc_rollback_transaction()

トランザクションによる変更を取り消し、データベースをトランザクション開始前の状態

に戻します。

構文 ISC_STATUS isc_rollback_transaction(



説明 isc_rollback_transaction() は、指定されたトランザクションをロールバックし、レコード

ストリームを閉じ、システムリソースを解放し、トランザクションハンドルを 0 に設定し

ます。通常は、エラーが発生したトランザクションの変更をすべて取り消す場合に使用し

ます。

この関数は、以下の場合にのみエラーになります。

• NULL または無効なトランザクションハンドルが渡された場合。

• 複数のデータベースを扱うトランザクションで、ロールバック中に通信リンク障害が発生

した場合。この場合、リモートノードのサブトランザクションが limbo 状態になります。

そのようなトランザクションは、データベース保守ユーティリティを使って手動でロール

バックしなければなりません。

例次のコードは、トランザクションをロールバックします。


戻り値 isc_rollback_transaction() は、ステータスベクターの第 2 要素を返します。0 の場合は正常





参照 isc_commit_transaction()、isc_rollback_retaining()、isc_start_transaction()



trans_handle isc_tr_handle * isc_start_transaction() の呼び出しで前もって設定されているトランザクションハンドルを指すポインタ。trans_handle がNULL の場合はエラーが返される


i s c _ s e r v i c e _ a t t a c h ( )

isc_service_attach()

InterBase Services Manager 機能に接続します。この操作は、InterBase サービス関数を

使ってタスクを実行したり Services Manager に対して情報を要求する前に行う必要があ

ります。

構文 ISC_STATUS isc_service_attach(


unsigned short service_length,

char *service,

isc_svc_handle *svc_handle,

unsigned short spb_length,

char *spb);

説明この関数は、特定の InterBase サーバー上の Services Manager に接続するために使いま

す。Services Manager に接続するには、InterBase サービスがホスト上で実行されている


ホスト名とリテラル文字列 service_mgr を service 引数に指定する必要があります。たとえ

ば、jupiter:service_mgr は、jupiter ホスト上の Services Manager に TCP/IP ネットワー

クプロトコルを使って接続するための文字列です。

ユーザー ID とそれに対応するパスワードをサービスパラメータバッファのオプションの

一部として指定する必要があります。Services Manager は、要求されたサービスタスク

を実行するときにこのユーザー ID を使います。

Delphi および C++Builder 用の InterBase Express パッケージには、Services Managerのビジュアルインターフェースを提供するコンポーネントが含まれています。『開発者ガイ

ド』を参照してください。

例 C/C++ コードの例については、12-3 ページの「isc_service_attach() による ServicesManager への接続」を参照してください。



service_length unsigned short サービス名の長さ（文字数）。0 は、サービス名が NULL終端の文字列であることを示す

service char * クライアントが接続を要求するサービスの名前を含んだ文字列

svc_handle isc_svc_handle * service 構造体のハンドルを格納する long 値へのポインタ

spb_length unsigned short サービスパラメータバッファの長さ（バイト数）

spb char * サービスパラメータバッファへのポインタ

15-136 A P I ガイド

i s c _ s e r v i c e _ d e t a c h ( )

戻り値 isc_service_attach() は、ステータスベクターの第 2 要素を返します。0 の場合は正常に終

了したことを示します。0 以外の値は、エラーが発生したことを示します。InterBase エラーが発生した場合は、ステータスベクターの第 1 要素が 1 に設定され、第 2 要素が





参照 isc_service_detach()、isc_service_query()、isc_service_start()

isc_service_detach()

InterBase Services Manager への接続を終了します。

構文 ISC_STATUS isc_service_detach(


isc_svc_handle *svc_handle);

説明すべてのタスクの実行が終了して必要な情報を Services Manager から取得したら、この

関数を使って接続を解除します。



例 C/C++ コードの例については、12-4 ページの「isc_service_detach() による ServicesManager からの接続解除」を参照してください。

戻り値 isc_service_detach() は、ステータスベクターの第 2 要素を返します。0 の場合は正常に終






参照 isc_service_attach()、isc_service_query()、isc_service_start()

isc_service_query()

クライアントが接続している InterBase サーバーに関する情報を要求して取得します。





i s c _ s e r v i c e _ q u e r y ( )

構文 ISC_STATUS isc_service_query(



isc_resv_handle *reserved,

unsigned short send_spb_length,

char *send_spb,

unsigned short request_spb_length,

char *request_spb,

unsigned short buffer_length,

char *buffer);

説明 isc_service_query() は、Services Manager に情報を要求するために使います。

isc_service_attach() によって、実行中の Services Manager に対してアクティブな接続が

確立されている必要があります（15-136 ページを参照）。



例 12-19 ページの「Services Manager に対するクエリー」に、C/C++ で isc_service_query()を使う例をいくつか示してあります。

戻り値 isc_service_query() は、ステータスベクターの第 2 要素を返します。0 の場合は正常に終









reserved isc_resv_handle * 将来のために予約。NULL でなければならない

send_spb_length unsigned short サービスパラメータバッファの長さ（バイト数）

send_spb char * Services Manager のフラグを格納するサービスパラメータバッファへのポインタ

request_spb_length unsigned short 要求バッファの長さ（バイト数）

request_spb char * 要求された情報の項目指定子を格納するバッファへのポインタ

buffer_length unsigned short 戻りバッファの長さ（バイト数）

buffer char * Services Manager から受け取った情報を格納するバッファへのポインタ

15-138 A P I ガイド

i s c _ s e r v i c e _ s t a r t ( )

参照 isc_service_attach()、isc_service_detach()、isc_service_start()

isc_service_start()

クライアントが接続している InterBase サーバー上でサービスタスクを実行します。

構文 ISC_STATUS isc_service_start(



isc_resv_handle *reserved,

unsigned short spb_length,

char *spb);

説明 Use isc_service_start() は、Services Manager によるタスクの実行を開始するために使い

ます。isc_service_attach() によって、実行中の Services Manager に対してアクティブな

接続が確立されている必要があります（15-136 ページを参照）。



例 12-5 ページの「isc_service_start() によるサービスタスクの起動」に、C/C++ でisc_service_start() を使う例をいくつか示してあります。

戻り値 isc_service_start() は、ステータスベクターの第 2 要素を返します。0 の場合は正常に終了

したことを示します。0 以外の値は、エラーが発生したことを示します。InterBase エラー

が発生した場合は、ステータスベクターの第 1 要素が 1 に設定され、第 2 要素が InterBaseエラーコードに設定されます。




参照 isc_service_attach()、isc_service_detach()、isc_service_query()




reserved isc_resv_handle * 将来のために予約。NULL でなければならない

spb_length unsigned short サービスパラメータバッファの長さ（バイト数）

spb char * Services Manager に対して指定されたタスクを実行するように指示するためのフラグおよびオプション引数を格納するサービスパラメータバッファへのポインタ


i s c _ s q l c o d e ( )

isc_sqlcode()

エラーステータスベクターの InterBase エラーコードを SQL エラーコード番号に変換し

ます。

構文 ISC_LONG isc_sqlcode (ISC_STATUS *status_vector);

説明 isc_sqlcode() は、status_vector から報告された SQL エラーを検索して、見つかった

InterBase エラーコードを対応する SQL エラーコードに変換します。通常この関数は、

SQLCODE と呼ばれるプログラム変数（複数の SQL 間で移植性を持たせるため）に、SQLエラー処理ルーチンに使用する SQL エラー番号を登録する場合に使います。

例次のコードは、DSQL アプリケーションで isc_sqlcode() を呼び出す方法を示しています。

#include <ibase.h>

long SQLCODE;


. . .


{



}

戻り値 isc_sqlcode() は、正常に終了した場合、InterBase のステータスベクターから変換した SQLエラーコードを返します。

有効な SQL エラーコードが見つからなかった場合は -999 を返します。

参照 isc_interprete()、isc_print_sqlerror()、isc_print_status()、isc_sql_interprete()

isc_sql_interprete()

SQL エラーメッセージ文字列を作成してユーザー定義のバッファに格納します。

構文 void isc_sql_interprete(

short SQLCODE,

char *buffer,

short buffer_length);



15-140 A P I ガイド

i s c _ s t a r t _ m u l t i p l e ( )

説明 isc_sql_interprete() は、0 未満（負）の SQLCODE から、対応する SQL エラーメッセー

ジ文字列を作成して、ユーザーが定義したバッファに格納します。この関数には、バイト

単位で表したバッファのサイズも渡さなければなりません。

SQLCODE の値に対応する SQL エラーメッセージを表示するには isc_print_sqlerror()を使用します。

例次のコードは、isc_sql_interprete() を呼び出しています。

#include <ibase.h>

long SQLCODE;

char err_buf[256];

. . .


{


isc_sql_interprete(SQLCODE, err_buf, sizeof(err_buff));

}


参照 isc_interprete()、isc_print_sqlerror()、isc_print_status()、isc_sqlcode()

isc_start_multiple()

複数のデータベースに対する新しいトランザクションを開始します。

構文 ISC_STATUS isc_start_multiple(




void *teb_vector_address);


SQLCODE short SQLCODE 値を格納する変数

buffer char * SQL エラーメッセージを格納するアプリケーションバッファ

buffer_length short buffer の長さ（バイト数）



説明 isc_start_multiple() は、以下の場合に呼び出します。

• 関数呼び出しで、任意の数の引数を利用できない言語を使用する場合

• トランザクション起動関数のコーディングの時点で、接続するデータベースの数がわから

ない場合

isc_start_multiple() は、接続先データベースの情報を InterBase に渡します。この情報は、

teb_vector が指すトランザクション確認バッファ（TEB）の配列に格納されます。

teb_vector は、連続する TEB で構成されるバイト配列で、接続するデータベースごとに

TEB が 1 つ割り当てられます。各 TEB は、トランザクションの対象となるデータベース

ハンドルへのポインタ、データベースのトランザクションパラメータバッファ（TPB）の

長さ（バイト数）、および TPB へのポインタの 3 つの項目で構成されます。TEB 内の各項

目は、isc_start_transaction() の呼び出しでパラメータとして直接渡される各項目に対応し

ます。C プログラムでは TEB を設定する必要がないので、可能な限り isc_start_multiple()ではなく isc_start_transaction() を使用してください。

TEB の設定と isc_start_multiple() 呼び出しについては、第 5 章「トランザクションの操

作」の 5-12 ページの「isc_start_multiple() の呼び出し」を参照してください。

例次のコードは、複数のデータベースのトランザクションを起動します。

#include <ibase.h>

typedef struct { /* ISC_TEB 構造体を定義します */int*dbb_ptr;

longtpb_len;

char*tpb_ptr;

} ISC_TEB;

ISC_TEB teb_vec[2]; /* TEB ベクターを宣言します */

ISC_STATUS isc_status[20]; /* ステータスベクター */

long *db0, *db1, /* データベースハンドル */

long *trans; /* トランザクションハンドル */

static char




db_handle_count short トランザクション確認バッファ（TEB）を通してこの関数に渡されるデータベースハンドルの数

teb_vector_address void * TEB へのポインタ

15-142 A P I ガイド


isc_tpb_0[] = { /* 初のトランザクションパラメータバッファを宣言します */

isc_tpb_version3, /* InterBase のバージョン */isc_tpb_write,/* 読み書きアクセス */isc_tpb_consistency, /* SERIALIZABLE */isc_tpb_wait,/* ロックの待機 */

isc_tpb_lock_write, 3, /* 更新のための IDS の予約 */'I','D','S',

isc_tpb_protected},/* 他のトランザクションによる

テーブルへの書き込みを許可しません */

isc_tpb_1[] = {/* 2 番めのトランザクションパラメータ */

/* バッファを宣言します */

isc_tpb_version3, /* InterBase のバージョン */isc_tpb_write,/* 読み書きアクセス */isc_tpb_consistency, /* SERIALIZABLE */isc_tpb_wait,/* ロックの待機 */

isc_tpb_lock_write, 3, /* 更新のためのテーブル OZS の予約 */'O','Z','S',

isc_tpb_protected};/* 他のトランザクションによる

テーブルへの書き込みを許可しません */

main()

{

db0 = db1 = 0;

trans = 0;

/* test_0 database に接続できない場合は、test_1 に接続します */

isc_attach_database(isc_status, 0, "test_0.ib", &db0, 0,0);

if (isc_status[0] == 1 && isc_status[1])

isc_attach_database(isc_status, 0, "test_1.ib", &db1, 0,0);

if (db0 && db1)

{ /* teb ベクターに、データベースハンドル、tpb の長さ、およびtbp ハンドルを割り当てます */

teb_vec[0].dbb_ptr = &db0;

teb_vec[0].tpb_len = sizeof (isc_tpb_0);

teb_vec[0].tpb_ptr = isc_tpb_0;

teb_vec[1].dbb_ptr = &db1;

teb_vec[1].tpb_len = sizeof (isc_tpb_1);

teb_vec[1].tpb_ptr = isc_tpb_1;

if (isc_start_multiple(isc_status, &trans, 2, teb_vec))

isc_print_status(isc_status);

}


i s c _ s t a r t _ t r a n s a c t i o n ( )

if (trans)

isc_commit_transaction(isc_status, &trans);

if (db0 && !trans)

isc_detach_database(isc_status, &db0);

if (db1 && !(trans && db0))

isc_detach_database(isc_status, &db1);



}

戻り値 isc_start_multiple() は、ステータスベクターの第 2 要素を返します。0 の場合は正常に終





トランザクションハンドルの詳細については、第 5 章「トランザクションの操作」の 5-2ページの「トランザクションハンドルの作成」を参照してください。TPB の作成と値の設

定については、第 5 章「トランザクションの操作」の 5-3 ページの「トランザクションパ

ラメータバッファの作成」を参照してください。TEB の詳細については、第 5 章「トラン

ザクションの操作」の 5-12 ページの「isc_start_multiple() の呼び出し」を参照してく

ださい。

参照 isc_commit_transaction()、isc_prepare_transaction()、isc_prepare_transaction2()、isc_rollback_transaction()、isc_start_transaction()

isc_start_transaction()

1 つ以上のデータベースを対象とするトランザクションを起動します。

構文 ISC_STATUS isc_start_transaction(





unsigned short tpb_length,

char *tpb_address,

[isc_db_handle *db_handle,

unsigned short tpb_length,

char *tpb_address ...]);

15-144 A P I ガイド


説明 isc_start_transaction() は、データベースハンドルとして指定された 1 つ以上のデータベー

スを対象とする新規トランザクションを起動します。

メモ更新するデータベースの個数が決まっていない場合や、関数呼び出しで可変個の引数をサ

ポートしない言語を使う場合は、isc_start_transaction() のかわりに isc_start_multiple() を使用します。

1 つのトランザクションで複数のデータベースにアクセスできます。この関数は、アクセス

する各データベースに関する情報、およびデータベースのアクセス条件をトランザクショ

ンパラメータバッファ（TPB）に渡します。TPB は、プログラムで宣言して登録する、可

変サイズのバイトベクターです。アクセスモードやロックモードなど、トランザクション

の動作に関する情報を含んでいます。

isc_start_transaction() は、大 16 個のデータベースを対象とするトランザクションを起

動できます。各参照されるデータベースに対して、データベースハンドルと TPB を渡す必

要があります。デフォルトのトランザクションパラメータを使用する場合は、tpb_lengthに 0 を、tpb_address を NULL ポインタに設定します。

例次のコードは、トランザクション起動関数を呼び出しています。

#include <ibase.h>

long

isc_status[20], /* ステータスベクター */

*db, /* データベースハンドル */*trans, /* トランザクションハンドル */

static char

isc_tpb_0[] = {

isc_tpb_version3, /* InterBase のバージョン */

isc_tpb_write,/* 読み書きアクセス */

isc_tpb_consistency, /* 一貫性モードトランザクション */




db_handle_count short この関数に渡されるデータベースハンドルの数

db_handle isc_db_handle * isc_attach_database() で前もって設定したデータベースハンドルを指すポインタ。このハンドルは、通知するイベントの対象となるデータベースを識別する。


tpb_length unsigned short トランザクションパラメータバッファ（TPB）の長さ

tpb_address char * TPB へのポインタ



isc_tpb_wait,/* ロックの待機 */

isc_tpb_lock_write, 3, /* 更新のための IDS テーブルの予約 */"I","D","S",

isc_tpb_protected};/* 他のトランザクションによる

このテーブルへの書き込みを許可しません */main()

{

db = trans = 0;

isc_attach_database(isc_status, 0, "test.ib", &db, 0,0);

if (db)

{

isc_start_transaction(

isc_status, &trans, 1, &db,

sizeof(isc_tpb_0), isc_tpb_0);



}

if (trans)

isc_commit_transaction(isc_status, &trans);

if (db && !trans)

isc_detach_database(isc_status, &db);



}

戻り値 isc_start_transaction() は、ステータスベクターの第 2 要素を返します。0 の場合は正常に





トランザクションハンドルの詳細については、第 5 章「トランザクションの操作」の 5-2ページの「トランザクションハンドルの作成」を参照してください。TPB の作成と値の設

定については、第 5 章「トランザクションの操作」の 5-3 ページの「トランザクションパ

ラメータバッファの作成」を参照してください。

参照 isc_commit_transaction()、isc_prepare_transaction()、isc_prepare_transaction2()、isc_rollback_transaction()、isc_start_multiple()

15-146 A P I ガイド

i s c _ t r a n s a c t i o n _ i n f o ( )

isc_transaction_info()

指定された名前付きトランザクションに関する情報を返します。

構文 ISC_STATUS isc_transaction_info(



short item_list_buffer_length,char *item_list_buffer,



説明 isc_transaction_info() は、トランザクション ID の管理に必要な情報を返します。この呼

び出しは、isc_prepare_transaction() の内部で使用されます。アプリケーションで使用する

必要はありません。

トランザクション ID に関する情報を抽出するには、情報が必要なトランザクション項目を

記載する項目リストバッファに次の定数を組み入れます。

isc_transaction_info() は、プログラム側で定義される 2 つのバッファを使用します。1 つは情報が必要なトランザクション項目を一覧した項目リストバッファ、もう 1 つは要求し

た情報を格納する結果バッファです。

項目リストバッファを定義するには、item_list_buffer_length および item_list_buffer_address を組み込みます。項目リストバッファは、構造を持たない通常のバイトベクターです。

結果バッファを定義するには、result_buffer_length および result_buffer_address を組み込

み、格納先バッファの長さとアドレスを指定します。InterBase エンジンは、関数の戻り

値をこのバッファに格納します。




item_list_buffer_length short 項目リストバッファのバイト数

item_list_buffer char * 項目リストバッファへのポインタ

result_buffer_length short 結果バッファのバイト数

result_buffer char * 結果バッファへのポインタ

表 15.25 トランザクション情報要求項目

項目用途次の値のサイズ値

isc_info_tra_id トランザクション ID を判定する 2 バイトトランザクション ID


i s c _ t r a n s a c t i o n _ i n f o ( )

結果バッファに格納される値は、バイナリ数値のアラインメントされていないクラスタで

す。どの数値も、下位バイトが先頭、上位バイトが末尾の汎用形式で表されます。符

号付き数値は、終バイトに符号が付きます。数値は、使用システムに固有のデータ型に

変換してください。

呼び出しには、トランザクション ID を指定する項目 isc_info_tra_id を組み込みます。

InterBase は、結果バッファにトランザクション ID を返します。要求に対する情報に加え

て、InterBase は結果バッファに次のステータスメッセージを返します。

この関数の戻り値は、情報の要求を InterBase が受信したことを示すだけです。要求され

た情報をすべて返すということではありません。トランザクションの詳細については、結

果バッファの内容をアプリケーションで解釈しなければなりません。

例次のコードは、トランザクションに関する情報を取得します。

static char /* 項目リストバッファを宣言します */tra_items[] =

{isc_info_tra_id};

/* 結果バッファを宣言します */CHAR tra_info[32];

isc_transaction_info(status_vector, &tr_handle,

sizeof (tra_items), /* 項目リストバッファの長さ */

&tra_items, /* 項目リストバッファのアドレス */

sizeof (tra_info), /* 結果バッファの長さ */

&tra_info);/* 結果バッファのアドレス */if (status_vector[0] == 1 && status_vector[1])

{


return(1);

}

戻り値 isc_transaction_info() は、ステータスベクターの第 2 要素を返します。0 の場合は正常に





表 15.26 ステータスメッセージの戻り項目

項目説明



isc_info_error 要求された情報は利用できない。ステータスベクターをチェックし、エラーコードとエラーメッセージを確認すること

15-148 A P I ガイド

i s c _ u n i n s t a l l _ e x e c u t e ( )

参照 isc_start_transaction()

isc_uninstall_execute()

インストールされている InterBase ファイル（例外については後述）を削除し、レジスト

リを更新し、参照カウントが 1 より小さい共有ファイルを削除し、InterBase Guardianサービスとおよび InterBase Server サービスをアンインストールします。

構文 MSG_NO isc_uninstall_execute(TEXT *uninstall_file_name,

FP_STATUS *fpstatus, void *status_arg, FP_ERROR *fp_error,

void *error_arg)

説明 isc_uninstall_execute() は、以下の処理を含む実際のアンインストールを行います。

• isc_uninstall_precheck() を呼び出してアンインストールが可能かどうかを確認する

• 共有ファイルについて、レジストリの UseCount エントリをデクリメントし、参照カウン

トが 1 より小さいファイルを削除します。ただし、msvcrt.dll など、Microsoft によって事

前に値 0 が割り当てられているファイルは除きます。

• ib_uninst.nnn に記載されているすべての InterBase ファイルを削除します。ただし、

InterBase セキュリティデータベース（デフォルトは admin.ib）とそのバックアップ、お

よび ib_license.dat は除きます。

• ib_uninst.nnn 内のレジストリエントリをすべて削除する

• Windows NT/2000/XP では、Guardian および Server サービスをアンインストールす

る。Windows 98 では、Run レジストリエントリを削除する

• fp_status() を一定間隔で呼び出し、呼び出し側にアンインストールのステータスを知らせ

る

• ユーザーまたはエラーによってアンインストールが取り消された場合はクリーンアップを

行う


uninstall_file_name

TEXT * インストールされたオプションが記載されているファイルの名前。NULL であってはならない

fp_status FP_STATUS * 0 ～ 100 の整数を受け取るコールバック関数へのポインタ。エンドユーザーがステータス情報を要求しない場合はNULL であってもよい

status_arg void* fp_status() に渡されるユーザー定義データ。多くの場合NULL

fp_error FP_ERROR* エラー番号を受け取り、isc_uninstall_execute() が中止、継続、再試行のいずれを行うかを指定するニーモニックを返すコールバック関数へのポインタ

error_arg void* fp_error() に渡されるユーザー定義データ。多くの場合NULL


i s c _ u n i n s t a l l _ p r e c h e c k ( )



isc_uninstall_precheck()

サーバーが実行中かどうか、ユーザーの権限が正しいかどうか、およびアンインストール

ファイルが有効かどうかをチェックします。

構文 MSG_NO isc_uninstall_precheck(TEXT *uninstall_file_name)

説明 isc_uninstall_precheck() は、以下のチェックを行って、アンインストールが可能かどうか

を確認します。

• オペレーティングシステムが有効かどうか（Windows の場合）

• アンインストールファイル（ib_uninst.nnn）が有効で、オプションのリストが含まれてい

るかどうか

• サーバーがインストールされている場合、実行中でないかどうか

• プラットフォームが Windows NT/2000/XP の場合、アンインストールを行うユーザー

が管理者グループまたはパワーユーザーグループのメンバーかどうか（Windows 98 では、

これに相当するチェックは行われない）



isc_vax_integer()

使用しないでください。整数のバイト順を逆転します。この関数はまだサポートされてい

ますが、isc_portable_integer() で置き換えられています。

isc_vax_integer() は、大 LONG（4 バイト）の値しかサポートしません。

構文 ISC_LONG isc_vax_integer(

char *buffer,

short length);


uninstall_file_name TEXT * isc_install_execute() によって作成されたアンインストールファイルの名前を指すポインタ。NULL であってはならない

15-150 A P I ガイド

i s c _ v e r s i o n ( )

説明 isc_vax_integer() は、buffer で指定された整数のバイト順を逆転した値を返します。

この関数の通常の用途は、データベースパラメータバッファに渡された整数を、下位バ

イトが先頭、上位バイトが末尾となる形式に変換することです。InterBase では、入力

パラメータバッファ（DPB）の形式で整数を表さなければならず、結果バッファに返され

るのは汎用形式で、下位バイトが先頭、上位バイトが末尾となります。isc_vax_integer()は、この形式の変換に使用します。

例次のコード例は、isc_database_info() などの関数から返される結果バッファである文字バッ

ファに格納されている 2 バイト値を変換します。

#include <ibase.h>

char *p;

. . .


{

/* 結果バッファの次のクラスタの項目型を読み取ります */item = *p++;

/* 結果バッファの次の値の長さを読み取り、変換します */len = isc_vax_integer(p, 2);

p += len;

/* ここで、len バイトサイズの実際のデータを処理します */. . .

}

戻り値 isc_vax_integer() は、常にバイト順を逆にした long 整数を返します。

参照 isc_attach_database()、isc_database_info()

isc_version()

データベースの実装番号とバージョン番号を返します。

構文 int isc_version(


isc_callback function_name,

void *user_arg);


buffer char * 変換する整数へのポインタ

length short 変換する整数の長さ（バイト数）有効な長さは、1、2、または 4 バイト。


i s c _ v e r s i o n ( )

説明 isc_version() は、db_handle で指定されたデータベースについて、データベースの実装番

号とオンディスク構造体（ODS）のバージョン番号を判定します。この情報は、

function_name が指す 2 つのコールバックに渡されます。

function_name は、void 型のポインタ user_arg および char 型のポインタを引数とする、

アプリケーション関数を示す必要があります。user_arg では、どの種類のパラメータも渡

すことができます。

isc_version() は、function_name を 2 回呼び出します。初は、データベース実行番号を

判定し、その情報を保持する文字列を作成します。さらに、以下の形式でデータベース実

装番号を格納する文字列を指すポインタおよび user_arg を指定した function_name を呼

び出します。

<implementation>(<class>), version "<version>"

ここで

• <implementation> は、"InterBase/NT" などのテキスト文字列です。

• <class> は、実装クラスを指定する "access method" などのテキスト文字列です。

• <version> は、バージョンを識別する "8.0" などの文字列です。InterBase 2007 は、バー

ジョン 8.0 の InterBase コードと同等です。そのため、その呼称として 8.0 を使用します。

• function_name で示されるコールバック関数は、上記の情報を自由に使うことができます。

コールバック関数から isc_version() に制御が戻ると、isc_version() は、ODS のメジャー

バージョン番号とマイナーバージョン番号を含む別の文字列を作成します。さらに、次の

形式で ODS のバージョン番号を含む文字列を指すポインタおよび user_arg を指定した、

function_name を呼び出します。

on disk structure version <ods_major_num>.<ods_minor_num>

ここで

• <ods_major_num> は、ODS のメジャーバージョン番号です。InterBase は、ODS バー

ジョン 9 と ODS バージョン 10 を両方サポートします。データベースサーバーは、どちら

のバージョンのデータベースにもアクセスできますが、個々のデータベースはバージョン

9 またはバージョン 10 のどちらか一方でなければなりません。


db_handle isc_db_handle * • isc_attach_database() の呼び出しによって前もって設定されているデータベースハンドルへのポインタ

• db_handle が NULL の場合は status_vector にエラーが返される

function_name isc_callback • 関連情報とともに呼び出す関数へのポインタ

• C プログラムで NULL ポインタが渡された場合は printf() が呼び出される

user_arg void * function_name の 2 つの引数のうち、初の引数として渡される、アプリケーションが指定するパラメータ

15-152 A P I ガイド

i s c _ w a i t _ f o r _ e v e n t ( )

• <ods_minor_num> は、ODS のマイナーバージョン番号です。マイナーバージョン番号が

異なっていても、メジャーバージョン番号が同じであれば、データベースへのアクセスに

は影響ありません。

ヒント function_name として NULL ポインタが渡された場合は、isc_version() は C 関数 printf()を指すように function_name を設定します。

例次のコードは、コールバック関数に NULL を指定して isc_version() を呼び出します。

#include <ibase.h>

. . .

int ret;

. . .

ret = isc_version(&db1, NULL, "¥t%s¥n");

戻り値 isc_version() は、正常に終了した場合は 0、そうでない場合は 0 以外の値を返します。

参照 isc_database_info()

isc_wait_for_event()

指定されたイベントグループのいずれかが通知されるまで同期モードで待機します。

メモ InterBase 3.3 では、isc_wait_for_event() は gds_$event_wait() という関数名でした。し

たがって、InterBase 3.3 を使用していたコードを新しいバージョンで再利用する場合、こ

の関数だけは gds_$ を isc_ に置き換えただけでは使用できません。

構文 ISC_STATUS isc_wait_for_event(



short length,

char *event_buffer,




db_handle isc_db_handle * • isc_attach_database() で前もって設定されているデータベースハンドルへのポインタ。このハンドルは、通知するイベントの対象となるデータベースを識別する。

• db_handle が NULL の場合は status_vector にエラーが返される



説明 isc_wait_for_event() は、要求したイベントの 1 つが通知されるまで、同期モードで待機す

る場合に使用します。イベントが発生するまで、呼び出しアプリケーションに制御は戻り

ません。

待機するイベントは、isc_event_block() で前もって割り当て、値を設定した event_bufferに指定します。

イベントが通知されると、event_buffer と同一の内容が result_buffer に入力されますが、

イベントカウントは更新されます。この時点で、isc_wait_for_event() から呼び出しアプリ

ケーションに制御権が返されます。アプリケーションは、isc_event_counts() を呼び出し、

どのイベントが通知されたかを判定します。

メモイベント通知を非同期モードで要求する場合は、isc_wait_for_event() ではなく、

isc_que_events() を使用します。Microsoft Windows アプリケーションや、処理を中断で

きないシステムでは、非同期で通知しなければなりません。

例次のコードは、3 つのイベント "DEC"、"HP"、"SUN" のうちの 1 つが通知されるのを待

機する isc_wait_for_event() を呼び出しています。

#include <ibase.h>



short length;


&event_buffer,

&result_buffer,

number_of_stocks,


isc_wait_for_event(

status_vector,

&database_handle,


result_buffer);

length short イベントパラメータバッファ（EPB）の長さ。割り当てを行った isc_event_block() から返される

event_buffer char * 待機中のイベントの発生回数を格納するイベントパラメータバッファを指すポインタ。このバッファは、isc_event_block()を呼び出して割り当てておく必要がある

result_buffer char * 更新後のイベントカウントを入力するためのイベントパラメータバッファを指すポインタ。このバッファは、isc_event_block() で前もって割り当てておかなければならない


15-154 A P I ガイド



{


}

/* isc_event_counts() を呼び出してバッファ内のイベント数を比較し、どのイベントが通知されたかを判定します */

戻り値 isc_wait_for_event() は、ステータスベクターの第 2 要素を返します。0 の場合は正常に終





参照 isc_event_block()、isc_que_events()



15-156 A P I ガイド

索引
AALIGN マクロ 6-16API 関数 2-1 ～ 2-7
BLOB データ 7-1, 7-23DSQL 6-1SQL ステートメントの処理 6-4 ～ 6-6

XSQLDA 6-6, 6-10イベント 11-1エラー処理 2-6 ～ 2-7, 10-1

DSQL アプリケーション 10-5 ～ 10-7カテゴリのまとめ 15-1サンプルプログラム 3-9情報取得 4-10, 7-14, 11-8データベース 4-1トランザクション 5-1, 5-2配列 8-1プロトタイプ 3-5変換 9-1

API 呼び出し , 参照 / 逆参照 2-2, 2-3

BBinary Large Objects →「BLOB」BLOB API 関数 7-1, 7-23BLOB ID 7-3

再設定 7-10作成 7-13宣言 7-13

BLOB ID の再設定 7-10BLOB サブタイプ 7-3

取得 15-34, 15-38設定 15-41フィルタリング 15-121

BLOB セグメント 7-4書き込み 15-128取得 7-10

サイズ 15-38定義 7-3読み取り 15-103割り当て 7-13

BLOB データ 7-1, 7-5 ～ 7-14DSQL アプリケーション 6-4, 7-5, 7-6 ～ 7-9, 7-

11格納 7-3, 7-12, 15-44キャッシュ 7-10

更新 7-11, 7-11 ～ 7-12, 15-129削除 7-14作成 15-42, 15-47サポート 7-2情報の取得 7-14 ～ 7-18情報の取り出し 15-37

デフォルト 15-34処理 2-5, 15-42, 15-44ステータスメッセージ 7-16選択 7-6 ～ 7-8取り出し 7-9フィルタ 7-24 ～ 7-27フィルタリング 15-34変換 7-18, 15-47読み取り 7-4, 7-6 ～ 7-10

BLOB フィルタ 7-24BLOB データ型

NULL 値 7-7, 7-10, 7-14配列 8-2ユーザー定義のデータ型 7-3

BLOB データのフィルタリング 7-24～7-27, 15-34⇒「BLOB データ」

BLOB データの読み取り 7-4, 7-6 ～ 7-10BLOB フィルタ 7-24

BLOB デスクリプタ 2-5, 7-4 ～ 7-5値の設定 7-4 ～ 7-5, 15-34構造体の定義 7-4

BLOB の概要 7-2BLOB パラメータバッファ 7-24 ～ 7-26

作成 15-35数値形式 7-26パラメータタイプ 7-26

BLOB ハンドル 7-12割り当て 15-42

BLOB フィルタ 7-4, 7-18 ～ 7-27BLOB を開く 7-27, 15-42, 15-121外部 7-18, 7-18 ～ 7-23

作成 7-19 ～ 7-23宣言 7-18

指定 15-47制御構造体の定義 7-20ユーザー定義のデータ型 7-18呼び出し 7-24

BLOB フィルタ関数

索引 I-1

定義 7-19動作マクロの定義 7-23入力 / 出力フィールド 7-21

BLOB 列作成 7-12 ～ 7-14データの書き込み 7-4, 7-7

BLOB フィルタ 7-24BOOLEAN データ型 6-12Borland C/C++ →「C 言語」

BPB →「BLOB パラメータバッファ」

CCAD ファイル 7-3CHARACTER VARYING データ型

DSQL アプリケーション 6-14CLOSE 6-5CREATE DATABASE 6-4

DSQL アプリケーション 15-76

DDATE データ 9-1

変換 9-2 ～ 9-3DECIMAL データ型

DSQL アプリケーション 6-14DECLARE CURSOR 6-5DECLARE FILTER 7-18, 7-19DELETE

BLOB データ 7-14DSQL アプリケーション 15-87

DESCRIBE 6-5DLL 3-8DOS アプリケーション 3-3DOS 環境変数 3-3DPB →「データベースパラメータバッファ」DSQL

プログラミング手法 6-16 ～ 6-33DSQL API 関数 6-1DSQL アプリケーション 2-4, 6-1

BLOB 処理 6-4, 7-5, 7-6 ～ 7-9, 7-11SQL ステートメント 6-4 ～ 6-6エラー処理 10-5 ～ 10-7カーソルの宣言 6-24, 6-30カーソルの定義 15-87拡張デスクリプタエリア → XSQLDAクエリー 6-21 ～ 6-32情報の取り出し 15-65

SELECT ステートメント 15-63

配列 6-4, 8-5, 15-13データの取り出し 15-79

DSQL ステートメント

実行 15-67, 15-71, 15-74, 15-77繰り返し 15-84

情報の取り出し 15-89入力パラメータ 15-65ハンドル

割り当て 15-60, 15-61DSQL_close オプション 15-83DSQL_drop オプション 15-83

EEPB →「イベントパラメータバッファ」EXECUTE 6-5EXECUTE IMMEDIATE 6-5EXECUTE PROCEDURE

DSQL アプリケーション 15-63, 15-71, 15-75

FFETCH 6-5FILE 構造体 4-2

GGDS.DLL 3-8

Iib_uninst 15-150ibase.h 2-2, 2-3

BLOB デスクリプタ 2-5XSQLDA 構造体 2-4エラー 2-6

INSERTBLOB データ 7-5, 7-11配列 8-12, 8-15

isc_add_user() 15-8ISC_ARRAY_BOUND 構造体 8-2, 8-4ISC_ARRAY_DESC 構造体 8-2ISC_ARRAY_DESC_V2 2-6isc_array_get_slice2() 15-12isc_array_lookup_bounds() 8-4, 8-9, 8-11, 15-

16isc_array_lookup_bounds2() 15-16isc_array_lookup_desc() 8-4, 15-19isc_array_lookup_desc2() 15-19isc_array_put_slice() 8-10, 8-14, 15-22isc_array_put_slice2 15-22

I-2 A P I ガイド

isc_array_put_slice2() 15-22isc_array_set_desc() 8-4, 15-29isc_array_set_desc2() 15-29isc_attach_database() 4-8, 15-31

DPB 4-3isc_blob_default_desc() 15-34isc_blob_default_desc2() 15-34isc_blob_gen_bpb() 7-24, 15-35isc_blob_gen_bpb2() 15-35isc_blob_info() 7-14 ～ 7-18, 15-37isc_blob_lookup_desc() 15-38isc_blob_lookup_desc2() 15-38isc_blob_set_desc() 15-41isc_blob_set_desc2() 15-41isc_cancel_blob() 7-14, 15-42isc_cancel_events() 11-10, 15-43isc_close_blob() 15-44isc_commit_retaining() 5-15, 15-45isc_commit_transaction() 5-14, 5-15, 5-16, 15-

46isc_create_blob2() 7-13, 7-27, 15-47ISC_DATABASE 環境変数 3-3isc_database_info() 4-10, 4-14, 15-50isc_db_handle 型 4-2isc_decode_sql_date() 15-52isc_decode_sql_time() 15-53isc_decode_timestamp() 9-2, 15-54isc_detach_database() 4-15, 15-58isc_drop_database() 4-16, 15-59isc_dsql_allocate_statement() 6-17 ～ 6-18, 15-

60isc_dsql_allocate_statement2() 15-61isc_dsql_describe() 6-8, 15-63isc_dsql_describe_bind() 15-65isc_dsql_exec_immed2() 15-77isc_dsql_execute() 6-17 ～ 6-18, 15-67isc_dsql_execute_immediate() 6-17, 15-74isc_dsql_execute2() 15-71isc_dsql_fetch() 7-9, 8-9, 15-79

SELECT ステートメント 15-79isc_dsql_prepare() 6-8, 6-17 ～ 6-18, 15-84

isc_dsql_sql_info() 15-89isc_dsql_set_cursor_name() 15-87isc_dsql_sql_info() 6-32 ～ 8-1, 15-89isc_encode_sql_date() 9-3, 15-95isc_encode_sql_time() 15-96isc_encode_timestamp() 15-97isc_event_block() 11-3 ～ 11-4, 15-98isc_event_counts() 11-8 ～ 11-9, 15-99

isc_expand_dpb() 4-7, 15-101ISC_EXPORT キーワード 2-4isc_get_client_version() 15-102, 15-103isc_get_segment() 7-10, 15-103

BLOB フィルタ 7-21isc_info_truncated 値 7-15isc_install_clear_options() 15-105isc_install_execute() 15-106isc_install_get_info() 15-108isc_install_get_message() 15-109isc_install_load_external_text() 15-109isc_install_precheck() 15-110isc_install_set_option() 15-112, 15-113isc_install_set_option()() 15-105isc_install_unset_option() 15-113isc_interprete() 10-3, 15-114isc_open_blob2() 7-27, 15-121ISC_PASSWORD 環境変数 3-3, 3-4isc_portable_integer() 9-3, 15-123, 15-150isc_prepare_transaction() 5-16, 15-124isc_prepare_transaction2() 5-17, 15-125isc_print_sqlerror() 10-5, 15-126isc_print_status() 10-3, 15-127isc_put_segment() 7-13, 15-128

BLOB フィルタ 7-21isc_que_events() 11-5 ～ 11-8, 15-130isc_rollback_retaining() 5-17isc_rollback_transaction() 5-14, 5-17, 15-135isc_sql_interprete() 10-6 ～ 10-7, 15-140isc_sqlcode() 10-5, 15-140isc_start_multiple() 5-12, 15-141

isc_start_transaction() との違い 15-145isc_start_transaction() 5-11, 15-144ISC_STATUS ポインタ 10-2isc_tr_handle 型 5-3isc_transaction_info() 15-147isc_uninstall_execute() 15-149isc_uninstall_precheck() 15-150ISC_USER 環境変数 3-4isc_version() 15-151isc_wait_for_event() 11-4 ～ 11-5, 15-153

Llimbo トランザクション 15-124

MMETADATALENGTH 2-6, 7-4Microsoft C/C++ →「C 言語」

索引 I-3

Microsoft Windows →「Windows」

NNCHAR VARYING データ型

DSQL アプリケーション 6-14NetWare サーバー

ユーザー名を返す 4-13NULL ステータス 6-11NULL 値

BLOB ハンドル 15-42BLOB 列 7-7, 7-10, 7-14拡張デスクリプタエリア 6-13, 6-15配列 8-5, 8-13, 8-14, 8-16

NULL ポインタ 5-11NUMERIC データ型


OODS →「オンディスク構造体」OPEN 6-5

PPC 開発環境 3-1PREPARE 6-5

RRDB$TRANSACTIONS 15-47

SSELECT

BLOB データ 7-5, 7-6 ～ 7-8⇒「単一行 SELECT」

SELECT ステートメント

DSQL アプリケーション 15-79作成 15-85実行 15-68, 15-71, 15-75情報の取り出し 15-63

単一行 SELECT 15-78配列 8-5, 8-6 ～ 8-8

SET TRANSACTIONDSQL アプリケーション 15-76

SQL エラー処理ルーチン 15-140SQL エラーメッセージ 10-5 ～ 10-7

作成 15-140表示 10-5, 15-126⇒「SQLCODE 変数」

SQL クライアント 3-1SQL ステートメント

BLOB データの選択 7-6 ～ 7-8DSQL アプリケーション 6-4 ～ 6-6

パラメータ , 値の設定 6-10, 6-11パラメータ、値の設定 6-18, 6-25

イベント通知 11-3作成 6-19, 6-22, 6-27時刻構造体 9-2実行 6-19, 6-21, 6-24, 6-25, 6-30, 6-31処理 6-18 ～ 6-21, 6-25 ～ 6-32

パラメータなし 6-17 ～ 6-18, 6-21 ～ 6-25指令 2-2, 2-4, 2-6

エラー処理 10-8選択リスト項目の取り出し 6-24定義済み定数

項目タイプ（BLOB）7-15定義済みマクロ 6-11

情報取得（SQL）6-32動作メッセージ（BLOB）7-23データ型（XSQLDA）6-11, 6-16

非クエリーステートメント 6-17 ～ 6-21日付の変換 9-2 ～ 9-3文字列への変換 6-5, 6-16

SQL デスクリプタエリア（拡張…） →「XSQLDA」

SQLCODE 変数

DSQL アプリケーション 10-5戻り値 15-126

TTPB →「トランザクションパラメータバッファ」

UUPDATE

BLOB データ 7-5, 7-11 ～ 7-12DSQL アプリケーション 15-87配列 8-12 ～ 8-15

VVARCHAR データ型

DSQL アプリケーション 6-14, 6-15

WWindows アプリケーション 2-4

イベント通知 11-4データ型の定義 3-4, 3-5

I-4 A P I ガイド

デフォルトディレクトリの設定 3-3Windows クライアント

セキュリティ 3-3接続 3-2, 3-3プログラムパラメータの設定 3-3

XXSQLDA 6-6 ～ 6-16

NULL 値の設定 6-15NULL 値の取り出し 6-11, 6-13構造体 2-4, 6-6サイズの変更 15-85出力デスクリプタ 6-6, 6-8, 6-11

作成 6-21, 6-26割り当て 6-11

宣言 6-6選択リスト項目 6-21, 6-23, 6-26

BLOB データ 7-6配列 8-6, 8-9

データ型の強制変換 6-15可変長データ 6-15数値 6-15

データ型の指定 6-11 ～ 6-16可変長データ 6-14, 6-15数値 6-14

データの配置（アラインメント）6-16入力デスクリプタ 6-6, 6-8, 6-10

作成 6-18 ～ 6-19, 6-26配列 8-13割り当て 6-11

フィールド 6-8⇒「XSQLVAR 構造体」

XSQLDA_LENGTH マクロ 6-11XSQLVAR 構造体 6-11, 6-20

BLOB データ 7-7, 7-12選択リスト項目の設定 6-23定義 6-6データ型 6-13配列 8-7フィールド 6-9割り当て 6-8

あアクション →「イベント」

アクセス配列 8-5 ～ 8-15配列 , DSQL アプリケーション 15-13

アクセスモードパラメータ 5-6, 5-8値

数値デスクリプタ 10-10⇒「NULL 値」

値パラメータSQL ステートメント 6-6

アドレスエラーメッセージ 10-10数値データ 6-16

アプリケーションBLOB データ 7-3, 7-7, 7-12, 7-14

型のチェック 7-19割り当て 15-42, 15-44

Windows →「Windows アプリケーション」

エラー処理 15-140コンパイル →「コンパイル」

データの復旧 15-126パフォーマンスの監視 15-50プログラミング 2-1 ～ 2-7リンク →「リンク」

⇒「DSQL アプリケーション」

アンインストールの手順 15-149

い一時データベース 15-59イベント 11-1

取得 11-8処理 2-6, 11-5 ～ 11-6待機 11-4, 11-6通知 15-99同期… 11-2, 15-153トランザクション制御 11-3非同期 11-2, 11-5

通知の取り消し 11-10, 15-43通知の要求 15-130

イベントバッファ , 再初期化 11-9イベントパラメータバッファ 11-2

イベントカウントの比較 15-99作成 11-3 ～ 11-4割り当て 15-98

インクルードファイル →「ibase.h」インストールオプション 15-112インストール環境 15-110

えエラー 10-7, 15-135

実行時… 10-1

索引 I-5

トランザクション 5-14エラーコード 10-2, 10-9

システム 10-10ステータスベクターの解析 10-7 ～ 10-10変換 10-5, 15-140

エラー処理 , API 関数 2-6 ～ 2-7, 10-1エラー処理ルーチン 5-14, 10-9

SQL ステートメント 15-140エラーステータス配列 2-6エラーステータスベクター 2-6

解析 10-7 ～ 10-13クラスタ 10-7数値デスクリプタ

数値の意味 10-10数値のデスクリプタ 10-7 ～ 10-9宣言 10-1チェック 10-2

エラーメッセージ 10-2アドレス 10-10作成 15-114テキストを返す 15-109表示 10-3, 10-5, 15-127⇒「SQL エラーメッセージ」

DSQL アプリケーション 10-5, 10-7エラー処理 , API 関数

DSQL アプリケーション 10-5, 10-7

おオブジェクト名 2-6, 7-4オプション , クリア 15-106オプションの説明 15-108オンディスク構造体

情報の取り出し 4-12

かカーソル

DSQL アプリケーション 15-87宣言 6-24, 6-30名前 15-87開く 15-87

外部 BLOB フィルタ →「BLOB フィルタ」

書き込みデータ配列 8-10 ～ 8-15

拡張 SQL デスクリプタエリア →「XSQLDA」

格納BLOB データ 7-3, 7-12データ 8-1, 8-13, 8-14

可変長データの処理 6-14, 6-15環境

PC 3-1情報の取り出し 4-13

環境変数 3-3監視 , パフォーマンス 15-50関数プロトタイプ 3-5

き逆転 , バイト順 9-3キャラクタセット

BLOB データ 7-4, 7-24情報の取得 15-34, 15-38設定 15-41

行DSQL アプリケーション 15-63情報の取り出し 15-63

行基準の指定 15-17, 15-20, 15-29競合の解決 5-9強制変換 , データ型（XSQLDA）6-15

くクエリー 2-4

DSQL アプリケーション 6-21 ～ 6-32配列 8-6⇒「SQL」

クライアントアプリケーション →「SQL クライア

ントアプリケーション、Windows クライアント

アプリケーション」クライアントバージョン 15-102, 15-103クライアントライブラリ 3-4

け結果バッファ 4-10

BLOB 7-15 ～ 7-16定義 4-10

書式化エラーメッセージ 10-4

こ更新

BLOB データ 7-11, 7-11 ～ 7-12, 15-129配列 8-11 ～ 8-15

項目タイプ定数（BLOB）7-15項目リストバッファ 7-15

⇒「isc_blob_info()」コミット 5-15, 5-16, 15-46

I-6 A P I ガイド

遅れ 5-17コンテキストの保持 15-45実行 15-46, 15-124, 15-125⇒「トランザクション」

コンパイル 2-7

さサウンドファイル , サポートされる… 7-3削除

データベース 4-16, 15-59配列 8-15

サンプルプログラム 3-9

し時刻構造体 9-2システムエラーコード 10-10システムクラッシュ 15-126実行時エラー 10-1自動復旧機能 15-126集合関数

配列 8-5出力

エラーメッセージ 10-3, 10-5, 15-126, 15-127出力デスクリプタ →「XSQLDA」

出力フィールドBLOB フィルタ 7-21

情報項目マクロ（SQL）6-32情報取得 API 関数 4-10, 7-14, 11-8初期化

BLOB ID 7-13BLOB ハンドル 7-12データベースハンドル 2-2, 4-2トランザクションハンドル 2-3, 5-3配列 ID 8-14配列デスクリプタ 15-29

すスイープ , データベース

情報の取り出し 4-13数値 9-3

XSQLDA での処理 6-14, 6-15バイト順 9-3メモリ上の配置（アラインメント）6-16

数値 →「値」

ステータス情報 6-11, 10-1ステータスベクター →「エラーステータスベク

ター」

ステータスメッセージBLOB データ 7-16トランザクション 15-148

せセキュリティ

Windows クライアント 3-3接続の必要条件 3-2

セキュリティデータベース 12-29位置 12-30ユーザーの削除 15-54ユーザーの追加 15-8

接続 , データベース 3-2⇒「データベースへの接続」

宣言BLOB ID 7-13BLOB ハンドル 7-12BLOB フィルタ 7-18BLOB デスクリプタ 2-5エラーステータスベクター 10-1カーソル 6-24, 6-30拡張デスクリプタエリア 6-6データベースハンドル 2-2, 4-2トランザクションハンドル 2-3, 5-3配列 ID 8-14

選択リスト 6-21, 6-23, 6-26BLOB データ 7-6項目の処理 6-25項目の取り出し 6-24定義 6-21⇒「クエリー」

そ添字（配列）8-2

たダイナミックリンクライブラリ → 「DLL」多次元配列 8-2, 8-4

次元の範囲 8-2単一行 SELECT


て定数

項目タイプ（BLOB）7-15ディレクトリ

Windows クライアント 3-3

索引 I-7

データ格納 8-1, 8-13, 8-14可変長

XSQLDA での処理 6-14, 6-15取得 8-4, 8-6, 8-8, 15-12

選択された行 8-9損失 5-14取り出し 7-9, 8-9

DSQL アプリケーション 15-79バイナリ 7-3破損 5-14復旧 15-126保護 →「セキュリティ」

読み取り 8-6 ～ 8-10データ型 3-4, 3-5

配列 8-1, 15-18未決定 7-3

データ型強制変換（XSQLDA）6-15データ型マクロ定数（XSQLDA）6-11 ～ 6-16データの書き込み

BLOB への… 7-4, 7-7BLOB フィルタ 7-24

配列 15-22データの取得 7-9, 8-4, 8-6, 8-8, 15-12

選択された行 8-9データの取り出し 7-9, 8-9

DSQL アプリケーション 15-79⇒「データの取得」

データの復旧 15-126データの保護 →「セキュリティ」

データの読み取り 8-6 ～ 8-10データの取得

DSQL アプリケーション 15-79データベース

アクセス 4-1, 6-2一時 15-59削除 15-59作成 6-4参照 2-2情報の取り出し 4-12, 4-13, 15-151

バージョン番号 15-151接続 3-2閉じる 5-14パフォーマンス統計値 4-13変更の取り消し 15-135⇒「マルチデータベース」

データベース API 関数 4-1データベース接続の解除 4-15, 15-58

⇒「データベースの接続解除」データベースの接続解除 4-2, 4-15

⇒「データベース接続の解除」データベースパラメータバッファ 2-3, 4-1

拡張 15-101記憶スペースの割り当て 4-7作成 4-3 ～ 4-6, 15-101数値形式 9-3パラメータ 4-5

実行時の追加 4-7データベースハンドル 4-2 ～ 4-3

実行時の割り当て 6-2初期化 2-2, 4-2宣言 2-2, 4-2定義 2-2複数のデータベース 6-2

データベースハンドルを 4-8データベースページ

情報の取り出し 4-12データベースへの接続 4-2 ～ 4-10, 6-2, 15-31

DPB 4-3Windows クライアント 3-2, 3-3一時… 15-59オプション 2-2システムリソースの解放 15-58情報の取得 4-10 ～ 4-15情報の取り出し 15-50⇒「データベースへの接続」

テーブルアクセス 5-9 ～ 5-10

テーブル名格納 8-4

テキストBLOB の種類 7-2

テキストファイル , サポートされる… 7-3デスクリプタエリア（拡張…） →「XSQLDA」

デスクリプタフィールド →「配列デスクリプタ、

BLOB デスクリプタ」

デフォルト , 取り出しBLOB 15-34

デフォルトディレクトリWindows クライアント 3-3

と同期イベント 11-2

通知の要求 15-153動的 SQL →「DSQL」閉じる

I-8 A P I ガイド

データベース 5-14トラップ 11-5 ～ 11-6

⇒「イベント」トランザクション 5-1

limbo 状態 15-124アクセスモード 5-6, 5-8イベント 11-3開始 2-3, 5-2, 15-141, 15-144コミット 5-15, 5-16, 5-17, 15-46

2 相コミットの実行 15-46, 15-124, 15-125コンテキストの保持 15-45適化 5-15

参照 2-3終了 5-14情報の取り出し 15-147ステータスメッセージ 15-148属性の指定 5-3 ～ 5-14テーブルへのアクセス 5-9 ～ 5-10トランザクション状態ブロック（TEB）5-12トランザクションパラメータバッファ（TPB）5-1 ～ 5-13排他レベル 5-6 ～ 5-8複数のデータベース 5-12, 5-16, 15-124, 15-

125, 15-141並列 5-7ロールバック 5-17, 15-135ロックの競合 5-8

トランザクション ID管理 15-147

トランザクションパラメータバッファ 2-3, 5-1作成 5-3 ～ 5-14数値形式 9-3定数 5-4デフォルト 5-11

トランザクションハンドル 5-2 ～ 5-3実行時の割り当て 6-3初期化 2-3, 5-3宣言 2-3, 5-3定義 2-3

に入力デスクリプタ →「XSQLDA」

入力パラメータDSQL ステートメント 15-65

入力フィールドBLOB フィルタ 7-21

ねネストした配列 8-2ネットワーク DLL 3-8

はバージョン番号

オンディスク構造体 4-12データベース 4-12, 15-151トランザクション処理 5-6

排他レベルパラメータ 5-6, 5-8アクセスの制限 5-7

バイト順の逆転 9-3バイナリデータ 7-3バイナリファイルタイプ , サポートされる… 7-3配列 8-5 ～ 8-15

API 関数 8-1DSQL アプリケーション 6-4, 15-13概要 8-1 ～ 8-2行基準の指定 15-17, 15-20, 15-29更新 8-11 ～ 8-15削除 8-15作成 8-2, 8-14サブセット

書き込み 8-2取得 8-2

処理 2-5 ～ 2-6添字 8-2多次元… 8-2, 8-4

次元の範囲 8-2データの取得 8-4, 8-6, 8-8, 15-12

選択された行 8-9データの読み取り 8-6 ～ 8-10

データバッファの作成 8-10ネスト 8-2配列型の列との関連付け 8-15列基準の指定 15-17, 15-20, 15-29⇒「エラーステータス配列」

配列 ID 8-11, 15-13初期化 8-14宣言 8-14取り出し 8-9

配列型の列 8-5, 8-13サイズの設定 15-19選択 8-6, 8-8データの書き込み 8-10 ～ 8-15, 15-22配列との関連付け 8-15

索引 I-9

配列スライス 8-6 ～ 8-101 スライスの変更 8-121 スライスの読み取り 8-9定義 8-1データの書き込み 8-10 ～ 8-15データバッファの作成 8-12

配列デスクリプタ 8-2 ～ 8-5値の設定 8-4 ～ 8-5, 8-8, 15-17作成 8-8, 8-11初期化 15-29データ型 15-18フラグの設定 15-17, 15-20, 15-29

配列バッファ 8-10, 8-12配列要素 8-2

サイズの設定 15-17パスワード 2-2

Windows クライアント 3-2, 3-4実行時に入力 15-101優先 3-4⇒「セキュリティ」

バッファ 8-10, 8-12BLOB フィルタ 7-24イベント…の再初期化 11-9エラーメッセージの取り込み 10-3, 10-6データベース接続 4-3, 4-10トランザクション 5-3

パフォーマンス統計値 4-13パフォーマンスの監視 15-50パラメータ 15-101

DPB 4-5, 4-7SQL ステートメント 6-6, 6-10, 6-11, 6-18, 6-

25パラメータのない SQL ステートメントの処

理 6-17 ～ 6-18, 6-21 ～ 6-25トランザクションパラメータバッファ（TPB）5-1 ～ 5-13入力 15-65

ハンドル →「データベースハンドル、トランザク

ションハンドル」

ひ引数 →「パラメータ」

ビットマップイメージ 7-2ビデオ 7-2ビデオファイル , サポートされる… 7-3非同期イベント 11-2, 11-5

通知の取り消し 11-10, 15-43

通知の要求 15-130非同期トラップ 11-5 ～ 11-6

作成 11-6ビュー

配列 8-5表示 →「出力」

開くBLOB 7-27, 15-42, 15-121カーソル 15-87

ふファイルタイプ

BLOB データ 7-3複数のデータベース

接続 6-2トランザクション 5-12, 5-16, 15-124, 15-125,

15-141符号付き数値 9-3プログラミング

API アプリケーション 2-1 ～ 2-7DSQL アプリケーション 6-1, 6-16 ～ 6-33Windows アプリケーション 2-4エラー処理 →「エラー」

文取得 6-32 ～ 8-1, 15-89

へ並列トランザクション 5-7ベクターグラフィックファイルタイプ, サポートさ

れる… 7-3ヘッダーファイル →「ibase.h」変換

日付 9-2 ～ 9-3変更

取り消し 15-135⇒「ロールバック」

ほポインタ

FILE 構造体 4-2トランザクション 5-11⇒「カーソル」

ホスト名の指定 3-3

まマクロ

ALIGN 6-16XSQLDA_LENGTH 6-11

I-10 A P I ガイド

情報取得（SQL）6-32データ型（XSQLDA）6-11 ～ 6-16動作メッセージ（BLOB）7-23

み未決定のデータ型 7-3未知のデータ型 7-3未知の文 6-32, 15-89

むムービー 7-2

めメタデータ名 2-6, 7-4メッセージ →「エラーメッセージ、ステータスメッ

セージ」メッセージファイル 15-109メモリ

情報の取り出し 4-13割り当て 6-11

も文字列

変換SQL ステートメント 6-5, 6-16

文字列アドレスエラーメッセージ 10-10

ゆユーザー定義の BLOB フィルタ 7-18ユーザー定義のデータ型

BLOB データ 7-3ユーザー名 2-2

Windows クライアント 3-2, 3-4実行時に入力 15-101情報の取り出し 4-13優先 3-4

よ要求バッファ

定義 4-10要求バッファ項目 4-10

らライブラリ

BLOB フィルタルーチン 7-18

ダイナミックリンク →「DLL」

りリンク 2-7

るルーチン

BLOB フィルタ 7-18, 7-24エラー処理 5-14, 10-9

SQL ステートメント 15-140

れ列

DSQL アプリケーション 15-63情報の取り出し 15-63配列 8-1, 8-6

列が基準の配列順指定 15-17, 15-20, 15-29

列名格納 8-4

ろロールバック 5-17, 15-135

⇒「トランザクション」ログファイル 10-6ロック対応パラメータ 5-8

わ割り当て , メモリ 6-11

索引 I-11

Documents

API - Embarcadero Websitedocs.embarcadero.com/.../1.2_JA/html/Pdf/APIGuide.pdf · 2009-02-06 · ii sql ステートメントを処理する api アプリケー ションの作成

API - Embarcadero Websitedocs.embarcadero.com/.../1.2_JA/html/Pdf/APIGuide.pdf · 2009-02-06 · ii sql ステートメントを処理する api アプリケーションの作成