<!--
doc/src/sgml/ref/pgproto.sgml
Pgpool-II documentation
-->

<refentry id="PGPROTO">
 <indexterm zone="pgproto">
  <primary>pgproto</primary>
 </indexterm>

 <refmeta>
  <refentrytitle>pgproto</refentrytitle>
  <manvolnum>1</manvolnum>
  <!--
  <refmiscinfo>Other Commands</refmiscinfo>
  -->
  <refmiscinfo>他のコマンド</refmiscinfo>
 </refmeta>

 <refnamediv>
  <refname>pgproto</refname>
  <refpurpose>
   <!--
   tests <productname>PostgreSQL</productname> or any other servers that understand the frontend/backend protocol.
   -->
   PostgreSQL もしくはフロントエンド/バックエンドプロトコルを理解しているサーバに対してテストする
  </refpurpose>
 </refnamediv>

 <refsynopsisdiv>
  <cmdsynopsis>
   <command>pgproto</command>
   <arg rep="repeat"><replaceable>option</replaceable></arg>
  </cmdsynopsis>
 </refsynopsisdiv>

 <refsect1 id="R1-PGPROTO-1">
  <!--
  <title>Description</title>
  -->
  <title>説明</title>
  <para>
   <command>pgproto</command>
   <!--
   tests <productname>PostgreSQL</productname> or any other servers that understand the frontend/backend protocol.
   -->
   PostgreSQL もしくはフロントエンド/バックエンドプロトコルを理解しているサーバに対してテストします
  </para>
 </refsect1>

 <refsect1>
  <!--
  <title>Options</title>
  -->
  <title>オプション</title>
  <para>
   <variablelist>
    <varlistentry>
     <term><option>-h <replaceable class="parameter">hostname</replaceable></option></term>
     <term><option>--hostname=<replaceable class="parameter">hostname</replaceable></option></term>
     <listitem>
      <para>
       <!--
       The host name of the machine on which the server is running. If the value begins with a slash, it is used as the directory for the Unix-domain socket (default: Unix-domain socket).
       -->
       サーバが稼働しているマシンのホスト名。
       "/"からホスト名が始まる場合、Unixドメインソケットのディレクトリとして使用されます (デフォルト: unixドメインソケット)。
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><option>-p <replaceable class="parameter">port</replaceable></option></term>
     <term><option>--port=<replaceable class="parameter">port</replaceable></option></term>
     <listitem>
      <para>
       <!--
       The port number (default:5432).
       -->
       ポート番号 (デフォルト:5432)
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><option>-u <replaceable class="parameter">username</replaceable></option></term>
     <term><option>--user=<replaceable class="parameter">username</replaceable></option></term>
     <listitem>
      <para>
       <!--
       The user name (default: OS user name).
       -->
       ユーザ名 (デフォルト: OSユーザ名)
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><option>-d <replaceable class="parameter">databasename</replaceable></option></term>
     <term><option>--database=<replaceable class="parameter">databasename</replaceable></option></term>
     <listitem>
      <para>
       <!--
       The database name (default: same as user).
       -->
       データベース名 (デフォルト: ユーザ名)
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><option>-f <replaceable class="parameter">filename</replaceable></option></term>
     <term><option>--proto-data-file=<replaceable class="parameter">filename</replaceable></option></term>
     <listitem>
      <para>
       <!--
       Text file describing message data to be sent to <productname>PostgreSQL</productname> (default: pgproto.data).
       -->
       サーバに送信するメッセージデータを記述したテキストファイル (デフォルト: pgproto.data)。
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><option>-r <replaceable class="parameter">naptime</replaceable></option></term>
     <term><option>--read-nap=<replaceable class="parameter">naptime</replaceable></option></term>
     <listitem>
      <para>
       <!--
       The nap time in micro seconds (default:0).
       Greater than 0 will let pgproto sleep between each data reading from socket.
       This is useful to simulate slow clients.
       -->
       待ち時間、単位はマイクロ秒 (デフォルト:0)。
       0より大きな値が指定された場合、ソケットから各データを読み込む際にスリープを入れます。
       これは、遅いクライアントをシミュレートします。
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><option>-D</option></term>
     <term><option>--debug</option></term>
     <listitem>
      <para>
       <!--
       Enable debug message.
       -->
       デバッグメッセージを表示します。
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><option>-v</option></term>
     <term><option>--version</option></term>
     <listitem>
      <para>
       <!--
       Print the command version, then exit.
       -->
       バージョンを表示して終了します。
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><option>-?</option></term>
     <term><option>--help</option></term>
     <listitem>
      <para>
       <!--
       Shows help for the command line arguments, then exit.
       -->
       コマンドのヘルプを表示します。
      </para>
     </listitem>
    </varlistentry>

   </variablelist>
  </para>
 </refsect1>

 <refsect1>
  <!--
  <title>Example</title>
  -->
  <title>例</title>
  <para>
   <!--
   In the example below, the first character in the file (i.e. 'Q')
   indicates the message kind specified in the PostgreSQL frontend/backend protocol.
   -->
   ファイル内の最初の文字 (Q)がフロントエンド/バックエンドプロトコルのメッセージの種類を表します。
  </para>
  <para>
   <!--
   Exceptions are 'Y' , 'y' and 'z'. 'Y' reads messages from backend
   until 'Ready for query' is received.
   'y' reads messages from backend while messages are coming from backend then stops
   if messages are not available for 1 second.
   'Y' is used for waiting for reply of 'Q' (simple query) or after 'S' (sync) in extended queries.
   'y' can be used for receiving messages after 'H' (flush).
   'z' reads 1 messages from backend. If no message arrives within 1 second, 'z' stops.
   If you want to read multiple messages, you can use repeat 'z' for the message count.
   'z' can be useful for 'H' message test when you already know how
   many reply messages will come.
   -->
   'Y'と'z'と'y'は例外です。
   'Y'は、Ready for queryが受信されるまで、バックエンドからメッセージを読み取ります。
   'y'は、バックエンドからメッセージを受信している間はメッセージを読み取り、1秒間メッセージを受信しなかった場合停止します。
   'Y'は、拡張クエリのSync ('S')、簡易問い合わせ ('Q')の応答を待つために使用できます。
   'y'は、Flush ('H')後にメッセージを受信するために使用できます。
   'z'は、バックエンドから1つメッセージを読みます。1秒間メッセージを受信しなかった場合停止します。
   'z'は、事前にいくつメッセージが届くかわかっている場合に'H'のテストのために利用することができます。
  </para>
  <para>
   <!--
   If you want to include a " (double quotation) in a string data type,
   for example "SELECT * FROM "aaa"", you can qualify it by using \ (back slash) like ""SELECT * FROM "aaa""

   A command line spread over multiple lines can be created using \ as well.
   -->
   "SELECT * FROM "aaa""のように文字列にダブルクォートを含める場合、"SELECT * FROM \"aaa\""のようにバックスラッシュを使用します。
   以下のように、\を使用して複数行にまたがるコマンド行を作成することもできます。
   <programlisting>
    'Q' "SELECT * FROM aaa \
    WHERE a = 1"
   </programlisting>
  </para>

  <para>
   <!--
   Here is an example input file:
   -->
   ここでは入力ファイルの例を示します。
   <programlisting>
    #
    # Test data example
    #
    'Q'	"SELECT * FROM aaa"
    'Y'
    'P'	"S1"	"BEGIN"	0
    'B'	""	"S1"	0	0	0
    'E'	""	0
    'C'	'S'	"S1"
    'P'	"foo"	"SELECT 1"	0
    'B'	"myportal"	"foo"	0	0	0
    'E'	"myportal"	0
    'P'	"S2"	"COMMIT"	0
    'B'	""	"S2"	0	0	0
    'E'	""	0
    'C'	'S'	"S2"
    'S'
    'Y'
    'X'
   </programlisting>
  </para>
  <para>
   <!--
   Here is an example output:
   -->
   ここでは出力例を示します。
   <programlisting>
    $ pgproto -p 11000 -d test -f sample.data
    FE=> Query (query="SELECT * FROM aaa")
    <= BE RowDescription
    <= BE CommandComplete(SELECT 0)
    <= BE ReadyForQuery(I)
    FE=> Parse(stmt="S1", query="BEGIN")
    FE=> Bind(stmt="S1", portal="")
    FE=> Execute(portal="")
    FE=> Close(stmt="S1")
    FE=> Parse(stmt="foo", query="SELECT 1")
    FE=> Bind(stmt="foo", portal="myportal")
    FE=> Execute(portal="myportal")
    FE=> Parse(stmt="S2", query="COMMIT")
    FE=> Bind(stmt="S2", portal="")
    FE=> Execute(portal="")
    FE=> Close(stmt="S2")
    FE=> Sync
    <= BE ParseComplete
    <= BE BindComplete
    <= BE CommandComplete(BEGIN)
    <= BE CloseComplete
    <= BE ParseComplete
    <= BE BindComplete
    <= BE DataRow
    <= BE CommandComplete(SELECT 1)
    <= BE ParseComplete
    <= BE BindComplete
    <= BE CommandComplete(COMMIT)
    <= BE CloseComplete
    <= BE ReadyForQuery(I)
    FE=> Terminate
   </programlisting>
  </para>
  <para>
   <!--
   Other example data files:
   -->
   その他のデータファイルの例です。
  </para>
  <para>
   Copy
   <programlisting>
    #
    # Test data example
    #

    # CopyIn
    #
    'Q'	"COPY t1 FROM STDIN"
    # CopyData
    'd'	"abc"
    # CopyDone
    'c'
    'Y'

    # CopyOut
    #
    'Q'	"COPY t1 TO STDOUT"
    'Y'

    #
    # Copy fail case
    #
    'Q'	"COPY t1 FROM STDIN"
    # CopyData
    'd'	"abc"
    # CopyFail
    'f'	"pgproto copy fail test"
    'Y'
    'X'
   </programlisting>
  </para>
  <para>
   Function Call
   <programlisting>
    #
    # Test data example
    #

    # Function call (lo_creat)
    # from PostgreSQL's src/include/catalog/pg_proc.data
    # { oid => '957', descr => 'large object create',
    #  proname => 'lo_creat', provolatile => 'v', proparallel => 'u',
    #  prorettype => 'oid', proargtypes => 'int4', prosrc => 'be_lo_creat' },

    'F'	957	1	0	1	1	"0"	0
    'Y'
    'X'
   </programlisting>
  </para>
 </refsect1>

</refentry>
