フィールドへのアクセスおよびフィールドの変更を行う関数

Fadd

Fadd は、フィールド化バッファに新しいフィールド値を追加します。

int
Fadd(FBFR *fbfr, FLDID fieldid, char *value, FLDLEN len)

以下はパラメータの説明です。

Fadd には、フィールド値に対するポインタを指定し、フィールド値自体は指定しません。これは、フィールド値を取得したり、フィールド値を返すその他の関数でも同じです。

フィールド長が固定されているフィールド型 (short 型、long 型、char 型、float 型、double 型)、またはフィールド長を指定できるフィールド型 (string 型) の場合、フィールド長を指定する必要はありません。フィールド長は無視されます。フィールド型が文字配列の場合は、フィールド長を指定する必要があります。フィールド長は FLDLEN 型で定義されます。たとえば、次のコードは、目的のフィールドのフィールド識別子を取得し、フィールド値をバッファに追加します。

FLDID fieldid, Fldid;
FBFR *fbfr;
. . .
fieldid = Fldid("fieldname");
if(Fadd(fbfr, fieldid, "new value", (FLDLEN)9) < 0)
          F_error("pgm_name");

デフォルトでは、文字配列型がネイティブなフィールド型と見なされます。したがって、関数には値の長さを渡す必要があります。追加する値が文字列配列以外の場合、value の型は、ポインタが指す値の型に応じて変わります。たとえば、次のコードは、long 型のフィールド値を追加します。

long lval;
. . .
lval = 123456789;
if(Fadd(fbfr, fieldid, &lval, (FLDLEN)0) < 0)
          F_error("pgm_name");

文字配列フィールドの場合、NULL フィールドは、長さ 0 で表します。文字列フィールドでは、フィールド値の一部として NULL 終了バイトが格納されるので、NULL 文字列を格納できます。つまり、NULL 終了バイトだけで構成される文字列は、長さ 1 であると見なされます。これ以外の型 (固定長の型) では、アプリケーション・プログラムで NULL と解釈される特殊な値を使用できますが、値のサイズは、実際に渡される値とは関係なく、フィールド型で指定されます (たとえば、long 型の場合は長さ 4)。NULL 値のアドレスを渡すとエラー (FEINVAL) が発生します。

埋め込み型の VIEW32 バッファの場合、Fadd32 は FVIEWFLD 型の構造体に対するポインタを格納します。FVIEWFLD 型の構造体には、vflags (現在未使用で 0 に設定されているフラグ・フィールド)、vname (VIEW 名を含む文字配列)、および data (C 構造体として格納される VIEW データに対するポインタ) が含まれています。アプリケーションは、Fadd32 に vname と data を提供します。FVIEWFLD 構造体は、次のとおりです。

typedef struct {
     TM32U vflags;                /* フラグ - 現在未使用 */
     char vname[FVIEWNAMESIZE+1]; /* VIEW の名前 */
     char *data;                  /* VIEW 構造体に対するポインタ */
} FVIEWFLD;

Fappend

Fappend は、フィールド化バッファに新しいフィールド値を付加します。

int
Fappend(FBFR *fbfr, FLDID fieldid, char *value, FLDLEN len)

以下はパラメータの説明です。

Fappend は、value で定義された値を指定した、新しい fieldid のフィールド・オカレンスを付加し、バッファを付加モードにします。付加モードでは、同じフィールド・セットを含む多数の行で構成された、サイズの大きいバッファが最適化されます。

次の例では、Fappend を使用して、各行に 5 つのフィールドがある 500 行のバッファを作成します。

for (i=0; i 500 ;i++) {
   if ((Fappend(fbfr, LONGFLD1, &lval1[i], (FLDLEN)0) < 0) ||
      (Fappend(fbfr, LONGFLD2, &lval2[i], (FLDLEN)0) < 0) ||
      (Fappend(fbfr, STRFLD1, &str1[i], (FLDLEN)0) < 0) ||
      (Fappend(fbfr, STRFLD2, &str2[i], (FLDLEN)0) < 0) ||
      (Fappend(fbfr, LONGFLD3, &lval3[i], (FLDLEN)0) < 0)) {
      F_error("pgm_name");
     break;
   }
}
Findex(fbfr, 0);

Fappend には、フィールド値に対するポインタを指定し、フィールド値自体は指定しません。これは、フィールド値を取得したり、フィールド値を返すその他の関数でも同じです。

フィールド長が固定されているフィールド型 (short 型、long 型、char 型、float 型、double 型)、またはフィールド長を指定できるフィールド型 (string 型) の場合、フィールド長を指定する必要ありません。フィールド長は無視されます。フィールド型が文字配列の場合は、フィールド長を指定する必要があります。フィールド長は FLDLEN 型で定義されます。

デフォルトでは、文字配列型がネイティブなフィールド型と見なされます。したがって、関数には値の長さを渡す必要があります。付加する値が文字列配列以外の場合、value の型は、ポインタが指す値の型に応じて変わります。

文字配列フィールドの場合、NULL フィールドは、長さ 0 で表します。文字列フィールドでは、フィールド値の一部として NULL 終了バイトが格納されるので、NULL 文字列を格納できます。つまり、NULL 終了バイトだけで構成される文字列は、長さ 1 であると見なされます。これ以外の型 (固定長の型) では、アプリケーション・プログラムで NULL と解釈される特殊な値を使用できますが、値のサイズは、実際に渡される値とは関係なく、フィールド型で指定されます (たとえば、long 型の場合は長さ 4)。NULL 値のアドレスを渡すとエラー (FEINVAL) が発生します。

Fchg

Fchg は、バッファ内のフィールド値を変更します。

int
Fchg(FBFR *fbfr, FLDID fieldid, FLDOCC oc, char *value, FLDLEN len)

以下はパラメータの説明です。

たとえば、次のコードは、carray 型のフィールドを value に格納された新しい値に変更します。

FBFR *fbfr;
FLDID fieldid;
FLDOCC oc;
FLDLEN len;
char value[50];
. . .
strcpy(value, "new value");
flen = strlen(value);
if(Fchg(fbfr, fieldid, oc, value, len) < 0)
       F_error("pgm_name");

oc が -1 の場合、フィールド値が新しいオカレンスとしてバッファに追加されます。oc が 0 以上であり、フィールドが見つかった場合、フィールド値は指定された新しい値に変更されます。oc が 0 以上であり、フィールドがない場合は、指定されたオカレンスとして値を追加できるまで、NULL オカレンスがバッファに追加されます。たとえば、バッファ上に存在しないフィールドのフィールド・オカレンス 3 を変更しようとすると、3 つの NULL オカレンス (オカレンス 0、 1 および 2) が追加され、続いて、フィールド値が指定されたオカレンス 3 が追加されます。NULL 値については、文字列型と文字型の値の場合は NULL 文字列 「\0」(長さ 1 バイト)、long 型と short 型のフィールドの場合は 0、float 型と double 型の値の場合は 0.0、文字配列の場合は 0 長の文字列が使用されます。

新しい値または変更された値は、value に格納されます。文字配列の場合、長さは len で指定されます。その他のフィールド型では、len は無視されます。値のポインタが NULL であり、フィールドが見つかった場合、そのフィールドは削除されます。削除対象のフィールド・オカレンスが見つからないと、エラー (FNOTPRES) と見なされます。

typedef struct {
     TM32U vflags;                /* フラグ - 現在未使用 */
     char vname[FVIEWNAMESIZE+1]; /* VIEW の名前 */
     char *data;                  /* VIEW 構造体に対するポインタ */
} FVIEWFLD;

バッファには、変更または追加されたフィールド値を格納できる領域が必要です。空き領域不足の場合、エラー (FNOSPACE) が返されます。

Fcmp

Fcmp は、2 つのフィールド化バッファのフィールド識別子とフィールド値を比較します。

int
Fcmp(FBFR *fbfr1, FBFR *fbfr2)

fbfr1 および fbfr2 は、フィールド化バッファに対するポインタです。

この関数は、2 つのバッファが同一の場合は 0 を返し、以下の条件のいずれかが成立する場合は -1 を返します。

ポインタと埋め込み型のバッファが同一かどうかは、以下の条件によって決まります。

Fcmp は、上記のいずれかの条件の逆が true である場合に 1 を返します。たとえば、fbfr2 フィールドのフィールド識別子が fbfr1 フィールドの対応するフィールド識別子より小さい場合、Fcmp は 1 を返します。

Fdel

Fdel は、指定されたフィールド・オカレンスを削除します。

int
Fdel(FBFR *fbfr, FLDID fieldid, FLDOCC oc)

以下はパラメータの説明です。

たとえば、次のコードは、指定されたフィールド識別子が示すフィールドの最初のオカレンスを削除します。

FLDOCC occurrence;
. . .
occurrence=0;
if(Fdel(fbfr, fieldid, occurrence) < 0)
            F_error("pgm_name");

指定されたフィールドが存在しない場合は -1 が返され、Ferror が FNOTPRES に設定されます。

ポインタ・フィールドの場合、Fdel32 は、参照されるバッファを変更したり、ポインタを解放しないで、FLD_PTR フィールド・オカレンスを削除します。データ・バッファは、オペークなポインタとして扱われます。

Fdelall

Fdelall は、指定されたフィールドのすべてのオカレンスをバッファから削除します。

int
Fdelall(FBFR *fbfr, FLDID fieldid)

以下はパラメータの説明です。

次の例を参照してください。

if(Fdelall(fbfr, fieldid) < 0)
     F_error("pgm_name");        /* フィールドが存在しない */

フィールドが見つからないと、-1 が返され、Ferror が FNOTPRES に設定されます。

ポインタ・フィールドの場合、Fdelall32 は、参照されるバッファを変更したり、ポインタを解放しないで、FLD_PTR フィールド・オカレンスを削除します。データ・バッファは、オペークなポインタとして扱われます。

Fdelete

Fdelete は、フィールド識別子の配列 (fieldid[]) にリストされているすべてのフィールドのすべてのオカレンスを削除します。

int
Fdelete(FBFR *fbfr, FLDID *fieldid)

以下はパラメータの説明です。

更新は、フィールド化バッファに対して直接行われます。フィールド識別子の配列内のエントリを特定の順序で並べる必要はありませんが、配列の最後のエントリは、フィールド識別子 0 (BADFLDID) でなければなりません。次の例を参照してください。

#include "fldtbl.h"
FBFR *dest;
FLDID fieldid[20];
. . .
fieldid[0] = A;   /* フィールドＡのためのフィールド識別子 */
fieldid[1] = D;   /* フィールドＤのためのフィールド識別子 */
fieldid[2] = BADFLDID;   /* 標識値 */
if(Fdelete(dest, fieldid) < 0)
         F_error("pgm_name");

宛先バッファに、A、B、C、D という 4 つのフィールドがある場合、上記の例では、フィールド B およびフィールド C のオカレンスのみを含むバッファが生成されます。

Fdelete を使用すると、Fdelall を数回呼び出す場合より効率的にバッファから複数のフィールドを削除できます。

ポインタ・フィールドの場合、Fdelete は、参照されるバッファを変更したり、ポインタを解放しないで、FLD_PTR フィールド・オカレンスを削除します。データ・バッファは、オペークなポインタとして扱われます。

Ffind

Ffind は、バッファ内の指定されたフィールド・オカレンスの値を検索します。

char*
Ffind(FBFR *fbfr, FLDID fieldid, FLDOCC oc, FLDLEN *len)

以下はパラメータの説明です。

上の例では、Ffind の戻り値として、文字ポインタのデータ型 (C の char*) が示されています。実際に返されるポインタの型は、ポインタが指す値の型と同じです。

次のコードは、この関数の使用方法を示します。

#include "fldtbl.h"
FBFR *fbfr;
FLDLEN len;
char* Ffind, *value;
. . .
if((value=Ffind(fbfr,ZIP,0, &len)) == NULL)
      F_error("pgm_name");

フィールドが見つかると、フィールドの長さが len 内に返され (len が NULL の場合は、長さは返されない)、フィールドの位置が関数の値として返されます。フィールドが見つからないと、NULL が返され、Ferror が FNOTPRES に設定されます。

Ffind は、フィールドに対して読み取り専用でアクセスするために使用します。Ffind からの戻り値でバッファを変更することはできません。フィールド値を変更できるのは、Fadd または Fchg 関数のみです。この関数は、埋め込み型のバッファにある指定されたフィールドのオカレンスは調べません。

Ffind からの戻り値は、バッファが変更されない限り有効です。この値は、short 型境界では確実に調整されますが、long 型または double 型の境界では、フィールド型が long 型または double 型でも、調整されない場合があります値の調整については、この章の後の説明を参照してください。変数を正しく境界に調整する必要があるプロセッサでは、正しく調整されていない値を参照すると、システム・エラーが発生します。次は、その例です。

long *l1,l2;
FLDLEN length;
char *Ffind;
. . .
if((l1=(long *)Ffind(fbfr, ZIP, 0, &length)) == NULL)
        F_error("pgm_name");
else
        l2 = *l1;

このコードは、次のように書き直さなければなりません。

if((l1==(long *)Ffind(fbfr, ZIP, 0, &length)) == NULL)
         F_error("pgm_name");
else
         memcpy(&l2,l1,sizeof(long));

Ffindlast

この関数は、フィールド化バッファ内のフィールドの最後のオカレンスを検索し、そのフィールドに対するポインタと、最後のフィールド・オカレンスのオカレンス番号と長さを返します。

char*
Ffindlast(FBFR *fbfr, FLDID fieldid, FLDOCC *oc, FLDLEN *len)

以下はパラメータの説明です。

上の例では、Ffindlast の戻り値として、文字ポインタのデータ型 (C の char*) が示されています。実際に返されるポインタの型は、ポインタが指す値の型と同じです。

Ffindlast が返す値は、バッファが変更されない限り有効です。

Ffindocc

Ffindocc は、バッファ内の指定したフィールドのオカレンスを調べ、ユーザ指定のフィールド値と一致する最初のフィールド・オカレンスのオカレンス番号を返します。

FLDOCC
Ffindocc(FBFR *fbfr, FLDID fieldid, char *value, FLDLEN len;)

以下はパラメータの説明です。

たとえば、次のコードは、oc を、指定された郵便番号のオカレンスに設定します。

#include "fldtbl.h"
FBFR *fbfr;
FLDOCC oc;
long zipvalue;
. . .
zipvalue = 123456;
if((oc=Ffindocc(fbfr,ZIP,&zipvalue, 0)) < 0)
       F_error("pgm_name");

文字列フィールドでは、正規表現がサポートされています。たとえば、次のコードは、oc を「J」で始まる NAME のオカレンスに設定します。

#include "fldtbl.h"
FBFR *fbfr;
FLDOCC oc;
char *name;
. . .
name = "J.*"
if ((oc = Ffindocc(fbfr, NAME, name, 1)) < 0)
        F_error("pgm_name");

注記 ただし、文字列上でのパターン照合を可能にするには、Ffindocc の 4 番目の引数を 0 以外にする必要があります。この引数が 0 の場合、単純な文字列比較が実行されます。フィールド値が見つからない場合は、-1 が返されます。

上位互換性のため、接頭辞としてアクセント記号 (^) 、また接尾辞としてドル記号 ($) が正規表現に暗黙的に追加されます。したがって、前の例にある正規表現は、実際には「^(J.*)$」として解釈されます。正規表現は、フィールド内の文字列値全体と一致しなければなりません。

Fget

Fget は、値が変更されたときに、フィールド化バッファのフィールドを検索するために使用されます。

int
Fget(FBFR *fbfr, FLDID fieldid, FLDOCC oc, char *loc, FLDLEN *maxlen)

以下はパラメータの説明です。

呼び出し側プログラムは、Fgetにプライベート・バッファに対するポインタとプライベート・バッファの長さを提供します。maxlen を NULL として指定すると、宛先バッファはフィールド値を格納できるだけのサイズを持つと想定され、バッファの長さは返されません。

Fget は、目的のフィールドがバッファにない場合 (FNOTPRES) または宛先バッファが小さすぎる場合 (FNOSPACE) にはエラーを返します。たとえば、次のコードは、郵便番号が文字配列または文字列として格納されている場合は、その郵便番号を検索します。

FLDLEN len;
char value[100];
. . .
len=sizeof(value);
if(Fget(fbfr, ZIP, 0, value, &len) < 0)
          F_error("pgm_name");

郵便番号が long 型として格納されている場合は、次のコードで郵便番号を取得できます。

FLDLEN len;
long value;
. . .
len = sizeof(value);
if(Fget(fbfr, ZIP, 0, value, &len) < 0)
          F_error("pgm_name");

Fgetalloc

char*
Fgetalloc(FBFR *fbfr, FLDID fieldid, FLDOCC oc, FLDLEN *extralen)

以下はパラメータの説明です。

上記の例では、Fgetalloc の戻り値として、文字ポインタのデータ型 (C の char*) が示されています。実際に返されるポインタの型は、ポインタが指す値の型と同じです。

Fgetalloc が成功すると、正しく境界に調整されたバッファ・フィールドのコピーに対する有効なポインタが返されます。失敗すると、NULL が返されます。malloc(3) が失敗すると、Fgetalloc からエラーが返され、Ferror が FMALLOC に設定されます。

Fgetalloc の最後のパラメータには、予備の領域を指定します。たとえば、空き領域が不足した場合に、フィールド化バッファに値を再度指定する代わりに、取得済みの領域を拡張する場合に取得する領域です。成功すると、割り当てられたバッファの長さが extralen に返されます。次の例を参照してください。

FLDLEN extralen;
FBFR *fieldbfr
char *Fgetalloc;
. . .
extralen = 0;
if (fieldbfr = (FBFR *)Fgetalloc(fbfr, ZIP, 0, &extralen) == NULL)
         F_error("pgm_name");

Fgetalloc で取得した領域を free で解放する処理は、呼び出し側プログラムの役割です。

Fgetlast

Fgetlast は、値の変更時にフィールド化バッファからフィールドの最後のオカレンスを検索するために使用します。

int
Fgetlast(FBFR *fbfr, FLDID fieldid, FLDOCC *oc, char *loc, FLDLEN *maxlen)

以下はパラメータの説明です。

呼び出し側プログラムは、Fgetlast にプライベート・バッファに対するポインタとブライペート・バッファの長さを提供します。Fgetlast は、Fget と同様に動作します。ただし、フィールド・オカレンスを指定する必要はなく、関数の戻り値として、最後のフィールド・オカレンスのオカレンス番号と値が返されます。ただし、occ に NULL を指定して関数を呼び出すと、オカレンス番号は返されません。

Fnext

Fnext は、指定されたフィールド・オカレンスの次のバッファ・フィールドを検索します。

int
Fnext(FBFR *fbfr, FLDID *fieldid, FLDOCC *oc, char *value, FLDLEN *len)

以下はパラメータの説明です。

バッファ内の最初のフィールドを取得するには、fieldid に FIRSTFLDID を代入します。フィールド識別子と最初のフィールド・オカレンスのオカレンス番号が対応するパラメータ内に返されます。フィールドが NULL でない場合は、フィールド値が value ポインタでアドレス指定されたメモリ位置にコピーされます。

len パラメータを使用すると、フィールド値を格納できるだけの領域が value に割り当てられているかどうかを判別できます。十分な領域が割り当てられていない場合は、Ferror が FNOSPACE に設定されます。値の長さが len パラメータ内に返されます。ただし、フィールドの値が NULL でない場合、len パラメータは、value に現在割り当てられている領域の長さも含んでいると見なします。

取り出されるフィールドが埋め込み型の VIEW32 バッファのときは、value パラメータは FVIEWFLD 構造体を指します。Fnext 関数は、構造体の vname フィールドと data フィールドを設定します。FVIEWFLD 構造体は、次のとおりです。

typedef struct {
     TM32U vflags;                /* フラグ - 現在未使用 */
     char vname[FVIEWNAMESIZE+1]; /* VIEW の名前 */
     char *data;                  /* VIEW 構造体に対するポインタ */
} FVIEWFLD;

フィールド値が NULL の場合は、value パラメータと length パラメータは変更されません。

フィールドがそれ以上見つからない場合は、Fnext は 0 を返し (バッファの終わり)、fieldid、occurrence、value は変更されません。

value パラメータが NULL でない場合は、length パラメータも NULL でないと想定されます。

以下の例は、バッファ内のすべてのフィールド・オカレンスを読み取ります。

FLDID fieldid;
FLDOCC occurrence;
char *value[100];
FLDLEN len;
. . .
for(fieldid=FIRSTFLDID,len=sizeof(value);
     Fnext(fbfr,&fieldid,&occurrence,value,&len) > 0;
     len=sizeof(value)) {
   /* 各フィールド・オカレンス用のコード */
}

Fnum

Fnum は、指定されたバッファに含まれているフィールド数を返します。エラーの場合は -1 を返します。

FLDOCC
Fnum(FBFR *fbfr)

fbfr は、フィールド化バッファに対するポインタです。たとえば、次のコードは、指定されたバッファ内のフィールド数を出力します。

if((cnt=Fnum(fbfr)) < 0)
  F_error("pgm_name");
else
  fprintf(stdout,"%d fields in buffer\n",cnt);

FLD_FML32 および FLD_VIEW32 フィールドは、格納するフィールド数に関係なく、単一フィールドとしてカウントされます。

Foccur

Foccur は、バッファ内の指定されたフィールドのオカレンス数を返します。

FLDOCC
Foccur(FBFR *fbfr, FLDID fieldid)

以下はパラメータの説明です。

埋め込み型の FML32 バッファ内でのフィールドのオカレンスはカウントされません。

フィールド・オカレンスがバッファ内にない場合は 0 が返され、エラーの場合は -1 が返されます。たとえば、次のコードは、指定されたバッファ内のフィールド ZIP のオカレンス数を出力します。

FLDOCC cnt;
. . .
if((cnt=Foccur(fbfr,ZIP)) < 0)
 F_error("pgm_name");
else
 fprintf(stdout,"Field ZIP occurs %d times in buffer\n",cnt);

Fpres

Fpres は、指定されたフィールド・オカレンスが存在する場合は true (1) を返し、存在しない場合は false (0) を返します。

int
Fpres(FBFR *fbfr, FLDID fieldid, FLDOCC oc)

以下はパラメータの説明です。

たとえば、次のコードは、fbfr が指すフィールド化バッファ内にフィールド ZIP が存在する場合、true を返します。

Fpres(fbfr,ZIP,0)

Fpres は、埋め込み型のバッファにある指定されたフィールドのオカレンスは確認しません。

Fvals および Fvall

char* 
Fvals(FBFR *fbfr,FLDID fieldid,FLDOCC oc)

char*
Fvall(FBFR *fbfr,FLDID fieldid,FLDOCC oc)

2 つの関数に共通するパラメータは、以下のとおりです。

Fvalsの場合、指定されたフィールド・オカレンスが見つからないと、NULL 文字列 \0 を返します。この関数は、戻り値をチェックせずにフィールドの値を別の関数に渡すのに役立ちます。ただし、この関数は、string 型のフィールドの場合のみ有効であり、ほかのフィールド型の場合は、自動的に NULL 文字列を返します (つまり、変換は行われません)。

Fvall の場合、指定されたフィールド・オカレンスが見つからないと、0 を返します。この関数は、戻り値をチェックせずにフィールドの値を別の関数に渡すのに役立ちます。ただし、この関数は、long 型と short 型のフィールドの場合のみ有効であり、ほかのフィールド型の場合は、自動的に 0 を返します (つまり、変換は行われません)。