<!--
$Header: /usr/prj/pg/cvsroot/doc/doc/src/sgml/ref/ecpg-ref.sgml,v 1.5 2001/09/14 10:18:19 t-ishii Exp $
Postgres documentation
-->

<refentry id="APP-ECPG">
 <refmeta>
  <refentrytitle id="app-ecpg-title">
   <application>ecpg</application>
  </refentrytitle>
  <manvolnum>1</manvolnum>
  <refmiscinfo>Application</refmiscinfo>
 </refmeta>
 <refnamediv>
  <refname>
   <application>ecpg</application>
  </refname>
  <refpurpose>
   <!--Embedded SQL C preprocessor-->
   埋め込みSQL用Cプリプロセッサです。<indexterm><primary>ecpg</primary></indexterm><indexterm><primary>PostgreSQL</primary><secondary>ecpg</secondary></indexterm><indexterm><primary sortas="うめこみSQL">埋め込みSQL</primary></indexterm>
  </refpurpose>
 </refnamediv>
 <refsynopsisdiv>
  <refsynopsisdivinfo>
   <date>1999-07-20</date>
  </refsynopsisdivinfo>
<synopsis>
ecpg [ -v ] [ -t ] [ -I include-path ] [ -o outfile ]  file1 [ file2 ] [ ... ]
</synopsis>

  <refsect2 id="R2-APP-ECPG-1">
   <refsect2info>
    <date>1999-07-20</date>
   </refsect2info>
   <title>
    <!--Inputs-->入力
   </title>
   <para>
    <!--<application>ecpg</application> accepts the following command
    line arguments:-->

    <application>ecpg</application>は、以下のコマンドライン引数を受け付けます。
</para>

    <variablelist>
     <varlistentry>
      <term>-v</term>
      <listitem>
       <para>
	<!--Print version information. -->
        バージョン情報を表示します。
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>-t</term>
      <listitem>
       <para>
	<!--Turn off auto-transaction mode.-->
        自動トランザクションモードを無効にします。
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>-I <replaceable class="parameter">path</replaceable></term>
      <listitem>
       <para>
	<!--Specify an additional include path.
	Defaults are <filename>.</filename>,
	<filename>/usr/local/include</filename>, the
	<productname>Postgres</productname> include path which is
	defined at compile time (default:
	<filename>/usr/local/pgsql/lib</filename>), and
	<filename>/usr/include</filename>.-->

        追加するinclude用パスを指定します。デフォルトでは、「<filename>.</filename>」、<filename>/usr/local/include</filename>、コンパイル時に定義される<productname>Postgres</productname>のinclude用パス（デフォルトでは、<filename>/usr/local/pgsql/lib</filename>）、<filename>/usr/include</filename>です。
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>-o</term>
      <listitem>
       <para>
	<!--Specifies that <application>ecpg</application> should write all its output to outfile.
	If no such option is given the output is written to
	<filename><replaceable>name</replaceable>.c</filename>,
	assuming the input file was 
	named <filename><replaceable>name</replaceable>.pgc</filename>.
	If the input file does have the expected
	<literal>.pgc</literal> suffix, then the output file will have 
	<literal>.pgc</literal> appended to the input file name.-->

        ecpgがそのすべての出力を出力ファイルに書き出すように指示します。このオプションがない場合、入力ファイル名が<filename><replaceable>name</replaceable>.pgc</filename>であると仮定すると、その出力は<filename><replaceable>name</replaceable>.c</filename>に書き出されます。入力ファイルが想定どおりの<literal>.pgc</literal>という拡張子を持っている場合、出力ファイルはその入力ファイルに<literal>.pgc</literal>を付けた場合と同じ動作になります。 
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><replaceable class="parameter">file</replaceable></term>
      <listitem>
       <para>
	<!--The files to be processed.-->
        処理対象ファイルです。
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
  </refsect2>

  <refsect2 id="R2-APP-ECPG-2">
   <refsect2info>
    <date>1998-11-05</date>
   </refsect2info>
   <title>
    <!--Outputs-->出力
   </title>
   <para>
    <!--<application>ecpg</application> will create a file or
    write to <filename>stdout</filename>.-->

    <application>ecpg</application>はファイルを生成するか、または、<filename>stdout</filename>に出力します。
</para>

    <variablelist>
     <varlistentry>
      <term><replaceable>return value</replaceable></term>
      <listitem>
       <para>
	<!--<application>ecpg</application> returns 0 to the shell on successful completion, -1
	for errors.-->

        <application>ecpg</application>は正常終了時には0を、エラー時には-1をシェルに返します。

       </para>
      </listitem>
     </varlistentry>
    </variablelist>
  </refsect2>
 </refsynopsisdiv>

 <refsect1 id="R1-APP-ECPG-description">
  <title><!--Description-->説明</title>
  <para>
   <!--<application>ecpg</application>
   is an embedded SQL preprocessor for the C language and the
   <productname>Postgres</productname>. It
   enables development of C programs with embedded SQL code.-->

   <application>ecpg</application>は、C言語と<productname>Postgres</productname>用の埋め込みSQLプリプロセッサです。これにより、埋め込みSQLを使用したCプログラムの開発が可能です。

  </para>

  <para>
   <!--Linus Tolke (<email>linus@epact.se</email>) was the
   original author of <application>ecpg</application> (up to version 0.2).
   Michael Meskes (<email>meskes@debian.org</email>)
   is the current author and maintainer of <application>ecpg</application>.
   Thomas Good (<email>tomg@q8.nrnet.org</email>)
   is the author of the last revision of the <application>ecpg</application> man page, on which
   this document is based.-->

   Linus Tolke（<email>linus@epact.se</email>）が<application>ecpg</application>の元の作者です（バージョン0.2まで）。現在はMichael Meskes（<email>meskes@debian.org</email>）が作者であり、<application>ecpg</application>の管理維持を行っています。Thomas Good（<email>tomg@q8.nrnet.org</email>）が<application>ecpg</application> manページの最新版の作者です。本文書はこのマニュアルページを元にしています。

  </para>
 </refsect1>

 <refsect1 id="R1-APP-ECPG-2">
  <title><!--Usage-->使用方法</title>

  <refsect2 id="R2-APP-ECPG-preprocessing">
   <title><!--Preprocessing for Compilation-->コンパイルの前処理</title>

   <para>
    <!--An embedded SQL source file must be preprocessed before
    compilation: -->

    埋め込みSQLのソースは、コンパイル前に以下のように前処理されなければなりません。
</para>

<programlisting>
ecpg [ -d ] [ -o <replaceable>file</replaceable> ] <replaceable>file</replaceable>.pgc
</programlisting>

<para>
    <!--where the optional <option>-d</option> flag turns on debugging.
    The <literal>.pgc</literal> extension is an 
    arbitrary means of denoting <application>ecpg</application> source.-->

    ここで、オプションの<option>-d</option>フラグはデバッグ機能を有効にします。<literal>.pgc</literal>という拡張子は、<application>ecpg</application>のソースであることを表す便宜的なものです。

   </para>

   <para>
    <!--You may want to redirect the preprocessor output to a log file.-->
    プリプロセッサの出力をログファイルにリダイレクトした方がよいでしょう。
   </para>
  </refsect2>

  <refsect2 id="R2-APP-ECPG-compiling">
   <title><!--Compiling and Linking-->コンパイルとリンクの作業</title>

   <para>
    <!--Assuming the <productname>Postgres</productname> binaries are in
    <filename>/usr/local/pgsql</filename>, you will need to compile
    and link your preprocessed source file:-->

    <productname>Postgres</productname>のバイナリが<filename>/usr/local/pgsql</filename>にあるとすると、下記のように前処理されたソースファイルのコンパイルとリンクを行わなければなりません。
</para>

<programlisting>
gcc -g -I /usr/local/pgsql/include [ -o <replaceable>file</replaceable> ] <replaceable>file</replaceable>.c -L /usr/local/pgsql/lib -lecpg -lpq
</programlisting>
  </refsect2>
 </refsect1>

 <refsect1 id="R1-APP-ECPG-grammar">
  <title><!--Grammar-->文法</title>

  <refsect2 id="R2-APP-ECPG-library">
   <title><!--Libraries-->ライブラリ</title>

   <para>
    <!--The preprocessor will prepend two directives to the source:-->
    プリプロセッサはソースの先頭に下記の2つの指示子を付与します。<indexterm><primary>ecpgtype.h</primary></indexterm><indexterm><primary>ecpglib.h</primary></indexterm>
</para>

<programlisting>
#include &lt;ecpgtype.h&gt;
#include &lt;ecpglib.h&gt;
</programlisting>
  </refsect2>

  <refsect2 id="R2-APP-declaration">
   <title><!--Variable Declaration-->変数宣言</title>

   <para>
    <!--Variables declared within <application>ecpg</application> source code must be prepended with:-->
    <application>ecpg</application>のソース内で宣言される変数は、以下の文で始まらなければなりません。
</para>

<programlisting>
EXEC SQL BEGIN DECLARE SECTION;
</programlisting>

   <para>
    <!--Similarly, variable declaration sections must terminate with:-->
    同様に、変数宣言部は以下の文で終わらなければなりません。
</para>

<programlisting>
EXEC SQL END DECLARE SECTION;
</programlisting>

    <note>
     <para>
      <!--Prior to version 2.1.0, each variable had to be declared 
      on a separate line.  As of version 2.1.0 multiple variables may
      be declared on a single line:-->

      バージョン2.1.0以前では、各変数は単独の行で宣言しなければいけませんでした。バージョン2.1.0では、以下のように1行に複数の変数を宣言することができます。
</para>


<programlisting>
char  foo[16], bar[16];
</programlisting>
</note>

  </refsect2>

  <refsect2 id="R2-APP-ECPG-errors">
   <title><!--Error Handling-->エラー処理</title>

   <para>
    <!--The SQL communication area is defined with:-->
    以下の文によりSQL通信部分が定義されます。
</para>

<programlisting>
EXEC SQL INCLUDE sqlca;
</programlisting>

    <note>
     <para>
      <!--The <literal>sqlca</literal> is in lowercase.
      While SQL convention may be 
      followed, i.e., using uppercase to separate embedded SQL 
      from C statements, sqlca (which includes the sqlca.h 
      header file) MUST be lowercase.  This is because the EXEC SQL
      prefix indicates that this INCLUDE will be parsed by <application>ecpg</application>.
      <application>ecpg</application> observes case sensitivity (SQLCA.h will not be found).
      <command>EXEC SQL INCLUDE</command>
      can be used to include other header files
      as long as case sensitivity is observed.-->

      <literal>sqlca</literal>は小文字で表します。SQLの慣習（たとえば埋め込みSQLとC言語の文を区別するために大文字を使用することなど）には従った方がよいのですが、sqlca（sqlca.hヘッダーファイルをincludeすることを示します）は必ず小文字でなければいけません。EXEC SQLという前置詞は、このINCLUDEが<application>ecpg</application>によって解析されることを示しているからです。<application>ecpg</application>は大文字/小文字の違いをそのまま使用します（SQLCA.hではファイルを検出できません）。<command>EXEC SQL INCLUDE</command>は大文字/小文字の違いさえ守られていれば、他のヘッダーファイルをインクルードする場合にも使用することができます。

     </para>
    </note>

   <para>
    <!--The sqlprint command is used with the EXEC SQL WHENEVER
    statement to turn on error handling throughout the 
    program:-->

    sqlprintコマンドは下記のようにEXEC SQL WHENEVER文内で使用されます。これによりプログラム全体を通してエラー処理が有効になります。
</para>


<programlisting>
EXEC SQL WHENEVER sqlerror sqlprint;
</programlisting>

<para>
    <!--and-->または、以下ののように使用されます。
</para>


<programlisting>
EXEC SQL WHENEVER not found sqlprint;
</programlisting>

    <note>
     <para>
      <!--This is <emphasis>not</emphasis> an exhaustive example of usage for
      the <command>EXEC SQL WHENEVER</command> statement.
      Further examples of usage may
      be found in SQL manuals (e.g., `The LAN TIMES Guide to SQL' by
      Groff and Weinberg).-->

      これは<command>EXEC SQL WHENEVER</command>文の完全な使用例では<emphasis>ありません</emphasis>。より多くの使用例がSQLのマニュアル（たとえば、GroffとWeinbergの『The LAN TIMES Guide to SQL』）に掲載されています。

     </para>
    </note>
  </refsect2>

  <refsect2 id="R2-APP-ECPG-connecting">
   <title><!--Connecting to the Database Server-->データベースサーバーへの接続</title>

   <para>
    <!--One connects to a database using the following:-->
    データベースに接続するには下記の様にします。
</para>

<programlisting>
EXEC SQL CONNECT TO <replaceable>dbname</replaceable>;
</programlisting>

<para>
    <!--where the database name is not quoted. Prior to version 2.1.0, the 
    database name was required to be inside single quotes.-->
    ここで、データベース名は引用符で囲まれていません。バージョン2.1.0以前ではデータベース名は一重引用符で囲む必要がありました。

   </para>

   <para>
    <!--Specifying a server and port name in the connect statement is also 
    possible. The syntax is:-->

    connect文でサーバー名とポート番号を指定することも可能です。下記がその構文です。
</para>

<programlisting>
<replaceable>dbname</replaceable>[@<replaceable>server</replaceable>][:<replaceable>port</replaceable>]
</programlisting>

<para>
    <!--or-->または以下のようにします。
</para>

<programlisting>
&lt;tcp|unix&gt;:postgresql://<replaceable>server</replaceable>[:<replaceable>port</replaceable>][/<replaceable>dbname</replaceable>][?<replaceable>options</replaceable>]
</programlisting>
  </refsect2>

  <refsect2 id="R2-APP-ECPG-queries">
   <title><!--Queries-->問い合わせ</title>

   <para>
    <!--In general, SQL queries acceptable to other applications such as
    <application>psql</application> can be embedded into your C
    code. Here are some examples of how to do that.-->

   通常、<application>psql</application>などの他アプリケーションで使用できるSQL問い合わせはCのコードに埋め込むことができます。ここで、埋め込む方法を示す例をいくつか示します。

   </para>

   <para>
    <!--Create Table:-->
    テーブルを作成するには以下のようにします。
</para>

<programlisting>
EXEC SQL CREATE TABLE foo (number int4, ascii char(16));
EXEC SQL CREATE UNIQUE index num1 on foo(number);
EXEC SQL COMMIT;
</programlisting>

   <para>
    <!--Insert:-->
    データを挿入するには以下のようにします。
</para>

<programlisting>
EXEC SQL INSERT INTO foo (number, ascii) VALUES (9999, 'doodad');
EXEC SQL COMMIT;
</programlisting>

   <para>
    <!--Delete:-->
    データを削除するには以下のようにします。
</para>

<programlisting>
EXEC SQL DELETE FROM foo WHERE number = 9999;
EXEC SQL COMMIT;
</programlisting>

   <para>
    <!--Singleton Select:-->
    1タプルを選択するには以下のようにします。 
</para>

<programlisting>
EXEC SQL SELECT foo INTO :FooBar FROM table1 WHERE ascii = 'doodad';
</programlisting>

   <para>
    <!--Select using Cursors:-->
    カーソルを使用して選択するには以下のようにします。
</para>

<programlisting>
EXEC SQL DECLARE foo_bar CURSOR FOR
    SELECT number, ascii FROM foo
    ORDER BY ascii;
EXEC SQL FETCH foo_bar INTO :FooBar, DooDad;
...
EXEC SQL CLOSE foo_bar;
EXEC SQL COMMIT;
</programlisting>

   <para>
    <!--Updates:-->
    データを更新するには以下のようにします。
</para>

<programlisting>
EXEC SQL UPDATE foo
    SET ascii = 'foobar'
    WHERE number = 9999;
EXEC SQL COMMIT;
</programlisting>
  </refsect2>
 </refsect1>

 <refsect1 id="R1-APP-ECPG-notes">
  <title><!--Notes-->注釈</title>
  <para>
   <!--There is no <command>EXEC SQL PREPARE</command> statement.-->
   <command>EXEC SQL PREPARE</command>文はありません。
  </para>

  <para>
   <!--The complete structure definition MUST be listed
   inside the declare section.-->
   完全な構造体定義は宣言部内に記述しなければなりません。

  </para>

  <para>
   <!--See the <filename>TODO</filename> file in the source for some more
   missing features.-->
   他の存在しない機能については、ソースディレクトリにある、<filename>TODO</filename>ファイルを参照してください。
  </para>

<!--
.SH FILES
.PD 0
.TP
.B /usr/src/pgsql/postgresql-${ver}/src/interfaces...
 ./ecpg/include.......source for &bsol;fIecpg&bsol;fP header files.
 ./ecpg/lib...........source for &bsol;fIecpg&bsol;fP libraries.
 ./ecpg/preproc.......source for &bsol;fIecpg&bsol;fP header files.
 ./ecpg/test..........source for &bsol;fIecpg&bsol;fP libraries.
 (test contains examples of syntax for ecpg SQL-C.)
.PD
.TP
.B /usr/local/pgsql/bin 
&bsol;fIPostgreSQL&bsol;fP binaries including &bsol;fIecpg&bsol;fP.
.PD
.TP
.B /usr/local/pgsql/include 
&bsol;fIPostgreSQL&bsol;fP headers including &bsol;fIecpglib.h&bsol;fP &bsol;fIecpgtype.h&bsol;fP 
and &bsol;fIsqlca.h&bsol;fP.
.PD
.TP
.B /usr/local/pgsql/lib 
&bsol;fIPostgreSQL&bsol;fP libraries including &bsol;fIlibecpg.a&bsol;fP and 
&bsol;fIlibecpg.so&bsol;fP.
-->

 </refsect1>
</refentry>

<!-- 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:
-->
