PostgreSQL プログラマガイド
Prev	Chapter 16. libpq	Next

問い合わせ実行関数

44) Once a connection to a database server has been successfully established, the functions described here are used to perform SQL queries and commands.

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

PQexec 45) Submit a query to Postgres and wait for the result. Postgres へ問い合わせを送り，その結果を待ちます．
```
PGresult *PQexec(PGconn *conn,
                 const char *query);
```
46) Returns a PGresult pointer or possibly a NULL pointer. A non-NULL pointer will generally be returned except in out-of-memory conditions or serious errors such as inability to send the query to the backend. If a NULL is returned, it should be treated like a PGRES_FATAL_ERROR result. Use PQerrorMessage to get more information about the error. 戻り値は PGresult へのポインタ，場合によっては NULL ポインタです．メモリ不足の状態，あるいはバックエンドへの問い合わせ送信が不可能といった深刻なエラーの場合を除けば，通常 NULL 以外のポインタが返ります．もし NULL が返った場合は，PGRES_FATAL_ERROR ステータスと同じように扱われるべきです．エラーについてさらに情報を得る場合は PQerrorMessage を使います．

47) The PGresult structure encapsulates the query result returned by the backend. libpq application programmers should be careful to maintain the PGresult abstraction. Use the accessor functions below to get at the contents of PGresult. Avoid directly referencing the fields of the PGresult structure because they are subject to change in the future. (Beginning in Postgres release 6.4, the definition of struct PGresult is not even provided in libpq-fe.h. If you have old code that accesses PGresult fields directly, you can keep using it by including libpq-int.h too, but you are encouraged to fix the code soon.)

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

PQresultStatus 48) Returns the result status of the query. PQresultStatus can return one of the following values: 問い合わせの結果ステータスを返します． PQresultStatus は以下のうちどれかの値を返します：
```
49)
PGRES_EMPTY_QUERY,
PGRES_COMMAND_OK,       /* the query was a command returning no data */
PGRES_TUPLES_OK,        /* the query successfully returned tuples */
PGRES_COPY_OUT,         /* Copy Out (from server) data transfer started */
PGRES_COPY_IN,          /* Copy In (to server) data transfer started */
PGRES_BAD_RESPONSE,     /* an unexpected response was received */
PGRES_NONFATAL_ERROR,
PGRES_FATAL_ERROR
```
```
PGRES_EMPTY_QUERY,
PGRES_COMMAND_OK,       /* 問い合わせは返すデータのないコマンドだった */
PGRES_TUPLES_OK,        /* 問い合わせがタプルを返すのに成功した */
PGRES_COPY_OUT,         /*（サーバからの）コピーアウトの開始 */
PGRES_COPY_IN,          /*（サーバへの）コピーインの開始 */
PGRES_BAD_RESPONSE,     /* 予期しない応答を受け取った */
PGRES_NONFATAL_ERROR,
PGRES_FATAL_ERROR
```
50) If the result status is PGRES_TUPLES_OK, then the routines described below can be used to retrieve the tuples returned by the query. Note that a SELECT that happens to retrieve zero tuples still shows PGRES_TUPLES_OK. PGRES_COMMAND_OK is for commands that can never return tuples. 結果ステータスが PGRES_TUPLES_OK であれば，問い合わせが返したタプルを以下で説明するルーチンを使って取り出すことができます．ただし，たまたま SELECT 文が返すタプルが 0 個だったような場合でも PGRES_TUPLES_OK となることに注意してください． PGRES_COMMAND_OK は，タプルを返すことがありえないコマンドに対するステータスです．
PQresStatus 51) Converts the enumerated type returned by PQresultStatus into a string constant describing the status code. PQresultStatus が返す列挙型のステータスコードから，コードを説明する文字列定数に変換します．
```
const char *PQresStatus(ExecStatusType status);
```
52) Older code may perform this same operation by direct access to a constant string array inside libpq,
```
extern const char * const pgresStatus[];
```
However, using the function is recommended instead, since it is more portable and will not fail on out-of-range values. 古いプログラムでは同じ操作をするのに libpq 内部の文字列定数
```
extern const char * const pgresStatus[];
```
に直接アクセスしていることがあります．しかしよりポータブルで，さらに範囲外の数値による障害も起こさない，この PQresStatus 関数を代わりに使うことを推奨します．
PQresultErrorMessage 53) returns the error message associated with the query, or an empty string if there was no error. 問い合わせに対応するエラーメッセージ，あるいはエラーがなにもなければ空文字列を返します．
```
const char *PQresultErrorMessage(PGresult *res);
```
54) Immediately following a PQexec or PQgetResult call, PQerrorMessage (on the connection) will return the same string as PQresultErrorMessage (on the result). However, a PGresult will retain its error message until destroyed, whereas the connection's error message will change when subsequent operations are done. Use PQresultErrorMessage when you want to know the status associated with a particular PGresult; use PQerrorMessage when you want to know the status from the latest operation on the connection. PQerrorMessage（接続に対するメッセージ）も，PQexec または PQgetResult 呼び出しの直後なら PQresultErrorMessage（結果に対するメッセージ）と同じ文字列を返します．しかし後続する操作を実行すると，接続に対するエラーメッセージは変化してしまうのに対し，PGresult はオブジェクトが破棄されるまでその内部のエラーメッセージを維持しつづけます．この PQresultErrorMessage は個々の PGresult オブジェクトに結びつけられたステータスを見るときに，そして PQerrorMessage は接続における最後の操作のステータスを見るときに使ってください．
PQntuples 55) Returns the number of tuples (instances) in the query result. 問い合わせ結果中のタプル（インスタンス）の数を返します．
```
int PQntuples(PGresult *res);
```
PQnfields 56) Returns the number of fields (attributes) in each tuple of the query result. 問い合わせ結果のタプルのフィールド（属性）の数を返します．
```
int PQnfields(PGresult *res);
```
PQbinaryTuples 57) Returns 1 if the PGresult contains binary tuple data, 0 if it contains ASCII data. PGresult がバイナリのタプルデータを含むときは 1 を， ASCII データのときは 0 を返します．
```
int PQbinaryTuples(PGresult *res);
```
58) Currently, binary tuple data can only be returned by a query that extracts data from a BINARY cursor. 今のところ，バイナリのタプルデータを返せるのは，BINARY カーソルからデータを取り出す問い合わせだけです．
PQfname 59) Returns the field (attribute) name associated with the given field index. Field indices start at 0. 与えられたフィールド（属性）のインデックスに対応するフィールド名を返します．　フィールドのインデックスは 0 から始まります．
```
char *PQfname(PGresult *res,
              int field_index);
```
PQfnumber 60) Returns the field (attribute) index associated with the given field name. 与えられたフィールド（属性）の名前に対応するフィールドのインデックスを返します．
```
int PQfnumber(PGresult *res,
              char* field_name);
```
61) -1 is returned if the given name does not match any field.
与えられた名前がどのフィールドとも一致しない場合は -1 が返されます．
PQftype 62) Returns the field type associated with the given field index. The integer returned is an internal coding of the type. Field indices start at 0. 与えられたフィールドのインデックスに対応する，フィールドの型を返します．返された整数は型の内部的な表現値です．フィールドのインデックスは 0 から始まります．
```
Oid PQftype(PGresult *res,
            int field_num);
```
PQfsize 63) Returns the size in bytes of the field associated with the given field index. Field indices start at 0. 与えられたフィールドのインデックスに対応する，フィールドのサイズをバイト数で返します．フィールドのインデックスは 0 から始まります．
```
int PQfsize(PGresult *res,
            int field_index);
```
64) PQfsize returns the space allocated for this field in a database tuple, in other words the size of the server's binary representation of the data type. -1 is returned if the field is variable size. PQfsize は，タプル内の指定されたフィールドに割り当てられた領域のサイズを返します．つまりこれは，このデータ型のサーバにおけるバイナリ表現のサイズです．フィールドが可変長の場合は -1 を返します．
PQfmod 65) Returns the type-specific modification data of the field associated with the given field index. Field indices start at 0. 与えられたフィールドのインデックスに対応する，データ型固有の修飾データを返します．フィールドのインデックスは 0 から始まります．
```
int PQfmod(PGresult *res,
           int field_index);
```
PQgetvalue 66) Returns a single field (attribute) value of one tuple of a PGresult. Tuple and field indices start at 0. PGresult からひとつのタプルを取り，その中からひとつのフィールド（属性）の値を返します．タプルとフィールドのインデックスは 0 から始まります．
```
char* PQgetvalue(PGresult *res,
                 int tup_num,
                 int field_num);
```
67) For most queries, the value returned by PQgetvalue is a null-terminated ASCII string representation of the attribute value. But if PQbinaryTuples() is TRUE, the value returned by PQgetvalue is the binary representation of the type in the internal format of the backend server (but not including the size word, if the field is variable-length). It is then the programmer's responsibility to cast and convert the data to the correct C type. The pointer returned by PQgetvalue points to storage that is part of the PGresult structure. One should not modify it, and one must explicitly copy the value into other storage if it is to be used past the lifetime of the PGresult structure itself. 大抵の問い合わせでは， PQgetvalue が返す値は属性値を NULL 終端の ASCII 文字列で表現したものとなります．しかし PQbinaryTuples() が真の場合， PQgetvalue が返す値はバックエンドサーバの内部フォーマットによるバイナリ型表現です．（ただしフィールドが可変長であってもそのサイズは含まれていません）したがって，これを正しい C の型にキャストして変換するのはプログラマの責任です． PQgetvalue が返すポインタは PGresult 構造体の記憶領域の一部ですから，これを変更してはいけません．もし値を PGresult 構造体自身の寿命を超えて使うのであれば，明示的に別の記憶領域にコピーしなければなりません．
PQgetlength 68) Returns the length of a field (attribute) in bytes. Tuple and field indices start at 0. フィールド（属性）の長さをバイト数で返します．タプルとフィールドのインデックスは 0 から始まります．
```
int PQgetlength(PGresult *res,
                int tup_num,
                int field_num);
```
69) This is the actual data length for the particular data value, that is the size of the object pointed to by PQgetvalue. Note that for ASCII-represented values, this size has little to do with the binary size reported by PQfsize. これは個々のデータ値に対する実際のデータ長で， PQgetvalue が指すオブジェクトのサイズです． ASCII 表現の値の場合，このサイズは PQfsize で得られるバイナリサイズとはあまり関連しないことに注意してください．
PQgetisnull 70) Tests a field for a NULL entry. Tuple and field indices start at 0. フィールドが NULL であるかどうかテストします．タプルとフィールドのインデックスは 0 から始まります．
```
int PQgetisnull(PGresult *res,
                int tup_num,
                int field_num);
```
71) This function returns 1 if the field contains a NULL, 0 if it contains a non-null value. (Note that PQgetvalue will return an empty string, not a null pointer, for a NULL field.) この関数はフィールドが NULL であれば 1 を，そうでなければ 0 を返します．（PQgetvalue は NULL フィールドに対して NULL ポインタではなく，空文字列を返すことに注意してください）
PQcmdStatus 72) Returns the command status string from the SQL command that generated the PGresult. PGresult の元となった SQL コマンドからコマンドステータス文字列を返します．
```
char *PQcmdStatus(PGresult *res);
```
PQcmdTuples 73) Returns the number of rows affected by the SQL command. SQL コマンドの実行によって影響を受けた行数を返します．
```
const char *PQcmdTuples(PGresult *res);
```
74) If the SQL command that generated the PGresult was INSERT, UPDATE or DELETE, this returns a string containing the number of rows affected. If the command was anything else, it returns the empty string. PGresult を生成した SQL コマンドが INSERT，UPDATE，あるいは DELETE の場合，そのコマンドの影響を受けた行数を文字列で返します．それ以外のコマンドの場合は空文字列を返します．
PQoidStatus 75) Returns a string with the object id of the tuple inserted, if the SQL command was an INSERT. Otherwise, returns an empty string. SQL コマンドが INSERT の場合，挿入されたタプルのオブジェクト ID を文字列で返します．それ以外の場合は空文字列を返します．
```
char* PQoidStatus(PGresult *res);
```

PQprint 76) Prints out all the tuples and, optionally, the attribute names to the specified output stream. 指定された出力ストリームへ，すべてのタプルと別途指定した属性名を表示します．

77)
void PQprint(FILE* fout,      /* output stream */
             PGresult* res,
             PQprintOpt* po);

void PQprint(FILE* fout,      /* 出力ストリーム */
             PGresult* res,
             PQprintOpt* po);

struct _PQprintOpt
        {

78)
                pqbool  header;      /* print output field headings and row count */
                pqbool  align;       /* fill align the fields */
                pqbool  standard;    /* old brain dead format */
                pqbool  html3;       /* output html tables */
                pqbool  expanded;    /* expand tables */
                pqbool  pager;       /* use pager for output if needed */
                char    *fieldSep;   /* field separator */
                char    *tableOpt;   /* insert to HTML <table ...> */
                char    *caption;    /* HTML <caption> */
                char    **fieldName; /* null terminated array of replacement field names */
                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; /* フィールド名を置き換える文字列 ヌル終端 */
        };

79) This function is intended to replace PQprintTuples(), which is now obsolete. The psql program uses PQprint() to display query results. この関数は，すでにサポートされなくなった PQprintTuples() 関数の置き換えを目的としたものです． psql プログラムは問い合わせ結果の表示に，この PQprint() を使っています．

PQprintTuples 80) Prints out all the tuples and, optionally, the attribute names to the specified output stream. 指定された出力ストリームへ，すべてのタプルと別途指定した属性名を表示します．

81)
void PQprintTuples(PGresult* res,
                   FILE* fout,      /* output stream */
                   int printAttName,/* print attribute names or not*/
                   int terseOutput, /* delimiter bars or not?*/
                   int width);      /* width of column, variable width if 0*/

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

PQdisplayTuples 82) Prints out all the tuples and, optionally, the attribute names to the specified output stream. 指定された出力ストリームへ，すべてのタプルと指定した属性名を表示します．

83)
void PQdisplayTuples(PGresult* res,
                     FILE* fout,           /* output stream */
                     int fillAlign,        /* space fill to align columns */
                     const char *fieldSep, /* field separator */
                     int printHeader,      /* display headers? */
                     int quiet);           /* suppress print of row count at end */

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

84) PQdisplayTuples() was intended to supersede PQprintTuples(), and is in turn superseded by PQprint(). PQdisplayTuples() は PQprintTuples() の置き換えを意図したものですが，今度は PQprint() に置き換えられました．

PQclear 85) Frees the storage associated with the PGresult. Every query result should be freed via PQclear when it is no longer needed. PGresult に割り当てられた記憶領域を開放します．個々の問い合わせ結果は，必要がなくなったら PQclear で（領域を）開放するべきです．
```
void PQclear(PQresult *res);
```
86) You can keep a PGresult object around for as long as you need it; it does not go away when you issue a new query, nor even if you close the connection. To get rid of it, you must call PQclear. Failure to do this will result in memory leaks in the frontend application. PQresult オブジェクトは必要な間保持しておくことができます．新しい問い合わせを発行する場合でも，接続を閉じてしまうまで PQresult は消えません． PQresult を追い払ってしまうには pQclear を呼び出さなければなりません．その操作に失敗してしまうと，フロントエンドアプリケーションのメモリリークを引き起こします．
PQmakeEmptyPGresult 87) Constructs an empty PGresult object with the given status. 与えられたステータスを持つ，空の PGresult オブジェクトを生成します．
```
PGresult* PQmakeEmptyPGresult(PGconn *conn, ExecStatusType status);
```
88) This is libpq's internal routine to allocate and initialize an empty PGresult object. It is exported because some applications find it useful to generate result objects (particularly objects with error status) themselves. If conn is not NULL and status indicates an error, the connection's current errorMessage is copied into the PGresult. Note that PQclear should eventually be called on the object, just as with a PGresult returned by libpq itself. これは libpq が空の PGresult オブジェクトの割り当て，初期化をするのに使う内部ルーチンです．一部のアプリケーションでは，それ自身で PGresult オブジェクトを生成すると便利なので（特にエラーステータスを含めたオブジェクト）この関数をエクスポートしています． conn が NULL でなく，ステータスがエラーを示している場合，コネクションの現在の errorMessage が PGresult にコピーされます．なお，libpq 自体が返す PGresult と同じように，最後に PQclear をこのオブジェクトに対して呼び出すべきです．