flocate() - VSAM レコードの位置指定

標準

標準/拡張機能	C/C++	依存項目
Language Environment	両方

形式

#include <stdio.h>

int flocate(FILE *stream, const void *key, size_t key_len, int options);

#define _OPEN_SYS_UNLOCKED_EXT 1
#include <stdio.h>

int flocate_unlocked(FILE *stream, const void *key, size_t key_len, int options);

機能説明

stream によって指し示されるストリームに関連する VSAM ファイル位置標識を、指定された残りの引数に従って移動します。

ユーザーのネーム・スペースが侵害されるのを回避するため、この非標準関数には 2 つの名前があります。1 つの名前の接頭部には 2 つの下線文字が付き、もう 1 つの名前の接頭部には付きません。接頭部下線文字が付いていない名前は、LANGLVL(EXTENDED) を使用する場合にのみ表示されます。

この関数を使用するには、その外部エントリー・ポイント名 (2 つの下線文字で始まる名前) を使用して呼び出すか、LANGLVL(EXTENDED) を使用してコンパイルする必要があります。LANGLVL(EXTENDED) を使用すると、ヘッダー内の関連情報も表示されます。

key は、位置付けに使用されるキーを指します。

key_len は、検索キーの長さを指定します。key_len 引数値は、__KEY_FIRST と __KEY_LAST を除いて、常にゼロ以外の値でなければなりません。

KSDS、KSDS PATH、および ESDS PATH: key は、register を除く、どのストレージ・タイプのフィールドもポイントできます。これは、通常、長さが key_len の文字ストリングを指します。key_len は、データ・セットのキー長以下でなければなりません。key_len が、ファイルのキー長と等しい場合は、全キー検索が自動的に使用されます。等しくない場合は、総称検索が使用されます。総称キー検索では、検索キーがキー・フィールドの先行位置です。位置付けられるレコードは、同じ総称キーを持つレコードのうちの最初のものです。
ESDS: key は、4 バイトまたは 8 バイトの値として保管されている可能性がある相対バイト・アドレスを指します。key_len は 4 または 8 のいずれかです。
RRDS: key は、unsigned long int として保管された相対レコード番号を指します。key_len は 4 または 8 のいずれかです。

options は、表 1 で説明する位置オプションを指定します。

表 1. flocate() の位置オプション・パラメーター
__KEY_FIRST	ファイル内の最初のレコードに位置付ける。以降の読み取りは前方向に行われる。key と key_len は無視される。
__KEY_LAST	ファイル内の最後のレコードに位置付ける。以降の読み取りは逆方向順に行われる。key と key_len は無視される。レコード・モードでオープンされた VSAM ファイルにのみ適用される。
__KEY_EQ	指定されたキーを持つ最初のレコードに位置付ける。以降の読み取りは前方向に行われる。
__KEY_EQ_BWD	指定されたキーを持つ最初のレコードに位置付ける。以降の読み取りは逆方向順に行われる。このオプションを使用するには、完全キー検索が必要です。key_len は、データ・セットに対して定義されたものと同じキー長でなければなりません。レコード・モードでオープンされた VSAM ファイルにのみ適用される。
__KEY_GE	指定されたキー以上のキーを持つ最初のレコードに位置付ける。
__RBA_EQ	指定された RBA のレコードに位置付ける。以降の読み取りは前方向に行われる。代替索引パスで __RBA_EQ を使用することはできない。 RRDS にこのオプションを使用することはお勧めしません。基礎的な VSAM ユーティリティーでは、RRDS ファイル内での RBA のシークはサポートしない。flocate() 関数は、ファイルの LRECL で値を除算し、同等の __KEY_EQ を使用することにより、RBA を相対レコード番号に変換しようとする。このオプションを KSDS に使用することはお勧めしません。任意のレコードの RBA は、別のレコードの挿入、削除、または更新によって、変わっていく可能性があるからです。
__RBA_EQ_BWD	指定された RBA のレコードに位置付ける。以降の読み取りは逆方向順に行われる。代替索引パスで __RBA_EQ_BWD を使用することはできない。 RRDS にこのオプションを使用することはお勧めしません。基礎的な VSAM ユーティリティーでは、RRDS ファイル内での RBA のシークはサポートしない。flocate() 関数は、ファイルの LRECL で値を除算し、同等の __KEY_EQ_BWD を使用することにより、RBA を相対レコード番号に変換しようとする。このオプションを KSDS に使用することはお勧めしません。任意のレコードの RBA は、別のレコードの挿入、削除、または更新によって、変わっていく可能性があるからです。レコード・モードでオープンされた VSAM ファイルにのみ適用される。
_KEY_EQ_BWD	指定されたキーを持つ最初のレコードに位置付ける。以降の読み取りは逆方向順に行われる。このオプションを使用するには、完全キー検索が必要です。key_len は、データ・セットに対して定義されたものと同じキー長に設定する必要があります。レコード・モードでオープンされた VSAM ファイルにのみ適用される。

注 :

非固有キーへのパスで flocate() を使用しようとした場合、位置は、結果的に、重複キー・セットの最初の物理レコードの位置になります。
flocate() は、レコード・ロックをすべて解除します。
VSAM データ・セットへの書き込みは、先行する flocate() の呼び出しの影響を受けることはありません。
レコードが見つからなかった場合、読み取りまたは書き込みを行う前に別の位置に正常に再配置する必要があります (flocate() 関数を使用して)。ただし、例外として、ファイルが初期ロードのためにオープンされたが、そのファイルにレコードがまだまったく書き込まれていない場合は、失敗した flocate() の後の書き込みが正常に行われます。

flocate_unlocked() は、スレッド・セーフでないことを除いて、機能的に flocate() と等価です。この関数をマルチスレッドのアプリケーション内で安全に使用できるのは、 flockfile() 関数または ftrylockfile() 関数のどちらかへの呼び出しが成功した後のように、呼び出しスレッドが (FILE*) オブジェクトを所有している間に、この関数を呼び出す場合だけです。

VSAM 拡張アドレッシング機能のデータ・セットの考慮事項: flocate() は、相対バイト・アドレス (RBA) 値が位置決めに使用される場合、4 または 8 のキー長を受け入れます。キー長を 8 にする必要があるのは、VSAM 拡張アドレッシング機能のデータ・セットで作業をする場合のみです。これは、このアドレスが 4 GB を超えた場合、その数値を収容するのに十分な大きさのキーが必要となるからです。

値 4 GB-1 を flocate() のキーとして使用する場合、キー長は 8 で、使用されるデータ型のサイズが 8 バイトである必要があります (例えば、X' 00000000FFFFFFFF')。キー長が 4 の場合、flocate() はそのキーを -1(EOF) として扱います。

戻り値

正常に実行された場合、flocate() は 0 を戻します。

レコードが見つからなかったか、または位置が EOF を超えている場合は、flocate() は EOF を戻します。

例

#include <stdio.h>

int main(void)
{
   FILE *stream;
   int   vsam_rc;
   char *key = "RECORD 27";

   stream = fopen("DD:MYCLUS", "rb+,type=record");
   vsam_rc = flocate(stream, key, 9, __KEY_EQ);
⋮
}