1.2. 問い合わせ実行関数

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

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

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

  戻り値は PGresult へのポインタ、場合によっては NULL ポイン タです。メモリ不足の状態、あるいはバックエンドへの問い合わせ 送信が不可能といった深刻なエラーの場合を除けば、通常 NULL 以 外のポインタが返ります。

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

• PQresultStatus 問い合わせの結果ステータスを返します。

  ExecStatusType PQresultStatus(const PGresult *res)

  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 が返す列挙型のステータスコードから、コードを説 明する文字列定数に変換します。

  char *PQresStatus(ExecStatusType status);

• PQresultErrorMessage 問い合わせに関するエラーメッセージを返します。エラーが何もなければ、空 の文字列を返します。

  char *PQresultErrorMessage(const PGresult *res);

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

• PQntuples 問い合わせの結果中のタプル(行)の数を返します。

  int PQntuples(const PGresult *res);

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

  int PQnfields(const PGresult *res);

• PQbinaryTuples PGresultがバイナリタプルデータを含む場合は 1を、ASCIIデータ の場合は 0を返します。

  int PQbinaryTuples(const PGresult *res);

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

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

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

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

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

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

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

  Oid PQftype(const PGresult *res,
              int field_index);

  システムテーブル pg_type に問い合わせることで、個々 のデータ型の名前とプロパティを取得することができます。 固有のデータ型のOIDは、ソースツリーの中の src/include/catalog/pg_type.hに定義されています。

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

  int PQfsize(const PGresult *res,
              int field_index);

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

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

  int PQfmod(const PGresult *res,
             int field_index);

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

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

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

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

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

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

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

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

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

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

  char * PQcmdStatus(const PGresult *res);

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

  char * PQcmdTuples(const PGresult *res);

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

• PQoidValue SQL コマンドが INSERT の場合、挿入された タプルのオブジェクト ID を返します。 それ以外の場合は、InvalidOidを返します。

  Oid PQoidValue(const PGresult *res);

  Oid型や、定数 InvalidOid は、 libpqのヘッダファイルをインクルー ドしたときに定義されます。両方とも、整数型になるでしょう。

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

  char * PQoidStatus(const PGresult *res);

  この関数は、PQoidValueがとって換わったので、推奨 されていません。また、スレッドセーフではありません。

• PQprint 指定されたストリームへ、全てのタプルと、別途指定した属性名を 表示します。

  void PQprint(FILE* fout,      /* 出力ストリーム */
               const PGresult *res,
               const PQprintOpt *po);
  
  struct {
      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; /* フィールド名に置き換わる文字列の配列。
                              ヌル終端 */
  } PQprintOpt;
         

  この関数は、問い合わせ結果を psql使用時と同 じ形式で出力しますが、もはやそうしたケースはなく、またこの関数も積極的 にサポートされなくなりました。

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

  void PQclear(PQresult *res);

  PGresultオブジェクトは、必要な間保持することが出来ます。 新しい問い合わせを発行する場合でも、接続を閉じてしまうまでは PGresultは消えません。PGresultを開放するには、 PQclearを呼び出さなくてはなりません。 その操作に失敗してしまうと、フロントエンドアプリケーションの メモリリークを引き起こしてしまいます。

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

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

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