情報カタログ・マネージャー プログラミングの手引きおよび解説書

API 呼び出しのための入力構造の作成

入力構造を作成するには、以下のステップに従ってください。

  1. DG2API.H を使用して長さと値を定義します。
  2. 出力構造全体のサイズを計算します。
  3. ヘッダー域を定義します。
  4. 定義域を定義します。
  5. オブジェクト域を定義します。

DG2API.H を使用して長さと値を定義する

情報カタログ・マネージャーでは、DG2API.H という名前の C 言語のヘッダー・ファイルが提供され ます。このファイルは、ユーザーが入力構造を作成したり出力構造を読んだり するために必要な多くの値の長さおよび有効な値を定義しています。 このファイルを (#include ステートメントを使用して) ユーザーの プログラムに組み込むと、特定のデータ・タイプ、構造、および関数原型 を自分で書く必要がなくなります。

DG2API.H には、図 9 に示すように、ヘッダー域と定義域 の作成に必要な構造のタイプ定義 (typedef) 宣言が含まれます。 (図 9 に示す WINDOWS とは、 Microsoft Windows 3.1 のみを意味します。)

図 9. DG2API.H: ヘッダー域と定義域の構造定義

#pragma pack(1)
/* Structure definition for the FLG header area */
  typedef   struct _FLG_HEADER_AREA {
     UCHAR        pchHIdent         [ FLG_H_IDENT_LEN      ];
     UCHAR        pchHDefLength     [ FLG_H_DEFAREA_LEN    ];
     UCHAR        pchHObjLength     [ FLG_H_OBJAREA_LEN    ];
     UCHAR        pchHObjEntryCount [ FLG_H_OBJAREAENT_LEN ];
     UCHAR        pchHCategory      [ FLG_H_CATEGORY_LEN   ];
     UCHAR        pchHObjTypeId     [ FLG_H_OBJTYPID_LEN   ];
     UCHAR        pchHReserved      [ FLG_H_RESERVED_LEN   ];
  } FLGHEADERAREA;
#ifdef WINDOWS
  typedef FLGHEADERAREA __huge *PFLGHEADERAREA;
#else
  typedef FLGHEADERAREA *PFLGHEADERAREA;
#endif
/* Structure definition for the FLG definition area */
  typedef   struct _FLG_DEFINITION_AREA {
     UCHAR        pchDPropName      [ FLG_D_PROPNM_LEN   ];
     UCHAR        pchDDataType      [ FLG_D_DATATYP_LEN  ];
     UCHAR        pchDDataLength    [ FLG_D_DATA_LEN     ];
     UCHAR        pchDTagName       [ FLG_D_PPN_LEN      ];
     UCHAR        pchDVF            [ FLG_D_VF_LEN       ];
     UCHAR        pchDUS            [ FLG_D_US_LEN       ];
     UCHAR        pchDCS            [ FLG_D_CS_LEN       ];
     UCHAR        pchDFS            [ FLG_D_FS_LEN       ];
     UCHAR        pchDReserved      [ FLG_D_RESERVED_LEN ];
  } FLGDEFINITIONAREA;
#ifdef WINDOWS
  typedef FLGDEFINITIONAREA __huge *PFLGDEFINITIONAREA;
#else
  typedef FLGDEFINITIONAREA *PFLGDEFINITIONAREA;
#endif

FLG_D または FLG_H で始まる変数は、DG2API.H で定義された構造部分の長さです。

DG2API.H ファイルで定義されているすべての定数のリストについては、付録 B, 情報カタログ・マネージャー API ヘッダー・ファイル − DG2APIHを参照してください。

定義されたこれらの構造を使用して、入力構造のヘッダー域と定義域に 必要な記憶域を定義することができます。図 10 は、DG2API.H ヘッダー・ファイルで定義されたデータ・タイプ を使用して、入力構造のヘッダー域と定義域を保管するためにあとで使用される構造を 定義する、DG2SAMP.C の一部を示しています。

図 10. DG2SAMP.C: ヘッダー域と定義域の定義

   //  This structure defines the input structure for FLGSearch.
   typedef _Packed struct SEARCH_STRUCT  {
      FLGHEADERAREA        srchHdr;
      FLGDEFINITIONAREA    srchDef;
      OBJECTAREA           Item;
   } SEARCHSTRUCT;
   typedef SEARCHSTRUCT  *PSEARCHSTRUCT;

入力構造が連続する記憶域として定義されるようにするために、図 9#pragma pack (1) 命令が使用され、図 10typedef _Packed struct 定義が使用されています。 別のプログラミング言語を使用して入力構造を作成する場合には、入力構造を 連続記憶域として定義するために類似のコマンドを出すことが必要な可能性も ありますので、ご注意ください。

入力構造全体のサイズを計算する

入力構造用の記憶域を割り振ることができるように、入力構造全体のサイズ を計算する必要があります。 この計算を行うためには、以下の値が分かっている必要があります。

DG2API.H では、ヘッダー域の長さ (FLG_HEADER_SIZE) および 1 つの定義レコード の長さ (FLG_DEFINITION_SIZE) を定義する変数が提供されます。

定義域の長さの計算

定義域の長さを計算するためには、図 11 に示すように、 各定義レコードの長さ (160) に、データを定義するために必要なレコード の数を掛けてください。

図 11. 定義域の長さの計算

 
Definition_area_length = number_of_properties × FLG_DEFINITION_SIZE

DG2API.H では、ユーザーのコードでこの計算を定義しやすくするために、 160 として定義された変数 FLG_DEFINITION_SIZE が提供されています。

ヘッダー域の定義で示されているように、ヘッダー域の定義域長フィールド を定義するためには、この値が必要です。

オブジェクト域の長さの計算

オブジェクト域の長さは、オブジェクト域に入るすべての値の長さの合計です。

ヘッダー域の定義で示されているように、ヘッダー域の オブジェクト域長フィールドを定義するためには、この値が必要です。

オブジェクト域を必要としたり予期したりしない API 呼び出し用 の入力構造を作成する場合には、オブジェクト域の値はゼロ (00000000) になります。

オブジェクト域の長さを正確に計算するには、オブジェクト域のすべての値の 長さが分かっている必要があります。 CHAR 値と TIMESTAMP 値の場合には、定義域で定義された長さを使用してください。 ただし、LONG VARCHAR 値と VARCHAR 値の場合には、各値の長さを調べたうえで、 長さ値の一部として 8 バイトの長さフィールドを含める必要があります。 この計算のための式を図 12 に示します。

図 12. オブジェクト域の正確な長さの計算

オブジェクト域の長さ = 特性 1 の長さ +
                      特性 2 の長さ +
                      特性 3 の長さ +
                     .
                     .
                     .

VARCHAR 値と LONG VARCHAR 値を含め、特性の値すべてに可能な最長の値を 含めることができるように、オブジェクト域を定義することもできます。 この方法を使用してすべての特性について最大データ長を合計すると、 オブジェクト域に関して定義した値が割り振られた記憶域に必ず収まるようになります。 VARCHAR 特性と LONG VARCHAR 特性については、最大長さ値の一部 として 8 バイト長フィールドを含めてください。 この計算のための式は次のとおりです。

図 13. オブジェクト域の可能な最大長の計算

オブジェクト域の長さ = 特性 1 の最大長 +
                       特性 2 の最大長 +
                       特性 3 の最大長 +
                        .
                        .
                        .

ただしこの方法を使用すると、特にいくつかの特性が最大長 32700 バイト の LONG VARCHAR フィールドである場合には、多くの記憶域を消費するこ とになりますのでご注意ください。

すべての部分の合計

割り振る必要のある記憶域を判別するための式を図 14 に示します。

図 14. 入力構造に必要な記憶域の計算

構造のサイズ = FLG_HEADER_SIZE +
               定義域の長さ +
               オブジェクト域の長さ

ヘッダー域の定義

入力構造は自己定義構造であるため、ヘッダー域にはその構造のサイズと 形式を定義するいくつかの値が含まれます。 これらの値を正しく定義するには、情報の集合全体と、作成する必要のある構造 を考慮する必要があります。

ヘッダー域は 160 バイトです。 各バイト位置には値を割り当てる必要があります。値を指定しない場合には、 その位置をブランクとして定義しなければなりません。 1 バイトまたは複数バイトの位置をブランクとして定義するための方法として、 C 言語の memset 関数を使用して構造全体を FLG_BLANK または ゼロ文字だけにセットしたうえで、C 言語の memcpy 関数を使用して 別の値にセットする必要のある情報だけをコピーするやり方があります。 この方法を使用すると、DG2API.H で定義された定数が使用しやすくなります。 これは、ブランクまたはゼロの上書きだけを配慮する必要があり、 値に埋め込みを行ってデータ長を合わせる必要がないためです。

ヘッダー域の各バイトの完全な仕様については、ヘッダー域 (常に必須)で 説明されています。

各 API 呼び出しのためのヘッダー域の構文については、情報カタログ・マネージャー API 呼び出しの構文で 説明します。

ヘッダー域の値のなかには特定の API 呼び出しでは必要のないものもありますが、図 15 で示したバイト・オフセット位置が入るようにヘッダー域を定義する必要があります。

図 15. ヘッダー域


バイト・レベルでの情報カタログ・マネージャー入力構造のヘッダー域の図。

これらのバイト・オフセット位置については、表 7 で説明されています。表 10 には、ヘッダー域の定義に役立つ DG2API.H 内の定数がリストされています。

表 10. ヘッダー域のバイト・オフセット位置および DG2API.H で定義された役に立つ定数
バイト 内容 DG2API.H で定義された役に立つ定数
0-7 FLG-HEAD FLG_H_IDENT FLG-HEAD
8-15 定義域の長さ FLG_DEFINITION_SIZE 160。1 つの定義域レコードの長さ。
16-23 オブジェクト域の長さ

24-31 オブジェクト域の項目カウント

32 区分 FLG_GROUPING_OBJ FLG_ELEMENTAL_OBJ FLG_CONTACT_OBJ FLG_DICTIONARY_OBJ FLG_PROGRAM_OBJ FLG_SUPPORT_OBJ FLG_ATTACHMENT_OBJ
G
E
C
D
P
S
A

33-38 オブジェクト・タイプの ID

39-159 予約域 (常にブランク)

ヘッダー域を定義する場合、次の 3 つの値は定義域とオブジェクト域の内容 によって異なります。

定義域の定義

定義域を定義するためには、入力構造内で API 呼び出しがどのような情報を 必要とするのかが分かっている必要があります。

定義域の各レコードの長さは 160 バイトです。 各バイト位置には値を割り当てる必要があります。値を指定しない場合には、 その位置をブランクとして定義しなければなりません。 1 バイトまたは複数バイトの位置をブランクとして定義するための方法として、C 言語の memset 関数を使用して構造全体を FLG_BLANK にセットした うえで、C 言語の memcpy 関数を使用して、別の値にセットする必要 のある情報だけをコピーするやり方があります。 この方法を使用すると、DG2API.H で定義された定数が使用しやすくなります。 これは、ブランクの上書きだけを配慮する必要があり、値に埋め込みを行って データ長を合わせる必要がないためです。 値のなかには特定の API 呼び出しでは必要のないものもありますが、 定義域は図 16 で示した 160 バイト全部を 常に含まなければなりません。

図 16. 定義域内のレコード


バイト・レベルでの情報カタログ・マネージャー入力構造の定義域 における単一定義レコードの図。

これらのバイト・オフセット位置については、表 9 で説明されています。表 11 には、定義域の定義に役立つ DG2API.H 内の定数がリストされています。

表 11. 定義域のバイト・オフセット位置および DG2API.H で定義された役に立つ定数
バイト 内容 DG2API.H 内の役に立つ変数
0-79 特性名

80-109 データ・タイプ FLG_DTYPE_CHAR FLG_DTYPE_VARCHAR FLG_DTYPE_LONGVARCHAR FLG_DTYPE_TIMESTAMP
CHAR
VARCHAR
LONG VARCHAR
TIMESTAMP

110-117 データ長

118-125 特性省略名 FLG_PPN_OBJTYPID FLG_PPN_INSTIDNT FLG_PPN_INST_NAME FLG_PPN_UPDATIME FLG_PPN_UPDATEBY FLG_PPN_EXTERNAL_NAME FLG_PPN_PTNAME FLG_PPN_DPNAME FLG_PPN_CREATOR
OBJTYPID
INSTIDNT
NAME
UPDATIME
UPDATEBY
NAME
PTNAME
DPNAME
CREATOR

126 値フラグ
FLG_REQUIRED
FLG_OPTIONAL
FLG_SYSTEM


R
O
S

127 UUI 順序番号
FLG_UUI_1
FLG_UUI_2
FLG_UUI_3
FLG_UUI_4
FLG_UUI_5
FLG_BLANK


1
2
3
4
5


128 大文字小文字の区別フラグ
FLG_YES
FLG_NO


Y
N

129 ファジー探索フラグ
FLG_YES
FLG_NO


Y
N

130-159 予約域 (常にブランク)

定義域内のすべてのバイト位置の特定の意味に関する詳細については、定義域 (常に必須)を参照してください。 使用している API 呼び出しの定義に関する詳細については、情報カタログ・マネージャー API 呼び出しの構文を参照してください。

オブジェクト域の定義

オブジェクト域における値の定義方法は、定義する各特性のデータ・タイプ によって異なります。 CHAR 値と TIMESTAMP 値は固定長であるため、比較的簡単に定義することができますが、 変数値 (VARCHAR および LONG VARCHAR) の定義はそれよりも複雑になります。

TIMESTAMP 値の長さと形式は固定されています。

CHAR 値は左寄せされ、後続ブランクが埋め込まれて、定義された長さに 合わされます。たとえば、次の例のようになります。

'My example                    '

すべての値は文字データでなければなりません。 値が数値の場合には、文字データに変換する必要があります。

いかなる値にも NULL 文字を使用することはできません。 指定した値によって固定長すべてが埋まらない場合には、未記入の位置をブランク またはゼロとして定義しなければなりません。 未使用のバイト位置をブランクまたはゼロとして定義するための方法として、C 言語の memset 関数を使用して構造全体を FLG_BLANK または ゼロ文字 ('0' または 0x30) にセットしたうえで、C 言語の memcpy 関数を使用して、 別の値にセットする必要のある情報だけをコピーすることができます。 この方法を使用すると、DG2API.H で定義された定数が使用しやすくなります。 これは、ブランクの上書きだけを配慮する必要があり、値に埋め込みを行って データ長を合わせる必要がないためです。

VARCHAR 値および LONG VARCHAR 値を指定する場合には、値の前に、その 値の長さを指定するための 8 バイトを加えてください。 たとえば、"Employee records -- Southwest Region" と いう VARCHAR 値を指定するために必要な値は、次のようになります。

00000036Employee records -- Southwest Region

この値は VARCHAR 値であるため、後続ブランクで値を埋め込む必要はありません。

ヘッダー域、定義域、およびオブジェクト域の定義例

このセクションでは、DG2SAMP.C のうちの入力構造を定義する部分について説明します。

オブジェクト域の長さの計算

図 17 に示すコードは、入力構造のオブジェクト域 の長さを計算するものです。

図 17. DG2SAMP.C: オブジェクト域の長さの判別

  //--------------------------------------------
  // Build input structure for FLGSearch
  //--------------------------------------------
  printf ("Enter object instance name:\n");
  gets(pszObjInstName);                      (1)
  ulInstValLen = strlen(pszObjInstName);     (2)
  ulInstLen = (FLG_VARIABLE_DATA_LENGTH_LEN + ulInstValLen);  (3)
  convertultoa(ulInstLen, pszLength);      (4)

図 17 のコードは以下のステップによってオブジェクト域を判別します。

(1)
pszObjInstName をユーザーが指定したオブジェクト・インスタンス名にセットします。

(2)
オブジェクト・インスタンス名の長さを判別します。

(3)
可変データ長フィールドの長さ (8) をオブジェクト・インスタンス名の長さに加算します。

(4)
オブジェクト域の長さの値を文字データに変換します。

ヘッダー域の定義

図 18 のコードは、DG2SAMP.C が FLGSearch のための入力構造の ヘッダー域をどのように定義するのかを示しています。 このヘッダー域には、図 19 と同じ値が入ります。

図 18. DG2SAMP.C: ヘッダー域の定義

  //--------------------------------------------
  //  Header
  //--------------------------------------------
  memset(&(SearchStruct.srchHdr), FLG_BLANK, FLG_HEADER_SIZE);  (1)
  memcpy(&SearchStruct.srchHdr.pchHIdent, FLG_H_IDENT, FLG_H_IDENT_LEN);             (2)
  memcpy(&SearchStruct.srchHdr.pchHDefLength, "00000160", FLG_H_DEFAREA_LEN);        (3)
  memcpy(&SearchStruct.srchHdr.pchHObjLength, pszLength , FLG_H_OBJAREA_LEN);        (4)
  memcpy(&SearchStruct.srchHdr.pchHObjEntryCount, "00000001", FLG_H_OBJAREAENT_LEN); (5)

図 18 に示すコードは、以下のステップに従って、C 言語を使用してヘッダー域を定義します。

(1)
ヘッダー域全体をブランクにセットします。

(2)
バイト 0-7 を識別子 (FLG_HEAD) にセットします。

(3)
定義の長さを 160 にセットします。

(4)
オブジェクト域の長さをセットします。 この長さはこのプログラムの前の部分で計算されています。

(5)
オブジェクト域の項目カウントを 1 にセットします。

図 19 は、図 18 の C 言語コードによって 定義された記憶域を示しています。

図 19. 定義されたヘッダー域 - SearchStruct.srchHdr


Figure FLAA2075 not displayed.

定義域の定義

図 20 のコードは、DG2SAMP.C が FLGSearch のための入力構造の 定義域をどのように定義するのかを示しています。 この定義域には、図 21 で示した値が入ります。

図 20. DG2SAMP.C: 定義域の定義

//--------------------------------------------
// Definition area
//--------------------------------------------
memset(&(SearchStruct.srchDef), FLG_BLANK, FLG_DEFINITION_SIZE);     (1)
memcpy(&SearchStruct.srchDef.pchDPropName,
"Name                                                                      ",FLG_D_PROPNM_LEN); (2)
memcpy(&SearchStruct.srchDef.pchDDataType, "VARCHAR                 ", FLG_D_DATATYP_LEN);      (3)
memcpy(&SearchStruct.srchDef.pchDDataLength, "00000080", FLG_D_DATA_LEN);  (4)
memcpy(&SearchStruct.srchDef.pchDTagName, "NAME    ", FLG_D_PPN_LEN);      (5)
memset(SearchStruct.srchDef.pchDCS, 'N', FLG_D_CS_LEN);  (6)
memset(SearchStruct.srchDef.pchDFS, 'N', FLG_D_FS_LEN);  (7)

図 20 に示すコードは、以下のステップに従って、C 言語を使用してレコード定義域を定義します。

(1)
定義レコード全体をブランクにセットします。

(2)
特性名を名前にセットします。

(3)
データ・タイプを VARCHAR にセットします。

(4)
データ長を 80 にセットします。

(5)
特性省略名を NAME にセットします。

(6)
大文字小文字の区別フラグを N にセットします。

(7)
ファジー探索フラグを N にセットします。

図 21 は、図 20 の C 言語コードによって 定義された記憶域を示しています。

図 21. 定義された定義域 - SearchStruct.srchDef


Figure FLAA2076 not displayed.

オブジェクト域の定義

図 22 は、DG2SAMP.C が FLGSearch のための入力構造のオブジェクト域を どのように定義するのかを示しています。 このオブジェクト域には、図 23 に示す値が入ります。

図 22. DG2SAMP.C: オブジェクト域の定義

//--------------------------------------------
// Object area
//--------------------------------------------
memset(&(SearchStruct.Item), FLG_BLANK, FLG_INST_NAME_LEN + FLG_VARIABLE_DATA_LENGTH_LEN); (1)
convertultoa(ulInstValLen, pszNameLength);                           (2)
pszInstanceName=strncat(pszNameLength,pszObjInstName,ulInstValLen);     (3)
memcpy(&SearchStruct.Item.Name, pszInstanceName, ulInstLen);         (4)

図 22 に示すコードは、以下のステップに従って、C 言語を使用してオブジェクト域を定義します。

(1)
オブジェクト域をブランクにセットします。

(2)
名前値の長さを文字データに変換します。

(3)
VARCHAR 値の長さをその値に連結します。

(4)
オブジェクト域に値の長さと値を入れます。

図 23 は、図 22 の C 言語コードによって 定義された記憶域を示しています。

図 23. 定義されたオブジェクト域 - SearchStruct.Item


Figure FLAA2077 not displayed.


[ ページのトップ | 前ページ | 次ページ | 目次 | 索引 ]