付 録 Ａ この 付 録 で は 、ODBC Interface を 使 っ て 、ODBC API か ら 拡 張 さ れ た Scalable SQL および Btrieve オペレーションを実行する方法について説明 します。次に、この付録の内容を示します。
➣ オーナネームを使ったファイルの操作
➣ バージョン情報の取得
➣ カレントセッション ID の識別
➣ コールバック関数のインストールと削除 (Windows v3.1 のみ)
➣ データの変換
➣ マスクの検証
➣ デフォルトマスクの取得
➣ データ値の検証
ODBC から拡張された Scalable SQL オペレーションの実行
Scalable SQL API の関数の中には、ODBC API にはないものがあります。
XQLCallback や XQLVersion などがこの中に含まれます。さらに、ODBC には Btrieve で使用するファイルのオーナネームという概念がありません。
し か し 、ODBC API 関 数 へ の 拡 張 機 能 で あ る SQLGetConnectOption と
SQLSetConnectOption を使うと、これらの関数にアクセスしたり、オーナ
ネームを持つファイルを作成することができます。これらの関数を使うと、
次のタスクを実行できます。
➣ ODBC Interface にオーナネームのリストを提供する。
➣ バージョン情報を取得する。
➣ カレントセッション ID を識別する。
➣ コールバック関数をインストールまたは削除する (Windows v3.1 のみ)。
➣ データの内部形式と表示形式を相互に変換する。
➣ マスクを検証する。
➣ デフォルトマスクを取得する。
➣ データの値を検証する。
表 A-1 には、ODBC のデータ型と C のデータ型との対応を示します。
表 A-1
C プラットフォームに依存しないデータ型
ODBC のデータ型 C のデータ型
HDBC long integer
RETCODE long (32-bit) integer
UDWORD long integer
UWORD short (16-bit) integer
SQLSetConnectOption と SQLGetConnectOption の使い方
表 A-2 には、SQLSetConnectOption と SQLGetConnectOption の使い方を示 します。
表 A-2
SQLSetConnectOption と SQLGetConnectOption の使い方
機能 ODBC 関数 fOption の値
ODBC Interface にオーナネームのリス トを提供する。
SQLSetConnectOption 1000
バージョン情報を取得する。 SQLGetConnectOption 1001 カレントセッション ID を識別する。 SQLGetConnectOption 1002 コールバック関数のインストールまた
は削除を行う (Windows v3.1 のみ)。
SQLSetConnectOption 1003
データの内部形式と外部形式を相互に 変換する。
SQLGetConnectOption 1004
フィールドへのデータ入力に使用する マスクを検証する。
SQLGetConnectOption 1005
フィールドへのデータ入力に使用する デフォルトマスクを取得する
SQLGetConnectOption 1006
フィールドまたはフィールドのグルー プの値を検証する。
SQLGetConnectOption 1007
付 録 Ａ 次に、SQLGetConnectOption に対する C/C++ を使った呼出し規約を示しま す。
RETCODE SQLGetConnectOption( hdbc, fOption, pvParam ) HDBC hdbc;
UWORD fOption;
UDWORD pvParam;
次に、SQLSetConnectOption に対する C/C++ を使った呼出し規約を示しま す。
RETCODE SQLSetConnectOption( hdbc, fOption, vParam ) HDBC hdbc;
UWORD fOption;
UDWORD vParam;
Option 1000: ODBC Interface にオーナネームのリストを提供する
オーナネームは、パスワードまたは暗号化キーとして動作し、Scalable SQL のテーブルや Btrieve のデータファイルに格納されている重要なデータへ のアクセスを制限します。SQLSetConnectOption を使って、SQL エンジン にオーナネームのリストを渡し、下層のテーブルをオープンすることがで きます。
パラメータの概要
表 A-3には、オーナネームのリストを渡すときの SQLSetConnectOption 関 数のパラメータをまとめてあります。
表 A-3
Option 1000 に対する SQLSetConnectOption のパラメータ
パラメータ 説明 値渡し 参照渡し
hdbc SQLAllocConnect の戻り値 ◆
fOption 定数値 (1000) ◆
vParam カンマで区切られた個別のオーナネーム
を 含 む 、Null で 終 わ る 文 字 列 の ア ド レ ス。オーナネームにスペースが含まれて いる場合は、オーナネームをシングルク ォーテーションマーク ( ’ ) で囲みます。
このバッファの内容は、SQLSetConnect Option 関数の処理中は修正されません。
呼出し時にコンパイラから警告が出され る の を 避 け る た め 、 こ の ア ド レ ス は UDWORD 型にキャストします。
◆
オーナネームのリストの提供
オーナネームが適用されている Scalable SQL のテーブルまたは Btrieve の ファイルを ODBC でオープンするには、表 A-3 で説明したパラメータを 使って SQLSetConnectOption を呼出します。
エラー
接続がアクティブでない場合 (オペレーションを完了するため、カーソル ID が内部的に割り当てられている必要があるため)、SQLSetConnectOption はエラーを返します。ネームリストが適切な形式になっていないと、エラ ーが発生します。
SQLGetConnectOption の呼出し
SQLGetConnectOption を呼出すには、実行するオプションに必要な形式に
従ってバッファを準備します。接続を割り当てたときに ODBC から取得 した接続ハンドル、オプション番号、およびバッファのアドレス (コンパ イラから警告が出されるのを避けるため、UDWORD 型にキャストする必 要があります) を渡して、関数を呼出します。
付 録 Ａ パラメータの概要
SQLGetConnectOption 関数のパラメータは、それぞれのオプションごとに
個別に説明します。これは、オプションによってパラメータの解釈が異な るためです。
エラー
下層の SQL API 関数がエラーを返すと、 SQLGetConnectOption もエラー を返します。ODBC 関数の SQLError を使用すると、ネイティブエラーコ ードパラメータに返されたステータスコードなどのエラー情報を取得する ことができます。
接続がアクティブでなく、オペレーションを完了するためにカーソル ID が内部的に必要とされた場合にも、SQLGetConnectOption はエラーステー タスを返すことがあります。
Option 1001:バージョン情報を取得する
このオプションを使用すると、Scalable SQL エンジンまたはリクエスタに 関するバージョン情報を取得することができます。
パラメータの概要
表 A-4 には、バージョン情報を取得するときの SQLGetConnectOption 関 数のパラメータをまとめてあります。
表 A-4
Option 1001 に対する SQLGetConnectOption のパラメータ
パラメータ 説明 値渡し 参照渡し
hdbc SQLAllocConnect の戻り値 ◆
fOption 定数値 (1001) ◆
vParam バッファのアドレス。呼出し時にコンパイ
ラから警告が出されるのを避けるため、こ のアドレスは UDWORD 型にキャストしま す。
◆
表 A-5 には、バージョン情報を取得するために使用するバッファの構造を 示します。
表 A-5
SQLGetConnectOption の Version パラメータブロックの形式
サイズ データ型 説明
4 文字列型 入力: 識別文字 XVER に初期化します。
出力: この中に XVER が含まれている場合、バージ ョ ン 情 報 は 次 に 続 く デ ー タ 要 素 に 含 ま れ ま す 。 XVER が含まれていない場合、この 4 バイトには Scalable SQL エンジンの古いバージョンに関する情 報が含まれます。この場合、先頭の 2 バイトにはバ ージョン番号、次の 2 バイトにはリビジョン番号が 含まれます。
2 整数型 4 バイトの識別文字を含めて、このバッファのサイ ズを設定します。
2 整数型 オプションコードです。リクエスタのバージョンを 取得するには 0、ローカルエンジンのバージョンを 取得するには 1 を設定します。また、次のデータ要 素で指定されるセッション ID をサポートするエン ジンのバージョンを取得するには 2、次のデータ要 素で指定される名前またはディレクトリパスを持つ データベースをサポートするエンジンのバージョン を取得するには 3 を設定します。
4 整数型 (先頭の 2 バイトのみ)
オプションコードに 2 が設定されている場合、有効 なセッション ID を渡します。また、オプションコ ードに 3 が設定されている場合は、Null で終了す る文字バッファのアドレスを渡します。このバッフ ァには、"@" で始まるデータベース名を表す文字 列、¥¥server¥volume: の形式の Netware サーバとボ リューム名、またはデータベースのディレクトリパ スが含まれます。
2 整数型 バージョン番号。
2 整数型 リビジョン番号。
2 整数型 製品のアップデート番号。65535 という戻り値は、
製品のアップデートレベルが決定できないことを表 します。
4 文字列型 対象となるエンジンまたはリクエスタのタイプを示 すコード。NWSV は Scalable SQL for Netware (Server Edition) を表し、RQST は Scalable SQL Requester を 表します。また、WIN3 は Scalable SQL for Windows を表します。
付 録 Ａ バージョン情報の取得
表 A-5 で説明した入力のためのバッファを設定した後、 SQLGetConnect Option を呼出します。指定したバージョン情報がバッファに返されます。
エラー
内部呼出しに失敗すると、SQLGetConnectOption はエラーを返します。
Option 1002: カレントセッション ID を識別する
通常、ODBC を使用するときには、セッション ID は必要ありません。し かし、バージョン情報を取得するオプションの中には、セッション ID を 必要とするものがあります。
パラメータの概要
表 A-6 には、カレントセッション ID を取得するときの SQLGetConnectOption
関数のパラメータをまとめてあります。
表 A-6
Option 1002 に対する SQLGetConnectOption のパラメータ
パラメータ 説明 値渡し 参照渡し
hdbc SQLAllocConnect の戻り値 ◆
fOption 定数値 (1002) ◆
vParam セッション ID をコピーする short integer のアドレス。呼出し時にコンパイラから警 告が出されるのを避けるため、このアドレ スは UDWORD 型にキャストします。
◆
セッションIDの取得
vParam パラメータとして short integer のアドレスを渡して、SQLGetConnect Option を呼出します。セッション ID がバッファに返されます (セッショ ンが確立されている場合)。
エラー
セッションが確立されていない (Scalable SQL または Btrieve データソー スへの接続が行われていない) 場合、SQLGetConnectOption はエラーを返 します。