問い合わせ実行関数

いったんデータベースサーバへの接続の確立が成功すれば，あとは このセクションで説明する関数を使って SQL の問い合わせやコマンドを実行します．

• PQexec Postgres へ問い合わせを送り， その結果を待ちます．

  PGresult *PQexec(PGconn *conn,
                   const char *query);

  戻り値は PGresult へのポインタ，場合によっては NULL ポインタです． メモリ不足の状態，あるいはバックエンドへの問い合わせ送信が 不可能といった深刻なエラーの場合を除けば，通常 NULL 以外の ポインタが返ります．もし NULL が返った場合は，PGRES_FATAL_ERROR ステータスと同じように扱われるべきです． エラーについてさらに情報を得る場合は PQerrorMessage を使います．

PGresult 構造体はバックエンドから返された問い合わせ結果をカプセル化したものです． libpq アプリケーションプログラマは PGresult による抽象化に注意を払うべきです． PGresult の内容は以下に挙げるアクセッサ関数を使って取り出してください． PGresult 構造体中のフィールドは将来予告なく変更されることがあります． ですから直接フィールドを参照することは避けてください． （Postgres リリース 6.4 の初期の段階から， PGresult 構造体の定義を libpq-fe.h の中から外しました） 以前作成したプログラムが PGresult のフィールドを直接操作している場合， libpq-int.h をインクルードすれば使い続けることができます． しかしそのプログラムは是非とも修正してください．

• PQresultStatus 問い合わせの結果ステータスを返します． PQresultStatus は以下のうちどれかの値を返します：

  PGRES_EMPTY_QUERY,
  PGRES_COMMAND_OK,       /* 問い合わせは返すデータのないコマンドだった */
  PGRES_TUPLES_OK,        /* 問い合わせがタプルを返すのに成功した */
  PGRES_COPY_OUT,         /*（サーバからの）コピーアウトの開始 */
  PGRES_COPY_IN,          /*（サーバへの）コピーインの開始 */
  PGRES_BAD_RESPONSE,     /* 予期しない応答を受け取った */
  PGRES_NONFATAL_ERROR,
  PGRES_FATAL_ERROR

  結果ステータスが PGRES_TUPLES_OK であれば，問い合わせが返した タプルを以下で説明するルーチンを使って取り出すことができます． ただし，たまたま SELECT 文が返すタプルが 0 個だったような場合でも PGRES_TUPLES_OK となることに注意してください． PGRES_COMMAND_OK は，タプルを返すことがありえないコマンドに 対するステータスです．

• PQresStatus PQresultStatus が返す列挙型のステータスコードから， コードを説明する文字列定数に変換します．

  const char *PQresStatus(ExecStatusType status);

  古いプログラムでは同じ操作をするのに libpq 内部の文字列定数

  extern const char * const pgresStatus[];

  に直接アクセスしていることがあります．しかしよりポータブルで，さらに 範囲外の数値による障害も起こさない，この PQresStatus 関数を代わりに使うことを 推奨します．

• PQresultErrorMessage 問い合わせに対応するエラーメッセージ，あるいはエラーがなにもなければ 空文字列を返します．

  const char *PQresultErrorMessage(PGresult *res);

  PQerrorMessage（接続に対するメッセージ）も，PQexec または PQgetResult 呼び出しの直後なら PQresultErrorMessage（結果に対するメッセージ）と同じ 文字列を返します． しかし後続する操作を実行すると，接続に対するエラーメッセージは変化してしまう のに対し，PGresult はオブジェクトが破棄されるまでその内部のエラーメッセージを 維持しつづけます． この PQresultErrorMessage は個々の PGresult オブジェクトに結びつけられた ステータスを見るときに，そして PQerrorMessage は接続における最後の操作の ステータスを見るときに使ってください．

• PQntuples 問い合わせ結果中のタプル（インスタンス）の数を返します．

  int PQntuples(PGresult *res);

• PQnfields 問い合わせ結果のタプルのフィールド（属性）の数を返します．

  int PQnfields(PGresult *res);

• PQbinaryTuples PGresult がバイナリのタプルデータを含むときは 1 を， ASCII データのときは 0 を返します．

  int PQbinaryTuples(PGresult *res);

  今のところ，バイナリのタプルデータを返せるのは，BINARY カーソルからデータを取り出す問い合わせだけです．

• PQfname 与えられたフィールド（属性）のインデックスに対応するフィールド名を 返します．　フィールドのインデックスは 0 から始まります．

  char *PQfname(PGresult *res,
                int field_index);

• PQfnumber 与えられたフィールド（属性）の名前に対応するフィールドのインデックスを 返します．

  int PQfnumber(PGresult *res,
                char* field_name);

  与えられた名前がどのフィールドとも一致しない場合は -1 が返されます．

• PQftype 与えられたフィールドのインデックスに対応する，フィールドの型を返します． 返された整数は型の内部的な表現値です． フィールドのインデックスは 0 から始まります．

  Oid PQftype(PGresult *res,
              int field_num);

• PQfsize 与えられたフィールドのインデックスに対応する，フィールドのサイズをバイト数で 返します． フィールドのインデックスは 0 から始まります．

  int PQfsize(PGresult *res,
              int field_index);

  PQfsize は，タプル内の指定されたフィールドに割り当てられた領域のサイズを返します． つまりこれは，このデータ型のサーバにおけるバイナリ表現のサイズです． フィールドが可変長の場合は -1 を返します．

• PQfmod 与えられたフィールドのインデックスに対応する， データ型固有の修飾データを返します． フィールドのインデックスは 0 から始まります．

  int PQfmod(PGresult *res,
             int field_index);

• PQgetvalue PGresult からひとつのタプルを取り， その中からひとつのフィールド（属性）の値を返します． タプルとフィールドのインデックスは 0 から始まります．

  char* PQgetvalue(PGresult *res,
                   int tup_num,
                   int field_num);

  大抵の問い合わせでは， PQgetvalue が返す値は属性値を NULL 終端の ASCII 文字列で表現したものとなります． しかし PQbinaryTuples() が真の場合， PQgetvalue が返す値はバックエンドサーバの内部フォーマットによるバイナリ型表現です． （ただしフィールドが可変長であってもそのサイズは含まれていません） したがって，これを正しい C の型にキャストして変換するのはプログラマの責任です． PQgetvalue が返すポインタは PGresult 構造体の記憶領域の一部ですから， これを変更してはいけません． もし値を PGresult 構造体自身の寿命を超えて使うのであれば， 明示的に別の記憶領域にコピーしなければなりません．

• PQgetlength フィールド（属性）の長さをバイト数で返します． タプルとフィールドのインデックスは 0 から始まります．

  int PQgetlength(PGresult *res,
                  int tup_num,
                  int field_num);

  これは個々のデータ値に対する実際のデータ長で， PQgetvalue が指すオブジェクトのサイズです． ASCII 表現の値の場合，このサイズは PQfsize で得られるバイナリサイズとはあまり関連 しないことに注意してください．

• PQgetisnull フィールドが NULL であるかどうかテストします． タプルとフィールドのインデックスは 0 から始まります．

  int PQgetisnull(PGresult *res,
                  int tup_num,
                  int field_num);

  この関数はフィールドが NULL であれば 1 を，そうでなければ 0 を返します． （PQgetvalue は NULL フィールドに対して NULL ポインタではなく， 空文字列を返すことに注意してください）

• PQcmdStatus PGresult の元となった SQL コマンドからコマンドステータス文字列を返します．

  char *PQcmdStatus(PGresult *res);

• PQcmdTuples SQL コマンドの実行によって影響を受けた行数を返します．

  const char *PQcmdTuples(PGresult *res);

  PGresult を生成した SQL コマンドが INSERT，UPDATE，あるいは DELETE の場合， そのコマンドの影響を受けた行数を文字列で返します． それ以外のコマンドの場合は空文字列を返します．

• PQoidStatus SQL コマンドが INSERT の場合，挿入されたタプルのオブジェクト ID を文字列で返します． それ以外の場合は空文字列を返します．

  char* PQoidStatus(PGresult *res);

• PQprint 指定された出力ストリームへ，すべてのタプルと別途指定した属性名を表示します．

  void PQprint(FILE* fout,      /* 出力ストリーム */
               PGresult* res,
               PQprintOpt* po);
  
  struct _PQprintOpt
          {
                  pqbool  header;      /* フィールド名ヘッダと行数表示の有無 */
                  pqbool  align;       /* フィールドの桁数合わせの有無 */
                  pqbool  standard;    /* 旧式フォーマット */
                  pqbool  html3;       /* HTML テーブル出力の有無 */
                  pqbool  expanded;    /* テーブルを広げて表示 */
                  pqbool  pager;       /* 必要な出力用ページャ使用の有無 */
                  char    *fieldSep;   /* フィールドセパレータ文字 */
                  char    *tableOpt;   /* HTML 文の <table ...> タグに追加する文字列 */
                  char    *caption;    /* HTML 文の <caption> */
                  char    **fieldName; /* フィールド名を置き換える文字列 ヌル終端 */
          };

  この関数は，すでにサポートされなくなった PQprintTuples() 関数の置き換えを 目的としたものです． psql プログラムは問い合わせ結果の表示に， この PQprint() を使っています．

• PQprintTuples 指定された出力ストリームへ， すべてのタプルと別途指定した属性名を表示します．

  void PQprintTuples(PGresult* res,
                     FILE* fout,      /* 出力ストリーム */
                     int printAttName,/* 属性名表示の有無 */
                     int terseOutput, /* 行／フィールド区切りの骨組みの有無 */
                     int width);      /* カラム幅． 0 にすると可変長 */

• PQdisplayTuples 指定された出力ストリームへ，すべてのタプルと 指定した属性名を表示します．

  void PQdisplayTuples(PGresult* res,
                       FILE* fout,           /* 出力ストリーム */
                       int fillAlign,        /* カラムの文字寄せの有無 */
                       const char *fieldSep, /* フィールドセパレータ */
                       int printHeader,      /* ヘッダ表示の有無 */
                       int quiet);           /* 末尾の行数表示の有無 */

  PQdisplayTuples() は PQprintTuples() の置き換えを意図したものですが， 今度は PQprint() に置き換えられました．

• PQclear PGresult に割り当てられた記憶領域を開放します． 個々の問い合わせ結果は，必要がなくなったら PQclear で （領域を）開放するべきです．

  void PQclear(PQresult *res);

  PQresult オブジェクトは必要な間保持しておくことができます． 新しい問い合わせを発行する場合でも，接続を閉じてしまうまで PQresult は消えません． PQresult を追い払ってしまうには pQclear を呼び出さなければなりません．その操作に失敗して しまうと，フロントエンドアプリケーションのメモリリークを 引き起こします．

• PQmakeEmptyPGresult 与えられたステータスを持つ，空の PGresult オブジェクトを生成します．

  PGresult* PQmakeEmptyPGresult(PGconn *conn, ExecStatusType status);

  これは libpq が空の PGresult オブジェクトの割り当て，初期化をするのに 使う内部ルーチンです．一部のアプリケーションでは，それ自身で PGresult オブジェクトを生成すると便利なので（特にエラーステータスを 含めたオブジェクト）この関数をエクスポートしています． conn が NULL でなく，ステータスがエラーを示している場合，コネクションの 現在の errorMessage が PGresult にコピーされます． なお，libpq 自体が返す PGresult と同じように，最後に PQclear をこのオブジェクトに 対して呼び出すべきです．