_Rlocate() — レコードの位置指定

形式

#include <recio.h>

_RIOFB_T *_Rlocate(_RFILE *fp, void *key, int klen_rrn, int opts);

言語レベル

ILE C Extension

スレッド・セーフ

はい

ただし、スレッド間でファイル・ポインターが渡された場合、入出力フィードバック域はそれらのスレッド間で共有されます。

ジョブ CCSID インターフェース

この関数に送信される文字データは、すべてジョブの CCSID 内にあると想定されます。 この関数によって戻された文字データは、すべてジョブの CCSID 内にあります。 詳しくは、 CCSID とロケールについて を参照してください。

説明

_Rlocate() 関数は、 fp に関連し、 key、 klen_rrn 、および opts パラメーターによって指定されたファイル内のレコードに位置指定します。 _Rlocate() 関数は、__NO_LOCK が指定されていない限り、 key、 klen_rrn 、および opts パラメーターによって指定されたレコードをロックします。

_Rlocate() 関数は、 _Ropen() 関数を使用してオープンされたデータベースおよび DDM ファイルに対して有効です。 以下は、 _Rlocate() 関数の有効なパラメーターです。

key
位置決めに使用するキー・フィールドを含むストリングを指します。
klen_rrn
キーによる位置決めの場合はキーの長さ、相対レコード番号による位置決めの場合は相対レコード番号の長さを指定します。
オプション
位置指定操作に使用する位置決めオプションを指定します。 指定できるマクロは、以下のとおりです。
__DFT
デフォルトは __KEY_EQ に設定され、 ファイルが更新用にオープンしている場合には、更新のためにレコードをロックします。
__END
ファイル内の最後のレコードの直後に位置指定します。 この位置に関連したレコードはありません。
__END_FRC
ファイル内の最後のレコードの直後に位置指定します。 バッファーに入れられた変更は、すべて永続します。 この位置に関連したレコードはありません。
__FIRST
現在 fp で使用されているアクセス・パス内の最初のレコードに位置指定します。 key パラメーターは無視されます。
__KEY_EQ
指定されたキーを持つ最初のレコードに位置指定します。
__KEY_GE
指定されたキー以上のキーを持つ最初のレコードに位置指定します。
__KEY_GT
指定されたキーより大きいキーを持つ最初のレコードに位置指定します。
__KEY_LE
指定されたキー以下のキーを持つ最初のレコードに位置指定します。
__KEY_LT
指定されたキーより小さいキーを持つ最初のレコードに位置指定します。
__KEY_NEXTEQ
現在位置で、長さが klen_rrn のキー値に等しいキーを持つ次のレコードに位置指定します。 key パラメーターは無視されます。
__KEY_NEXTUNQ
アクセス・パス内の現在位置から、ユニーク・キーを持つ次のレコードに位置指定します。 key パラメーターは無視されます。
__KEY_PREVEQ
現在位置で、長さが klen_rrn のキー値に等しいキーを持つ以前のレコードに位置指定します。 key パラメーターは無視されます。
__KEY_PREVUNQ
アクセス・パス内の現在位置から、ユニーク・キーを持つ以前のレコードに位置指定します。 key パラメーターは無視されます。
__LAST
現在 fp で使用されているアクセス・パス内の最後のレコードに位置指定します。 key パラメーターは無視されます。
__NEXT
現在 fp で使用されているアクセス・パス内の次のレコードに位置指定します。 key パラメーターは無視されます。
__PREVIOUS
現在 fp で使用されているアクセス・パス内の以前のレコードに位置指定します。 key パラメーターは無視されます。
__RRN_EQ
klen_rrn パラメーターで指定された相対レコード番号を持つレコードに位置指定します。
__START
ファイル内の直前の最初のレコードに位置指定します。 この位置に関連したレコードはありません。
__START_FRC
ファイル内の最初のレコードの直前のレコードに位置指定します。 この位置に関連したレコードはありません。 バッファーに入れられた変更は、すべて永続します。
__DATA_ONLY
データ・レコードのみに位置指定します。 削除されたレコードは無視されます。
__KEY_NULL_MAP
キーによってレコードに位置指定する際に、NULL キー・マップを考慮します。
__NO_LOCK
位置指定されたレコードは、ロックされません。
__NO_POSITION
ファイルの位置は変更されませんが、 ファイルが更新のためにオープンしている場合、位置指定されたレコードはロックされます。
__PRIOR
要求されたレコードの直前に位置指定します。

他のオプションとともに開始または終了オプション (__START、__START_FRC、__END または __END_FRC) を指定する場合は、 開始または終了オプションが優先し、他のオプションは無視されます。

ユーザーが __START または __END に位置指定され、_Rreads 操作を実行している場合、errno は EIOERROR に設定されます。

戻り値

_Rlocate() 関数は、fp に関連した _RIOFB_T 構造体を指すポインターを戻します。 _Rlocate() 操作が成功した場合、num_bytes フィールドには 1 が入ります。 __START、__START_FRC、_END、または __END_FRC が指定されている場合は、num_bytes フィールドが EOF に設定されます。 _Rlocate() 操作が正常終了しなかった場合、num_bytes フィールドにはゼロが含まれます。 key および rrn フィールドは更新され、 key フィールドには、部分的なキーが指定されていても完全なキーが含まれます。

errno の値は、次のいずれかに設定されます。
表 1. errno 値
値 意味
EBADKEYLN 指定されたキーの長さが無効です。
ENOTREAD ファイルは読み取り操作用にオープンされていません。
EIOERROR 回復不能入出力エラーが起こりました。
EIORECERR 回復可能入出力エラーが起こりました。
errnoの設定については、 表1 および表1を参照のこと。

例

#include <stdio.h>
#include <stdlib.h>
#include <recio.h>
 
int main(void)
{
    _RFILE   *in;
    char     new_purchase[21] = "PEAR      1002022244";
 
    /* Open the file for processing in keyed sequence.              */
 
    if ( (in = _Ropen("MYLIB/T1677RD4", "rr+, arrseq=N")) == NULL )
    {
        printf("Open failed\n");
        exit(1);
    };
 
    /* Update the first record in the keyed sequence.               */
 
    _Rlocate(in, NULL, 0, __FIRST);
    _Rupdate(in, new_purchase, 20);
 
    /* Force the end of data.                                       */
 
    _Rfeod(in);
 
    _Rclose(in);
}

関連情報