ページの先頭行へ戻る
Interstage Shunsaku Data Manager V9.0.6 アプリケーション開発ガイド
FUJITSU Software
第2部 APIでのアプリケーション開発 > 第11章 C APIのアプリケーション開発 > 11.2 C APIの使用方法 > 11.2.2 データの検索
前次

11.2.2 データの検索

C APIでは、以下に示す操作ができます。


これらの操作を組み合わせることによって、さまざまなアプリケーションを作成することができます。

参考

ダイレクトアクセスキーを使ったデータ検索も可能です。

ダイレクトアクセスキー機能の詳細については、“第6章 ダイレクトアクセス機能”を参照してください。

データを検索するサンプルプログラムは、“J.1 データの検索”を参照してください。

以降に、データの検索を行うアプリケーションの作成方法について説明します。


11.2.2.1 条件に一致するXML文書の件数を取得する

条件に一致するデータを取り出す前に、件数のみ取得したい場合があります。


このような場合、ShunGetHitCount関数の引数に条件式を指定して、件数のみを取得します。

条件に一致するXML文書の件数を取得する場合の流れについて、以下の図に示します。


図11.4 条件に一致するXML文書の件数を取得する場合の流れ


記述例 

SHUNHSTMT StmtH;
/* データ操作ハンドルの割当て */
ShunAllocHandle(ConH, &StmtH);                            (1)
/* 検索式を指定してヒット件数を取得 */
ShunGetHitCount(StmtH,                               
"/document/base/prefecture == '大阪'",
           &Hit_Cnt);                                     (2)

/* ヒット件数の取出し */
printf("ヒット件数              = %d\n", Hit_Cnt);

/* データ操作ハンドルの解放 */
ShunFreeHandle(StmtH);                                    (3)

(1) データ操作ハンドルの割当て

事前にデータ操作ハンドルを割り当てます。データ操作ハンドルは、ShunAllocHandle関数に、親ハンドルとなるコネクションハンドルを指定して割り当てます。


(2) 検索の実行

ShunGetHitCount関数のパラメタに、データ操作ハンドル、検索式を指定して検索を実行します。ヒット件数のみを返却します。


(3) データ操作ハンドルの解放

データの検索および結果の取出しが完了したら、ShunFreeHandle関数でデータ操作ハンドルを解放します。


11.2.2.2 件数に応じて検索した結果を取得する

Webアプリケーションでは、画面にすべての検索結果を表示するのではなく、任意の件数ごとにページ制御することが一般的です。


このような場合、ShunSearch関数の引数に返信開始番号と返信要求件数を指定して、取得するデータの件数を制御します。

件数に応じて検索した結果を取得する場合の流れについて、以下の図に示します。


図11.5 件数に応じて検索した結果を取得する場合の流れ


記述例 

SHUNHSTMT StmtH;
/* データ操作ハンドルの割当て */
ShunAllocHandle(ConH, &StmtH);                              (1)

/* 検索を実行 */
ShunSearch(StmtH, 11, NULL, 0, 5,                             
           "/document/base/prefecture == '大阪'",
           "/document/base/name, /document/base/price",
           NULL,
           &Hit_Cnt, &Return_Cnt, &Returnable_Cnt,
           &Rec_Id_Out, &Data,
           &First_Pos, &Last_Pos);                          (2)

/* 検索した結果の取出し */
printf("ヒット件数              = %d\n", Hit_Cnt);           (3)
if(Hit_Cnt > 0) {
  for (i = 0; i < Return_Cnt; i++) {
    printf("[結果]%d件目 = %s\n", i+1, Data[i].Data);
  }
}

/* データ操作ハンドルの解放 */
ShunFreeHandle(StmtH);                                      (4)

(1) データ操作ハンドルの割当て

事前にデータ操作ハンドルを割り当てます。データ操作ハンドルは、ShunAllocHandle関数に、親ハンドルとなるコネクションハンドルを指定して割り当てます。


(2) 検索の実行

ShunSearch関数のパラメタに、データ操作ハンドル、データの取得位置（取得開始位置または取得終了位置）、データの最大件数、検索式およびリターン式を指定して検索を実行します。

ポイント

  • ShunSearch関数では、検索条件に一致したXML文書のヒット件数も返却します。この値を利用して、検索結果のページ数などを求めることができます。

  • 返信要求件数には、1画面に表示する件数を指定します。


(3) 検索した結果の取出し

ShunSearch関数では、検索した結果のアドレスを返却します。

検索した結果は、構造体の配列で構成されていますので、これをもとにデータを取り出します。

ポイント

ShunSearch関数では、検索結果とともにXML文書を一意に識別するレコードID(コンダクタ制御情報および返信レコード識別子)を返却します。レコードIDは、対応するXML文書の全体を取り出したり、削除、更新する場合に使用します。


(4) データ操作ハンドルの解放

データの検索および結果の取出しが完了したら、ShunFreeHandle関数でデータ操作ハンドルを解放します。


11.2.2.3 条件を追加しながら検索した結果を取得する

検索した結果の件数が非常に多いとき、さらに条件を追加して件数を絞りたい場合があります。


このような場合、ShunSearch関数の引数に指定する検索式に条件を追加して新しい検索式を作成し、再度検索する処理を行います。この操作を繰り返すことで、画面に表示された検索結果を参照しながら検索結果を絞り込むことができます。

条件を追加しながら検索した結果を取得する場合の流れについて、以下の図に示します。


図11.6 条件を追加しながら検索した結果を取得する場合の流れ


記述例

条件を追加しながら検索した結果を取得する場合の記述例については“11.2.2.2 件数に応じて検索した結果を取得する”を参照してください。

ポイント

ShunSearch関数では、検索結果とともにXML文書を一意に識別するレコードID(コンダクタ制御情報および返信レコード識別子)を返却します。レコードIDは、対応するXML文書の全体を取り出したり、削除、更新する場合に利用します。


11.2.2.4 ヒット件数の上限値を設定する

ヒット件数の上限値を設定することで、ソートまたは集計の応答性能を安定させることができます。ヒット件数が上限値を超えた場合には、ソートまたは集計を中断し検索条件に一致したヒット件数を通知します。

ヒット件数が上限値を超えないように検索式に条件を追加し、ソートまたは集計の検索範囲を絞り込みます。

ヒット件数の上限値を設定するには、ShunSetStatementAttr関数を使用します。


ヒット件数の上限値を設定する場合の流れについて、以下の図に示します。


図11.7 ヒット件数の上限値を設定する場合の流れ


記述例

SHUNHSTMT StmtH;
/* データ操作ハンドルの割当て */
ShunAllocHandle(ConH, &StmtH);

/* ヒット件数の上限値を設定 */
ShunSetStatementAttr(StmtH, SHUN_ATTR_HIT_COUNT_LIMIT,10000);            (1)

/* ソート式を指定して検索を実行 */
ShunSearch(StmtH, 1, NULL, 0, 30,
           "/document/base/prefecture == '大阪'", 
           "/document/base/name, /document/base/price",
           "/document/base/price/text() DESC",
           &Hit_Cnt, &Return_Cnt, &Returnable_Cnt,
           &Rec_Id_Out, &Data,
           &First_Pos, &Last_Pos);                           

/* ヒット件数が上限値を超えているかの確認 */
ShunGetStatementAttr(StmtH, SHUN_ATTR_HIT_COUNT_LIMIT_OVER,&Attr_Value);     (2)
if(Attr_Value == SHUN_TRUE) {
  printf("ヒット件数が上限値を超えました\n");
  printf("ヒット件数              = %d\n", Hit_Cnt);                        (3)
}
else {
/* 検索した結果の取出し */
  printf("ヒット件数              = %d\n", Hit_Cnt);
  if(Hit_Cnt > 0) {
   for (i = 0; i < Return_Cnt; i++) {
     printf("[結果]%d件目 = %s\n", i+1, Data[i].Data);
   }
  }
}

/* データ操作ハンドルの解放 */
ShunFreeHandle(StmtH);

(1) ヒット件数の上限値設定

ShunSetStatementAttr関数のパラメタにヒット件数の上限値を設定します。

注意

ソート式が設定されていない場合には、ShunSearch関数実行時にエラーとなります。


(2) ヒット件数が上限値を超えているかの確認

ShunGetStatementAttr関数でヒット件数が上限値を超えているかの確認をします。


(3) ヒット件数の取出し

ヒット件数が上限値を超えている場合は、ヒット件数のみ取出し可能です。


11.2.2.5 レコードIDを利用してXML文書全体を取得する

XML文書の中から必要なXML文書を検索する場合、はじめからXML文書全体を取得するのではなく、XML文書を識別するのに有効な部分情報を取得します。利用者は、これらの部分情報から、詳細情報を取得したいXML文書を特定します。


XML文書の全体を取り出すには、部分情報を取り出したときに一緒に返却されるレコードID(コンダクタ制御情報および返信レコード識別子)を利用します。ShunSearchRecId関数の引数にレコードIDを指定することで目的のXML文書の全体を取り出すことができます。

レコードIDを利用してXML文書全体を取得する場合の流れについて、以下の図に示します。


図11.8 レコードIDを利用してXML文書全体を取得する場合の流れ


記述例

SHUNHSTMT StmtH;
/* データ操作ハンドルの割当て */
ShunAllocHandle(ConH, &StmtH);                                 (1)

/* レコードＩＤを指定して検索を実行 */
ShunSearchRecId(StmtH, 1, Rec_Id_In, &Rec_Id_Out, &Data);      (2)

/* 検索した結果の取出し */
printf("[結果] = %s\n", Data[0].Data);                         (3)

/* データ操作ハンドルの解放 */
ShunFreeHandle(StmtH);                                         (4)

(1) データ操作ハンドルの割当て

事前にデータ操作ハンドルを割り当てます。データ操作ハンドルは、ShunAllocHandle関数に、親ハンドルとなるコネクションハンドルを指定して割り当てます。


(2) 検索の実行

ShunSearchRecId関数のパラメタに、データ操作ハンドル、依頼レコード数、依頼レコードIDの配列を指定して検索を実行します。

ポイント

ShunSearchRecId関数では、複数のレコードIDを指定することで、一度に複数のXML文書を取得することもできます。


(3) 検索結果の取出し

ShunSearchRecId関数では、検索した結果のアドレスを返却します。

検索した結果は、構造体の配列で構成されていますので、これをもとにデータを取り出します。また、XML文書が存在しない場合、以下のように結果が返却されます。

  • 指定したレコードIDに対応するデータがすべてが存在しない場合
    Rec_Id_Out指定した領域がNULLに設定されます。

  • 指定したレコードIDに対応するデータの一部が存在しない場合
    取り出したレコードIDに対応するデータのデータサイズ(Data[x].Data_Len)に0が設定され、データへのアドレス(Data[x].Data)にはNULLが設定されます。


(4) データ操作ハンドルの解放

データの検索および結果の取出しが完了したら、ShunFreeHandle関数でデータ操作ハンドルを解放します。


11.2.2.6 データをソートして取得する

検索した結果をある特定の要素をキーとしてソートして取得したい場合があります。


データの部分情報をソートして取得するには、ShunSearch関数にソート式を指定して実行します。

データをソートして取得する場合の流れについて、以下の図に示します。


図11.9 データをソートして取得する場合の流れ


記述例 

SHUNHSTMT StmtH;
/* データ操作ハンドルの割当て */
ShunAllocHandle(ConH, &StmtH);                                (1)

/* ソート式を指定して検索を実行 */
ShunSearch(StmtH, 1, NULL, 0, 30,
           "/document/base/prefecture == '大阪'", 
           "/document/base/name, /document/base/price",
           "/document/base/price/text() DESC",
           &Hit_Cnt, &Return_Cnt, &Returnable_Cnt,
           &Rec_Id_Out, &Data,
           &First_Pos, &Last_Pos);                            (2)

/* 検索した結果の取出し */
printf("ヒット件数              = %d\n", Hit_Cnt);             (3)
if(Hit_Cnt > 0) {
  for (i = 0; i < Return_Cnt; i++) {
    printf("[結果]%d件目 = %s\n", i+1, Data[i].Data);
  }
}

/* データ操作ハンドルの解放 */
ShunFreeHandle(StmtH);                                        (4)

(1) データ操作ハンドルの割当て

事前にデータ操作ハンドルを割り当てます。データ操作ハンドルは、ShunAllocHandle関数に、親ハンドルとなるコネクションハンドルを指定して割り当てます。


(2) 検索の実行

ShunSearch関数のパラメタに、データ操作ハンドル、データの取得位置（取得開始位置または取得終了位置）、データの最大件数、検索式およびリターン式を指定して検索を実行します。

ポイント

ShunSearch関数にソート式を指定した場合、検索条件に一致したすべてのXML文書を参照してソート処理を行います。検索式には、結果件数が適正な値となるような条件を指定し、ソート対象のデータを絞ることが応答性能をよくするポイントです。ソートを実施する前に検索条件に一致したXML文書の件数を調べるには、ShunGetHitCount関数を利用します。

注意

ソート式に指定したキーの長さによって返却できる件数が決まります。最大件数は1000件です。データの取得位置やデータの最大件数に返却可能な最大件数を超える値を指定しても、それ以上のデータは返却することができません。
返却可能なデータの最大件数は、ShunSearch関数の出力パラメタに返却されます。キーの長さと返却可能なデータ件数の目安については、“付録C 定量値”を参照してください。

参考

データの取得位置を指定することにより、続きのデータを取り出すことができます。これにより1000件以上のデータを取り出すことができます。詳細については、“11.2.2.7 条件に一致するXML文書を連続して取得する”を参照してください。


(3) 検索した結果の取出し

ShunSearch関数では、検索した結果のアドレスを返却します。

検索した結果は、構造体の配列で構成されていますので、これをもとにデータを取り出します。

ポイント

ShunSearch関数では、検索結果とともにXML文書を一意に識別するレコードID(コンダクタ制御情報および返信レコード識別子)を返却します。レコードIDは、対応するXML文書の全体を取り出したり、削除、更新する場合に利用します。


(4) データ操作ハンドルの解放

データの検索および結果の取出しが完了したら、ShunFreeHandle関数でデータ操作ハンドルを解放します。


11.2.2.7 条件に一致するXML文書を連続して取得する

Webアプリケーションでは、検索した結果を一定件数ごとに区切って、前後に連続したデータを取得したい場合があります。


XML文書を連続して取得するには、ShunSearch関数を利用します。ShunSearch関数の引数である取得開始位置、または、取得終了位置に、その直前の検索処理によって取得した最終位置情報、または、先頭位置情報を指定します。

条件に一致するXML文書を連続して取得する場合の流れについて、以下の図に示します。


図11.10 条件に一致するXML文書を連続して取得する場合の流れ


記述例 

SHUNHSTMT StmtH;
SHUNPOS *First_Pos, *Last_Pos;
int iDirection, Direction;
SHUNPOS *sFirst_Pos, *sLast_Pos, Reply_Pos;

/* データ操作ハンドルの割当て */                                           (1)
ShunAllocHandle(ConH, &StmtH);

// どのページを表示するかによってShunSearchの第３パラメタと第４パラメタの設定を変更
// 次のページを表示する場合は iDirectionがNEXT、前のページを表示する場合は iDirectionがPREVとする
if(iDirection == NEXT) {
  // 次のページを表示する場合                                              (3)
  Reply_Pos = sLast_Pos;
  Direction = SHUN_DIRECTION_FORWARD_EXCLUSIVE;
}else if(iDirection == PREV) {
  // 前のページを表示する場合                                              (4)
  Reply_Pos = sFirst_Pos;
  Direction = SHUN_DIRECTION_BACKWARD_EXCLUSIVE;
}else{
  // 最初のページを表示する場合                                            (2)
  Reply_Pos = NULL;
  Direction = 0;
}

/* 検索の実行 */                                                          (5)
ShunSearch(StmtH, 1, Reply_Pos, Direction, 30,
           Search_Exp, Return_Exp, Sort_Exp,
           &Hit_Cnt, &Return_Cnt, &Returnable_Cnt,
           &Rec_Id_Out,
           &Data, &First_Pos, &Last_Pos); 

/* 検索した結果の取出し */                                                 (6)
printf("ヒット件数              = %d\n", Hit_Cnt);
if(Hit_Cnt != 0) { 
  for (i = 0; i < Return_Cnt; i++) {
    printf("[結果] %s\n", Data[i].Data);
  } 
}

/* 先頭位置情報と最終位置情報を格納 */                                     (7)
sLast_Pos = Last_Pos;
sFirst_Pos = First_Pos;

/* データ操作ハンドルの解放 */                                             (8)
ShunFreeHandle(StmtH);


(1) データ操作ハンドルの割当て
事前にデータ操作ハンドルを割り当てます。データ操作ハンドルは、ShunAllocHandle関数に、親ハンドルとなるコネクションハンドルを指定して割り当てます。

(2) 最初のページを表示する場合
最初のページを表示する検索処理では、最初のデータから取出しを行うため、データの取得位置（取得開始位置または取得終了位置）にはNULLを指定します。取得位置にNULLを指定すると、返信開始番号に指定した位置からデータを取り出します。

(3) 次のページを表示する場合
次のページを表示する検索処理では、前回の検索時に取得した最終位置情報を取得開始位置に指定します。この指定により前回取得したデータの次のページのデータを取得します。

(4) 前のページを表示する場合
前のページを表示する検索処理では、前回の検索時に取得した先頭位置情報を取得終了位置に指定します。この指定により前回取得したデータの前の部分のデータを取得します。

(5) 検索の実行
ShunSearch関数のパラメタに、データ操作ハンドル、データの取得位置（取得開始位置または取得終了位置）、データの最大件数、検索式、リターン式、先頭位置情報および最終位置情報を受け取るための領域を指定して検索を実行します。
ポイント
先頭位置情報または最終位置情報を受け取るための領域には、取得開始位置または取得終了位置に指定した領域と同じ領域を指定することができます。そのときには、古い位置情報は取得開始位置を特定するために使用されたあと破棄され、今回の検索で新たな位置情報が設定されます。

(6) 検索した結果の取出し
ShunSearch関数では、検索した結果のアドレスを返却します。検索した結果は、構造体の配列で構成されていますので、これをもとにデータを取り出します。

(7) 先頭位置情報と最終位置情報を格納
先頭位置情報と最終位置情報を格納します。

(8) データ操作ハンドルの解放
データの検索および結果の取出しが完了したら、ShunFreeHandle関数でデータ操作ハンドルを解放します。

11.2.2.8 条件に一致するデータの内容を集計する


検索した結果をある特定の要素の値で集計して取得したい場合があります。

データの内容を集計するには、ShunSearch関数を利用します。ShunSearch関数の引数であるリターン式に集合関数指定を指定すると、検索した結果が集計されて返却されます。集計処理では、合計値、平均値、最大値、最小値または件数を求めることができます。
条件に一致するデータの内容を集計する場合の流れについて、以下の図に示します。

図11.11 条件に一致するデータの内容を集計する場合の流れ

記述例 


SHUNHSTMT StmtH;
/* データ操作ハンドルの割当て */
ShunAllocHandle(ConH, &StmtH);                               (1)

/* 集計を実行 */
ShunSearch(StmtH, 1, NULL, 0, 30,
           "/document/base/prefecture == '大阪'", 
           "max(/document/base/price/text())",
           "/document/base/prefecture/text()",
           &Hit_Cnt, &Return_Cnt, &Returnable_Cnt,
           &Rec_Id_Out, &Data,
           &First_Pos, &Last_Pos);                           (2)

/* 集計した結果の取出し */
printf("ヒット件数              = %d\n", Hit_Cnt);            (3)
if(Hit_Cnt > 0) {
  for (i = 0; i < Return_Cnt; i++) {
    printf("[結果]%d件目 = %s\n", i+1, Data[i].Data);
  }
}

/* データ操作ハンドルの解放 */
ShunFreeHandle(StmtH);                                       (4)

(1) データ操作ハンドルの割当て
事前にデータ操作ハンドルを割り当てます。データ操作ハンドルは、ShunAllocHandle関数に、親ハンドルとなるコネクションハンドルを指定して割り当てます。

(2) 集計の実行
ShunSearch関数のパラメタに、データ操作ハンドル、データの取得位置（取得開始位置または取得終了位置）、データの最大件数、検索式およびリターン式を指定して検索を実行します。リターン式には集合関数指定を指定します。
注意
ソート式に指定したキーの長さによって返却できるグループの数が決まります。最大グループ数は1000グループです。データの取得位置やデータの最大件数に返却可能な最大グループ数を超える値を指定しても、それ以上のデータは返却することができません。
返却可能なデータの最大件数は、ShunSearch関数の出力パラメタに返却されます。キーの長さと返却可能なグループ件数の目安については、“付録C 定量値”を参照してください。
参考
データの取得位置を指定することにより、続きのデータを取り出すことができます。これにより1000グループ以上のデータを取り出すことができます。詳細については、“11.2.2.7 条件に一致するXML文書を連続して取得する”を参照してください。

(3) 集計した結果の取出し
ShunSearch関数では、集計した結果のアドレスを返却します。
集計した結果は、構造体の配列で構成されていますので、これをもとにデータを取り出します。

(4) データ操作ハンドルの解放
データの検索および結果の取出しが完了したら、ShunFreeHandle関数でデータ操作ハンドルを解放します。

前次
Copyright 2007-2021 FUJITSU LIMITED