<!--
$Header: /usr/prj/pg/cvsroot/doc/doc/src/sgml/libpq.sgml,v 1.30 2001/09/12 08:36:01 k-kondo Exp $
-->

 <chapter id="libpq">
<!--
  <title>libpq - C Library</title>
-->
  <title>libpq――C言語ライブラリ</title>
<indexterm><primary>libpq</primary></indexterm><indexterm><primary>PostgreSQL</primary><secondary>libpq</secondary></indexterm>
  <para>
<!--
   <filename>libpq</filename> is the <acronym>C</acronym>
   application programmer's interface to
   <productname>Postgres</productname>.  <filename>libpq</filename> is
   a set of library routines that allow client programs to pass
   queries to the <productname>Postgres</productname> backend server
   and to receive the results of these queries.
   <filename>libpq</filename> is also the underlying engine for
   several other <productname>Postgres</productname> application
   interfaces, including <filename>libpq++</filename> (C++),
   <filename>libpgtcl</filename> (Tcl),
   <productname>Perl</productname>, and <filename>ecpg</filename>.
   So some aspects of libpq's behavior will be important to you if you
   use one of those packages.
-->
   <filename>libpq</filename>は、<acronym>C</acronym>言語のアプリケーションプログラマ用の<productname>Postgres</productname>インターフェイスです。<filename>libpq</filename>は、クライアントプログラムから<productname>Postgres</productname>のバックエンドサーバーに問い合わせを渡し、その結果を受け取るためのライブラリルーチンの集合です。<filename>libpq</filename>は、<filename>libpq++</filename>（C++）、<filename>libpgtcl</filename>（Tcl）、<productname>Perl</productname>、<filename>ecpg</filename>などを含む、他の<productname>Postgres</productname>のアプリケーションインターフェイスを支えるエンジンでもあります。ですので、libpqの動作は、これらのインターフェイスパッケージを使用する人にとって重要なものになります。
  </para>

  <para>
<!--
   Three short programs are included at the end of this section to
   show how to write programs that use <filename>libpq</filename>.
   There are several complete examples of <filename>libpq</filename>
   applications in the following directories:
-->
   このセクションの最後には、<filename>libpq</filename>の使い方を示す、3つの短いプログラムを載せておきました。また以下に示すディレクトリに、<filename>libpq</filename>を利用したアプリケーションプログラムの完全な例があります。</para>

<programlisting>
../src/test/regress
../src/test/examples
../src/bin/psql
</programlisting>

  <para>
<!--
   Frontend programs that use <filename>libpq</filename> must include
   the header file <filename>libpq-fe.h</filename> and must link with
   the <filename>libpq</filename> library.
-->
   <filename>libpq</filename>を使用してフロントエンドプログラムを作成するには、ヘッダーファイル<filename>libpq-fe.h</filename>のインクルードと、<filename>libpq</filename>のライブラリとのリンクが必要です。
  </para>

 <sect1 id="libpq-connect">
<!--
  <title>Database Connection Functions</title>
-->
  <title>データベース接続関数</title>
<indexterm><primary>libpq</primary><secondary sortas="でーたべーすせつぞくかんすう">データベース接続関数</secondary></indexterm>
  <para>
<!--
   The following routines deal with making a connection to a
   <productname>Postgres</productname> backend server.  The
   application program can have several backend connections open at
   one time.  (One reason to do that is to access more than one
   database.)  Each connection is represented by a
   <structname>PGconn</> object which is obtained from
   <function>PQconnectdb</> or <function>PQsetdbLogin</>.  Note that
   these functions will always return a non-null object pointer,
   unless perhaps there is too little memory even to allocate the
   <structname>PGconn</> object.  The <function>PQstatus</> function
   should be called to check whether a connection was successfully
   made before queries are sent via the connection object.
-->
   <productname>Postgres</productname>のバックエンドサーバーとの接続を作成するには、以下のルーチンを使用します。アプリケーションプログラムは、バックエンドとの接続を一度に複数個開くことができます（1つの理由として、複数のデータベースへのアクセスが挙げられます）。個々の接続は、<function>PQconnectdb</>または<function>PQsetdbLogin </>を呼び出すことで得られる<structname>PGconn</>オブジェクトによって表されます。なおこれらの関数は、<structname>PGconn</>オブジェクトに割り当てるほんのわずかなメモリの余裕さえもない場合を除き、NULLではなく常にオブジェクトのポインタを返します。またこのコネクションオブジェクトを通じて問い合わせを送る前に、<function>PQstatus</>を呼び出して、データベースとの接続に成功したかどうかをチェックすべきでしょう。
</para>

    <itemizedlist>
     <listitem>
      <para>
       <emphasis><function>PQconnectdb</function></emphasis>――
<!--
       Makes a new connection to the database server.
-->
       データベースサーバーとの接続を新たに確立します。<indexterm><primary>libpq</primary><secondary sortas="かんすう">関数</secondary><tertiary>PQconnectdb</tertiary></indexterm><indexterm><primary>PQconnectdb</primary></indexterm>
</para>
<synopsis>
PGconn *PQconnectdb(const char *conninfo)
</synopsis>

<para>
<!--
   This routine opens a new database connection using the parameters
   taken from the string <literal>conninfo</literal>.  Unlike
   PQsetdbLogin() below, the parameter set can be extended without
   changing the function signature, so use either of this routine or
   the non-blocking analogues PQconnectStart / PQconnectPoll is
   prefered for application programming.  The passed string can be
   empty to use all default parameters, or it can contain one or more
   parameter settings separated by whitespace.
-->
   このルーチンは、<literal>conninfo</literal>形式の文字列をパラメータに指定することによって、データベースとの接続を新たに1つ確立します。PQsetdbLogin()とは異なり、関数のプロトタイプを変更せずに引数を拡張できるので、アプリケーションプログラムを作成する際には、このルーチンか、もしくは非ブロックモードでよく似た処理をするPQconnectStart/PQconnectPollを使用することをお勧めします。
   </para>

   <para>
<!--
   Each parameter setting is in the form <literal>keyword =
   value</literal>.
   (To write a null value or a value containing spaces, surround it
   with single quotes, e.g., <literal>keyword = 'a value'</literal>.
   Single quotes within the value must be written as
   <literal>&bsol;'</literal>. Spaces around the equal sign are optional.)
   The currently recognized parameter keywords are:
-->
   すべてのパラメータは、<literal>keyword = value</literal>という形で設定します（NULL値やスペースを含む値を書く場合は、一重引用符で囲みます。たとえば、<literal>keyword = 'a value'</literal>といった具合です。値が一重引用符を含む場合は、<literal>&bsol;'</literal>というように書かなくてはいけません。等号の前後のスペースは、任意で付けられます）。有効なパラメータのキーワードは以下に示すとおりです。
</para>

   <variablelist>
    <varlistentry>
     <term><literal>host</literal></term>
     <listitem>
     <para>
<!--
      Name of host to connect to. 
      If this begins with a slash, it specifies Unix-domain
      communication rather than TCP/IP communication; the value is the
      name of the directory in which the socket file is stored.
      The default is to connect to a Unix-domain socket in
      <filename>/tmp</filename>.
-->
      接続するホスト名を指定します。この引数をスラッシュで始めた場合、TCP/IPによる通信ではなく、Unixドメインの通信を明示することになります。<literal>host</literal>の値はソケットファイルが保存されているディレクトリの名前になります。デフォルトでは、<filename>/tmp</filename>にあるUnixドメインのソケットに接続します。
     </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><literal>hostaddr</literal></term>
     <listitem>
     <para>
<!--
      IP address of host to connect to. This should be in standard
      numbers-and-dots form, as used by the BSD functions inet_aton et
      al. If a non-zero-length string is specified, TCP/IP
      communication is used.
-->
      接続するホストのIPアドレスを指定します。これは、一般的な数字とピリオドを組み合わせた形になっています。BSDのinet_aton関数やそれに相当するものが使用するものと同じ形式です。長さが0でない文字列が指定されると、TCP/IP通信が使用されます。
     </para>
     <para>
<!--
      Using hostaddr instead of host allows the application to avoid a
      host name look-up, which may be important in applications with
      time constraints. However, Kerberos authentication requires the
      host name. The following therefore applies. If host is specified
      without hostaddr, a hostname look-up is forced. If hostaddr is
      specified without host, the value for hostaddr gives the remote
      address; if Kerberos is used, this causes a reverse name
      query. If both host and hostaddr are specified, the value for
      hostaddr gives the remote address; the value for host is
      ignored, unless Kerberos is used, in which case that value is
      used for Kerberos authentication. Note that authentication is
      likely to fail if libpq is passed a host name that is not the
      name of the machine at hostaddr.
-->
      hostの代わりにhostaddrを使用することで、アプリケーションがホスト名の検索をせずに済みます。特に、時間に制約のあるアプリケーションでは、重要になるでしょう。しかし、Kerberos認証を行うアプリケーションでは、ホスト名が必要になります。結局、以下のようになります。hostaddrを使わず、hostを使用した場合は、ホスト名からのIPアドレス検索が強制的に実行されます。hostを使わず、hostaddrを使用した場合、hostaddrはリモートマシンのIPアドレスとなります。このとき、Kerberosを使用している場合は、IPアドレスからホスト名の逆引きが行われます。hostとhostaddrの両方を使用した場合、hostaddrがリモートマシンのIPアドレスとなります。このとき、Kerberosが使用されていない場合はhostに与えられた値は無視され、使用されている場合はKerberos認証にhostの値が使用されます。libpqに渡されたホスト名が、hostaddrに対応するマシンの名前が一致しない場合は、認証に失敗する可能性があるので、注意してください。
      </para>
     <para>
<!--
      Without either a host name or host address, libpq will connect
      using a local Unix domain socket.
-->
      ホスト名もホストのアドレスも用いない場合、libpqはローカルのUNIXドメインのソケットを使用して接続します。
     </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><literal>port</literal></term>
     <listitem>
     <para>
<!--
      Port number to connect to at the server host,
      or socket filename extension for Unix-domain connections.
-->
      サーバーホストでの接続用のポート番号、または、UNIXドメイン接続の場合は、ソケットファイルの拡張子を指定します。
     </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><literal>dbname</literal></term>
     <listitem>
     <para>
<!--
      The database name.
-->
      データベース名を指定します。
     </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><literal>user</literal></term> 
     <listitem>
     <para>
<!--
      User name to connect as.
-->
      データベースへ接続するユーザー名を指定します。
     </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><literal>password</literal></term>
     <listitem>
     <para>
<!--
      Password to be used if the server demands password
      authentication.
-->
      サーバーがパスワードによる認証を必要としたときに使用されるパスワードを指定します。
     </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><literal>options</literal></term>
     <listitem>
      <para>
<!--
       Trace/debug options to be sent to the server.
-->
       サーバーに送る、トレース/デバッグオプションを指定します。
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><literal>tty</literal></term>
     <listitem>
     <para>
<!--
      A file or tty for optional debug output from the backend.
-->
      バックエンドからのデバッグ出力のためのファイル、またはttyを指定します。
     </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><literal>requiressl</literal></term>
     <listitem>
     <para>
<!--
      Set to '1' to require SSL connection to the backend. Libpq
      will then refuse to connect if the server does not support
      SSL. Set to '0' (default) to negotiate with server.
-->
      '1'を設定すると、SSL接続をバックエンドに要求します。サーバーがSSLをサポートしていない場合、libpqは接続を拒否します。'0'（デフォルト）を指定すると、通常のサーバーとの通信になります。
     </para>
     </listitem>
    </varlistentry>
   </variablelist>

<para>

<!--
   If  any  parameter is unspecified, then the corresponding
   environment variable (see "Environment Variables" section)
   is checked. If the  environment  variable is not set either,
   then hardwired defaults are used.
   The return value is a pointer to an abstract struct
   representing the connection to the backend.
-->
   どのパラメータも指定しなかった場合、該当する環境変数をチェックします（<xref linkend="libpq-envars">を参照）。環境変数も設定されていない場合は、環境に組み込みのデフォルト値が使用されます。返り値は、バックエンドとの接続を表した、抽象的な構造体へのポインタです。
   </para>
  </listitem>

  <listitem>
   <para>
   <emphasis><function>PQsetdbLogin</function></emphasis>――
<!--
       Makes a new connection to the database server.
-->
       新たにデータベースサーバーとの接続を確立します。<indexterm><primary>libpq</primary><secondary sortas="かんすう">関数</secondary><tertiary>PQsetdbLogin</tertiary></indexterm><indexterm><primary>PQsetdbLogin</primary></indexterm>
</para>

<synopsis>
PGconn *PQsetdbLogin(const char *pghost,
                     const char *pgport,
                     const char *pgoptions,
                     const char *pgtty,
                     const char *dbName,
                     const char *login,
                     const char *pwd)
</synopsis>


<para>
<!--
   This is the predecessor of <function>PQconnectdb</function> with a
   fixed number of parameters but the same functionality.   
-->
   これは、<function>PQconnectdb</function>の前にあったもので、パラメータの数が固定ですが、機能的には同じものです。
   </para>
  </listitem>

  <listitem>
   <para>
   <emphasis><function>PQsetdb</function></emphasis>――
<!--
       Makes a new connection to the database server.<indexterm><primary>libpq</primary><secondary sortas="かんすう">関数</secondary><tertiary>PQsetdb</tertiary></indexterm><indexterm><primary>PQsetdb</primary></indexterm>
-->
       新たにデータベースサーバーとの接続を確立します。
</para>

<synopsis>
PGconn *PQsetdb(char *pghost,
                char *pgport,
                char *pgoptions,
                char *pgtty,
                char *dbName)
</synopsis>

<para>
<!--
   This is a macro that calls <function>PQsetdbLogin()</function> with
   null pointers for the login and pwd parameters.  It is provided
   primarily for backward compatibility with old programs.
-->
   これは<function>PQsetdbLogin()</function>を、ログイン名とパスワードにNULLポインタを指定して呼び出すマクロです。古いプログラムとの互換性を提供します。
   </para>
  </listitem>

 <listitem>
  <para>
   <emphasis><function>PQconnectStart</function></emphasis>、
   <emphasis><function>PQconnectPoll</function></emphasis>――
<!--
   Make a connection to the database server in a non-blocking manner.
-->
   非ブロック形式でデータベースサーバーとの接続を確立します。<indexterm><primary>libpq</primary><secondary sortas="かんすう">関数</secondary><tertiary>PQconnectStart</tertiary></indexterm><indexterm><primary>PQconnectStart</primary></indexterm><indexterm><primary>liqpq</primary><secondary>PQconnectPoll</secondary></indexterm>
</para>

<synopsis>
PGconn *PQconnectStart(const char *conninfo)
</synopsis>
<synopsis>
PostgresPollingStatusType PQconnectPoll(PGconn *conn)
</synopsis>

<para>
<!--
   These two routines are used to open a connection to a database
   server such that your application's thread of execution is not
   blocked on remote I/O whilst doing so.
-->
   これらの2つルーチンを使用すると、リモートホストで入出力処理をしている間もアプリケーション実行スレッドがブロックされないように、データベースサーバーとの接続を開始することができます。
  </para>
  <para>
<!--
   The database connection is made using the parameters taken from the
   string <literal>conninfo</literal>, passed to PQconnectStart. This
   string is in the same format as described above for PQconnectdb.
-->
   PQconnectStartに渡された<literal>conninfo</literal>文字列からパラメータを取得し、データベース接続が生成されます。この文字列は、PQconnectdbの場合と同じ形式で記述されています。
  </para>
  <para>
<!--
   Neither PQconnectStart nor PQconnectPoll will block, as long as a
   number of restrictions are met:
-->
   PQconnectStartとPQconnectPollは、以下の制限下ではブロックしません。
</para>

   <itemizedlist>
    <listitem>
     <para>
<!--
      The hostaddr and host parameters are used appropriately to
      ensure that name and reverse name queries are not made. See the
      documentation of these parameters under PQconnectdb above for
      details.
-->
      hostaddrとhostパラメータは、ホスト名からのIPアドレス検索やホスト名の逆引きが起こらないように適切に使用されなければいけません。これらのパラメータについての詳細は、前述のPQconnectdbの節を参照してください。
     </para>
    </listitem>

    <listitem>
     <para>
<!--
      If you call PQtrace, ensure that the stream object into which
      you trace will not block.
-->
      PQtraceを呼び出す場合は、使用するストリームオブジェクトがブロックされない事が保証されていなくてはいけません。
     </para>
    </listitem>

    <listitem>
     <para>
<!--
      You ensure for yourself that the socket is in the appropriate
      state before calling PQconnectPoll, as described below.
-->
      プログラマ自身が、後に示すように、PQconnectPollを呼び出す前にソケットが適切な状態にあることを保証しなくてはいけません。
     </para>
    </listitem>
   </itemizedlist>

  <para>
<!--
   To begin, call
   <literal>conn=PQconnectStart("&lt;connection_info_string&gt;")</literal>.
   If conn is NULL, then libpq has been unable to allocate a new
   PGconn structure. Otherwise, a valid PGconn pointer is returned
   (though not yet representing a valid connection to the
   database). On return from PQconnectStart, call
   status=PQstatus(conn). If status equals CONNECTION_BAD,
   PQconnectStart has failed.
-->
   まず始めに、<literal>conn=PQconnectStart("&lt;connection_info_string&gt;")</literal>を呼び出します。connがNULLである場合、libpqは新たにPGconn構造体を割り当てることに失敗したことを表します。そうでない場合は、適切なPGconnへのポインタが返されます（ただし、データベースに正しく接続されていることを表しているわけではありません）。PQconnectStartから値が帰ってきた段階で、status=PQstatus(conn)を呼び出します。もし、statusがCONNECTION_BADと等しい場合には、PQconnectStartが失敗しています。
  </para>
  <para>
<!--
   If PQconnectStart succeeds, the next stage is to poll libpq so that
   it may proceed with the connection sequence.  Loop thus: Consider a
   connection 'inactive' by default. If PQconnectPoll last returned
   PGRES_POLLING_ACTIVE, consider it 'active' instead. If
   PQconnectPoll(conn) last returned PGRES_POLLING_READING, perform a
   select for reading on PQsocket(conn). If it last returned
   PGRES_POLLING_WRITING, perform a select for writing on
   PQsocket(conn). If you have yet to call PQconnectPoll, i.e. after
   the call to PQconnectStart, behave as if it last returned
   PGRES_POLLING_WRITING.  If the select shows that the socket is
   ready, consider it 'active'. If it has been decided that this
   connection is 'active', call PQconnectPoll(conn) again. If this
   call returns PGRES_POLLING_FAILED, the connection procedure has
   failed.  If this call returns PGRES_POLLING_OK, the connection has
   been successfully made.
-->
   PQconnectStartが成功したら、次は接続シーケンスを進めるために、libpqを調査します。以下のくり返しです。接続はデフォルトでは「非アクティブ」状態だと判断されます。もし、PQconnectPollがPGRES_POLLING_ACTIVEを返したら、接続が「アクティブ」状態だと判断します。PQconnectPollが最終的にPGRES_POLLING_READINGを返したら、PQsocket(conn)での読み込みをチェックするselectを実行します。もし返り値がPGRES_POLLING_WRITINGであれば、PQsocket(conn)での書き込みをチェックするselectを実行します。またPQconnectPollをまだ呼び出していないときは、返り値がPGRES_POLLING_WRITINGの場合と同じようにします。selectを実行した結果、ソケットの準備ができているようであれば、接続が「アクティブ」になったと思ってください。接続が「アクティブ」になったことが決まったら、もう一度PQconnectPoll(conn)を呼び出します。もし、PQconnectPollの返り値がPGRES_POLLING_FAILEDの場合は、接続プロシージャは失敗しています。PGRES_POLLING_OKの場合は、接続に成功しています。
  </para>
  <para>
<!--
    Note that the use of select() to ensure that the socket is ready
    is merely a (likely) example; those with other facilities
    available, such as a poll() call, may of course use that instead.
-->
    ソケットの準備ができたことを保証するためにselect()が実行されるのは、単純な例（のようなもの）であることに注意してください。他のもの（たとえばpoll()呼び出し）が使用できるのであれば、そちらが使用されることも起こり得ます。
  </para>
  <para>
<!--
    At any time during connection, the status of the connection may be
    checked, by calling PQstatus. If this is CONNECTION_BAD, then the
    connection procedure has failed; if this is CONNECTION_OK, then the
    connection is ready.  Either of these states should be equally
    detectable from the return value of PQconnectPoll, as above. Other
    states may be shown during (and only during) an asynchronous
    connection procedure. These indicate the current stage of the
    connection procedure, and may be useful to provide feedback to the
    user for example. These statuses may include:
-->
    接続している間は、いつでもPQstatusを呼び出すことで、接続の状態をチェックすることができます。もし、CONNECTION_BADであるならば、接続プロシージャは失敗しており、CONNECTION_OKなら、成功しています。前に示したように、このいずれの状態も、PQconnectPollの返り値から、同じように気づかなければいけません。これ以外の状態は、非同期の接続プロシージャの間（やその間だけ）現れることがあります。
</para>

    <itemizedlist>
     <listitem>
      <para>
<!--
      CONNECTION_STARTED: Waiting for connection to be made.
-->
      CONNECTION_STARTED――接続が確立するのを待っています。
      </para>
     </listitem>
     <listitem>
      <para>
<!--
      CONNECTION_MADE: Connection OK; waiting to send.
-->
      CONNECTION_MADE――接続はOKです。送信されるのを待っています。
      </para>
     </listitem>
     <listitem>
      <para>
<!--
      CONNECTION_AWAITING_RESPONSE: Waiting for a response from the
      postmaster.
-->
      CONNECTION_AWAITING_RESPONSE――postmasterからの応答を待っています。
      </para>
     </listitem>
     <listitem>
      <para>
<!--
      CONNECTION_AUTH_OK: Received authentication; waiting for backend
      start-up.
-->
      CONNECTION_AUTH_OK――認証済みです。バックエンドが起動するのを待っています。
      </para>
     </listitem>
     <listitem>
      <para>
<!--
      CONNECTION_SETENV: Negotiating environment.
-->
      CONNECTION_SETENV――環境とやりとりしています。
      </para>
     </listitem>
    </itemizedlist>

<para>
<!--
    Note that, although these constants will remain (in order to
    maintain compatibility) an application should never rely upon
    these appearing in a particular order, or at all, or on the status
    always being one of these documented values. An application may do
    something like this:
-->
    これらの定数は消えることはありません（互換性を保つため）が、アプリケーションは、これらが特定の順で出現したり、ドキュメントに書いてある値のどれかに必ずステータス値が該当するということを決して当てにしてはいけません。アプリケーションは、以下に示すようにするべきです。
</para>

<programlisting>
    switch(PQstatus(conn))
    {
        case CONNECTION_STARTED:
            feedback = "Connecting...";
        break;

        case CONNECTION_MADE:
            feedback = "Connected to server...";
            break;
.
.
.
        default:
        feedback = "Connecting...";
    }
</programlisting>

  <para>
<!--
   Note that if PQconnectStart returns a non-NULL pointer, you must
   call PQfinish when you are finished with it, in order to dispose of
   the structure and any associated memory blocks. This must be done
   even if a call to PQconnectStart or PQconnectPoll failed.
-->
   PQconnectStartがNULLでないポインタを返した場合、処理を終了する際には、構造体や関連するメモリブロックを始末するために、PQfinishを呼び出さなくてはいけません。この処理は、PQconnectStartやPQconnectPollの呼び出しに失敗した場合にも、必ず実行されなければいけません。
  </para>
  <para>
<!--
   PQconnectPoll will currently block if libpq is compiled with
   USE_SSL defined. This restriction may be removed in the future.
-->
   libpqがUSE_SSLを定義してコンパイルされた場合、現在はPQconnectPollは使用できません。この制限はなくなる予定です。
  </para>
  <para>
<!--
   PQconnectPoll will currently block under Windows, unless libpq is
   compiled with WIN32_NON_BLOCKING_CONNECTIONS defined. This code has
   not yet been tested under Windows, and so it is currently off by
   default. This may be changed in the future.
-->
   libpqがWIN32_NON_BLOCKING_CONNECTIONSを定義せずにコンパイルされた場合、現在のPQconnectPollはWindows環境下で使用できません。このコードはまだWindows環境下でテストされておらず、そのため、デフォルトではoffになっています。この点も変更される予定です。
  </para>
  <para>
<!--
   These functions leave the socket in a non-blocking state as if 
   <function>PQsetnonblocking</function> had been called.
-->
   これらの関数は、あたかも<function>PQsetnonblocking</function>が呼び出されたかのように、非ブロック状態のソケットを残します。
  </para>
 </listitem>

  <listitem>
   <para>
<!--
   <function>PQconndefaults</function> Returns the default connection
   options.
-->
   <emphasis><function>PQconndefaults</function></emphasis>――デフォルトの接続オプションを返します。<indexterm><primary>libpq</primary><secondary sortas="かんすう">関数</secondary><tertiary>PQconndefaults</tertiary></indexterm><indexterm><primary>PQconndefaults</primary></indexterm>
</para>

<synopsis>
PQconninfoOption *PQconndefaults(void)
<!--
struct PQconninfoOption
{
    char   *keyword;   /* The keyword of the option */
    char   *envvar;    /* Fallback environment variable name */
    char   *compiled;  /* Fallback compiled in default value */
    char   *val;       /* Option's current value, or NULL */
    char   *label;     /* Label for field in connect dialog */
    char   *dispchar;  /* Character to display for this field
                          in a connect dialog. Values are:
                          ""        Display entered value as is
                          "*"       Password field - hide value
                          "D"       Debug option - don't show by default */
    int     dispsize;  /* Field size in characters for dialog */
}
-->
struct PQconninfoOption
{
    char   *keyword;   /* オプションのキーワード */
    char   *envvar;    /* 代替となる環境変数の名前 */
    char   *compiled;  /* コンパイル時に組み込まれた代替となるデフォルト値 */
    char   *val;       /* オプションの現在値かNULL */
    char   *label;     /* 接続ダイアログの当該フィールドのラベル */
    char   *dispchar;  /* 接続ダイアログの当該フィールドに表示する文字
                          値：
                          ""        入力されたとおりの文字列を表示
                          "*"       パスワードフィールド：値を隠す
                          "D"       デバッグ用オプション：デフォルトで
                                    は表示されない */
    int     dispsize;  /* ダイアログ上のフィールドの大きさ（文字数） */
}
</synopsis>

<para>
<!--
   Returns a connection options array.  This may
   be used to determine all possible PQconnectdb options and their
   current default values.  The return value points to an array of
   PQconninfoOption structs, which ends with an entry having a NULL
   keyword pointer.  Note that the default values ("val" fields)
   will depend on environment variables and other context.
   Callers must treat the connection options data as read-only.
-->
   接続オプションの配列を返します。この関数は、使用可能なPQconnectdbのオプションのすべてや、その時点でのデフォルト値を決定するために使用することができます。返り値は、PQconninfoOption構造体の配列へのポインタで、NULL文字のポインタが配列の末尾にきます。（"val"フィールドの）デフォルト値は、環境変数や他のコンテキストに依存します。呼び出し側では、接続オプションの情報は、読み込み専用として取り扱わなければいけません。
   </para>
   <para>
<!--
    After processing the options array, free it by passing it to
    PQconninfoFree().  If this is not done, a small amount of memory
    is leaked for each call to PQconndefaults().
-->
    オプションの配列を処理した後は、PQconninfoFree()を使用して解放します。この処理をしないと、PQconndefaults()が呼び出されるたびに少しずつメモリを浪費します。
   </para>
   <para>
<!--
    In Postgres versions before 7.0, PQconndefaults() returned a
    pointer to a static array, rather than a dynamically allocated
    array.  That wasn't thread-safe, so the behavior has been changed.
-->
    バージョン7.0以前のPostgresでは、PQconndefaults()は動的に割り当てられた配列ではなく、静的な配列へのポインタを返していました。これはスレッドセーフではなかったので、変更されました。
   </para>
  </listitem>

  <listitem>
   <para>
   <emphasis><function>PQfinish</function></emphasis>――
<!--
   Close  the  connection to the backend.  Also frees
   memory used by the PGconn object.
-->
   バックエンドとの接続を閉じます。同時にPGconnオブジェクトに使われていたメモリを解放します。<indexterm><primary>libpq</primary><secondary sortas="かんすう">関数</secondary><tertiary>PQfinish</tertiary></indexterm><indexterm><primary>PQfinish</primary></indexterm>
</para>

<synopsis>
void PQfinish(PGconn *conn)
</synopsis>

<para>
<!--
   Note that even if the backend connection attempt fails (as
   indicated by PQstatus), the application should call PQfinish
   to free the memory used by the PGconn object.
   The PGconn pointer should not be used after PQfinish has been
   called.
-->
   たとえバックエンドとの接続が失敗したとしても（PQstatusで調べます）、アプリケーションはPQfinishを呼び出しPGconnオブジェクトが占めるメモリを解放するべきです。そしてPQfinishを呼び出したら、もうPGconnへのポインタを使ってはいけません。
   </para>
  </listitem>

  <listitem>
   <para>
   <emphasis><function>PQreset</function></emphasis>――
<!--
   Reset the communication  port  with  the  backend.
-->
   バックエンドとのコミュニケーションポートをリセットします。<indexterm><primary>libpq</primary><secondary sortas="かんすう">関数</secondary><tertiary>PQreset</tertiary></indexterm><indexterm><primary>PQreset</primary></indexterm>
</para>

<synopsis>
void PQreset(PGconn *conn)
</synopsis>

<para>
<!--
   This function will close the connection
   to the backend and attempt to  reestablish  a  new
   connection to the same postmaster, using all the same
   parameters previously used.  This may be useful for
   error recovery if a working connection is lost.
-->
   この関数はバックエンドとの接続を閉じ、それから再度同じpostmasterと新たな接続を確立しようとします。パラメータは前回と同じものを使います。これは稼働中の接続が失われた場合のエラーリカバリに役立つでしょう。
   </para>
  </listitem>

  <listitem>
   <para>
   <emphasis><function>PQresetStart</function></emphasis>、
   <emphasis><function>PQresetPoll</function></emphasis>――
<!--
   Reset the communication  port  with  the  backend, in a
   non-blocking manner.
-->
   バックエンドとのコミュニケーションポートを、非ブロック形式でリセットします。<indexterm><primary>libpq</primary><secondary sortas="かんすう">関数</secondary><tertiary>PQresetStart</tertiary></indexterm><indexterm><primary>PQresetStart</primary></indexterm><indexterm><primary>libpq</primary><secondary sortas="かんすう">関数</secondary><tertiary>PQresetPoll</tertiary></indexterm><indexterm><primary>PQresetPoll</primary></indexterm>
</para>

<synopsis>
int PQresetStart(PGconn *conn);
</synopsis>
<synopsis>
PostgresPollingStatusType PQresetPoll(PGconn *conn);
</synopsis>

<para>
<!--
    These functions will close the connection to the backend and
    attempt to reestablish a new connection to the same postmaster,
    using all the same parameters previously used. This may be useful
    for error recovery if a working connection is lost. They differ
    from PQreset (above) in that they act in a non-blocking
    manner. These functions suffer from the same restrictions as
    PQconnectStart and PQconnectPoll.
-->
    これらの関数はバックエンドとの接続を閉じ、それから再度同じpostmasterと新たな接続を確立しようとします。パラメータは前回と同じものを使います。これらは稼働中の接続が失われた場合のエラーリカバリに役立つでしょう。PQreset（前述）との違いは、この2つの関数が非ブロック作法で動作することです。また、PQconnectStartやPQconnectPollと同じ制限を受けます。
   </para>
   <para>
<!--
    Call PQresetStart. If it returns 0, the reset has failed. If it
    returns 1, poll the reset using PQresetPoll in exactly the same
    way as you would create the connection using PQconnectPoll.
-->
    PQresetStartを呼び出して、0を返したら、リセットに失敗しています。返り値が1ならば、PQconnectPollを使って接続を確立したときと同じように、PQresetPollを使用してリセットをします。
       </para>
  </listitem>

 </itemizedlist>

<para>
<!--
libpq application programmers should be careful to
maintain the PGconn abstraction.  Use the accessor functions below to
get at the contents of PGconn.  Avoid directly referencing the fields
of the PGconn structure because they are subject to change in the
future.
(Beginning in <productname>Postgres</productname> release 6.4, the
definition of struct PGconn is not even provided in
<filename>libpq-fe.h</filename>.If you have old code that accesses
PGconn fields directly, you can keep using it by including
<filename>libpq-int.h</filename> too, but you are encouraged to fix
the code soon.)
-->
libpqアプリケーションプログラマはPGconnによる抽象化に注意を払うべきです。PGconnの内容は以下に挙げるアクセッサ関数を使って取り出してください。PGconn構造体中のフィールドは将来予告なく変更されることがあります。ですから直接フィールドを参照することは避けてください（<productname>Postgres</productname>リリース6.4の初期の段階から、PGconn構造体の定義を<filename>libpq-int.h</filename>の中から外しました。以前作成したプログラムがPGconnのフィールドを直接操作している場合、<filename>libpq-int.h</filename>をインクルードすれば使い続けることができます。しかしそのプログラムは是非とも修正してください）。<indexterm><primary>libpq</primary><secondary sortas="かんすう">関数</secondary><tertiary>libpq-int.h</tertiary></indexterm><indexterm><primary>libpq-int.h</primary></indexterm>
</para>

<itemizedlist>
<listitem>
<para>
<emphasis><function>PQdb</function></emphasis>――
<!--
         Returns the database name of the connection.
-->
         その接続のデータベース名を返します。<indexterm><primary>libpq</primary><secondary sortas="かんすう">関数</secondary><tertiary>PQdb</tertiary></indexterm><indexterm><primary>PQdb</primary></indexterm>
</para>

<synopsis>
char *PQdb(const PGconn *conn)
</synopsis>

<para>
<!--
PQdb and the next several functions return the values established
at connection.  These values are fixed for the life of the PGconn
object.
-->
PQdbと以下のいくつかの関数は、接続時に確定した値を返します。これらの値はPGconnオブジェクトの寿命の間一定です。
</para>
</listitem>

<listitem>
<para>
<emphasis><function>PQuser</function></emphasis>――
<!--
         Returns the user name of the connection.
-->
         その接続のユーザー名を返します。<indexterm><primary>libpq</primary><secondary sortas="かんすう">関数</secondary><tertiary>PQuser</tertiary></indexterm><indexterm><primary>PQuser</primary></indexterm>
</para>

<synopsis>
char *PQuser(const PGconn *conn)
</synopsis>
</listitem>

<listitem>
<para>
<emphasis><function>PQpass</function></emphasis>――
<!--
         Returns the password of the connection.
-->
         その接続のパスワードを返します。<indexterm><primary>libpq</primary><secondary sortas="かんすう">関数</secondary><tertiary>PQpass</tertiary></indexterm><indexterm><primary>PQpass</primary></indexterm>
</para>

<synopsis>
char *PQpass(const PGconn *conn)
</synopsis>
</listitem>

<listitem>
<para>
<emphasis><function>PQhost</function></emphasis>――
<!--
         Returns the server host name of the connection.
-->
         その接続のサーバーホスト名を返します。<indexterm><primary>libpq</primary><secondary sortas="かんすう">関数</secondary><tertiary>PQhost</tertiary></indexterm><indexterm><primary>PQhost</primary></indexterm>
</para>
<synopsis>
char *PQhost(const PGconn *conn)
</synopsis>
</listitem>

<listitem>
<para>
<emphasis><function>PQport</function></emphasis>――
<!--
         Returns the port of the connection.
-->
         その接続のポート番号を返します。<indexterm><primary>libpq</primary><secondary sortas="かんすう">関数</secondary><tertiary>PQport</tertiary></indexterm><indexterm><primary>PQport</primary></indexterm>
</para>
<synopsis>
char *PQport(const PGconn *conn)
</synopsis>
</listitem>

<listitem>
<para>
<emphasis><function>PQtty</function></emphasis>――
<!--
         Returns the debug tty of the connection.
-->
         その接続のデバッグ用ttyを返します。<indexterm><primary>libpq</primary><secondary sortas="かんすう">関数</secondary><tertiary>PQtty</tertiary></indexterm><indexterm><primary>PQtty</primary></indexterm>
</para>
<synopsis>
char *PQtty(const PGconn *conn)
</synopsis>
</listitem>

<listitem>
<para>
<emphasis><function>PQoptions</function></emphasis>――
<!--
       Returns the backend options used in  the  connection.
-->
       その接続のバックエンドオプションを返します。<indexterm><primary>libpq</primary><secondary sortas="かんすう">関数</secondary><tertiary>PQoptions</tertiary></indexterm><indexterm><primary>PQoptions</primary></indexterm>
</para>
<synopsis>
char *PQoptions(const PGconn *conn)
</synopsis>
</listitem>

<listitem>
<para>
<emphasis><function>PQstatus</function></emphasis>――
<!--
         Returns the status of the connection. 
-->
         その接続のステータスを返します。<indexterm><primary>libpq</primary><secondary sortas="かんすう">関数</secondary><tertiary>PQstatus</tertiary></indexterm><indexterm><primary>PQstatus</primary></indexterm>
</para>
<synopsis>
ConnStatusType PQstatus(const PGconn *conn)
</synopsis>

      <para>
<!--
       The status can be one of a number of values.
       However, only two of these are
       seen outside of an asynchronous connection procedure -
       <literal>CONNECTION_OK</literal> or
       <literal>CONNECTION_BAD</literal>. A good
       connection to the database has the status CONNECTION_OK.
       A failed connection
       attempt is signaled by status
       <literal>CONNECTION_BAD</literal>.
       Ordinarily, an OK status will remain so until
       <function>PQfinish</function>, but a
       communications failure might result in the status changing to
       <literal>CONNECTION_BAD</literal> prematurely.
       In that case the application
       could try to recover by calling <function>PQreset</function>.
-->
       ステータスは、数多くの値の中の1つをとります。しかし、<literal>CONNECTION_OK</literal>と<literal>CONNECTION_BAD</literal>の2つのステータス値だけは、非同期の接続プロシージャの側面を見せます。データベースへの接続が良好なときはステータスがCONNECTION_OKとなります。接続の失敗は、普通<literal>CONNECTION_BAD</literal>で通知されます。OKステータスは、<function>PQfinish</function>が呼び出されるまで残りますが、バックエンドとの通信はステータスが途中で<literal>CONNECTION_BAD</literal>に変わったときに、失敗に終わることがあります。そのような場合、アプリケーションの方で<function>PQreset</function>を呼び出すことで、復旧を試すことができます。
      </para>

      <para>
<!--
       See the entry for PQconnectStart and PQconnectPoll with regards
       to other status codes
       that might be seen.
-->
       他の表示される可能性のあるステータスコードについては、PQconnectStartとPQconnectPollの節を参照してください。
      </para>
     </listitem>

     <listitem>
      <para>
       <emphasis><function>PQerrorMessage</function></emphasis>――
<!--
       Returns the error message most recently generated by
       an operation on the connection.
-->
       その接続上で最後に出力された操作上のエラーメッセージを返します。<indexterm><primary>libpq</primary><secondary sortas="かんすう">関数</secondary><tertiary>PQerrorMessage</tertiary></indexterm><indexterm><primary>PQerrorMessage</primary></indexterm>
</para>

<synopsis>
char *PQerrorMessage(const PGconn* conn);
</synopsis>

      <para>
<!--
       Nearly all libpq functions will set
       <function>PQerrorMessage</function> if they fail.
       Note that by libpq convention, a non-empty
       <function>PQerrorMessage</function> will
       include a trailing newline.
-->
       ほぼすべてのlibpq関数は動作に失敗したとき<function>PQerrorMessage</function>の内容を設定します。なお<function>PQerrorMessage</function>はlibpqの慣習に従い、空文字列でなければ末尾に改行を含みます。
      </para>
     </listitem>

     <listitem>
      <para>
       <emphasis><function>PQbackendPID</function></emphasis>――
<!--
       Returns the process <acronym>ID</acronym> of the backend server 
      handling this connection.
-->
       その接続を維持するバックエンドサーバーのプロセス<acronym>ID</acronym>を返します。<indexterm><primary>libpq</primary><secondary sortas="かんすう">関数</secondary><tertiary>PQbackendPID</tertiary></indexterm><indexterm><primary>PQbackendPID</primary></indexterm>
</para>

<synopsis>
int PQbackendPID(const PGconn *conn);
</synopsis>

<para>
<!--
       The backend <acronym>PID</acronym> is useful for debugging
       purposes and for comparison
       to NOTIFY messages (which include the <acronym>PID</acronym> of
       the notifying backend).
       Note that the <acronym>PID</acronym> belongs to a process
       executing on the database
       server host, not the local host!
-->
       バックエンドの<acronym>PID</acronym>は、デバッグする場合や通知（NOTIFY）メッセージ（これは通知を発行したバックエンドの<acronym>PID</acronym>を含んでいます）の比較に便利です。この<acronym>PID</acronym>はデータベースサーバー上で実行されているプロセスのものであり、ローカルホスト側のものではありません！ 注意してください。
      </para>
     </listitem>

     <listitem>
      <para>
       <emphasis><function>PQgetssl</function></emphasis>――
<!--
       Returns the SSL structure used in the connection, or NULL
       if SSL is not in use. 
-->
       その接続で使用されているSSL構造体を返します。SSLが使用されていない場合は、NULLを返します。<indexterm><primary>libpq</primary><secondary sortas="かんすう">関数</secondary><tertiary>PQgetssl</tertiary></indexterm><indexterm><primary>PQgetssl</primary></indexterm>
</para>

<synopsis>
SSL *PQgetssl(const PGconn *conn);
</synopsis>

<para>
<!--
       This structure can be used to verify encryption levels, check
       server certificate and more. Refer to the OpenSSL documentation
       for information about this structure.
-->
       この構造体は、暗号化のレベルの照合やサーバーの認証のチェックなどに役立ちます。この構造体については、OpenSSLのドキュメントを参照してください。
      </para>
      <para>
<!--
       You must define <literal>USE_SSL</literal> in order to get the
       prototype for this function. Doing this will also 
       automatically include <filename>ssl.h</filename> from OpenSSL.
-->
       この関数のプロトタイプを得るには、<literal>USE_SSL</literal>を定義してください。こうすると、OpenSSLの<filename>ssl.h</filename>も自動的にインクルードされます。
      </para>
     </listitem>

    </itemizedlist>
  
  </sect1>

<sect1 id="libpq-exec">
<!--
<title>Query Execution Functions</title>
-->
<title>問い合わせ実行関数</title>
<indexterm><primary>libpq</primary><secondary sortas="といあわせじっこうかんすう">問い合わせ実行関数</secondary></indexterm>
<para>
<!--
Once a connection to a database server has been successfully
established, the functions described here are used to perform
SQL queries and commands.
-->
いったんデータベースサーバーへの接続の確立が成功すれば、あとはこのセクションで説明する関数を使ってSQLの問い合わせやコマンドを実行します。
</para>

<itemizedlist>
<listitem>
<para>
<emphasis><function>PQexec</function></emphasis>――
<!--
          Submit a query to <productname>Postgres</productname>
          and wait for the result.
-->
          <productname>Postgres</productname>へ問い合わせを送り、その結果を待ちます。<indexterm><primary>libpq</primary><secondary sortas="かんすう">関数</secondary><tertiary>PQexec</tertiary></indexterm><indexterm><primary>PQexec</primary></indexterm>
</para>

<synopsis>
PGresult *PQexec(PGconn *conn,
                 const char *query);
</synopsis>

<para>
<!--
          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で得ることができます。
</para>
</listitem>
</itemizedlist>

<para>
<!--
The <function>PGresult</function> structure encapsulates the query result
returned by the backend.
<filename>libpq</filename> 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 <productname>Postgres</productname> 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.)
-->
<function>PGresult</function>構造体は、バックエンドからの問い合わせ結果をカプセル化したものです。<application>libpq</application>アプリケーションのプログラマは、PGresultによる抽象化に注意を払うべきです。PGresultの内容は以下に挙げるアクセッサ関数を使って取り出してください。PGresult構造体中のフィールドは将来予告なく変更されることがあります。ですから直接フィールドを参照することは避けてください（<productname>Postgres</productname>リリース6.4の初期の段階から、PGresult構造体の定義をlibpq-fe.hの中から外しました。以前に作成したプログラムがPGresultのフィールドを直接操作している場合、libpq-int.hをインクルードすれば使い続けることができます。しかしそのプログラムは是非とも修正してください）。<indexterm><primary>libpq</primary><secondary sortas="PGresultこうぞうたい">PGresult構造体</secondary></indexterm>
</para>

<itemizedlist>
<listitem>
<para>
<emphasis><function>PQresultStatus</function></emphasis>――
<!--
          Returns the result status of the query.
-->
          問い合わせの結果ステータスを返します。<indexterm><primary>libpq</primary><secondary sortas="かんすう">関数</secondary><tertiary>PQresultStatus</tertiary></indexterm><indexterm><primary>PQresultStatus</primary></indexterm>
</para>

<synopsis>
ExecStatusType PQresultStatus(const PGresult *res)
</synopsis>

<para>
<!--
PQresultStatus can return one of the following values:
-->
PQresultStatusは以下のうちどれかの値を返します。
</para>

<itemizedlist>
 <listitem>
<!--
  <para><literal>PGRES_EMPTY_QUERY</literal> - The string sent to the
  backend was empty.</para>
-->
  <para><literal>PGRES_EMPTY_QUERY</literal>――バックエンドへ送信した文字列が空だった。</para>
 </listitem>
 <listitem>
<!--
  <para><literal>PGRES_COMMAND_OK</literal> - Successful completion of
  a command returning no data</para>
-->
  <para><literal>PGRES_COMMAND_OK</literal>――コマンドの実行が成功し、データが返ってこなかった。</para>
 </listitem>
 <listitem>
<!--
  <para><literal>PGRES_TUPLES_OK</literal> - The query successfully
  executed</para>
-->
  <para><literal>PGRES_TUPLES_OK</literal>――問い合わせの実行に成功した。</para>
 </listitem>
 <listitem>
<!--
  <para><literal>PGRES_COPY_OUT</literal> - Copy Out (from server)
  data transfer started</para>
-->
  <para><literal>PGRES_COPY_OUT</literal>――（サーバーからの）データのコピーアウトの開始。</para>
 </listitem>
 <listitem>
<!--
  <para><literal>PGRES_COPY_IN</literal> - Copy In (to server) data
  transfer started</para>
-->
  <para><literal>PGRES_COPY_IN</literal>――（サーバーへの）データのコピーインが始まった。</para>
 </listitem>
 <listitem>
<!--
  <para><literal>PGRES_BAD_RESPONSE</literal> - The server's response
  was not understood</para>
-->
  <para><literal>PGRES_BAD_RESPONSE</literal>――サーバーからの応答が不正だった。</para>
 </listitem>
 <listitem>
  <para><literal>PGRES_NONFATAL_ERROR</literal></para>
 </listitem>
 <listitem>
  <para><literal>PGRES_FATAL_ERROR</literal></para>
 </listitem>
</itemizedlist>

<para>
<!--
If  the result status is <literal>PGRES_TUPLES_OK</literal>, 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
<literal>PGRES_TUPLES_OK</literal>.
<literal>PGRES_COMMAND_OK</literal> is for commands that can never
return tuples (INSERT, UPDATE, etc.). A response of
<literal>PGRES_EMPTY_QUERY</literal> often exposes a bug in the client
software.
-->
結果ステータスが<literal>PGRES_TUPLES_OK</literal>であれば、問い合わ
せが返したタプルを以下で説明するルーチンを使って取り出すことができま
す。
ただし、たまたまSELECT文が返すタプルが0個だったような場合でも
<literal>PGRES_TUPLES_OK</literal>となることに注意してください。
<literal>PGRES_COMMAND_OK</literal>は、INSERTやUPDATEのようにタプルを返すことがありえないコ
マンドに対するステータスです。
<literal>PGRES_EMPTY_QUERY</literal>が返るのは、
クライアントアプリケーション側にバグの可能性がある場合です。
</para>
</listitem>

<listitem>
<para>
<emphasis><function>PQresStatus</function></emphasis>――
<!--
	Converts the enumerated type returned by PQresultStatus into
	a string constant describing the status code.
-->
        PQresultStatusが返す列挙型のステータスコードから、コードを説明する文字列定数に変換します。<indexterm><primary>libpq</primary><secondary sortas="かんすう">関数</secondary><tertiary>PQresStatus</tertiary></indexterm><indexterm><primary>PQresStatus</primary></indexterm>
</para>

<synopsis>
char *PQresStatus(ExecStatusType status);
</synopsis>
</listitem>

<listitem>
<para>
<emphasis><function>PQresultErrorMessage</function></emphasis>――
<!--
returns the error message associated with the query, or an empty string
if there was no error.
-->
問い合わせに関するエラーメッセージを返します。エラーが何もなければ、空の文字列を返します。<indexterm><primary>libpq</primary><secondary sortas="かんすう">関数</secondary><tertiary>PQresultErrorMessage</tertiary></indexterm><indexterm><primary>PQresultErrorMessage</primary></indexterm>
</para>
<synopsis>
char *PQresultErrorMessage(const PGresult *res);
</synopsis>

<para>
<!--
Immediately following a <function>PQexec</function> or
<function>PQgetResult</function> call,
<function>PQerrorMessage</function> (on the connection) will return
the same string as <function>PQresultErrorMessage</function> (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
<function>PQresultErrorMessage</function> when you want to
know the status associated with a particular PGresult; use
<function>PQerrorMessage</function> when you want to know the status
from the latest operation on the connection.
-->
<function>PQerrorMessage</function>（接続に対するメッセージ）も、<function>PQexec</function>または<function>PQgetResult</function>呼び出しの直後なら<function>PQresultErrorMessage</function>（結果に対するメッセージ）と同じ文字列を返します。しかし後続する操作を実行すると、接続に対するエラーメッセージは変化してしまうのに対し、PGresultはオブジェクトが破棄されるまでその内部のエラーメッセージを維持し続けます。この<function>PQresultErrorMessage</function>は個々のPGresultオブジェクトに結び付けられたステータスを見るときに、そして<function>PQerrorMessage</function>は接続における最後の操作のステータスを見るときに使ってください。
</para>
</listitem>

<listitem>
<para>
<emphasis><function>PQntuples</function></emphasis>――
<!--
          Returns the number of tuples (rows)
          in the query result.
-->
          問い合わせの結果中のタプル（行）の数を返します。<indexterm><primary>libpq</primary><secondary sortas="かんすう">関数</secondary><tertiary>PQntuples</tertiary></indexterm><indexterm><primary>PQntuples</primary></indexterm>
</para>

<synopsis>
int PQntuples(const PGresult *res);
</synopsis>
</listitem>

<listitem>
<para>
<emphasis><function>PQnfields</function></emphasis>――
<!--
          Returns   the   number    of    fields
          (attributes) in each tuple of the query result.
-->
          問い合わせ結果のタプルのフィールド（属性）の数を返します。<indexterm><primary>libpq</primary><secondary sortas="かんすう">関数</secondary><tertiary>PQnfields</tertiary></indexterm><indexterm><primary>PQnfields</primary></indexterm>
</para>

<synopsis>
int PQnfields(const PGresult *res);
</synopsis>
</listitem>

<listitem>
<para>
<emphasis><function>PQbinaryTuples</function></emphasis>――
<!--
          Returns 1 if the PGresult contains binary tuple data,
	  0 if it contains ASCII data.
-->
          PGresultがバイナリタプルデータを含む場合は1を、ASCIIデータの場合は0を返します。<indexterm><primary>libpq</primary><secondary sortas="かんすう">関数</secondary><tertiary>PQbinaryTuples</tertiary></indexterm><indexterm><primary>PQbinaryTuples</primary></indexterm>
</para>
<synopsis>
int PQbinaryTuples(const PGresult *res);
</synopsis>

<para>
<!--
Currently, binary tuple data can only be returned by a query that
extracts data from a <acronym>BINARY</acronym> cursor.
-->
いまのところ、バイナリのタプルデータを返せるのは、<acronym>BINARY</acronym>カーソルからデータを取り出す問い合わせだけです。
</para>
</listitem>

<listitem>
<para>
<emphasis><function>PQfname</function></emphasis>――
<!--
 Returns the field (attribute) name associated with the given field
 index. Field indices start at 0.
-->
与えられたフィールド（属性）のインデックスに対応するフィールド名を返します。フィールドのインデックスは0から始まります。<indexterm><primary>libpq</primary><secondary sortas="かんすう">関数</secondary><tertiary>PQfname</tertiary></indexterm><indexterm><primary>PQfname</primary></indexterm>
</para>

<synopsis>
char *PQfname(const PGresult *res,
                    int field_index);
</synopsis>
</listitem>

<listitem>
<para>
<emphasis><function>PQfnumber</function></emphasis>――
<!--
            Returns  the  field  (attribute)  index
          associated with the given field name.
-->
            与えられたフィールド（属性）の名前に対応するフィールドのインデックスを返します。<indexterm><primary>libpq</primary><secondary sortas="かんすう">関数</secondary><tertiary>PQfnumber</tertiary></indexterm><indexterm><primary>PQfnumber</primary></indexterm>
</para>
<synopsis>
int PQfnumber(const PGresult *res,
              const char *field_name);
</synopsis>

<para>
<!--
        -1 is returned if the given name does not match any field.
-->
        与えられた名前がどのフィールドとも一致しない場合は-1が返されます。
</para>
</listitem>

<listitem>
<para>
<emphasis><function>PQftype</function></emphasis>――
<!--
            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から始まります。<indexterm><primary>libpq</primary><secondary sortas="かんすう">関数</secondary><tertiary>PQftype</tertiary></indexterm><indexterm><primary>PQftype</primary></indexterm>
</para>
<synopsis>
Oid PQftype(const PGresult *res,
            int field_index);
</synopsis>

<para>
<!--
You can query the system table <literal>pg_type</literal> to obtain
the name and properties of the various datatypes. The
<acronym>OID</acronym>s of the built-in datatypes are defined in
<filename>src/include/catalog/pg_type.h</filename> in the source tree.
-->
システムテーブル<literal>pg_type</literal>に問い合わせることで、個々のデータ型の名前とプロパティを取得することができます。固有のデータ型の<acronym>OID</acronym>は、ソースツリーの中の<filename>src/include/catalog/pg_type.h</filename>に定義されています。<indexterm><primary>pg_type.h</primary></indexterm>
</para>
</listitem>

<listitem>
<para>
<emphasis><function>PQfsize</function></emphasis>――
<!--
          Returns  the  size  in bytes of the field
          associated with the given field index.
          Field indices start at 0.
-->
          与えられたフィールドのインデックスに対応する、フィールドのサイズをバイト数で返します。フィールドのインデックスは0から始まります。<indexterm><primary>libpq</primary><secondary sortas="かんすう">関数</secondary><tertiary>PQfsize</tertiary></indexterm><indexterm><primary>PQfsize</primary></indexterm>
</para>

<synopsis>
int PQfsize(const PGresult *res,
            int field_index);
</synopsis>

<para>
<!--
	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を返します。
</para>
</listitem>

<listitem>
<para>
<emphasis><function>PQfmod</function></emphasis>――
<!--
          Returns  the type-specific modification data of the field
          associated with the given field index.
          Field indices start at 0.
-->
          与えられたフィールドのインデックスに対応する、データ型固有の修飾データを返します。フィールドのインデックスは0から始まります。<indexterm><primary>libpq</primary><secondary sortas="かんすう">関数</secondary><tertiary>PQfmod</tertiary></indexterm><indexterm><primary>PQfmod</primary></indexterm>
</para>

<synopsis>
int PQfmod(const PGresult *res,
           int field_index);
</synopsis>
</listitem>

<listitem>
<para>
<emphasis><function>PQgetvalue</function></emphasis>――
<!--
            Returns a single field  (attribute)  value of one tuple
	    of a PGresult.
	    Tuple and field indices start at 0.
-->
            PGresultから1つのタプルを取り、その中から1つのフィールド（属性）の値を返します。タプルとフィールドのインデックスは0から始まります。<indexterm><primary>libpq</primary><secondary sortas="かんすう">関数</secondary><tertiary>PQgetvalue</tertiary></indexterm><indexterm><primary>PQgetvalue</primary></indexterm>
</para>
<synopsis>
char* PQgetvalue(const PGresult *res,
                 int tup_num,
                 int field_num);
</synopsis>

<para>
<!--
For most queries, the value returned by
<function>PQgetvalue</function> is a null-terminated
<acronym>ASCII</acronym> string  representation of the attribute
value.  But if <function>PQbinaryTuples()</function> is 1,
the  value  returned  by <function>PQgetvalue</function>  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  <function>PQgetvalue</function> 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.
-->
<function>PQgetvalue</function>が返す値は属性値をNULL終端の<acronym>ASCII</acronym>文字列で表現したものとなります。しかし<function>PQbinaryTuples()</function>が真の場合、<function>PQgetvalue</function>が返す値はバックエンドサーバーの内部フォーマットによるバイナリ型表現です（ただしフィールドが可変長であってもそのサイズは含まれていません）。したがって、これを正しいCの型にキャストして変換するのはプログラマの責任です。<function>PQgetvalue</function>が返すポインタは、Gresult構造体の記憶領域の一部ですから、これを変更してはいけません。もし値をPGresult構造体自身の寿命を超えて使うのであれば、明示的に別の記憶領域にコピーしなければいけません。
</para>
</listitem>

<listitem>
<para>
<emphasis><function>PQgetlength</function></emphasis>――
<!--
          Returns   the   length  of  a  field (attribute) in bytes.
          Tuple and field indices start at 0.
-->
          フィールド（属性）の長さをバイト数で返します。タプルとフィールドのインデックスは0から始まります。<indexterm><primary>libpq</primary><secondary sortas="かんすう">関数</secondary><tertiary>PQgetlength</tertiary></indexterm><indexterm><primary>PQgetlength</primary></indexterm>
</para>

<synopsis>
int PQgetlength(const PGresult *res,
                int tup_num,
                int field_num);
</synopsis>

<para>
<!--
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で得られるバイナリサイズとはあまり関連しないことに注意してください。
</para>
</listitem>

<listitem>
<para>
<emphasis><function>PQgetisnull</function></emphasis>――
<!--
           Tests a field for a NULL entry.
           Tuple and field indices start at 0.
-->
           フィールドがNULLであるかどうかテストします。タプルとフィールドのインデックスは0から始まります。<indexterm><primary>libpq</primary><secondary sortas="かんすう">関数</secondary><tertiary>PQgetisnull</tertiary></indexterm><indexterm><primary>PQgetisnull</primary></indexterm>
</para>

<synopsis>
int PQgetisnull(const PGresult *res,
                int tup_num,
                int field_num);
</synopsis>

<para>
<!--
            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ポインタではなく、空文字列を返すことに注意してください）。
</para>
</listitem>

<listitem>
<para>
<emphasis><function>PQcmdStatus</function></emphasis>――
<!--
          Returns the command status string from the SQL command that
	  generated the PGresult.
-->
          PGresultの元となったSQLコマンドからコマンドステータス文字列を返します。<indexterm><primary>libpq</primary><secondary sortas="かんすう">関数</secondary><tertiary>PQcmdStatus</tertiary></indexterm><indexterm><primary>PQcmdStatus</primary></indexterm>
</para>

<synopsis>
char * PQcmdStatus(const PGresult *res);
</synopsis>
</listitem>

<listitem>
<para>
<emphasis><function>PQcmdTuples</function></emphasis>――
<!--
	  Returns the number of rows affected by the SQL command.
-->
          SQLコマンドの実行によって影響を受けた行数を返します。<indexterm><primary>libpq</primary><secondary sortas="かんすう">関数</secondary><tertiary>PQcmdTuples</tertiary></indexterm><indexterm><primary>PQcmdTuples</primary></indexterm>
</para>
<synopsis>
char * PQcmdTuples(const PGresult *res);
</synopsis>

<para>
<!--
          If the <acronym>SQL</acronym> 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を生成した<acronym>SQL</acronym>コマンドがINSERT、UPDATE、DELETEの場合、そのコマンドの影響を受けた行数を文字列で返します。それ以外のコマンドの場合は空文字列を返します。
</para>
</listitem>

<listitem>
<para>
<emphasis><function>PQoidValue</function></emphasis>――
<!--
          Returns the object id of  the  tuple
          inserted,  if  the <acronym>SQL</acronym> command was an INSERT.
          Otherwise, returns <literal>InvalidOid</literal>.
-->
          <acronym>SQL</acronym>コマンドがINSERTの場合、挿入されたタプルのオブジェクトIDを返します。それ以外の場合は、<literal>InvalidOid</literal>を返します。<indexterm><primary>libpq</primary><secondary sortas="かんすう">関数</secondary><tertiary>PQoidValue</tertiary></indexterm><indexterm><primary>PQoidValue</primary></indexterm>
</para>

<synopsis>
Oid PQoidValue(const PGresult *res);
</synopsis>

<para>
<!--
          The type <type>Oid</type> and the constant
          <literal>InvalidOid</literal>
          will be defined if you include the
          <application>libpq</application>
          header file. They will both be some integer type.
-->
          <type>Oid</type>型や、定数<literal>InvalidOid</literal>は、<application>libpq</application>のヘッダーファイルをインクルードしたときに定義されます。両方とも、整数型になるでしょう。
</para>
</listitem>

<listitem>
<para>
<emphasis><function>PQoidStatus</function></emphasis>――
<!--
          Returns a string with the object id of  the  tuple
          inserted,  if  the <acronym>SQL</acronym> command was an
	  INSERT.
          Otherwise, returns an empty string.
-->
          <acronym>SQL</acronym>コマンドがINSERTの場合、挿入されたタプルのオブジェクトIDを文字列で返します。それ以外の場合は空文字列を返します。<indexterm><primary>libpq</primary><secondary sortas="かんすう">関数</secondary><tertiary>PQoidStatus</tertiary></indexterm><indexterm><primary>PQoidStatus</primary></indexterm>
</para>

<synopsis>
char * PQoidStatus(const PGresult *res);
</synopsis>

<para>
<!--
This function is deprecated in favor of <function>PQoidValue</function>
and is not thread-safe.
-->
この関数は、<function>PQoidValue</function>が取って代わったので、推奨されていません。また、スレッドセーフではありません。
</para>
</listitem>

<listitem>
<para>
<emphasis><function>PQprint</function></emphasis>――
<!--
          Prints out all the  tuples  and,  optionally,  the
          attribute  names  to  the specified output stream.
-->
          指定されたストリームへ、すべてのタプルと、別途指定した属性名を表示します。<indexterm><primary>libpq</primary><secondary sortas="かんすう">関数</secondary><tertiary>PQprint</tertiary></indexterm><indexterm><primary>PQprint</primary></indexterm>
</para>

<synopsis>
<!--void PQprint(FILE* fout,      /* output stream */
             const PGresult *res,
             const PQprintOpt *po);

struct {
    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 <replaceable>table ...</replaceable> */
    char    *caption;    /* HTML <replaceable>caption</replaceable> */
    char    **fieldName; /* null terminated array of replacement field names */
} PQprintOpt;-->
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 文の<replaceable>table...</replaceable>
                            タグに追加する文字列 */
    char    *caption;    /* HTML 文の<replaceable>caption</replaceable>
                            に追加する文字列 */
    char    **fieldName; /* フィールド名に置き換わる文字列の配列。
                            NULL終端 */
} PQprintOpt;
</synopsis>

<para>
<!--
This function was formerly used by <application>psql</application>
to print query results, but this is no longer the case and this
function is no longer actively supported.
-->
この関数は、問い合わせ結果を<application>psql</application>使用時と同じ形式で出力しますが、もはやそうしたケースはなく、またこの関数も積極的にサポートされなくなりました。
</para>
</listitem>

<listitem>
<para>
<emphasis><function>PQclear</function></emphasis>――
<!--
          Frees  the  storage  associated with the PGresult.
          Every query result should be freed via PQclear  when
          it  is  no  longer needed.
-->
          PGresultに割り当てられた記憶領域を解放します。個々の問い合わせ結果は、必要なくなったときにPQclearで解放するべきです。<indexterm><primary>libpq</primary><secondary sortas="かんすう">関数</secondary><tertiary>PQclear</tertiary></indexterm><indexterm><primary>PQclear</primary></indexterm>
</para>

<synopsis>
void PQclear(PQresult *res);
</synopsis>

<para>
<!--
          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 <function>PQclear</function>.  Failure to do
          this will result in memory leaks in  the  frontend
          application.
-->
          PGresultオブジェクトは、必要な間保持することができます。新しい問い合わせを発行する場合でも、接続を閉じてしまうまではPGresultは消えません。PGresultを解放するには、<function>PQclear</function>を呼び出さなくてはいけません。その操作に失敗してしまうと、フロントエンドアプリケーションのメモリリークを引き起こしてしまいます。
</para>
</listitem>

<listitem>
<para>
<emphasis><function>PQmakeEmptyPGresult</function></emphasis>――
<!--
          Constructs an empty PGresult object with the given status.
-->
          与えられたステータスを持った、空のPGresultオブジェクトを生成します。<indexterm><primary>libpq</primary><secondary sortas="かんすう">関数</secondary><tertiary>PQmakeEmptyPGresult</tertiary></indexterm><indexterm><primary>PQmakeEmptyPGresult</primary></indexterm>
</para>

<synopsis>
PGresult* PQmakeEmptyPGresult(PGconn *conn, ExecStatusType status);
</synopsis>

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

</itemizedlist>
</sect1>

<sect1 id="libpq-async">
<!--
<title>Asynchronous Query Processing</title>
-->
<title>非同期問い合わせ関数</title>
<indexterm><primary>libpq</primary><secondary sortas="ひどうきといあわせかんすう">非同期問い合わせ関数</secondary></indexterm>

<para>
<!--
The <function>PQexec</function> function is adequate for submitting
queries in simple synchronous
applications.  It has a couple of major deficiencies however:
-->
シンプルな同期型のアプリケーションの場合。問い合わせの実行は<function>PQexec</function>関数で十分です。しかし、大きな問題をいくつか抱えています。
</para>

<itemizedlist>
<listitem>
<para>
<!--
<function>PQexec</function> waits for the query to be completed.  The
application may have other work to do (such as maintaining a user
interface), in which case it won't want to block waiting for the
response.
-->
<function>PQexec</function>は、問い合わせが完了するまで待ち状態になります。この間、アプリケーションにはほかにするべき作業があるかもしれません（たとえばユーザーインターフェイスの調整など）。このような場合は応答待ちでブロックされたくありません。
</para>
</listitem>
<listitem>
<para>
<!--
Since control is buried inside <function>PQexec</function>, it is hard
for the frontend to decide it would like to try to cancel the ongoing
query.  (It can be done from a signal handler, but not otherwise.)
-->
制御は<function>PQexec</function>関数の中に埋め込まれてしまっています。したがって、処理中の問い合わせをキャンセルするタイミングをフロントエンド側で判断するのは困難です（もっとも、シグナルハンドラからは可能ですが）。
</para>
</listitem>
<listitem>
<para>
<!--
<function>PQexec</function> can return only one PGresult structure.
If the submitted query string contains multiple <acronym>SQL</acronym>
commands, all but the last PGresult are discarded by
<function>PQexec</function>.
-->
<function>PQexec</function>が返せるPGresult構造体は1つだけです。もし送信した問い合わせ文字列が複数の<acronym>SQL</acronym>コマンドを含んでいる場合、<function>PQexec</function>は最後のものだけを除いて、残りすべてのPGresultを破棄してしまいます。

</para>
</listitem>
</itemizedlist>

<para>
<!--
Applications that do not like these limitations can instead use the
underlying functions that <function>PQexec</function> is built from:
<function>PQsendQuery</function> and <function>PQgetResult</function>.
-->
アプリケーションにとってこのような制限が望ましくない場合は、代わりに<function>PQexec</function>を構成する関数<function>PQsendQuery</function>と<function>PQgetResult</function>を使用してください。
</para>
<para>
<!--
Older programs that used this functionality as well as 
<function>PQputline</function> and <function>PQputnbytes</function>
could block waiting to send data to the backend, to
address that issue, the function <function>PQsetnonblocking</function>
was added.
-->
<function>PQputline</function>や<function>PQputnbytes</function>と同様に、この機能性を使っている古いプログラムは、バックエンドへのデータ送信待ちをブロックしてしまう可能性がありました。この問題に対応するために、<function>PQsetnonblocking</function>が追加されました。
</para>
<para>
<!--
Old applications can neglect to use <function>PQsetnonblocking</function>
and get the older potentially blocking behavior.  Newer programs can
use <function>PQsetnonblocking</function> to achieve a completely
non-blocking connection to the backend.
-->
古めのアプリケーションでは、<function>PQsetnonblocking</function>が使われていなかったり、昔の潜在的にブロックする挙動を得ていなかったりしました。新しいプログラムでは、<function>PQsetnonblocking</function>を使うことで、バックエンドと完全にブロックされない接続をすることができるようになりました。
</para>


<itemizedlist>
 <listitem>
   <para>
<!--
    <function>PQsetnonblocking</function> Sets the nonblocking status
    of the connection.
-->
    <emphasis><function>PQsetnonblocking</function></emphasis>――接続のステータスを設定します。
</para>

<synopsis>
int PQsetnonblocking(PGconn *conn, int arg)
</synopsis>

<para>
<!--
    Sets the state of the connection to nonblocking if arg is TRUE,
    blocking if arg is FALSE.  Returns 0 if OK, -1 if error.
-->
    引数がTRUEの場合は、接続が非ブロック状態になり、FALSEの場合はブロック状態になります。成功した場合は0を、失敗した場合は-1を返します。
   </para>
   <para>
<!--
    In the nonblocking state, calls to
    <function>PQputline</function>, <function>PQputnbytes</function>,
    <function>PQsendQuery</function> and <function>PQendcopy</function>
    will not block but instead return an error if they need to be called
    again.
-->
    非ブロック状態においては、<function>PQputline</function>、<function>PQputnbytes</function>、<function>PQsendQuery</function>、<function>PQendcopy</function>の呼び出しはブロックされませんが、その代わり、エラーを返した場合にはそれらの関数をもう一度呼び出さなければいけません。
    </para>
   <para>
<!--
    When a database connection has been set to non-blocking mode and
    <function>PQexec</function> is called, it will temporarily set the
    state of the connection to blocking until the <function>PQexec</function> 
    completes.
-->
    データベース接続が非ブロックモードになっていて、<function>PQexec</function>を呼び出したときには、<function>PQexec</function>が完了するまで、一時的に接続をブロック状態にします。
   </para>
   <para>
<!--
    More of libpq is expected to be made safe for 
    <function>PQsetnonblocking</function> functionality in the near
    future.
-->
    libpqの多くのものについても、近い将来<function>PQsetnonblocking</function>が安全に機能するようになると思われます。
  </para>
 </listitem>

<listitem>
<para>
<emphasis><function>PQisnonblocking</function></emphasis>――
<!--
       Returns the blocking status of the database connection.
-->
       データベース接続がブロックされているかどうかを返します。<indexterm><primary>libpq</primary><secondary sortas="かんすう">関数</secondary><tertiary>PQisnonblocking</tertiary></indexterm><indexterm><primary>PQisnonblocking</primary></indexterm>
</para>

<synopsis>
int PQisnonblocking(const PGconn *conn)
</synopsis>

<para>
<!--
       Returns TRUE if the connection is set to non-blocking mode,
       FALSE if blocking.
-->
       接続が非ブロックモードになっている場合はTRUEを返し、ブロックモードのときはFALSEを返します。
</para>
</listitem>

<listitem>
<para>
<emphasis><function>PQsendQuery</function></emphasis>――
<!--
          Submit a query to <productname>Postgres</productname> without
	  waiting for the result(s).  TRUE is returned if the query was
	  successfully dispatched, FALSE if not (in which case, use
	  PQerrorMessage to get more information about the failure).
-->
          結果を待たずに問い合わせを<productname>Postgres</productname>に送ります。問い合わせはただちに送信され、成功すればTRUEを、失敗すればFALSEを返します（この場合、PQerrorMessageを使えば失敗した理由の詳細を知ることができます）。<indexterm><primary>libpq</primary><secondary sortas="かんすう">関数</secondary><tertiary>PQsendQuery</tertiary></indexterm><indexterm><primary>PQsendQuery</primary></indexterm>
</para>

<synopsis>
int PQsendQuery(PGconn *conn,
                const char *query);
</synopsis>

<para>
<!--
	  After successfully calling <function>PQsendQuery</function>, call
          <function>PQgetResult</function> one or more
	  times to obtain the query results.  <function>PQsendQuery</function> may not be called
	  again (on the same connection) until <function>PQgetResult</function> has returned NULL,
	  indicating that the query is done.
-->
          <function>PQsendQuery</function>呼び出しが成功したら、<function>PQgetResult</function>を繰り返し呼び出して、問い合わせの実行結果を取得します。<function>PQgetResult</function>がNULLを返し、問い合わせが完了したことを示すまでは、同じ接続で<function>PQsendQuery</function>を再度呼んではいけません。
</para>
</listitem>

<listitem>
<para>
<function>PQgetResult</function>
<!--
          Wait for the next result from a prior
	  <function>PQsendQuery</function>,
	  and return it.  NULL is returned when the query is complete
	  and there will be no more results.
-->
          先に実行されたPQsendQueryの結果を逐次待ち、その結果を返します。問い合わせ実行が完了した場合NULLを返します。NULLが返った場合、取り出す結果はそれ以上ありません。
</para>

<synopsis>
PGresult *PQgetResult(PGconn *conn);
</synopsis>

<para>
<!--
	  <function>PQgetResult</function> must be called repeatedly
	  until it returns NULL,
	  indicating that the query is done.  (If called when no query is
	  active, <function>PQgetResult</function> will just return
	  NULL at once.)
	  Each non-null result from <function>PQgetResult</function>
	  should be processed using the same PGresult accessor
	  functions previously described.
	  Don't forget to free each result object with
	  <function>PQclear</function> when done with it.
	  Note that <function>PQgetResult</function> will block only
	  if a query is active and the necessary response data has not
	  yet been read by <function>PQconsumeInput</function>.
-->
          問い合わせが完了したことを示すNULLが返るまで、<function>PQgetResult</function>を繰り返して呼び出さなければなりません（問い合わせがなされていない状態で呼び出すと、<function>PQgetResult</function>はただちにNULLを返すだけです）。PQgetResultから得られるNULLでない個々の結果は、前に説明した<function>PGresult</function>のアクセッサ関数と同じものを使って処理してください。処理が終わったら<function>PQclear</function>を使い、個々の結果オブジェクトの領域を解放するのを忘れないように。なお、問い合わせが実行中であり、かつ<function>PQconsumeInput</function>を使って必要な応答データを読み込んでいないときだけは、<function>PQgetResult</function>が処理をブロックしてしまうことに注意してください。
</para>
</listitem>

</itemizedlist>

<para>
<!--
Using <function>PQsendQuery</function> and <function>PQgetResult</function>
solves one of <function>PQexec</function>'s problems:
If a query string contains multiple <acronym>SQL</acronym> commands,
the results of those commands can be obtained individually.  (This
allows a simple form of overlapped processing, by the way: the
frontend can be handling the results of one query while the backend is
still working on later queries in the same query string.)  However,
calling <function>PQgetResult</function> will
still cause the frontend to block until the backend completes the
next <acronym>SQL</acronym> command.  This can be avoided by proper
use of three more functions:
-->
<function>PQsendQuery</function>と<function>PQgetResult</function>を使うことで<function>PQexec</function>の問題は1つ解決します。つまり、問い合わせが複数の<acronym>SQL</acronym>コマンドを含んでいる場合でも、これらのコマンドの結果を個々に得ることができるわけです（これは多重処理をシンプルな形で実現します。単一の文字列に含まれる複数の問い合わせのうち、後にくるものが処理中でもフロントエンドは先に完了した結果から扱うことができるからです）。しかしバックエンドが次の<acronym>SQL</acronym>コマンドの処理に入ると、それが完了するまでやはり<function>PQgetResult</function>の呼び出しがフロントエンドをブロックしてしまいます。これを防ぐには、さらに3つの関数をうまく使うことが大切です。
</para>


<itemizedlist>
<listitem>
<para>
<emphasis><function>PQconsumeInput</function></emphasis>――
<!--
	  If input is available from the backend, consume it.
-->
          バックエンドからの入力が可能になった時点で、それを「吸い取り」ます。<indexterm><primary>libpq</primary><secondary sortas="かんすう">関数</secondary><tertiary>PQconsumeInput</tertiary></indexterm><indexterm><primary>PQconsumeInput</primary></indexterm>
</para>

<synopsis>
int PQconsumeInput(PGconn *conn);
</synopsis>

<para>
<!--
<function>PQconsumeInput</function> normally returns 1 indicating "no
error",
but returns 0 if there was some kind of trouble (in which case
<function>PQerrorMessage</function> is set).  Note that the result
does not say whether any input data was actually collected. After
calling <function>PQconsumeInput</function>, the application may check
<function>PQisBusy</function> and/or <function>PQnotifies</function>
to see if their state has changed.
-->
<function>PQconsumeInput</function>は通常、「エラーなし」を示す1を返しますが、何らかの障害があると0を返します（この場合は、<function>PQerrorMessage</function>がセットされます）。この結果は何らかの入力データが、実際に収集されたかどうかを示しているのではないことに注意してください。<function>PQconsumeInput</function>の呼び出し後、アプリケーションは<function>PQisBusy</function>、または必要があれば<function>PQnotifies</function>を呼び出して状態に変化がないか調べることができます。
</para>
<para>
<!--
<function>PQconsumeInput</function> may be called even if the
application is not prepared to deal with a result or notification just
yet.  The routine will read available data and save it in a buffer,
thereby causing a <function>select</function>(2) read-ready indication
to go away.  The application can thus use
<function>PQconsumeInput</function> to clear the
<function>select</function> condition immediately, and then examine
the results at leisure.
-->
<function>PQconsumeInput</function>は、結果や通知を扱うようにまだ準備していないアプリケーションからでも呼び出すことができます。このルーチンは有効なデータを読み込んでバッファに保存し、結果として<function>select</function>(2)による読み込み準備完了の通知をリセットします。したがってアプリケーションは<function>PQconsumeInput</function>を使うと<function>select</function>の検査条件をただちに満たすことができますから、あとはゆっくりと結果を調べてやればいいわけです。
</para>
</listitem>

<listitem>
<para>
<emphasis><function>PQisBusy</function></emphasis>――
<!--
Returns 1 if a query is busy, that is,
<function>PQgetResult</function> would block waiting for input.  A 0
return indicates that <function>PQgetResult</function> can be called
with assurance of not blocking.
-->
この関数が1を返したのであれば、問い合わせは処理の最中で、<function>PQgetResult</function>も入力を待ったままブロック状態になってしまうでしょう。0が返ったのであれば、<function>PQgetResult</function>を呼び出してもブロックされないことが保証されます。<indexterm><primary>libpq</primary><secondary sortas="かんすう">関数</secondary><tertiary>PQisBusy</tertiary></indexterm><indexterm><primary>PQisBusy</primary></indexterm>

</para>

<synopsis>
int PQisBusy(PGconn *conn);
</synopsis>

<para>
<!--
<function>PQisBusy</function> will not itself attempt to read data
from the backend;
therefore <function>PQconsumeInput</function> must be invoked first,
or the busy state will never end.
-->
<function>PQisBusy</function>自身はバックエンドからデータを読み込む操作をしません。ですから、まずは最初に<function>PQconsumeInput</function>を呼び出さなければいけません。さもなければ、ビジー状態がいつまでも続くことになるでしょう。
</para>
</listitem>

<listitem>
<para>
<!--
<function>PQflush</function> Attempt to flush any data queued to the
backend, returns 0 if successful (or if the send queue is empty) or
EOF if it failed for some reason.
-->
<emphasis><function>PQflush</function></emphasis>――
送信待ちのデータをバックエンドへ送信します。データの送信に成功するか送信待ちのデータがなければ、0を返します。何らかの理由で失敗した場合は、EOFを返します。<indexterm><primary>libpq</primary><secondary sortas="かんすう">関数</secondary><tertiary>PQflush</tertiary></indexterm><indexterm><primary>PQflush</primary></indexterm>
</para>

<synopsis>
int PQflush(PGconn *conn);
</synopsis>

<para>
<!--
<function>PQflush</function> needs to be called on a non-blocking
connection before calling <function>select</function> to determine if
a response has arrived.  If 0 is returned it ensures that there is no
data queued to the backend that has not actually been sent.  Only
applications that have used <function>PQsetnonblocking</function> have
a need for this.
-->
非ブロック接続時には、<function>select</function>を呼び出して応答を判定する前に、<function>PQflush</function>を呼び出しておかなければいけません。0が返ってきた場合、バックエンドへの送信待ちデータがないことが保証されます。<function>PQsetnonblocking</function>を使用しているアプリケーションのみでこの関数が必要になります。
</para>
</listitem>

<listitem>
<para>
<emphasis><function>PQsocket</function></emphasis>――
<!--
	  Obtain the file descriptor number for the backend connection
	  socket.
	  A valid descriptor will be &gt;= 0; a result of -1 indicates
	  that no backend connection is currently open.
-->
          バックエンドとの接続ソケットに対するファイルディスクリプタ番号を得ます。有効なディスクリプタなら値は0以上です。-1の場合は、バックエンドとの接続がまだオープンされていないことを示します。<indexterm><primary>libpq</primary><secondary sortas="かんすう">関数</secondary><tertiary>PQsocket</tertiary></indexterm><indexterm><primary>PQsocket</primary></indexterm>
</para>

<synopsis>
int PQsocket(const PGconn *conn);
</synopsis>

<para>
<!--
<function>PQsocket</function> should be used to obtain the backend
socket descriptor in preparation for executing
<function>select</function>(2).  This allows an application using a
blocking connection to wait for either backend responses or other
conditions.
If the result of <function>select</function>(2) indicates that data
can be read from the backend socket, then
<function>PQconsumeInput</function> should be called to read the data;
after which, <function>PQisBusy</function>,<function>PQgetResult</function>,
and/or <function>PQnotifies</function> can be used to process the
response.
-->
<function>select</function>(2)を実行する際に使うバックエンドへのソケットディスクリプタを得るには、この<function>PQsocket</function>を使います。アプリケーションはこの関数によってバックエンドからの応答、あるいはその他の状態を待つことができるようになります。もし<function>select</function>(2)がバックエンドへのソケットからデータを読み込める状態に なったことを示したら、<function>PQconsumeInput</function>を呼び出してデータを読み込みます。それから<function>PQisBusy</function>や<function>PQgetResult</function>、あるいは必要なら<function>PQnotifies</function>を使って応答を処理します。
</para>
<para>
<!--
Non-blocking connections (that have used <function>PQsetnonblocking</function>)
should not use <function>select</function> until <function>PQflush</function>
has returned 0 indicating that there is no buffered data waiting to be
sent to the backend.
-->
<function>PQflush</function>が0を返して、バックエンドへの送信を待っているバッファリングされたデータがないことを示すまで、<function>PQsetnonblocking</function>を使った非ブロック接続は、<function>select</function>を使用すべきではありません。
</para>
</listitem>

</itemizedlist>

<para>
<!--
A typical frontend using these functions will have a main loop that
uses <function>select</function>(2) to wait for all the conditions
that it must respond to.  One of the conditions will be input
available from the backend, which in <function>select</function>'s
terms is readable data on the file descriptor identified by
<function>PQsocket</function>.
When the main loop detects input ready, it should call
<function>PQconsumeInput</function> to read the input.  It can then
call <function>PQisBusy</function>, followed by <function>PQgetResult</function>
if <function>PQisBusy</function> returns false (0).  It can also call
<function>PQnotifies</function> to detect NOTIFY messages (see
"Asynchronous Notification", below).
-->
これらの関数を使用するフロントエンドは、<function>select</function>(2)を使ったメインループを備え、応答しなくてはいけないすべての状態を待ちます。やがてこの状態のうち1つ（<function>select</function>関数の点から見れば、<function>PQsocket</function>で確認したファイルディスクリプタから読み込めるデータ）がバックエンドから入力可能になります。メインループは入力が可能になったことを検出したら、<function>PQconsumeInput</function>を呼び出して入力を読み込みます。続いて<function>PQisBusy</function>を呼び出し、<function>PQisBusy</function>がFALSE(0)を返したら、さらに
<function>PQgetResult</function>を呼び出します。あるいは<function>PQnotifies</function>を呼び出して、通知メッセージを検出する場合もあります（後出の「非同期通知」セクションを参照）。
</para>

<para>
<!--
A frontend that uses
<function>PQsendQuery</function>/<function>PQgetResult</function>
can also attempt to cancel a query that is still being processed by
the backend.
-->
<function>PQsendQuery</function>/<function>PQgetResult</function>を使うと、バックエンドで処理中の問い合わせをフロントエンドからキャンセルするよう要求することができます。
</para>

<itemizedlist>
<listitem>
<para>
<emphasis><function>PQrequestCancel</function></emphasis>――
<!--
	  Request that <productname>Postgres</productname> abandon
	  processing of the current query.
-->
          <productname>Postgres</productname>に現在の問い合わせの処理を中断するよう要求します。<indexterm><primary>libpq</primary><secondary sortas="かんすう">関数</secondary><tertiary>PQrequestCancel</tertiary></indexterm><indexterm><primary>PQrequestCancel</primary></indexterm>
</para>

<synopsis>
int PQrequestCancel(PGconn *conn);
</synopsis>

<para>
<!--
The return value is 1 if the cancel request was successfully
dispatched, 0 if not.  (If not, <function>PQerrorMessage</function>
tells why not.)
Successful dispatch is no guarantee that the request will have any
effect, however.  Regardless of the return value of
<function>PQrequestCancel</function>,
the application must continue with the normal result-reading
sequence using <function>PQgetResult</function>.  If the cancellation
is effective, the current query will terminate early and return
an error result.  If the cancellation fails (say, because the
backend was already done processing the query), then there will
be no visible result at all.
-->
キャンセル要求の受け入れが成功すれば、1を、そうでなければ0を返します（失敗した場合は、<function>PQerrorMessage</function>で原因を知ることができます）。しかし要求の受け入れが成功したとしても、その要求の効果が出ることはまったく保証していません。したがって、アプリケーションは<function>PQrequestCancel</function>の戻り値にかかわらず、<function>PQgetResult</function>を使った通常の結果読み込みシーケンスを継続しなければいけません。もしキャンセル操作が有効であれば、現在の問い合わせは間もなく中断され、エラーが結果として返ります。キャンセル操作に失敗した場合（つまりバックエンドがすでに問い合わせ処理を終了していたため）、目に見える結果は何も出てこなくなります。
</para>
</listitem>
</itemizedlist>

<para>
<!--
Note that if the current query is part of a transaction, cancellation
will abort the whole transaction.
-->
なお、処理中の問い合わせがトランザクションの一部だと、キャンセル処理によってトランザクション全体がアボートされます。
</para>

<para>
<!--
<function>PQrequestCancel</function> can safely be invoked from a
signal handler.
So, it is also possible to use it in conjunction with plain
<function>PQexec</function>, if the decision to cancel can be made in
a signal handler.  For example, <application>psql</application>
invokes <function>PQrequestCancel</function> from a SIGINT signal
handler, thus allowing interactive cancellation of queries that it
issues through <function>PQexec</function>.
Note that <function>PQrequestCancel</function> will have no effect if
the connection is not currently open or the backend is not currently
processing a query.
-->
<function>PQrequestCancel</function>はシグナルハンドラから起動しても大丈夫です。また、単に<function>PQexec</function>と組み合わせて使うことができます。たとえば<application>psql</application>は<function>PQexec</function>を通して発行された問い合わせのキャンセル処理を、SIGINTシグナルハンドラから<function>PQrequestCancel</function>を起動することで、インタラクティブに実行できるようになっています。なお、接続がオープンされていない、あるいはバックエンドが問い合わせの処理をしていない状態では、<function>PQrequestCancel</function>の呼び出しは何の効果もありません。
</para>

</sect1>

<sect1 id="libpq-fastpath">
<!--
<title>Fast Path</title>
-->
<title>近道</title>
<indexterm><primary>libpq</primary><secondary sortas="ちかみち">近道</secondary></indexterm>

<para>
<!--
<productname>Postgres</productname> provides a fast path interface to
send function calls to the backend.  This is a trapdoor into system
internals and can be a potential security hole.  Most users will not
need this feature.
-->
<productname>Postgres</productname>は、バックエンドへの関数呼び出しインターフェイスに近道を用意しています。これはシステム内部への抜け穴であると同時に、潜在的なセキュリティホールにもなり得ます。大多数のユーザーの人はこの機能を必要とはしないでしょう。
</para>

<itemizedlist>
<listitem>
<para>
<emphasis><function>PQfn</function></emphasis>――
<!--
	Request execution of a backend function via the fast path interface.
-->
        「近道」を使ってバックエンドの関数実行を要求します。<indexterm><primary>libpq</primary><secondary sortas="かんすう">関数</secondary><tertiary>PQfn</tertiary></indexterm><indexterm><primary>PQfn</primary></indexterm>
</para>

<synopsis>
PGresult* PQfn(PGconn* conn,
               int fnid,
               int *result_buf,
               int *result_len,
               int result_is_int,
               const PQArgBlock *args,
               int nargs);
</synopsis>

<para>
<!--
     The fnid argument is the object identifier of the function to be
     executed.
     result_buf is the buffer in which
     to place the return value.  The caller must  have  allocated
     sufficient space to store the return value (there is no check!).
     The actual result length will be returned in the integer pointed
     to  by  result_len.   If a 4-byte integer result is expected, set
     result_is_int to 1; otherwise set it to 0.  (Setting
     result_is_int to 1 tells libpq to byte-swap the value if
     necessary, so that it is delivered as a proper int value for the
     client machine.  When result_is_int is 0, the byte string sent by
     the backend is returned unmodified.)
     args and nargs specify the arguments to be passed to the function.
-->
     このうちfnid引数は、実行する関数のオブジェクト識別子、result_bufは戻り値を格納するバッファです。呼び出し側は戻り値を格納するのに十分な領域を確保しておかなければいけません（ライブラリ側ではこのチェックはしていません！）。結果の実データ長はresult_lenが指す整数で返されます。結果が4バイト整数だと想定できるならresult_is_intを1に、そうでなければ0を設定します（result_is_intを1にすれば、必要に応じて値のバイト順を入れ換えるようlibpqに指示することになります。そしてクライアントマシン上で正しい整数値となるように転送します。result_is_intが0の場合は、バックエンドが送ったバイト列を何も修正せずに返します）。argsとnargsは関数に渡す引数を指定します。
</para>

<synopsis>
typedef struct {
    int len;
    int isint;
    union {
        int *ptr;
        int integer;
    } u;
} PQArgBlock;
</synopsis>

<para>
<!--
     <function>PQfn</function> always returns a valid PGresult*. The resultStatus
     should be checked before the result is used.   The
     caller is responsible for  freeing  the  PGresult  with
     <function>PQclear</function> when it is no longer needed.
-->
     <function>PQfn</function>は有効な正しいPGresult*を返します。結果を使う前にはまず、resultStatusを調べておくべきでしょう。結果が必要なくなった時点で、<function>PQclear</function>によって、PGresultを解放するのは、呼び出し側の責任です。
</para>
</listitem>
</itemizedlist>

</sect1>

<sect1 id="libpq-notify">
<!--
<title>Asynchronous Notification</title>
-->
<title>非同期通知</title>
<indexterm><primary>libpq</primary><secondary sortas="ひどうきつうち">非同期通知</secondary></indexterm><indexterm><primary sortas="ひどうきつうち">非同期通知</primary></indexterm><indexterm><primary sortas="つうち">通知</primary></indexterm>

<para>
<!--
<productname>Postgres</productname> supports asynchronous notification
via the LISTEN and NOTIFY commands.  A backend registers its interest
in a particular notification condition with the LISTEN command (and
can stop listening with the UNLISTEN command).  All backends listening
on a particular condition will be notified asynchronously when a
NOTIFY of that condition name is executed by any backend.  No
additional information is passed from the notifier to the listener.
Thus, typically, any actual data that needs to be communicated is
transferred through a database relation.
Commonly the condition name is the same as the associated relation,
but it is not necessary for there to be any associated relation.
-->
<productname>Postgres</productname>はLISTENとNOTIFYコマンドによる非同期通知機能をサポートしています。バックエンドはLISTENコマンドを受け取ると、特定の通知条件に関心を持ったことを登録します（これを止めるにはUNLISTENコマンドを使います）。特定の条件を待っているすべてのバックエンドは、同じ条件名のNOTIFYコマンドが任意のバックエンドによって実行された時点で非同期的に通知を受けます。ただし通知の発行側から受信側へ渡される付加的な情報はありません。したがって、典型的には両者の間で受け渡す必要のある実際のデータは、データベースリレーションを通じて転送することになります。一般的に、条件名は関連するリレーション名と同じものですが、必ず関連するリレーションが必要とされるわけではありません。
</para>

<para>
<!--
<filename>libpq</filename> applications submit LISTEN and UNLISTEN
commands as ordinary SQL queries.  Subsequently, arrival of NOTIFY
messages can be detected by calling PQnotifies().
-->
<application>libpq</application>アプリケーションは、通常のSQLによる問い合わせと同じようにLISTEN/UNLISTENコマンドを発行することができます。通知メッセージの到着は、続いてPQnotifies()を呼び出せば検出できます。
</para>

<itemizedlist>
<listitem>
<para>
<emphasis><function>PQnotifies</function></emphasis>――
<!--
          Returns  the next notification from a list of unhandled
          notification messages received from the backend.  Returns
	  NULL if there are no pending notifications.  Once a
	  notification is returned from PQnotifies, it is considered
	  handled and will be removed from the list of notifications.
-->
          バックエンドから受信した通知メッセージのうち、まだ処理されていないもののリストから次の通知を返します。保留中の通知がなくなればNULLを返します。PQnotifiesが通知を返すとその通知はもはや処理が済んだものとみなされ、通知リストから取り除かれます。<indexterm><primary>libpq</primary><secondary sortas="かんすう">関数</secondary><tertiary>PQnotifies</tertiary></indexterm><indexterm><primary>PQnotifies</primary></indexterm>
</para>

<synopsis>
PGnotify* PQnotifies(PGconn *conn);

<!--typedef struct pgNotify {
    char relname[NAMEDATALEN];       /* name of relation
                                      * containing data */
    int  be_pid;                     /* process id of backend */
} PGnotify;-->
typedef struct pgNotify {
    char relname[NAMEDATALEN];       /* データを含むリレーションの名前 */
    int  be_pid;                     /* バックエンドのプロセスID */
} PGnotify;
</synopsis>

<para>
<!--
After processing a PGnotify object returned by <function>PQnotifies</function>,
be sure to free it with <function>free()</function> to avoid a memory
leak.
-->
メモリリークを防ぐため、<function>PQnotifies</function>が返したPGnotifyオブジェクトの処理が終わったら、必ず<function>free()</function>で領域を解放してください。
</para>
<note>
<para>
<!--
 In <productname>Postgres</productname> 6.4 and later,
 the <literal>be_pid</literal> is the notifying backend's,
 whereas in earlier versions it was always your own backend's
 <acronym>PID</acronym>.
-->
6.4より前のバージョンでは、<literal>be_pid</literal>が常に接続しているバックエンドのプロセスIDだったのに対し、6.4とそれ以降の<productname>Postgres</productname>では通知を発行したバックエンドの<acronym>プロセスID</acronym>になります。
</para>
</note>
</listitem>
</itemizedlist>

<para>
<!--
The  second  sample program gives an example of the use
of asynchronous notification.
-->
2つ目のサンプルプログラムは、非同期通知の使い方の一例です。
</para>

<para>
<!--
<function>PQnotifies()</function> does not actually read backend data;
it just returns messages previously absorbed by another
<application>libpq</application> function.  In prior releases of
<application>libpq</application>, the only way to ensure timely
receipt of NOTIFY messages was to constantly submit queries, even
empty ones, and then check <function>PQnotifies()</function> after
each <function>PQexec()</function>.  While this still works, it is
deprecated as a waste of processing power.
-->
<function>PQnotifies()</function>は実際にバックエンドのデータを読み出すわけではありません。これは単に、他の<application>libpq</application>関数が吸収してしまっていた通知メッセージを返すだけです。以前のリリースでは、通知メッセージを適切な時点で確実に受け取るには、空の問い合わせでもなんでも、とにかく一定時間ごとに問い合わせを送り、そして<function>PQexec()</function>を実行するたびに<function>PQnotifies()</function>をチェックするしかありませんでした。今でもこの方法は動作しますが、処理能力の無駄使いをすることになるのでやめておくべきでしょう。
</para>
<para>
<!--
A better way to check for NOTIFY
messages when you have no useful queries to make is to call
<function>PQconsumeInput()</function>, then check
<function>PQnotifies()</function>.
You can use <function>select</function>(2) to wait for backend data to
arrive, thereby using no <acronym>CPU</acronym> power unless there is
something to do.  (See <function>PQsocket()</function> to obtain the
file descriptor number to use with <function>select</function>.)
Note that this will work OK whether you submit queries with
<function>PQsendQuery</function>/<function>PQgetResult</function> or
simply use <function>PQexec</function>.  You should, however, remember
to check <function>PQnotifies()</function> after each
<function>PQgetResult</function> or <function>PQexec</function>, to see
if any notifications came in during the processing of the query.
-->
実行するべき問い合わせがないときに通知メッセージをチェックするよい方法は、まず<function>PQconsumeInput()</function>を呼び出し、それから<function>PQnotifies()</function>をチェックすることです。バックエンドからのデータの到着を<function>select</function>(2)で待つことができ、不必要な動作で<acronym>CPU</acronym>パワーを消費してしまうことがありません（<function>select</function>で使用するファイル識別子番号の取得については、<function>PQsocket()</function>を参照してください）。なお、これは問い合わせに<function>PQsendQuery</function>と<function>PQgetResult</function>を使ったときでも、またはおなじみの<function>PQexec</function>を使ったときでも動作します。しかし通知が問い合わせの処理中に届いていないかどうか、<function>PQgetResult</function>あるいは<function>PQexec</function>の実行ごとに<function>PQnotifies()</function>を調べることを忘れないようにしておくべきです。
</para>

</sect1>

<sect1 id="libpq-copy">
<!--
<title>Functions Associated with the COPY Command</title>
-->
<title>COPYコマンドに関連した関数</title>
<indexterm><primary>libpq</primary><secondary sortas="COPYこまんどかんれんのかんすう">COPYこまんどかんれんの関数</secondary></indexterm>

<para>
<!--
 The COPY command in <productname>Postgres</productname> has options
 to  read  from or  write  to  the  network  connection  used by
 <filename>libpq</filename>.
 Therefore, functions are necessary to access this  network
 connection directly so applications may take advantage of this
 capability.
-->
<productname>Postgres</productname>のCOPYコマンドでは、<filename>libpq</filename>が使っているネットワーク接続に対して読み込み、あるいは書き込みを選ぶことができるようになっています。そこでこのネットワーク接続に直接アクセスするための関数が必要になります。もちろんアプリケーションもこの機能によって恩恵を受けるでしょう。
 </para>

<para>
<!--
 These functions should be executed only after obtaining a
 <literal>PGRES_COPY_OUT</literal>
 or <literal>PGRES_COPY_IN</literal> result object from
 <function>PQexec</function> or <function>PQgetResult</function>.
-->
これらの関数は、<function>PQexec</function>または<function>PQgetResult</function>から、<literal>PGRES_COPY_OUT</literal>または<literal>PGRES_COPY_IN</literal>結果オブジェクトを受け取った後にのみ、実行すべきです。
</para>

<itemizedlist>
<listitem>
<para>
<emphasis><function>PQgetline</function></emphasis>――
<!--
          Reads  a  newline-terminated  line  of  characters
          (transmitted  by the backend server) into a buffer
          string of size length.
-->
          改行で終端する文字列（バックエンドから送信されたもの）を長さlengthのバッファstringに読み込みます。<indexterm><primary>libpq</primary><secondary sortas="かんすう">関数</secondary><tertiary>PQgetline</tertiary></indexterm><indexterm><primary>PQgetline</primary></indexterm>
</para>

<synopsis>
int PQgetline(PGconn *conn,
              char *string,
              int length)
</synopsis>

<para>
<!--
Like <function>fgets</function>(3),  this  routine copies up to
length-1 characters into string. It is like
<function>gets</function>(3), however, in that it converts the
terminating newline into a null character.
<function>PQgetline</function> returns <literal>EOF</literal> at EOF,
0 if the entire line has been read, and 1 if the buffer is full but the
terminating newline has not yet been read.
-->
<function>fgets</function>(3)と同様、このルーチンはバッファに最大(length-1)個の文字をコピーしますが、終端の改行がNULL文字に置き換えられる点では、<function>gets</function>(3)に似ています。<function>PQgetline</function>は、ファイルの終端では<literal>EOF</literal>を、行全体が読み込まれれば0を返します。そしてまだ終端の改行が読み込まれていないうちにバッファがいっぱいになってしまった場合は1を返します。
</para>
<para>
<!--
Notice that the application must check to see if a
new line consists of  the  two characters  "&bsol;.",
which  indicates  that the backend server has finished sending
the results  of  the  copy  command.
If  the  application might
receive lines that are more than length-1  characters  long,
care is needed to be sure one recognizes the "&bsol;." line correctly
(and does not, for example, mistake the end of a long data line
for a terminator line).
The code in
<filename>
src/bin/psql/copy.c
</filename>
contains example routines that correctly handle the  copy protocol.
-->
アプリケーションは新しく読み込んだ行が、"&bsol;."という2文字であるかどうか確認しなければいけません。この2文字は、COPYコマンドの結果をバックエンドサーバーが送信し終えたことを示すものです。アプリケーションには、仮に(length-1)文字より長い行を受け取るようなことがあっても、間違いなく最終行（"&bsol;."）を認識するような配慮が必要です（またたとえば長いデータの行の切れっぱしを、最終行と取りちがえないようにもしてください）。プログラム<filename>src/bin/psql/copy.c</filename>が、COPYプロトコルを正しく処理するルーチンを持っています。
</para>
</listitem>

<listitem>
<para>
<emphasis><function>PQgetlineAsync</function></emphasis>――
<!--
          Reads  a  newline-terminated  line  of  characters
          (transmitted  by the backend server) into a buffer
          without blocking.
-->
          改行で終端する行（バックエンドから送信されたもの）を、ブロッキングなしでバッファに読み込みます。<indexterm><primary>libpq</primary><secondary sortas="かんすう">関数</secondary><tertiary>PQgetlineAsync</tertiary></indexterm><indexterm><primary>PQgetlineAsync</primary></indexterm>
</para>

<synopsis>
int PQgetlineAsync(PGconn *conn,
                   char *buffer,
                   int bufsize)
</synopsis>

<para>
<!--
This routine is similar to <function>PQgetline</function>, but it can
be used by applications
that must read COPY data asynchronously, that is without blocking.
Having issued the COPY command and gotten a <literal>PGRES_COPY_OUT</literal>
response, the
application should call <function>PQconsumeInput</function> and
<function>PQgetlineAsync</function> until the
end-of-data signal is detected.  Unlike
<function>PQgetline</function>, this routine takes responsibility for
detecting end-of-data.
On each call, <function>PQgetlineAsync</function> will return data if
a complete newline-terminated data line is available in libpq's input
buffer, or if the incoming data line is too long to fit in the buffer
offered by the caller.
Otherwise, no data is returned until the rest of the line arrives.
-->
<function>PQgetline</function>と似ていますが、このルーチンはCOPYコマンドのデータを非同期的に、つまりブロッキングなしで読み出さなければならないアプリケーションで使います。COPYコマンドを発行し、そして<literal>PGRES_COPY_OUT</literal>を受け取ったら、アプリケーションはデータ終了の合図を受け取るまで<function>PQconsumeInput</function>と<function>PQgetlineAsync</function>を呼び出し続けます。<function>PQgetline</function>と違い、このルーチンはデータ終了の検出に対して責任を持ちます。<function>PQgetlineAsync</function>が個々の呼び出しでデータを返すのは次の場合です。1つはデータ行を、改行終端の完全な形でlibpqの入力バッファから取り出すことができる場合。もう1つは、呼び出し側が用意したバッファでは受信データが長すぎて、収まりきらない場合です。一方、このような長い行の残り部分が届かない限りは、何も返しません。
</para>
<para>
<!--
The routine returns -1 if the end-of-copy-data marker has been
recognized, or 0 if no data is available, or a positive number giving
the number of bytes of data returned.  If -1 is returned, the caller
must next call <function>PQendcopy</function>, and then return to
normal processing.
The data returned will not extend beyond a newline character.  If
possible a whole line will be returned at one time.  But if the buffer
offered by the caller is too small to hold a line sent by the backend,
then a partial data line will be returned.  This can be detected by
testing whether the last returned byte is "<literal>&bsol;n</literal>" or
not.
The returned string is not null-terminated.  (If you want to add a
terminating null, be sure to pass a bufsize one smaller than the room
actually available.)
-->
このルーチンは、コピーされるデータの終端を示すマークを認識すると-1を、また何もデータがなければ0を、そしてデータを返す場合はそのバイト数を正の値で返します。もし-1が返されたら、呼び出し側は次に<function>PQendcopy</function>を呼び出さなければいけません。それから通常の処理に戻ります。返されるデータは改行文字までで、可能であれば行全体を一度に返します。しかし呼び出し側が準備したバッファが少なすぎ、バックエンドから送られてくる行を保持しておくことができない場合には、部分ごとのデータを返します。これは最後の1バイトが"<literal>&bsol;n</literal>"かどうかを確認すれば検出できます。なお、返される文字列はNULL終端にはなっていません（終端NULLをあとから付け加えるのであれば、(実際のバッファサイズ- 1)をbufsizeとして渡すようにしてください）。
</para>
</listitem>

<listitem>
<para>
<emphasis><function>PQputline</function></emphasis>――
<!--
Sends  a  null-terminated  string  to  the backend server.
Returns 0 if OK, <literal>EOF</literal> if unable to send the string.
-->
NULL終端の文字列をバックエンドサーバーに送信します。正常終了なら0を返し、文字列を送信できなかった場合は<literal>EOF</literal>を返します。<indexterm><primary>libpq</primary><secondary sortas="かんすう">関数</secondary><tertiary>PQputline</tertiary></indexterm><indexterm><primary>PQputline</primary></indexterm>
</para>

<synopsis>
int PQputline(PGconn *conn,
              const char *string);
</synopsis>

<para>
<!--
Note the application must explicitly  send  the  two
characters  "<literal>&bsol;.</literal>" on a final line  to indicate to
the backend that it has finished sending its data.
-->
アプリケーションはデータ送信の完了をバックエンドに示すために、最終行で"<literal>&bsol;.</literal>"の2文字を明示的に送信しなければいけません。
</para>
</listitem>

<listitem>
<para>
<emphasis><function>PQputnbytes</function></emphasis>――
<!--
Sends  a  non-null-terminated  string  to  the backend server.
Returns 0 if OK, EOF if unable to send the string.
-->
NULL終端されていない文字列をバックエンドサーバーに送信します。正常終了なら0を返し、文字列を送信できなかった場合はEOFを返します。<indexterm><primary>libpq</primary><secondary sortas="かんすう">関数</secondary><tertiary>PQputnbytes</tertiary></indexterm><indexterm><primary>PQputnbytes</primary></indexterm>
</para>

<synopsis>
int PQputnbytes(PGconn *conn,
                const char *buffer,
                int nbytes);
</synopsis>

<para>
<!--
This is exactly like <function>PQputline</function>, except that the
data buffer need
not be null-terminated since the number of bytes to send is
specified directly.
-->
送信するバイト数を直接指定するので、データバッファがNULL終端である必要がない点を除けば、これは<function>PQputline</function>とまったく同様のものです。
</para>
</listitem>

<listitem>
<para>
<emphasis><function>PQendcopy</function></emphasis>――
<!--
 Syncs with the backend.  This function waits until
 the  backend  has  finished  the  copy.  It should
 either be issued when the  last  string  has  been
 sent  to  the  backend using <function>PQputline</function> or when
 the last string has been  received  from  the  backend
 using <function>PGgetline</function>.  It must be issued or the
 backend may get "out of sync"  with  the  frontend.   Upon
 return from this function, the backend is ready to
 receive the next query.
 The return value is 0  on  successful  completion,
 nonzero otherwise.
-->
 バックエンドと同期します。この関数はバックエンドがコピーを完了するのを待ちます。この関数は、<function>PQputline</function>を使ったバックエンドへの文字列送信が完了した時点、あるいは<function>PGgetline</function>を使ったバックエンドからの文字列受信が完了した時点のいずれでも呼び出すべきです。さもないと、バックエンドがフロントエンドとの「同期ずれ」を起こしてしまうかもしれません。この関数から戻った時点で、バックエンドの次の問い合わせを受ける準備が整います。同期が成功すれば0を、そうでなければ0以外の値を返します。<indexterm><primary>libpq</primary><secondary sortas="かんすう">関数</secondary><tertiary>PQendcopy</tertiary></indexterm><indexterm><primary>PQendcopy</primary></indexterm>
</para>

<synopsis>
int PQendcopy(PGconn *conn);
</synopsis>


<para>
<!--
As an example:
-->
例を示します。</para>

<programlisting>
PQexec(conn, "create table foo (a int4, b char(16), d double precision)");
PQexec(conn, "copy foo from stdin");
PQputline(conn, "3&bsol;thello world&bsol;t4.5&bsol;n");
PQputline(conn,"4&bsol;tgoodbye world&bsol;t7.11&bsol;n");
...
PQputline(conn,"&bsol;&bsol;.&bsol;n");
PQendcopy(conn);
</programlisting>
</listitem>
</itemizedlist>

<para>
<!--
When using <function>PQgetResult</function>, the application should
respond to a <literal>PGRES_COPY_OUT</literal> result by executing
<function>PQgetline</function> repeatedly, followed by
<function>PQendcopy</function> after the terminator line is seen.
It should then return to the <function>PQgetResult</function> loop
until <function>PQgetResult</function> returns NULL. Similarly a
<literal>PGRES_COPY_IN</literal> result is processed by a series of
<function>PQputline</function> calls followed by
<function>PQendcopy</function>, then return to the
<function>PQgetResult</function> loop.
This arrangement will ensure that a copy in or copy out command
embedded in a series of <acronym>SQL</acronym> commands will be
executed correctly.
-->
<function>PQgetResult</function>を使う場合、アプリケーションは<function>PQgetline</function>を繰り返し呼び出して<literal>PGRES_COPY_OUT</literal>に応答し、最終行を見つけたら続いて<function>PQendcopy</function>を呼び出します。それから、<function>PQgetResult</function>がNULLを返すまで、<function>PQgetResult</function>のループに戻っておくべきです。同じように<literal>PGRES_COPY_IN</literal>は連続した<function>PQputline</function>で処理し、それから<function>PQendcopy</function>で締めくくった後に<function>PQgetResult</function>のループに戻ります。このようにすることで、一連の<acronym>SQL</acronym>コマンド群に含めたコピーイン/アウトコマンドを確実に、また正しく実行できるはずです。
</para>
<para>
<!--
Older applications are likely to submit a copy in or copy out
via <function>PQexec</function> and assume that the transaction is
done after <function>PQendcopy</function>.
This will work correctly only if the copy in/out is the only
<acronym>SQL</acronym> command in the query string.
-->
比較的古いアプリケーションでは、コピーイン/アウトを<function>PQexec</function>で実行し、<function>PQendcopy</function>の実行でトランザクションは完了する、と想定していることがよくあります。これは文字列中の<acronym>SQL</acronym>が唯一コピーイン/アウトであったときにのみ正しく動作します。
</para>

</sect1>

<sect1 id="libpq-trace">
<!--
<title><application>libpq</application> Tracing Functions</title>
-->
<title><application>libpq</application>トレース関数</title>
<indexterm><primary>libpq</primary><secondary sortas="とれーすかんすう">トレース関数</secondary></indexterm>

<itemizedlist>
<listitem>
<para>
<emphasis><function>PQtrace</function></emphasis>――
<!--
          Enable  tracing of the frontend/backend communication to a
	  debugging file stream.
-->
          フロントエンドとバックエンド間の通信トレースを開始し、デバッグ用のファイルストリームに書き出します。<indexterm><primary>libpq</primary><secondary sortas="かんすう">関数</secondary><tertiary>PQtrace</tertiary></indexterm><indexterm><primary>PQtrace</primary></indexterm>
</para>

<synopsis>
void PQtrace(PGconn *conn
             FILE *debug_port)
</synopsis>
</listitem>

<listitem>
<para>
<emphasis><function>PQuntrace</function></emphasis>――
<!--
          Disable tracing started by PQtrace
-->
          PQtraceで開始されたトレースを停止します。<indexterm><primary>libpq</primary><secondary sortas="かんすう">関数</secondary><tertiary>PQuntrace</tertiary></indexterm><indexterm><primary>PQuntrace</primary></indexterm>
</para>
<synopsis>
void PQuntrace(PGconn *conn)
</synopsis>
</listitem>
</itemizedlist>

</sect1>

<sect1 id="libpq-control">
<title>
<!--
<application>libpq</application> Control Functions</title>
-->
<application>libpq</application>制御関数</title>
<indexterm><primary>libpq</primary><secondary sortas="libpqせいぎょかんすう">libpq制御関数</secondary></indexterm>

<itemizedlist>
<listitem>
<para>
<emphasis><function>PQsetNoticeProcessor</function></emphasis>――
<!--
Control reporting of notice and warning messages generated by libpq.
-->
libpqが生成する、注意/警告メッセージの出力方法を制御します。<indexterm><primary>libpq</primary><secondary sortas="かんすう">関数</secondary><tertiary>PQsetNoticeProcessor</tertiary></indexterm><indexterm><primary>PQsetNoticeProcessor</primary></indexterm>
</para>

<synopsis>
typedef void (*PQnoticeProcessor) (void *arg, const char *message);

PQnoticeProcessor
PQsetNoticeProcessor(PGconn *conn,
                     PQnoticeProcessor proc,
                     void *arg);
</synopsis>
</listitem>
</itemizedlist>


<para>
<!--
By default, <application>libpq</application> prints "notice"
messages from the backend on <filename>stderr</filename>,
as well as a few error messages that it generates by itself.
This behavior can be overridden by supplying a callback function that
does something else with the messages.  The callback function is passed
the text of the error message (which includes a trailing newline), plus
a void pointer that is the same one passed to
<function>PQsetNoticeProcessor</function>.
(This pointer can be used to access application-specific state if needed.)
The default notice processor is simply
-->
バックエンドからの「注意」メッセージを、<application>libpq</application>はデフォルトで<filename>stderr</filename>に出力します。もちろん、わずかですがlibpq自身が生成するメッセージも、同じように出力されます。この動作は、メッセージテキストに対して何らかの処理をするコールバック関数（警告プロセッサ）を用意すれば、置き換えることができます。このコールバック関数には、エラーメッセージのテキスト（末尾に改行を含む）と、<function>PQsetNoticeProcessor</function>に渡されたvoid型のポインタがそのまま渡されます（必要であれば、このポインタをアプリケーション固有の状態を知るために使います）。デフォルトの警告プロセッサは、以下のような単純なものです。</para>

<programlisting>
static void
defaultNoticeProcessor(void * arg, const char * message)
{
    fprintf(stderr, "%s", message);
}
</programlisting>
<!--
To use a special notice processor, call
<function>PQsetNoticeProcessor</function> just after
creation of a new PGconn object.
-->
<para>特定の警告プロセッサを使うには、PGconnオブジェクトを生成したのちに、<function>PQsetNoticeProcessor</function>を呼び出すだけです。
</para>

<para>
<!--
The return value is the pointer to the previous notice processor.
If you supply a callback function pointer of NULL, no action is taken,
but the current pointer is returned.
-->
返り値は直前の警告プロセッサへのポインタです。0のコールバック関数ポインタを与えた場合は、何のアクションも得られませんが、現在のポインタを得ることができます。
</para>

<para>
<!--
Once you have set a notice processor, you should expect that that function
could be called as long as either the PGconn object or PGresult objects
made from it exist.  At creation of a PGresult, the PGconn's current
notice processor pointer is copied into the PGresult for possible use by
routines like <function>PQgetvalue</function>.
-->
一旦警告プロセッサをセットしたら、PGconnオブジェクトか、それから生成されたPGresultオブジェクトが存在している間は、その関数が呼び出される可能性があると考えておくべきです。PGresultの生成時には、PGconnの現在の警告プロセッサのポインタが、<function>PQgetvalue</function>のようなルーチンで使用可能であるように、PGresultへコピーされます。
</para>

</sect1>

<sect1 id="libpq-multibyte">

<title>マルチバイトサポート関数</title>
<indexterm><primary>libpq</primary><secondary sortas="まるちばいとさぽーとかんすう">マルチバイトサポート関数</secondary></indexterm>

<para>
本節では、マルチバイトサポートを有効にした場合に利用できる関数を説明します。

</para>

<itemizedlist>
<listitem>
<para>
<emphasis><function>PQsetClientEncoding</function></emphasis>――

クライアント側のエンコーディングを設定します。<indexterm><primary>libpq</primary><secondary sortas="かんすう">関数</secondary><tertiary>PQsetClientEncoding</tertiary></indexterm><indexterm><primary>PQsetClientEncoding</primary></indexterm>

</para>

<synopsis>
int PQsetClientEncoding(PGconn *<replaceable>conn</replaceable>, const char *<replaceable>encoding</replaceable>)
</synopsis>

<para>
<replaceable>conn</replaceable>とはバックエンドとの接続を意味し、<replaceable>encoding</replaceable>は使用したいエンコーディングを意味します。エンコーディングの設定に成功すると0を返し、失敗すると-1を返します。
</para>
</listitem>

<listitem>
<para>
<emphasis><function>PQclientEncoding</function></emphasis>――

現在の接続のエンコーディングIDを取得します。<indexterm><primary>libpq</primary><secondary sortas="かんすう">関数</secondary><tertiary>PQclientEncoding</tertiary></indexterm><indexterm><primary>PQclientEncoding</primary></indexterm>

</para>

<synopsis>
int PQclientEncoding(const PGconn *<replaceable>conn</replaceable>)
</synopsis>

</listitem>

<listitem>
<para>
<emphasis><function>pg_encoding_to_char</function></emphasis>――

エンコーディングIDをエンコーディング名に変換します。<indexterm><primary>libpq</primary><secondary sortas="かんすう">関数</secondary><tertiary>pg_encoding_to_char</tertiary></indexterm><indexterm><primary>pg_encoding_to_char</primary></indexterm>
</para>

<synopsis>
char *pg_encoding_to_char(int <replaceable>encoding_id</replaceable>)
</synopsis>

</listitem>

<listitem>
<para>
<emphasis><function>pg_char_to_encoding</function></emphasis>――

エンコーディング名をエンコーディングIDに変換します。<indexterm><primary>libpq</primary><secondary sortas="かんすう">関数</secondary><tertiary>pg_char_to_encoding</tertiary></indexterm><indexterm><primary>pg_char_to_encoding</primary></indexterm>

</para>
<synopsis>
int pg_char_to_encoding(char *<replaceable>encoding</replaceable>)
</synopsis>

</listitem>

</itemizedlist>

</sect1>

<sect1 id="libpq-envars">
<!--
<title>Environment Variables</title>
-->
<title>環境変数</title>
<indexterm><primary>libpq</primary><secondary sortas="かんきょうへんすう">環境変数</secondary></indexterm>

<para>
<!--
The following environment variables can be used to select default
connection parameter values, which will be used by
<function>PQconnectdb</function> or <function>PQsetdbLogin</function>
if no value is directly specified by the calling code.
These are useful to avoid hard-coding database names into simple
application programs.
-->
以下の環境変数は、プログラムが<function>PQconnectdb</function>または<function>PQsetdbLogin</function>の接続パラメータの値を明確に指定しなかった場合、接続パラメータのデフォルト値として使われます。簡単なアプリケーションプログラムでシステム既定値以外のデータベース名を選ぶのに便利です。
</para>

<itemizedlist>
<listitem>
<para>
<!--
<envar>PGHOST</envar> sets the default server name.
If this begins with a slash, it specifies Unix-domain communication
rather than TCP/IP communication; the value is the name of the
directory in which the socket file is stored (default "/tmp").
-->
<emphasis><envar>PGHOST</envar></emphasis>――デフォルトサーバー名を指定します。スラッシュ（/）で始まっている場合は、TCP/IP通信ではなく、UNIXドメインの通信を明示的に指定したことになります。そしてその値はソケットファイルが格納されているディレクトリ名（デフォルトは"/tmp"）です。<indexterm><primary>PGHOST</primary></indexterm><indexterm><primary sortas="かんきょうへんすう">環境変数</primary><secondary>PGHOST</secondary></indexterm>
</para>
</listitem>
<listitem>
<para>
<!--
<envar>PGPORT</envar> sets the default TCP port number or Unix-domain
socket file extension for communicating with the
<productname>Postgres</productname> backend.
-->
<emphasis><envar>PGPORT</envar></emphasis>――デフォルトの<productname>Postgres</productname>
バックエンドとのTCP通信ポート番号あるいはUNIXドメインソケットファイルの拡張子を指定します。<indexterm><primary>PGPORT</primary></indexterm><indexterm><primary sortas="かんきょうへんすう">環境変数</primary><secondary>PGPORT</secondary></indexterm>
</para>
</listitem>
<listitem>
<para>
<!--
<envar>PGDATABASE</envar>  sets the default 
<productname>Postgres</productname> database name.
-->
<emphasis><envar>PGDATABASE</envar></emphasis>――デフォルトの<productname>Postgres</productname>のデータベース名を指定します。<indexterm><primary>PGDATABASE</primary></indexterm><indexterm><primary sortas="かんきょうへんすう">環境変数</primary><secondary>PGDATABASE</secondary></indexterm>
</para>
</listitem>
<listitem>
<para>
<!--
<envar>PGUSER</envar>
sets the username used to connect to the database and for authentication.
-->
<emphasis><envar>PGUSER</envar></emphasis>――データベースの接続と認証に使われるユーザー名を指定します。<indexterm><primary>PGUSER</primary></indexterm><indexterm><primary sortas="かんきょうへんすう">環境変数</primary><secondary>PGUSER</secondary></indexterm>
</para>
</listitem>
<listitem>
<para>
<!--
<envar>PGPASSWORD</envar>
sets the password used if the backend demands password authentication.
-->
<emphasis><envar>PGPASSWORD</envar></emphasis>――バックエンドがパスワード認証を要求した場合に使われるパスワードを指定します。<indexterm><primary>PGPASSWORD</primary></indexterm><indexterm><primary sortas="かんきょうへんすう">環境変数</primary><secondary>PGPASSWORD</secondary></indexterm>
</para>
</listitem>
<listitem>
<para>
<!--
<envar>PGREALM</envar> sets the Kerberos realm to  use  with  
<productname>Postgres</productname>, if  it is different from the
local realm.
If <envar>PGREALM</envar> is set, <productname>Postgres</productname> 
applications  will  attempt authentication  with  servers for this
realm and use separate ticket files to avoid conflicts with  local
ticket  files.   This  environment  variable is only
used if Kerberos authentication is selected by the backend.
-->
<emphasis><envar>PGREALM</envar></emphasis>――<productname>Postgres</productname>で使うKerberosのrealmがローカルのものと異なる場合に、そのrealmを指定します。<envar>PGREALM</envar>が設定された場合は、<productname>Postgres</productname>は指定されたrealmのサーバーと認証を行おうとし、別のチケットファイルを使って、ローカルのチケットファイルと競合しないようにします。この環境変数はバックエンドがKerberosによる認証を選択した場合にのみ使われます。<indexterm><primary>PGREALM</primary></indexterm><indexterm><primary sortas="かんきょうへんすう">環境変数</primary><secondary>PGREALM</secondary></indexterm>
</para>
</listitem>
<listitem>
<para>
<!--
<envar>PGOPTIONS</envar> sets additional runtime  options  for  
the <productname>Postgres</productname> backend.
-->
<emphasis><envar>PGOPTIONS</envar></emphasis>――<productname>Postgres</productname>バックエンドに対して、追加するランタイムオプションを指定します。<indexterm><primary>PGOPTIONS</primary></indexterm><indexterm><primary sortas="かんきょうへんすう">環境変数</primary><secondary>PGOPTIONS</secondary></indexterm>
</para>
</listitem>
<listitem>
<para>
<!--
<envar>PGTTY</envar> sets the file or tty on which  debugging  
messages from the backend server are displayed.
-->
<emphasis><envar>PGTTY</envar></emphasis>――バックエンドサーバーのデバッグメッセージを出力するファイル、あるいはttyを指定します。<indexterm><primary>PGTTY</primary></indexterm><indexterm><primary sortas="かんきょうへんすう">環境変数</primary><secondary>PGTTY</secondary></indexterm>
</para>
</listitem>
</itemizedlist>

<para>
<!--
The following environment variables can be used to specify user-level
default behavior for every Postgres session:
-->
以下の環境変数は、Postgresとのセッションにおける、ユーザーレベルのデフォルト動作を指定するのに使います。
</para>

<itemizedlist>
<listitem>
<para>
<!--
<envar>PGDATESTYLE</envar>
sets the default style of date/time representation.
-->
<emphasis><envar>PGDATESTYLE</envar></emphasis>――デフォルトの日付表示スタイルを指定します。<indexterm><primary>PGDATESTYLE</primary></indexterm><indexterm><primary sortas="かんきょうへんすう">環境変数</primary><secondary>PGDATESTYLE</secondary></indexterm>
</para>
</listitem>
<listitem>
<para>
<!--
<envar>PGTZ</envar>
sets the default time zone.
-->
<emphasis><envar>PGTZ</envar></emphasis>――デフォルトのタイムゾーンを指定します。<indexterm><primary>PGTZ</primary></indexterm><indexterm><primary sortas="かんきょうへんすう">環境変数</primary><secondary>PGTZ</secondary></indexterm>
</para>
</listitem>
<listitem>
<para>
<!--
<envar>PGCLIENTENCODING</envar>
sets the default client encoding (if MULTIBYTE support was selected
when configuring Postgres).
-->
<emphasis><envar>PGCLIENTENCODING</envar></emphasis>――クライアントのデフォルトのエンコーディングを指定します（Postgresをconfigureした際にマルチバイトのサポートを選択している場合）。<indexterm><primary>PGCLIENTENCODING</primary></indexterm><indexterm><primary sortas="かんきょうへんすう">環境変数</primary><secondary>PGCLIENTENCODING</secondary></indexterm>
</para>
</listitem>
</itemizedlist>

<para>
<!--
The following environment variables can be used to specify default internal
behavior for every Postgres session:
-->
以下の環境変数は、個々のPostgresとのセッションにおける、デフォルトの内部動作を指定するのに使います。
</para>

<itemizedlist>
<listitem>
<para>
<!--
<envar>PGGEQO</envar>
sets the default mode for the genetic optimizer.
-->
<emphasis><envar>PGGEQO</envar></emphasis>――遺伝的アルゴリズムよるオプティマイザの動作モードを指定します。<indexterm><primary>PGGEQO</primary></indexterm><indexterm><primary sortas="かんきょうへんすう">環境変数</primary><secondary>PGGEQO</secondary></indexterm>
</para>
</listitem>
</itemizedlist>

<para>
<!--
Refer to the <command>SET</command> <acronym>SQL</acronym> command
for information on correct values for these environment variables.
-->
これらの環境変数の正しい設定値については、<acronym>SQL</acronym>の<command>SET</command>コマンドを参照してください。
</para>

</sect1>

<sect1 id="libpq-threading">
<!--
<title>Threading Behavior</title>
-->
<title>スレッドの振る舞い</title>
<indexterm><primary>libpq</primary><secondary sortas="すれっどのふるまい">スレッドの振る舞い</secondary></indexterm>

<para>
<!--
<filename>libpq</filename> is thread-safe as of
<productname>Postgres</productname> 7.0, so long as no two threads
attempt to manipulate the same PGconn object at the same time.  In
particular, you can't issue concurrent queries from different threads
through the same connection object.  (If you need to run concurrent
queries, start up multiple connections.)
-->
<filename>libpq</filename>は、<productname>Postgres</productname> 7.0現在、同時に同じPGconnオブジェクトを操作するスレッドがない、という条件下では、スレッドセーフです。特に、異なるスレッドから、同じ接続オブジェクトを通して同時に問い合わせを発行することはできません（同時に問い合わせを実行する必要がある場合は、接続は複数にしてください）。
</para>

<para>
<!--
PGresult objects are read-only after creation, and so can be passed
around freely between threads.
-->
PGresultオブジェクトは生成されると読み込み専用です。したがって、スレッド間を自由に渡ることができます。
</para>

<para>
<!--
The deprecated functions <function>PQoidStatus</function> and
<function>fe_setauthsvc</function> are not thread-safe and should not be
used in multi-thread programs.  <function>PQoidStatus</function> can be
replaced by <function>PQoidValue</function>.  There is no good reason to
call <function>fe_setauthsvc</function> at all.
-->
推奨されない関数<function>PQoidStatus</function>や<function>fe_setauthsvc</function>はスレッドセーフではなく、またマルチスレッドプログラムで使用すべきではありません。<function>PQoidStatus</function>は<function>PQoidValue</function>に置き換えることができます。いかなる場合においても、<function>fe_setauthsvc</function>は呼び出すべきではありません。
</para>

</sect1>


 <sect1 id="libpq-example">
<!--
  <title>Example Programs</title>
-->
  <title>サンプルプログラム</title>
<indexterm><primary>libpq</primary><secondary sortas="さんぷるぷろぐらむ">サンプルプログラム</secondary></indexterm>

  <example id="libpq-example-1">
<!--
   <title>libpq Example Program 1</title>
-->
   <title>libpqサンプルプログラム1</title>

<programlisting>
/*
 * testlibpq.c
 *
<!--
 * Test the C version of libpq, the PostgreSQL frontend
 * library.
-->
 * PostgreSQLフロントエンドライブラリlibpq
 * Cバージョンのテスト
 */
#include &lt;stdio.h&gt;
#include &lt;libpq-fe.h&gt;

void
exit_nicely(PGconn *conn)
{
    PQfinish(conn);
    exit(1);
}

main()
{
    char       *pghost,
               *pgport,
               *pgoptions,
               *pgtty;
    char       *dbName;
    int         nFields;
    int         i,
                j;

    /* FILE *debug; */

    PGconn     *conn;
    PGresult   *res;

<!--    /*
     * begin, by setting the parameters for a backend connection if the
     * parameters are null, then the system will try to use reasonable
     * defaults by looking up environment variables or, failing that,
     * using hardwired constants
     */-->
    /*
     * バックエンドとの接続に必要なパラメータをセットしてプログラムを
     * 開始します。
     * パラメータが NULL であれば、環境変数を探して妥当と思われる値を
     * 使おうとしますが、見付からない場合は、システムデフォルトの値を
     * 使います。
     */
<!--    pghost = NULL;              /* host name of the backend server */
    pgport = NULL;              /* port of the backend server */
    pgoptions = NULL;           /* special options to start up the backend
                                 * server */
    pgtty = NULL;               /* debugging tty for the backend server */
    dbName = "template1";-->
    pghost = NULL;              /* バックエンドサーバーが動作しているホスト名 */
    pgport = NULL;              /* バックエンドサーバーのポート番号 */
    pgoptions = NULL;           /* バックエンドのスタートアップオプション */
    pgtty = NULL;               /* バックエンドのデバッグ用 tty */
    dbName = "template1";

<!--    /* make a connection to the database */-->
    /* データベースへ接続 */
    conn = PQsetdb(pghost, pgport, pgoptions, pgtty, dbName);

<!--    /*
     * check to see that the backend connection was successfully made
     */-->
    /*
     * バックエンドとの接続が成功したことを確認
     */
    if (PQstatus(conn) == CONNECTION_BAD)
    {
        fprintf(stderr, "Connection to database '%s' failed.&bsol;n", dbName);
        fprintf(stderr, "%s", PQerrorMessage(conn));
        exit_nicely(conn);
    }

    /* debug = fopen("/tmp/trace.out","w"); */
    /* PQtrace(conn, debug);  */

<!--    /* start a transaction block */-->
    /* トランザクションブロックの開始 */
    res = PQexec(conn, "BEGIN");
    if (!res || PQresultStatus(res) != PGRES_COMMAND_OK)
    {
        fprintf(stderr, "BEGIN command failed&bsol;n");
        PQclear(res);
        exit_nicely(conn);
    }

<!--    /*
     * should PQclear PGresult whenever it is no longer needed to avoid
     * memory leaks
     */-->
    /*
     * メモリリークを防ぐため、必要がなくなったら、すぐに
     * PQclear(PGresult) しましょう
     */
    PQclear(res);

<!--    /*
     * fetch rows from the pg_database, the system catalog of
     * databases
     */-->
    /*
     * データベースのシステムカタログ、pg_database からインスタンスを
     * 取り出す
     */
    res = PQexec(conn, "DECLARE mycursor CURSOR FOR select * from pg_database");
    if (!res || PQresultStatus(res) != PGRES_COMMAND_OK)
    {
        fprintf(stderr, "DECLARE CURSOR command failed&bsol;n");
        PQclear(res);
        exit_nicely(conn);
    }
    PQclear(res);
    res = PQexec(conn, "FETCH ALL in mycursor");
    if (!res || PQresultStatus(res) != PGRES_TUPLES_OK)
    {
        fprintf(stderr, "FETCH ALL command didn't return tuples properly&bsol;n");
        PQclear(res);
        exit_nicely(conn);
    }

<!--    /* first, print out the attribute names */-->
    /* まず属性名を表示 */
    nFields = PQnfields(res);
    for (i = 0; i &lt; nFields; i++)
        printf("%-15s", PQfname(res, i));
    printf("&bsol;n&bsol;n");

<!--    /* next, print out the rows */-->
    /* 次にインスタンスを表示 */
    for (i = 0; i &lt; PQntuples(res); i++)
    {
        for (j = 0; j &lt; nFields; j++)
            printf("%-15s", PQgetvalue(res, i, j));
        printf("&bsol;n");
    }
    PQclear(res);

<!--    /* close the cursor */-->
    /* カーソルを閉じる */
    res = PQexec(conn, "CLOSE mycursor");
    PQclear(res);

<!--    /* commit the transaction */-->
    /* トランザクションをコミットする */
    res = PQexec(conn, "COMMIT");
    PQclear(res);

<!--    /* close the connection to the database and cleanup */-->
    /* バックエンドとの接続を閉じ、後始末 */
    PQfinish(conn);

    /* fclose(debug); */
    return 0;

}
</programlisting>
  </example>

  <example id="libpq-example-2">
<!--
   <title>libpq Example Program 2</title>
-->
   <title>libpqサンプルプログラム2</title>
<indexterm><primary>libpq</primary><secondary sortas="さんぷるぷろぐらむ">サンプルプログラム</secondary></indexterm>

<programlisting>
<!--/*
 * testlibpq2.c
 *  Test of the asynchronous notification interface
 *
 * Start this program, then from psql in another window do
 *   NOTIFY TBL2;
 *
 * Or, if you want to get fancy, try this:
 * Populate a database with the following:
 *
 *   CREATE TABLE TBL1 (i int4);
 *
 *   CREATE TABLE TBL2 (i int4);
 *
 *   CREATE RULE r1 AS ON INSERT TO TBL1 DO
 *     (INSERT INTO TBL2 values (new.i); NOTIFY TBL2);
 *
 * and do
 *
 *   INSERT INTO TBL1 values (10);
 *
 */-->
/*
 * testlibpq2.c
 *  非同期通知のインターフェイスのテスト
 *
 * まずこのプログラムを実行し、それから他のウィンドウで psql から
 *
 *   NOTIFY TBL2;
 *
 * としてみてください。
 *
 * もうちょっと凝ってみたい場合は、次のようにします。
 * まず以下のようなデータベースを作ります。
 *
 *   CREATE TABLE TBL1 (i int4);
 *
 *   CREATE TABLE TBL2 (i int4);
 *
 *   CREATE RULE r1 AS ON INSERT TO TBL1 DO
 *     (INSERT INTO TBL2 values (new.i); NOTIFY TBL2);
 *
 * そして
 *
 *   INSERT INTO TBL1 values (10);
 *
 * としてください。
 *
 */
#include &lt;stdio.h&gt;
#include "libpq-fe.h"

void
exit_nicely(PGconn *conn)
{
    PQfinish(conn);
    exit(1);
}

main()
{
    char       *pghost,
               *pgport,
               *pgoptions,
               *pgtty;
    char       *dbName;

    PGconn     *conn;
    PGresult   *res;
    PGnotify   *notify;

<!--    /*
     * begin, by setting the parameters for a backend connection if the
     * parameters are null, then the system will try to use reasonable
     * defaults by looking up environment variables or, failing that,
     * using hardwired constants
     */-->
    /*
     * バックエンドとの接続に必要なパラメータをセットしてプログラムを
     * 開始します。
     * パラメータが NULL であれば、環境変数を探して妥当と思われる値を
     * 使おうとしますが、見つからない場合は、システムデフォルトの定数
     * を使います。
     */
<!--    pghost = NULL;              /* host name of the backend server */
    pgport = NULL;              /* port of the backend server */
    pgoptions = NULL;           /* special options to start up the backend
                                 * server */
    pgtty = NULL;               /* debugging tty for the backend server */
    dbName = getenv("USER");    /* change this to the name of your test
                                 * database */-->
    pghost = NULL;              /* バックエンドが動作しているホスト名 */
    pgport = NULL;              /* バックエンドのポート番号 */
    pgoptions = NULL;           /* バックエンドのスタートアップオプション */
    pgtty = NULL;               /* バックエンドのデバッグ用の tty */
    dbName = getenv("USER");    /* これは読者のテスト用データベースの名前に
                                   適宜置き換えてください */
                                 

<!--    /* make a connection to the database */-->
    /* データベースへ接続 */
    conn = PQsetdb(pghost, pgport, pgoptions, pgtty, dbName);

<!--    /*
     * check to see that the backend connection was successfully made
     */-->
    /*
     * バックエンドとの接続が成功したことを確認
     */
    if (PQstatus(conn) == CONNECTION_BAD)
    {
        fprintf(stderr, "Connection to database '%s' failed.&bsol;n", dbName);
        fprintf(stderr, "%s", PQerrorMessage(conn));
        exit_nicely(conn);
    }

    res = PQexec(conn, "LISTEN TBL2");
    if (!res || PQresultStatus(res) != PGRES_COMMAND_OK)
    {
        fprintf(stderr, "LISTEN command failed&bsol;n");
        PQclear(res);
        exit_nicely(conn);
    }

<!--    /*
     * should PQclear PGresult whenever it is no longer needed to avoid
     * memory leaks
     */-->
    /*
     * メモリリークを防ぐため、必要がなくなったら、すぐに
     * PQclear(PGresult) しましょう
     */
    PQclear(res);

    while (1)
    {

<!--        /*
         * wait a little bit between checks; waiting with select()
         * would be more efficient.
         */-->
        /*
         * チェックの繰り返しの間、ちょっとだけ待ち時間を入れます。
         * select() で待ち時間を入れればより効果的になります。
         */
        sleep(1);
<!--        /* collect any asynchronous backend messages */-->
        /* バックエンドの非同期メッセージを取りこむ */
        PQconsumeInput(conn);
<!--        /* check for asynchronous notify messages */-->
        /* 非同期通知メッセージのチェック */
        while ((notify = PQnotifies(conn)) != NULL)
        {
            fprintf(stderr,
                 "ASYNC NOTIFY of '%s' from backend pid '%d' received&bsol;n",
                    notify-&gt;relname, notify-&gt;be_pid);
            free(notify);
        }
    }
}
</programlisting>
  </example>

  <example id="libpq-example-3">
<!--
   <title>libpq Example Program 3</>
-->
   <title>libpqサンプルプログラム3</>
<indexterm><primary>libpq</primary><secondary sortas="さんぷるぷろぐらむ">サンプルプログラム</secondary></indexterm>

<programlisting>
<!--/*
 * testlibpq3.c Test the C version of Libpq, the Postgres frontend
 * library. tests the binary cursor interface
 *
 *
 *
 * populate a database by doing the following:
 *
 * CREATE TABLE test1 (i int4, d real, p polygon);
 *
 * INSERT INTO test1 values (1, 3.567, polygon '(3.0, 4.0, 1.0, 2.0)');
 *
 * INSERT INTO test1 values (2, 89.05, polygon '(4.0, 3.0, 2.0, 1.0)');
 *
 * the expected output is:
 *
 * tuple 0: got i = (4 bytes) 1, d = (4 bytes) 3.567000, p = (4
 * bytes) 2 points   boundbox = (hi=3.000000/4.000000, lo =
 * 1.000000,2.000000) tuple 1: got i = (4 bytes) 2, d = (4 bytes)
 * 89.050003, p = (4 bytes) 2 points   boundbox =
 * (hi=4.000000/3.000000, lo = 2.000000,1.000000)
 *
 *
 */-->
/*
 * testlibpq3.c Postgres フロントエンドライブラリ libpq
 *              C バージョンのテスト
 *              バイナリカーソルのテスト
 *
 *
 *
 * まず以下のようなデータベースを作ります。
 *
 * CREATE TABLE test1 (i int4, d real, p polygon);
 *
 * INSERT INTO test1 values (1, 3.567, polygon '(3.0, 4.0, 1.0, 2.0)');
 *
 * INSERT INTO test1 values (2, 89.05, polygon '(4.0, 3.0, 2.0, 1.0)');
 *
 * 出力は以下のようになるはずです。
 *
 * tuple 0: got
 * i = (4 bytes) 1,
 * d = (4 bytes) 3.567000,
 * p = (4 bytes) 2 points   boundbox = (hi=3.000000/4.000000,
 * lo =1.000000,2.000000)
 * tuple 1: got
 * i = (4 bytes) 2,
 * d = (4 bytes) 89.050003,
 * p = (4 bytes) 2 points   boundbox = (hi=4.000000/3.000000,
 * lo = 2.000000,1.000000)
 *
 *
 */
#include &lt;stdio.h&gt;
#include "libpq-fe.h"
<!--#include "utils/geo-decls.h"    /* for the POLYGON type */-->
#include "utils/geo-decls.h"    /* POLYGON型を使うのに必要 */

void
exit_nicely(PGconn *conn)
{
    PQfinish(conn);
    exit(1);
}

main()
{
    char       *pghost,
               *pgport,
               *pgoptions,
               *pgtty;
    char       *dbName;
    int         nFields;
    int         i,
                j;
    int         i_fnum,
                d_fnum,
                p_fnum;
    PGconn     *conn;
    PGresult   *res;

<!--    /*
     * begin, by setting the parameters for a backend connection if the
     * parameters are null, then the system will try to use reasonable
     * defaults by looking up environment variables or, failing that,
     * using hardwired constants
     */-->
    /*
     * バックエンドとの接続に必要なパラメータをセットしてプログラムを
     * 開始します。
     * パラメータが NULL であれば、環境変数を探して妥当と思われる値を
     * 使おうとしますが、見つからない場合は、システムデフォルトの定数
     * を使います。
     */
<!--    pghost = NULL;              /* host name of the backend server */
    pgport = NULL;              /* port of the backend server */
    pgoptions = NULL;           /* special options to start up the backend
                                 * server */
    pgtty = NULL;               /* debugging tty for the backend server */

    dbName = getenv("USER");    /* change this to the name of your test
                                 * database */-->
    pghost = NULL;              /* バックエンドサーバーのホスト名 */
    pgport = NULL;              /* バックエンドのポート番号 */
    pgoptions = NULL;           /* バックエンドのスタートアップオプション*/
    pgtty = NULL;               /* バックエンドのデバッグ用 tty */

    dbName = getenv("USER");    /* これは読者のテスト用データベースの
                                   名前に適宜置き換えてください。*/

<!--    /* make a connection to the database */-->
    /* データベースに接続します */
    conn = PQsetdb(pghost, pgport, pgoptions, pgtty, dbName);

<!--    /*
     * check to see that the backend connection was successfully made
     */-->
    /*
     * バックエンドとの接続が成功したことを確認
     */
    if (PQstatus(conn) == CONNECTION_BAD)
    {
        fprintf(stderr, "Connection to database '%s' failed.&bsol;n", dbName);
        fprintf(stderr, "%s", PQerrorMessage(conn));
        exit_nicely(conn);
    }

<!--    /* start a transaction block */-->
    /* トランザクションブロックの開始 */
    res = PQexec(conn, "BEGIN");
    if (!res || PQresultStatus(res) != PGRES_COMMAND_OK)
    {
        fprintf(stderr, "BEGIN command failed&bsol;n");
        PQclear(res);
        exit_nicely(conn);
    }

<!--    /*
     * should PQclear PGresult whenever it is no longer needed to avoid
     * memory leaks
     */-->
    /*
     * メモリリークを防ぐため、必要がなくなったら、すぐに
     * PQclear(PGresult) しましょう
     */
    PQclear(res);

<!--    /*
     * fetch rows from the pg_database, the system catalog of
     * databases
     */-->
    /*
     * データベースのシステムカタログ、pg_database からインスタンスを
     * 取り出す
     */
   res = PQexec(conn, "DECLARE mycursor BINARY CURSOR FOR select * from test1");
    if (!res || PQresultStatus(res) != PGRES_COMMAND_OK)
    {
        fprintf(stderr, "DECLARE CURSOR command failed&bsol;n");
        PQclear(res);
        exit_nicely(conn);
    }
    PQclear(res);

    res = PQexec(conn, "FETCH ALL in mycursor");
    if (!res || PQresultStatus(res) != PGRES_TUPLES_OK)
    {
        fprintf(stderr, "FETCH ALL command didn't return tuples properly&bsol;n");
        PQclear(res);
        exit_nicely(conn);
    }

    i_fnum = PQfnumber(res, "i");
    d_fnum = PQfnumber(res, "d");
    p_fnum = PQfnumber(res, "p");

    for (i = 0; i &lt; 3; i++)
    {
        printf("type[%d] = %d, size[%d] = %d&bsol;n",
               i, PQftype(res, i),
               i, PQfsize(res, i));
    }
    for (i = 0; i &lt; PQntuples(res); i++)
    {
        int        *ival;
        float      *dval;
        int         plen;
        POLYGON    *pval;

<!--        /* we hard-wire this to the 3 fields we know about */-->
        /*
     * テーブル上の3つのフィールドの型はわかっているので
     * ここでは変数に直接結び付けます
     */
        ival = (int *) PQgetvalue(res, i, i_fnum);
        dval = (float *) PQgetvalue(res, i, d_fnum);
        plen = PQgetlength(res, i, p_fnum);

<!--        /*
         * plen doesn't include the length field so need to
         * increment by VARHDSZ
         */-->
        /*
         * planはフィールド長の分を含んでいないので、VARHDSZ を
         * 加えます
         */
        pval = (POLYGON *) malloc(plen + VARHDRSZ);
        pval-&gt;size = plen;
        memmove((char *) &amp;pval-&gt;npts, PQgetvalue(res, i, p_fnum), plen);
        printf("tuple %d: got&bsol;n", i);
        printf(" i = (%d bytes) %d,&bsol;n",
               PQgetlength(res, i, i_fnum), *ival);
        printf(" d = (%d bytes) %f,&bsol;n",
               PQgetlength(res, i, d_fnum), *dval);
        printf(" p = (%d bytes) %d points &bsol;tboundbox = (hi=%f/%f, lo = %f,%f)&bsol;n",
               PQgetlength(res, i, d_fnum),
               pval-&gt;npts,
               pval-&gt;boundbox.xh,
               pval-&gt;boundbox.yh,
               pval-&gt;boundbox.xl,
               pval-&gt;boundbox.yl);
    }
    PQclear(res);

<!--    /* close the cursor */-->
    /* カーソルを閉じる */
    res = PQexec(conn, "CLOSE mycursor");
    PQclear(res);

<!--    /* commit the transaction */-->
    /* トランザクションをコミット */
    res = PQexec(conn, "COMMIT");
    PQclear(res);

<!--    /* close the connection to the database and cleanup */-->
    /* データベースとの接続を閉じ、後始末 */
    PQfinish(conn);

    return 0;
}
</programlisting>
  </example>

 </sect1>
</chapter>

<!-- Keep this comment at the end of the file
Local variables:
mode:sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"./reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:("/usr/lib/sgml/catalog")
sgml-local-ecat-files:nil
End:
-->
