Btrieve API Guide (v11)

Stat Extended(65)(Btrieve API)

Stat Extended オペレーション(B_EXTENDED_STAT)にはいくつかのサブファンクションがあります。これを使って、アプリケーションは開いているファイルについての情報を収集することができます。

表 29 Stat Extended(65) のサブファンクション
サブファンクション ID
説明
1
エクステンション ファイル名の一覧表示
2
ファイルのシステム データ情報
3
重複による競合レコードおよびキーの識別
4
ファイル情報
5
ゲートウェイの識別
6
ロック オーナーの識別
7
セキュリティ情報
8
ステータス コード 71(参照整合性の定義に違反があります)の発生原因となる、テーブル名またはファイル名の一覧表示

パラメーター

 
オペレーション コード
ポジション ブロック
データ バッファー
データ バッファー長
キー バッファー
キー番号
送り値

 

戻り値
 

 
 

前提条件

対象となるファイルが開いていることが必要です。

手順

  1. オペレーション コードに 65 を設定します。
  2. ファイルのポジション ブロックを渡します。
  3. データ バッファーに拡張 Stat 構造体を格納します。各サブファンクションで必要な拡張 Stat 構造体の詳細については、以降のセクションを参照してください。
  4. データ バッファー長を指定します。
  5. キー番号に 0 を設定します。

サブファンクション 1:拡張ファイル情報

入力ポジション ブロックで指定されたファイルの場合、このサブファンクションは、指定データ ファイルと関連付けられたエクステンション ファイルについての情報を返します。返される情報には、存在するエクステンション ファイルの数、関数によって返された番号、および返されたファイルの名前が含まれます。

入力データ バッファー構造体

エクステンション ファイルに関する情報を取得するには、データ バッファーに拡張ファイル ディスクリプターを次のとおりに作成する必要があります。

表 30 拡張ファイル ディスクリプター
要素
長さ(バイト単位)
説明
識別バイト
4
Stat Extended 呼び出しのタイプ。Extended Stat 呼び出しを示す 0x45、0x78、0x53、0x74 の 4 バイトを指定します。これらは ASCII の ExSt、または Intel 型、LoHi およびリトル エンディアン方式のハードウェアの値 0x74537845 に相当します。
サブファンクション
4
Stat Extended 呼び出しのタイプ。0x00000001 を指定します。
名前空間
4
ファイルの命名規則。0x00000000 を指定します。
ファイルの最大数
4
返されるファイル名の最大数。この値には、拡張ファイルを構成するエクステンション ファイルの数を超える値を設定できます(拡張ファイルには最大 32 個のエクステンション ファイルが含まれます)。
先頭ファイルのシーケンス
4
返される先頭のファイル名のシーケンス番号。ベース ファイルから始めるには 0 を指定し、先頭のエクステンション ファイルから始めるには 1 を指定します(以下同様)。エクステンション ファイルの数を超える値を指定すると、トランザクショナル インターフェイスからステータス コード 0 が返されますが、ファイル名は何も返されません。
バッファー スペース
n
戻りデータ用に余分な空き領域を確保することができます。ステータス コード 22 が返された場合は、もっと大きなデータ バッファー サイズを指定してオペレーションを再試行してください。

出力データ バッファー構造体

拡張ファイル サブファンクションの場合、トランザクショナル インターフェイスではデータ バッファー長パラメーターの値が更新され、表 31 で説明されているような拡張ファイル構造体がデータ バッファーに返されます。

表 31 拡張ファイルの戻りバッファー
要素
長さ(バイト単位)
説明
ファイル数
4
拡張ファイルを構成するオペレーティング システム ファイルの数。
エクステンション ファイル数
4
返されたエクステンション ファイルの数。
ファイル名部分(返された各ファイル名について繰り返される)
ファイル名の長さ
4
エクステンション ファイル名の長さ。
ファイル名
n
エクステンション ファイル名。

サブファンクション 2:システム データ情報

入力ポジション ブロックで指定されたファイルの場合、このサブファンクションは、ファイルに定義されたシステム キーがあるかどうか、また、そのファイルはログ可能(トランザクション一貫性保守が可能)であるかどうかに関する情報を返します。

入力データ バッファー構造体

ファイルでのシステム データの使用に関する情報を取得するには、データ バッファーにシステム データ ディスクリプターを次のとおりに作成する必要があります。

表 32 システム データ ディスクリプター
要素
長さ(バイト単位)
説明
識別バイト
4
Extended Stat 呼び出しのための一意な識別子。ExSt を指定します。表 30 を参照してください。
サブファンクション
4
Stat Extended 呼び出しのタイプ。0x00000002 を指定します。

出力データ バッファー構造体

システム データ サブファンクションの場合、トランザクショナル インターフェイスでは次のようなシステム データ構造体がデータ バッファーに返されます。

表 33 システム データの戻りバッファー
要素
長さ(バイト単位)
説明
システム データを持つ
1
ファイルのレコードにシステム定義のログ キー(システム データとも言います)が含まれているかどうかを示します。1 = Yes、0 = No。
ログ キーを持つ
1
システム定義のログ キーが現在使用されているか、それとも削除されているかどうかを示します。1 = Yes、0 = No(削除された)。
ログ可能
1
トランザクション一貫性保守を実現するために使用できる重複のないキーがファイルにあるかどうかを示します。このキーは、ユーザー定義の重複のないキーか、システム定義のログ キーのいずれかになります。1 = Yes、0 = No。
ログ キー番号
1
トランザクショナル インターフェイスでトランザクション ログ キーとして現在使用されているキー番号。システム定義のログ キーがトランザクション ログ キーとして使用されている場合、この値は 125 になります。
システム データのサイズ
2
システム定義のログ キーのサイズで、8 になります。
システム データのバージョン
2
データベース エンジンのメジャー バージョンを含んでいる 2 バイト フィールド。たとえば、バージョン 9.x ならば 0x0009、バージョン 10.x ならば 0x000a となります。

サブファンクション 3:重複レコードによる競合情報

入力ポジション ブロックで指定されたファイルの場合、このサブファンクションは、指定データ ファイルと関連付けられたエクステンション ファイルについての情報を返します。返される情報には、直前の失敗した挿入または更新操作でステータス コード 5(重複キー)の発生原因となった、レコード アドレスおよびキー番号が含まれます。

入力データ バッファー構造体

一番最近ステータス コード 5(重複キー)を発生させたレコード アドレスおよびキー番号に関する情報を取得するには、データ バッファーに重複レコード情報ディスクリプターを次のとおりに作成する必要があります。

表 34 重複レコードによる競合ディスクリプター
要素
長さ(バイト単位)
説明
識別バイト
4
Extended Stat 呼び出しのための一意な識別子。ExSt を指定します。表 30 を参照してください。
サブファンクション
4
Stat Extended 呼び出しのタイプ。0x00000003 を指定します。

出力データ バッファー構造体

システム データ サブファンクションの場合、トランザクショナル インターフェイスでは次のようなシステム データ構造体がデータ バッファーに返されます。

表 35 重複レコードによる競合の戻りバッファー
要素
長さ(バイト単位)
説明
重複レコード アドレス
4
重複するキー値を含んでいるレコードの物理アドレス。
キー番号
4
重複する値を含んでいるキーのキー番号。

サブファンクション 4: ファイル情報

入力ポジション ブロックで指定されたファイルの場合、このサブファンクションは、指定データ ファイルと関連付けられたエクステンション ファイルについての情報を返します。返される情報には次のものが含まれます。トランザクショナル インターフェイスがファイルの識別に使用する内部ファイル ID、現在開いているファイル ハンドル数、ファイルが前回開かれたときのタイムスタンプ、およびファイル プロパティを示すさまざまなフラグがあります。

入力データ バッファー構造体

開いているファイルに関する情報を取得するには、データ バッファーにファイル情報ディスクリプターを次のとおりに作成する必要があります。

表 36 ファイル情報ディスクリプター - 開いているファイル
要素
長さ(バイト単位)
説明
識別バイト
4
Extended Stat 呼び出しのための一意な識別子。ExSt を指定します。表 30 を参照してください。
サブファンクション
4
Stat Extended 呼び出しのタイプ。0x00000004 を指定します。
バッファー スペース
12
戻り情報に必要な追加バイト。出力データ バッファー構造体を参照してください。ファイル情報サブファンクションの場合、トランザクショナル インターフェイスではデータ バッファーにファイル情報構造体が返されます。

出力データ バッファー構造体

ファイル情報サブファンクションの場合、トランザクショナル インターフェイスでは次のようなファイル情報構造体がデータ バッファーに返されます。

表 37 ファイル情報構造体 - 開いているファイル
要素
長さ(バイト単位)
説明
FileID
4
トランザクショナル インターフェイスがファイルを識別するために使用する重複のない番号。
NumberOfHandles
4
トランザクショナル インターフェイスがこのファイルで開いている現在のハンドル数。
OpenTimeStamp
4
トランザクショナル インターフェイスが物理ファイルを前回開いたときのシステム時間。システム時間は、世界協定時刻(UTC)を基に 1970 年 1 月 1 日の午前零時からの秒数で表されます。
FileUsageCount
4
各チェックポイントまたはシステム トランザクションごとにこの数が増加します。また使用回数は FCR にも置かれます。ここで返される数は、トランザクショナル インターフェイスのキャッシュ内で表されるファイルの使用回数です。チェックポイントを開始すると、この数が増加します。
Flags
4
さまざまな値を設定できる 4 バイトのビットマップ。設定可能な値の説明については、次の表を参照してください。将来的にはさらに多くのフラグが追加されます。

Flags フィールドに使用できる値については、次の表で説明します。

表 38 ファイル情報フラグ
名前
説明
0x00000001
明示的ロック
現在ファイル上で明示的ロックがあります。
0x00000002
クライアント トランザクション
現在ファイル上で、クライアント トランザクションが少なくとも 1 つ開いています。
0x00000004
読み取り専用
ファイルはトランザクショナル インターフェイスによって読み取り専用で開かれています。これは CD-ROM ドライブまたは読み取り専用ディレクトリです。
0x00000008
Continuous オペレーション
ファイルは現在 Continuous オペレーション モードです。
0x00000010
参照整合性
ファイルには参照整合性制約が設定されています。
0x00000020
オーナー読み取り/書き込み
ファイルには読み取り/書き込みのオーナー ネームが割り当てられています。ファイルの読み取り/書き込みにはオーナー ネームが要求されます。
0x00000040
オーナー読み取り OK
書き込みを行う場合にのみ要求されるオーナー ネームを持ちます。読み取りは、オーナー ネームなしで行うことができます。
0x00000080
不正なオーナーでのオープン
このファイルには読み取り OK のオーナー ネームが割り当てられています。ハンドルが不正なオーナー ネームで開かれました。
0x00000100
オーナー暗号化
ファイルにはオーナー ネームの暗号化フラグが設定されています。このフラグは、ファイル内のすべてのページは暗号化されており、テキスト エディターでは読み取れないことを意味します。

サブファンクション 5:ゲートウェイ情報

入力ポジション ブロックで指定されたファイルの場合、このサブファンクションは、ファイルの制御を行うゲートウェイ エンジンについての情報を返します。

入力データ バッファー構造体

指定されたファイルの処理を行うゲートウェイ エンジンに関する情報を取得するには、データ バッファーにゲートウェイ情報ディスクリプターを次のとおりに作成する必要があります。

表 39 ゲートウェイ情報ディスクリプター
要素
長さ(バイト単位)
説明
識別バイト
4
Extended Stat 呼び出しのための一意な識別子。ExSt を指定します。表 30 を参照してください。
サブファンクション
4
Stat Extended 呼び出しのタイプ。0x00000005 を指定します。
バッファー スペース
最低でも 80
戻り情報に必要な追加バイト。詳細については出力データ バッファー構造体を参照してください。

出力データ バッファー構造体

ゲートウェイ情報サブファンクションの場合、トランザクショナル インターフェイスではデータ バッファー長パラメーターが更新され、次のようなゲートウェイ情報構造体がデータ バッファーに返されます。

表 40 ファイル情報構造体 - ゲートウェイ情報
要素
長さ(バイト単位)
説明
メジャー バージョン
4
エンジンのメジャー バージョン。たとえば、バージョン 7 または 8 などです。
マイナー バージョン
4
エンジンのマイナー バージョン。たとえば、05 または 82 などです。
パッチ レベル
4
エンジンのパッチ レベル。たとえば、1、2、または 3 になります。
プラットフォーム
4
エンジンが動作しているオペレーティング システム プラットフォーム。
サーバー名
64
データベース エンジンが動作しているマシンの名前を示すヌル終端文字列。Btrieve API 呼び出しによって返されるデータ バッファー長には、サーバー名とヌル終端文字を含めた戻りデータの実際の長さが格納されます。

サブファンクション 6:ロック オーナーの識別

入力ポジション ブロックで指定されたファイルの場合、このサブファンクションは、一番最近ファイルのアクセス時にステータス コード 84 または 85 を発生させた原因に関する情報を返します。

入力データ バッファー構造体

ステータス 84 または 85 の原因に関する情報を取得するには、データ バッファーにロック オーナー情報ディスクリプターを次のとおりに作成する必要があります。

表 41 ロック オーナー情報ディスクリプター
要素
長さ(バイト単位)
説明
識別バイト
4
Extended Stat 呼び出しのための一意な識別子。ExSt を指定します。表 30 を参照してください。
サブファンクション
4
Stat Extended 呼び出しのタイプ。0x00000006 を指定します。
バッファー スペース
最低でも 96
戻り情報に必要な追加バイト。詳細についてはサブファンクション 7:セキュリティ情報を参照してください。

出力データ バッファー構造体

ロック オーナー情報サブファンクションの場合、トランザクショナル インターフェイスではデータ バッファー長パラメーターが更新され、次のようなロック オーナー情報構造体がデータ バッファーに返されます。

表 42 ロック オーナー情報の戻りバッファー
要素
長さ(バイト単位)
説明
クライアント ID
16
ブロックしているクライアントの 16 バイトのクライアント ID。
フラグ
4
発生した競合のタイプを示すフラグを含む 4 バイトのビットマップ。各フラグの値の説明については、次の表を参照してください。
トランザクション内での時間
4
ブロックしたクライアントがトランザクション中にロックするミリ秒数。これは、オペレーションを再試行するかどうかを決定するのに役立ちます。
キー番号
4
競合がキー ページ上で発生した場合、この要素はその競合に関与しているキーを示します。この情報を確認すれば、データベースの設計で予測される競合を減らすのに役立ちます。
トランザクション レベル
4
この数がゼロ以外の場合、ブロックしているクライアントは現在トランザクション中です。いくつかのページやレコードはトランザクションが完了するまでロックされるので、この情報はオペレーションを再試行するかどうかを決定するのに役立ちます。
予約済み
8
今後の使用に備えて予約されています。ブロックしているクライアントに関して有用だと思われる情報がある場合は、Pervasive Software までご連絡ください。
表示名
64
これはヌルで終了する文字列です。これは Monitor 内で各クライアントごとに表示される識別名と同じです。最低でも現在の表示名の長さの最大値である 64 バイトを使用してください。Btrieve API 呼び出しによって返されるデータ バッファー長には、表示名とヌル終端文字を含めた戻りデータの実際の長さが格納されます。

以前にブロックしていたクライアントの記録がトランザクショナル インターフェイスにない場合、出力データ バッファー長はゼロに設定されます。

フラグ フィールドに使用できる値については、次の表で説明します。

表 43 ロック オーナーのフラグ
名前
説明
0x00000001
暗黙ロック
ブロックしたクライアントは暗黙ロックを使用しています。
0x00000002
明示的ロック
ブロックしたクライアントは明示的ロックを使用しています。
0x00000010
ファイル ロック
ブロックしたクライアントはファイル ロックを使用しています。
0x00000020
ページ ロック
ブロックしたクライアントはページ ロックを使用しています。
0x00000040
レコード ロック
ブロックしたクライアントはレコード ロックを使用しています。
0x00000100
データ ページ
競合がページ ロックの場合、このフラグは競合がデータ ページで発生したことを示します。
0x00000200
キー ページ
競合がページ ロックの場合、このフラグは競合がキー ページで発生したことを示します。
0x00000400
可変ページ
競合がページ ロックの場合、このフラグは競合が可変ページで発生したことを示します。
0x00000800
同じプロセス
このフラグが設定された場合、ブロックしているクライアント ID の最初の 12 バイトと、ブロックされたクライアント(Stat Extended 呼び出しを発行したクライアント)の最初の 12 バイトが同じです。この場合、同じコンピューター上の同じプロセスからブロックした 2 つのクライアントがあることを意味します。Btrieve API 呼び出しを行うシングル スレッドのアプリケーションの場合は、このオペレーションを再試行しても役立ちません。ブロックしている動作を終了または中止する必要があります。
0x00001000
書き込みノー ウェイト
ブロックしたクライアントがバイアス 500 を使用していることを示します。
0x00002000
書き込み保持
ブロックしたクライアントが、ページへの変更を行って、そのトランザクションが終了するまでページ全体をロックしたことを示します。この状況は、変更によってキー エントリが別のページへ移動した場合に、キー ページの暗黙ロックで発生します。
0x00004000
読み取りノー ウェイト
明示的レコード ロックの場合、このフラグは、ブロックしたクライアントがロック バイアス 200 または 400 のいずれかを使用していることを示します。
0x00008000
複数読み取り
明示的レコード ロックの場合、このフラグは、ブロックしたクライアントがロック バイアス 300 または 400 のいずれかを使用していることを示します。

サブファンクション 7:セキュリティ情報

このサブファンクションは、クライアントが現在のファイルにアクセスするために、どのように認証および許可されたかについての情報を返します。セキュリティに使用されている現在のデータベースに関する情報も示します。

入力データ バッファー構造体

このハンドルが持っているどのアクセス権がどのように認証されたかについてセキュリティ情報を取得するには、データ バッファーにセキュリティ情報ディスクリプターを次のとおりに作成する必要があります。

表 44 セキュリティ情報ディスクリプター
要素
長さ(バイト単位)
説明
識別バイト
4
Stat Extended 呼び出しのタイプ。0x45785374 を指定します。(これは、ASCII の ExSt に相当します。)
識別バイト
4
Stat Extended 呼び出しのタイプ。0x00000007 を指定します。
バッファー スペース
最低でも 142
戻り情報に必要な追加バイト。詳細については「結果」を参照してください。

出力データ バッファー構造体

セキュリティ情報サブファンクションの場合、MicroKernel ではデータ バッファー長パラメーターが更新され、次のようなセキュリティ情報構造体がデータ バッファーに返されます。

表 45 セキュリティ情報の戻りバッファー
要素
長さ(バイト単位)
説明
ハンドルのフラグ
4
このハンドルのセキュリティに使用されているメソッドを示すフラグを含む 4 バイトのビットマップ。各フラグの値の説明については、次の表を参照してください。
ハンドルのフラグ
4
このクライアントの、現在のデフォルト データベースのセキュリティに使用されているメソッドを示すフラグを含む 4 バイトのビットマップ。各フラグの値の説明については、次の表を参照してください。
アクセス権
4
これらは、このハンドルを使用するクライアントに与えられているアクセス権です。各フラグの値の説明については、アクセス権の表を参照してください。
ハンドル データベース名のバッファー サイズ
2
ヌルで終わるハンドル データベース名文字列の格納に使用されるバッファーの長さ。
ハンドル テーブル名のバッファー サイズ
2
ヌルで終わるハンドル テーブル名文字列の格納に使用されるバッファーの長さ。メモ:テーブル名は、ファイルがデータベースにバインドされない限りわかりません(たとえば参照制約)。つまり、ファイルは、ファイルのテーブル名で参照される URI 接続文字列を使用して開かれています。URI 接続文字列の詳細については、『Pervasive PSQL Programmer's Guide』の「データベース URI」 を参照してください。
ハンドル ユーザー名のバッファー サイズ
2
ヌルで終わるハンドル ユーザー名文字列の格納に使用されるバッファーの長さ。
現在のデータベース名のバッファー サイズ
2
ヌルで終わる現在のデータベース名文字列の格納に使用されるバッファーの長さ。
現在のユーザー名のバッファー サイズ
2
ヌルで終わる現在のユーザー名文字列の格納に使用されるバッファーの長さ。
ハンドル データベース名
可変
このハンドルのセキュリティを確立するために使用されるデータベース名。
ハンドル テーブル名
可変
このハンドルと関連付けられているテーブル名。
ハンドル ユーザー名
可変
このハンドルのセキュリティを確立するために使用されるユーザー名。
現在のデータベース名
可変
このクライアントの、現在のデフォルトのデータベース名。
現在のユーザー名
可変
このクライアントの、現在のデフォルト データベースに関連付けられているユーザー名。

2 つの Flags フィールドで使用できる値については、以下の表で説明します。

表 46 セキュリティ フラグ
名前
説明
0x00000001
信頼される
このハンドルは信頼されています。割り当てられたデータベースはありません。
0x00000002
暗黙
データベース ログインは暗黙です - 開いている間。
0x00000004
明示的
データベース ログインは明示的です - Btrieve Login が実行されました。
0x00000008
データベースによる認証
認証はデータベース セキュリティによって行われました。このフラグが設定されていなければ、認証はオペレーティング システムのセキュリティによって行われました。
0x00000010
データベースによる許可
許可はデータベース セキュリティによって行われました。このフラグが設定されていなければ、許可はオペレーティング システムのセキュリティによって行われました。
0x00000020
Windows 名前付きパイプ
認証がオペレーティング システムによるものである場合、これはセキュリティに NT 名前付きパイプが使用されたことを示します。
0x00000040
ワークグループ
認証がオペレーティング システムによるものである場合、これはワークグループ エンジン式のセキュリティが行われたことを示します。つまり、認証も許可も行われていないということです。
0x00000080
Btpasswd
認証が Linux オペレーティング システムによるものである場合、これは etc/btpasswd ファイルが使用されたことを示します。
0x00000100
PAM
認証が Linux オペレーティング システムによるものである場合、これは PAM 認証が使用されたことを示します。
0x00000200
RTSS Complete
認証がオペレーティング システムによるものである場合、これは、"Complete" に設定された RTSS を使用して認証が行われたことを示します。
0x00000400
RTSS Preauthorized
認証がオペレーティング システムによるものである場合、これは、"Preauthorized" に設定された RTSS を使用して認証が行われたことを示します。
0x00000800
RTSS Disabled
認証がオペレーティング システムによるものである場合、これは、"Disabled" に設定された RTSS を使用して認証が行われたことを示します。

表 47 アクセス権フラグ
名前
説明
0x00000000
No Rights
データベース オブジェクトに対する権限がありません。アクセス権は与えられていません。
0x00000001
Open
ファイルを開くために与えられるアクセス権。これは、レコードの読み取りが可能であることも意味します。
0x00000002
Insert
レコードを挿入するために与えられるアクセス権。
0x00000004
Update
レコードを更新するために与えられるアクセス権。
0x00000008
Create
このファイルを作成するために与えられるアクセス権。
0x00000010
Delete
レコードを削除するために与えられるアクセス権。
0x00000020
Execute
SQL でストアド プロシージャを実行するために与えられるアクセス権。
0x00000040
Alter
SQL でこのファイルを変更するために与えられるアクセス権。
0x00000080
Refer
SQL でこのファイルを参照するために与えられるアクセス権。
0x00000100
Create View
SQL でこのファイルのビューを作成するために与えられるアクセス権。
0x00000200
Create Stored Procedure
SQL でこのファイルのストアド プロシージャを作成するために与えられるアクセス権。

結果

Stat Extended オペレーションが正常に実行されなかった場合は、トランザクショナル インターフェイスから次のステータス コードのいずれかが返されます。

3
ファイルが開いていません。
6
キー番号パラメーターが不正です。
22
データ バッファー パラメーターが短すぎます。
62
ディスクリプターが不正です。


Stat(15)

Step First(33)