コマンド実行関数いったんデータベースサーバへの接続の確立が成功すれば、本節で説明する関数を使ってSQLの問い合わせやコマンドを実行します。主要な関数PQexecコマンドをサーバに送信し、結果を待機します。*command);戻り値はPGresultへのポインタ、場合によってはヌルポインタです。メモリ不足の状態、あるいはサーバへのコマンド送信が不可能といった深刻なエラーの場合を除けば、通常非ヌルのポインタが返ります。PQresultStatus関数を呼び出して、何かエラー(ヌルポインタ値を含むエラー。この場合はPGRES_FATAL_ERRORが返されます)がないか戻り値を検査しなければなりません。したエラーの詳しい情報はPQerrorMessageで得ることができます。コマンド文字列には(セミコロンで区切った)複数のSQLコマンドを含めることができます。単一のPQexec呼び出しで送信された複数の問い合わせは、単一トランザクションで処理されます。問い合わせ文字列内に明示的なBEGIN/COMMITがある場合は、複数のトランザクションに分離されます。返されるPGresult構造体はその文字列内で最後に実行されたコマンドの結果のみが含まれることに注意してください。そのコマンドの1つが失敗したとすると、文字列の処理はそこで中断し、エラー条件が含まれるPGresultが返されます。PQexecParamsサーバにコマンドを送信し、結果を待ちます。SQLコマンドテキストとは別にパラメータを渡すことができます。resultFormat);PQexecParamsとPQexecは似ていますが、前者は次の機能が追加されています。パラメータ値をコマンド文字列とは別に適切に指定することができ、また、問い合わせの結果をテキスト書式としてでもバイナリ書式としてでも要求できます。PQexecParamsはプロトコル3.0以降でのみサポートされ、プロトコル2.0で使用した場合は失敗します。この関数の引数を以下に示します。conn接続オブジェクトです。これを通してコマンドを送信します。command実行させるSQLコマンド文字列です。パラメータが使用される場合は、コマンド文字列内で$1、$2などのように参照されます。nParams提供されるパラメータ数です。これは配列paramTypes[]、paramValues[]、paramLengths[]、paramFormats[]の要素数です。(この配列ポインタは、nParamsが0の場合、NULLとすることができます。)paramTypes[]パラメータシンボルに代入されるデータ型をOIDで指定したものです。paramTypesがNULL、または、ある配列要素が0の場合、サーバは、型指定のないリテラル文字列に対して行う推定方法と同じ方法を使用して、パラメータシンボルのデータ型を推定します。paramValues[]パラメータの実際の値を指定します。配列内のヌルポインタは対応するパラメータがNULLであることを意味します。なくば、このポインタはゼロ終端のテキスト文字列(テキスト書式)、または、サーバで想定している書式によるバイナリデータ(バイナリ書式)を指し示します。paramLengths[]バイナリ書式のパラメータの実データ長を指定します。NULLパラメータおよびテキスト書式のパラメータでは無視されます。バイナリパラメータが存在しない場合、この配列ポインタはヌルとしてもかまいません。paramFormats[]パラメータがテキスト(パラメータに対応する配列要素に0を設定)か、バイナリ(パラメータに対応する配列要素に1を設定)かを指定します。この配列ポインタがヌルの場合、すべてのパラメータはテキスト文字列であると仮定されます。バイナリ書式で渡された値は、バックエンドが想定する内部表現の知識を必要とします。整数はネットワークバイト順に渡されなければなりません。numericによる値は、src/backend/utils/adt/numeric.c::numeric_send()およびsrc/backend/utils/adt/numeric.c::numeric_recv()で実装されたようにサーバストレージ書式の知識を必要とします。resultFormat結果をテキスト書式で取り出したい場合は0を、バイナリ書式で取り出したい場合は1を指定します。(現時点では、プロトコル内部では実現可能ですが、結果の列ごとに異なる書式を指定して取り出す機構は存在しません。)PQexecに対するPQexecParamsの主要な利点は、コマンド文字列とパラメータ値を分離することができることです。これにより、面倒でエラーを招きやすい引用符付けやエスケープ処理を行なう必要がなくなります。PQexecと異なり、PQexecParamsは、文字列内に最大でも1つのSQLコマンドを入れることができます。(セミコロンを入れることはできますが、空でないコマンドを1つ以上入れることはできません。これは、プロトコル自体の制限ですが、SQLインジェクション攻撃に対する追加の防御となりますので、多少役に立ちます。OID経由のパラメータ型の指定は、特にプログラムの中で特定のOID値がソースに直接書き込まれることを好まない場合には退屈です。パラメータの型をサーバ自身で決定できない場合や、望む型と異なる型を選択する場合であっても、これを避けることができます。SQLコマンドテキストでどのデータ型を送信するかを示すためにパラメータシンボルに明示的なキャストをつけてください。$1::bigint;デフォルトではパラメータ$1の型はxと同じデータ型に割り当てられますが、これにより強制的にbigintとして扱われます。この方法または型のOIDを数字で指定する方法で、パラメータの型を強制的に決定することがバイナリ書式においてパラメータ値を送る時に強く推奨されます。これは、バイナリ書式はテキスト書式より情報が少なく、そのために、サーバが型の不一致という問題を検出する機会が少なくなるためです。PQprepare指定パラメータを持つプリペアド文の作成要求を送信し、その完了を待ちます。*paramTypes);PQprepareは、後でPQexecPreparedを使用して実行するプリペアド文を作成します。この機能を使用して、繰り返し使用されるコマンドの解析と計画作成を実行時に毎回行うのではなく、一回のみ行うようにすることができます。PQprepareはプロトコル3.0以降でのみサポートされ、プロトコル2.0を使用している場合は失敗します。この関数はquery文字列からstmtNameという名前のプリペアド文を作成します。queryは単一のSQLコマンドでなければなりません。stmtNameを""にして、無名の文を作成することができます。無名の文が既に存在していた場合は自動的に置き換えられます。その他の場合、文の名前が現在のセッションで既に存在するとエラーになります。何らかのパラメータが使用される場合、問い合わせ内では$1、$2などで参照します。nParamsはパラメータ数です。その型については事前にparamTypes[]配列で指定されています。(nParamsがゼロの場合、この配列ポインタはNULLにすることができます。paramTypes[]は、OIDによりパラメータシンボルに割り当てるデータ型を指定します。paramTypesがNULLの場合、もしくは、配列内の特定要素がゼロの場合、サーバはそのパラメータシンボルに対して、型指定の無いリテラル文字列に対する処理と同等の方法でデータ型を割り当てます。問い合わせではnParamsより多くのパラメータシンボルを使用することができます。これらのシンボルに対するデータ型も同様に推測されます。(どのようなデータ型が推測されるかを検出する手法についてはPQdescribePreparedを参照してください。)PQexec同様、結果は通常PGresultオブジェクトで、その内容でサーバ側の成功や失敗を示します。ヌルという結果はメモリ不足や全くコマンドを送信することができなかったことを示します。したエラーの詳細情報を入手するにはPQerrorMessageを使用してください。SQL文を実行することでも作成可能です。プリペアド文を削除するlibpq関数はありませんが、この目的のためにDEALLOCATESQL文を使用することができます。PQexecPrepared指定パラメータによるプリペアド文の実行要求を送信し、結果を待ちます。resultFormat);PQexecPreparedとPQexecParamsは似ていますが、前者では実行されるコマンドは、問い合わせ文字列を与えるのではなく、事前にプリペアド文を指名することで指定されます。この機能により、繰り返し使用する予定のコマンドを実行する度にではなく、一度だけ解析、計画作成を行うことができます。この文は現在のセッションで事前に準備されていなければなりません。PQexecPreparedは、プロトコル3.0以降の接続でのみサポートされます。プロトコル2.0で使用した場合は失敗します。パラメータは、問い合わせ文字列ではなく指定されたプリペアド文の名前を与える点を除き、PQexecParamsと同じです。paramTypes[]パラメータは存在しません。(プリペアド文のパラメータ型はその作成時点で決定されているため、これは不要です。)PQdescribePrepared指定したプリペアド文に関する情報入手要求を送り、入手完了まで待機します。*stmtName);PQdescribePreparedにより、アプリケーションは事前にプリペアド文に関する情報を入手できます。PQdescribePreparedはプロトコル3.0以降の接続でのみサポートされます。プロトコル2.0で使用すると失敗します。stmtNameを""またはNULLとすることで、無名の文を参照することができます。これ以外では、存在するプリペアド文の名前でなければなりません。成功すると、PGRES_COMMAND_OKというステータスのPGresultが返されます。PQnparamsおよびPQparamtype関数をこのPGresultに適用して、プリペアド文のパラメータに関する情報を得ることができます。PQnfields、PQfname、PQftype関数などを使用して、文の結果列(もしあれば)に関する情報を提供できます。PQdescribePortal指定したポータルに関する情報入手要求を送信し、完了まで待機します。*portalName);PQdescribePortalにより、アプリケーションは事前に作成されたポータルの情報を入手することができます。SQLコマンドで作成したカーソルの属性を確認することができます。PQdescribePortalはプロトコル3.0以降の接続でのみサポートされます。プロトコル2.0で使用すると失敗します。portalNameに""またはNULLを指定して、無名のポータルを参照することができます。これ以外では、既存のポータルの名前でなければなりません。成功すると、PGRES_COMMAND_OKというステータスのPGresultが返されます。PQnfields、PQfname、PQftype関数などをこのPGresultに適用して、ポータルの結果列(もしあれば)に関する情報を得ることができます。PGresult構造体はサーバから返された結果をカプセル化します。libpqアプリケーションのプログラマは注意してPGresultという抽象化を維持してください。以下のアクセス用関数を使用して、PGresultの内容を取り出してください。将来の変更に影響されますので、PGresult構造体のフィールドを直接参照することは避けてください。PQresultStatusコマンドの結果状態を返します。*res);PQresultStatusは以下のいずれかの値を返します。PGRES_EMPTY_QUERYサーバに送信された文字列が空でした。PGRES_COMMAND_OKデータを返さないコマンドが正常終了しました。PGRES_TUPLES_OKデータを返すコマンド(SELECTやSHOWなど)が正常終了しました。PGRES_COPY_OUT(サーバからの)コピーアウトデータ転送が始まりました。PGRES_COPY_IN(サーバへの)コピーインデータ転送が始まりました。PGRES_BAD_RESPONSEサーバが不明な応答を返しました。PGRES_NONFATAL_ERROR致命的ではない(注意喚起もしくは警告)エラーが発生しました。PGRES_FATAL_ERROR致命的なエラーが発生しました。PGRES_COPY_BOTH(サーバからおよびサーバへの)コピーイン/アウトデータ転送が始まりました。現在こればストリーミングレプリケーションのみで使用されます。このためこの状態は通常のアプリケーションでは起こりません。PGRES_SINGLE_TUPLEPGresultには現在のコマンドからの結果タプルが1つ含まれます。この状態は問い合わせで単一行モードが選択された場合(項31.5参照)のみ起こります。結果状態がPGRES_TUPLES_OKまたはPGRES_SINGLE_TUPLEであれば、以下で説明する関数を使って問い合わせが返した行を取り出すことができます。SELECTコマンドが返す行が0個だったような場合でもPGRES_TUPLES_OKとなることに注意してください。PGRES_COMMAND_OKは、行を決して返さない(INSERTまたはUPDATEなどRETURNINGの無い句など)コマンド用です。PGRES_EMPTY_QUERYという応答はクライアントソフトウェアの不具合を示しているかもしれません。PGRES_NONFATAL_ERROR状態の場合、結果はPQexecや他の問い合わせ実行関数によって直接返されません。その代わりに、この種の結果は注意喚起プロセッサ(項31.12参照)に渡されます。PQresStatusPQresultStatusが返す列挙型から状態コードを説明する文字列定数に変換します。呼び出し元はこの結果を解放してはいけません。status);PQresultErrorMessageコマンドに関するエラーメッセージを返します。エラーが何もなければ、空の文字列を返します。*res);エラーがあった場合、返される文字列の最後には改行が含まれます。呼び出し元はこの結果を直接解放してはいけません。関連するPGresultハンドルがPQclearに渡された時にこれは解放されます。(接続に対する)PQerrorMessageも、PQexecまたはPQgetResult呼び出しの直後なら(結果に対する)PQresultErrorMessageと同じ文字列を返します。接続に対するエラーメッセージは続いて操作を行うと変化してしまうのに対し、PGresultは自身が破棄されるまでそのエラーメッセージを維持し続けます。このPQresultErrorMessageは個々のPGresultに結び付けられた状態を確認する時に、そしてPQerrorMessageは接続における最後の操作の状態を確認する時に使用してください。PQresultErrorFieldエラー報告の個々のフィールドを返します。fieldcode);fieldcodeはエラーフィールド識別子です。以下に示すシンボルを参照してください。PGresultがエラーではない、もしくは、警告付きの結果である場合や指定したフィールドを含まない場合、NULLが返されます。通常フィールド値には改行が含まれません。フィールド値は関連するPGresultハンドルがPQclearに渡された時に解放されます。以下のフィールドコードが使用できます。PG_DIAG_SEVERITY深刻度。このフィールドの内容は(エラーメッセージの場合)ERROR、FATAL、もしくは、PANIC、(注意喚起メッセージの場合)WARNING、NOTICE、DEBUG、INFO、もしくは、LOGです。これらは、多言語化により翻訳されている可能性があります。PG_DIAG_SQLSTATEエラーのSQLSTATEコードです。SQLSTATEコードは発生したエラーの種類を識別します。フロントエンドアプリケーションにより、特定のデータベースエラーに対して所定の操作(エラー処理など)を行うために使用できます。起こり得るSQLSTATEコードの一覧については付録Aを参照してください。このフィールドは多言語化されず、また、常に存在します。PG_DIAG_MESSAGE_PRIMARY可読性を高めた主要エラーメッセージです。