<!--
$Header: /usr/prj/pg/cvsroot/doc/doc/src/sgml/plsql.sgml,v 1.24 2001/09/10 09:17:06 k-kondo Exp $
-->

<chapter id="plpgsql"> 
<!--  <title>PL/pgSQL - <acronym>SQL</acronym> Procedural Language</title> -->
  <title>PL/pgSQL――<acronym>SQL</acronym>手続き言語</title>
<indexterm><primary>PL/pgSQL</primary></indexterm><indexterm><primary sortas="げんご">言語</primary><secondary>PL/pgSQL</secondary></indexterm>
<!-- <para>
  PL/pgSQL is a loadable procedural language for the
  <productname>Postgres</productname> database system.
 </para> -->

 <para>
  PL/pgSQLは、<productname>Postgres</productname>データベースシステムのためのロード可能な手続き言語です。
 </para>
   
<!-- <para>
  This package was originally written by Jan Wieck. This
  documentation was in part written 
  by Roberto Mello (<email>rmello@fslc.usu.edu</email>).
 </para> -->

 <para>
 このパッケージはJan Wieckによって書かれたものを元にしています。このドキュメントの一部はRoberto Mello（<email>rmello@fslc.usu.edu</email>）によって書かれています
。
 </para>

  <sect1 id="plpgsql-overview">
<!--   <title>Overview</title> -->
   <title>概要</title>

   <para>
<!--    The design goals of PL/pgSQL were to create a loadable procedural
    language that -->
    PL/pgSQLの設計目的は、次のような特徴の読み込み可能な手続き言語でした。<indexterm><primary>PL/pgSQL</primary><secondary sortas="せっけいもくてき">設計目的</secondary></indexterm>
</para>

    <itemizedlist>
     <listitem>
      <para>
<!--       can be used to create functions and trigger procedures, -->
       関数とトリガプロシージャを作成するために使用できること
      </para>
     </listitem>
     <listitem>
      <para>
       <acronym>SQL</acronym>言語に制御構造を追加すること
<!--       adds control structures to the <acronym>SQL</acronym> language, -->
      </para>
     </listitem>
     <listitem>
      <para>
<!--       can perform complex computations, -->
       複雑な演算が可能であること
      </para>
     </listitem>
     <listitem>
      <para>
<!--       inherits all user defined types, functions and operators, -->
       すべてのユーザー定義型、関数、演算子を継承すること
      </para>
     </listitem>
     <listitem>
      <para>
<!--       can be defined to be trusted by the server, -->
       trusted functionとして定義ができること 
      </para>
     </listitem>
     <listitem>
      <para>
<!--       is easy to use. -->
        使いやすいこと
      </para>
     </listitem>
    </itemizedlist>

   <para>
<!--    The PL/pgSQL call handler parses the function's source text and
    produces an internal binary instruction tree the first time the
    function is called. The produced bytecode is identified
    in the call handler by the object ID of the function. This ensures
    that changing a function by a DROP/CREATE sequence will take effect
    without establishing a new database connection.  -->

    PL/pgSQL呼び出しハンドラは関数のソーステキストを解析し、初めてその関数が呼び出されたときにバイナリ形式の命令ツリーを内部で作成します。作成されたバイトコードは呼び出しハンドラ内で関数のオブジェクトIDによって識別されます。これによって確実にDROP/CREATEといった流れによる関数の変更を新しくデータベースに接続することなく反映できます。

   </para>
<!--   <para>
    For all expressions and <acronym>SQL</acronym> statements used in
    the function, the PL/pgSQL bytecode interpreter creates a
    prepared execution plan using the <acronym>SPI</acronym> manager's 
    <function>SPI_prepare()</function> and
    <function>SPI_saveplan()</function> functions. This is done the 
    first time the individual
    statement is processed in the PL/pgSQL function. Thus, a function with
    conditional code that contains many statements for which execution
    plans would be required, will only prepare and save those plans
    that are really used during the lifetime of the database
    connection. 
   </para> -->
   <para>
    関数で使用されるすべての式と<acronym>SQL</acronym>文に対して、PL/pgSQLのバイトコードのインタープリタは<acronym>SPI</acronym>マネージャの<function>SPI_prepare()</function>と<function>SPI_saveplan()</function>関数を使用して遂行可能な実行計画の準備を作成します。これは、PL/pgSQL関数内で、初めてその文が処理されたときに行われます。したがって、実行計画用に必要となる文を多く含む、条件付きのコードがある関数は、そのデータベース接続が有効である期間に実際に使われた部分についての計画のみが作成され、保存されます。
   </para>
  <para>
<!--  This means that you have to be careful about your user-defined
  functions. For example: -->
  これは、ユーザー定義関数には気をつけなければいけないことを示しています。たとえば、以下のような関数を考えてみましょう。
</para>

<programlisting>
CREATE FUNCTION populate() RETURNS INTEGER AS '
DECLARE
<!--     Declarations -->
     -- 宣言部
BEGIN
    PERFORM my_function();
END;
' LANGUAGE 'plpgsql';
</programlisting>

<para>
<!--    If you create the above function, it will reference the OID for
    <function>my_function()</function> in its bytecode. Later, if you
    drop and re-create <function>my_function()</function>, then
    <function>populate()</function> will not be able to find
    <function>my_function()</function> anymore. You would then have to
    re-create <function>populate()</function>. -->

    上記のような関数を作成した場合、この関数のバイトコードは<function>my_function()</function>のOIDを参照します。このあとで、たとえば、<function>my_function()</function>を削除して作り直した場合、<function>populate()</function>は<function>my_function()</function>を見つけることができません。このときは、<function>populate()</function>を作り直さなければいけないのです。
   </para>

   <para>
<!--    Because PL/pgSQL saves execution plans in this way, queries that appear
    directly in a PL/pgSQL function must refer to the same tables and fields
    on every execution; that is, you cannot use a parameter as the name of
    a table or field in a query.  To get around
    this restriction, you can construct dynamic queries using the PL/pgSQL
    EXECUTE statement ーーー at the price of constructing a new query plan
    on every execution. -->

    PL/pgSQLはこのように実行プランを保存するので、直接PL/pgSQL関数内に現れる問い合わせはあらゆる実行において同じテーブルとフィールドを参照するものでなければいけません。つまり、問い合わせ中でテーブルやフィールド名を引数として使用することはできません。この制約を回避する方法は、問い合わせごとに問い合わせプランを作成してしまう無駄を覚悟でPL/pgSQLのEXECUTE文を使用して動的な問い合わせを作成することです。
   </para>
   <para>
<!--    Except for input/output conversion and calculation functions
    for user defined types, anything that can be defined in C language
    functions can also be done with PL/pgSQL. It is possible to
    create complex conditional computation functions and later use
    them to define operators or use them in functional indices. -->

    入出力変換とユーザー定義型用の計算関数を除き、C言語関数で定義できることはすべてPL/pgSQLでも実現できます。複雑な条件のある演算処理関数の作成や作成した関数を使った演算子の定義、関数インデックスに作成した関数を使用することが可能です。
   </para>
  <sect2 id="plpgsql-advantages">
<!--   <title>Advantages of Using PL/pgSQL</title> -->
   <title>PL/pgSQLを使用することの利点</title>
<indexterm><primary>PL/pgSQL</primary><secondary sortas="りてん">利点</secondary></indexterm>
   <itemizedlist>
    <listitem>
     <para>
<!--      Better performance (see <xref linkend="plpgsql-advantages-performance">) -->
          よりよいパフォーマンス（<xref linkend="plpgsql-advantages-performance">を参照）
     </para>
    </listitem>

    <listitem>
     <para>
      <!--SQL support (see <xref linkend="plpgsql-advantages-sqlsupport">)-->
      SQLサポート（<xref linkend="plpgsql-advantages-sqlsupport">を参照）
     </para>
    </listitem> 

    <listitem>
     <para>
     <!-- Portability (see <xref linkend="plpgsql-advantages-portability">)-->
      移植性（<xref linkend="plpgsql-advantages-portability">を参照）
     </para>
    </listitem>
   </itemizedlist>

   <sect3 id="plpgsql-advantages-performance">
<!--    <title>Better Performance</title> -->
    <title>よりよいパフォーマンス</title>

    <para>
<!--     <acronym>SQL</acronym> is the language PostgreSQL (and
     most other Relational Databases) use as query
     language. It's portable and easy to learn. But every
     <acronym>SQL</acronym> statement must be executed
     individually by the database server. -->

     <acronym>SQL</acronym>はPostgreSQL（その他のたいていのリレーショナルデータベースも）が問い合わせ言語として使用している言語です。移植性があり、習得が容易です。しかし、あらゆる<acronym>SQL</acronym>文は、データベースサーバーによって個々に実行されなければいけません。
    </para>

    <para>
<!--     That means that your client application must send each
     query to the database server, wait for it to process it,
     receive the results, do some computation, then send
     other queries to the server. All this incurs inter
     process communication and may also incur network
     overhead if your client is on a different machine than
     the database server. -->
     これはクライアントアプリケーションに対して以下のようなことを要求しています。まず、データベースサーバーに問い合わせを送信します。次にそれが処理されるのを待ちます。次に、結果を取得します。次に若干の計算を行います。そしてから、サーバーに次の問い合わせを送信します。クライアントがデータベースサーバーマシンからみて異なるマシンの場合、内部プロセス通信を招き、ネットワークオーバーへッドを起こすかもしれません。
    </para>

    <para>
<!--     With PL/pgSQL you can group a block of computation and a
     series of queries <emphasis>inside</emphasis> the
     database server, thus having the power of a procedural
     language and the ease of use of SQL, but saving lots of
     time because you don't have the whole client/server
     communication overhead. Your application will enjoy a
     considerable performance increase by using PL/pgSQL.  -->

     PL/pgSQLを使うことで、計算と複数の問い合わせをデータベースサーバー<emphasis>内部</emphasis>にひとまとめに実行することができます。このように、手続き言語の威力とSQLの使いやすさを持ち合わせているにもかかわらず、すべてにおいてクライアント/サーバー通信のオーバーへッドがないのでだいぶ時間を節約できます。
    </para>
   </sect3>

   <sect3 id="plpgsql-advantages-sqlsupport">
<!--    <title>SQL Support</title> -->
    <title>SQLサポート</title>
<indexterm><primary>PL/pgSQL</primary><secondary sortas="SQLさぽーと">PL/pgSQLサポート</secondary></indexterm>
    <para>
<!--     PL/pgSQL adds the power of a procedural language to the
     flexibility and ease of <acronym>SQL</acronym>. With
     PL/pgSQL you can use all the datatypes, columns, operators
     and functions of SQL.     -->

     PL/pgSQLは<acronym>SQL</acronym>の平易性と柔軟性に手続き言語のパワーを加えたものです。PL/pgSQLをはすべてのデータ型、カラム、オペレータ、SQLの関数を使用することができます。
    </para>
   </sect3>

   <sect3 id="plpgsql-advantages-portability">
<!--    <title>Portability</title> -->
    <title>移植性</title>
<indexterm><primary>PL/pgSQL</primary><secondary sortas="いしょくせい">移植性</secondary></indexterm>
    <para>
<!--     Because PL/pgSQL functions run inside PostgreSQL, these
     functions will run on any platform where PostgreSQL
     runs. Thus you can reuse code and have less development costs. -->
     
     PL/pgSQL関数はPostgreSQLの内部で実行されるので、関数はPostgreSQLが動いていればどんなプラットフォームでも実行できます。これによって、コードの再利用ができるので、開発コストを削減することができます。
    </para>
   </sect3>
  </sect2>

  <sect2 id="plpgsql-overview-developing-in-plpgsql">
   <!--<title>Developing in PL/pgSQL</title>-->
   <title>PL/pgSQLでの開発</title>
<indexterm><primary>PL/pgSQL</primary><secondary sortas="かいはつ">開発</secondary></indexterm>
   <para>
<!--    Developing in PL/pgSQL is pretty straight forward, especially
    if you have developed in other database procedural languages,
    such as Oracle's PL/SQL. Two good ways of developing in
    PL/pgSQL are: -->

    特にOracleのPL/SQLのような他のデータベースの手続き言語で開発したことがあるならば、PL/pgSQLにおける開発はとても入りやすいでしょう。PL/pgSQLで開発する2つのよい方法を紹介します。
</para>

    <itemizedlist>
     <listitem>
      <para>
<!--       Using a text editor and reloading the file with <command>psql</command> -->

         テキストエディタと<command>psql</command>を使ってファイルを再読み込みする方法を使用する方法

      </para>
     </listitem>

     <listitem>
      <para>
<!--       Using PostgreSQL's GUI Tool: pgaccess -->

         PostgreSQLのGUIツールであるpgaccessを使う方法

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

   <para>
<!--    One good way to develop in PL/pgSQL is to simply use the text
    editor of your choice to create your functions, and in another
    console, use <command>psql</command> (PostgreSQL's interactive monitor) to load
    those functions. If you are doing it this way (and if you are
    a PL/pgSQL novice or in debugging stage), it is a good idea to 
    always <command>DROP</command> your function before creating it. That way
    when you reload the file, it'll drop your functions and then
    re-create them. For example: -->

    PL/pgSQLで開発する1つのよい方法は、単純に関数を作成するのに自分の好きなテキストエディタを使い、もう1つのコンソールで、<command>psql</command>（PostgreSQLインタラクティブモニタ）を使用して関数を読み込ませることです。この方法で行う場合には（そしてあなたがPL/pgSQL初心者もしくはデバッグ中であれば）関数の作成の前に<command>DROP</command>文でその関数を削除しておくのがよいでしょう。このようにファイルを再読み込みする場合に、関数を削除して、それから関数を作り直します。以下が例です。<indexterm><primary>psql</primary></indexterm>
</para>

<programlisting>
drop function testfunc(integer);
create function testfunc(integer) return integer as '
    ....
end;
' language 'plpgsql';
</programlisting>

   <para>
<!--    When you load the file for the first time,
    <productname>PostgreSQL</> will raise a warning saying this
    function doesn't exist and go on to create it. To load an SQL
    file (filename.sql) into a database named "dbname", use the command: -->

    初めてファイルを読み込ませるときには<productname>PostgreSQL</>はこの関数は存在しないということと、その関数を作成するという警告を発します。「dbname」という名前のデータベースにSQLファイル（filename.sql）を読み込ませるには以下のコマンドを使用します。
</para>

<programlisting>
psql -f filename.sql dbname
</programlisting>

   <para>
<!--    Another good way to develop in PL/pgSQL is using
    <productname>PostgreSQL</>'s GUI tool: pgaccess. It does some
    nice things for you, like escaping single-quotes, and making
    it easy to recreate and debug functions. -->

    Pl/pgSQLにおける開発のもう1つのよい方法は、<productname>PostgreSQL</>のGUIツールであるpgaccessを使う方法です。これを利用すると、一重引用符をエスケープさせたり、関数の作り直しやデバッグ関数の作成が容易に行えるというよい点があります。

   </para>
  </sect2>
 </sect1>

  <!-- **** PL/pgSQL Description **** -->

  <sect1 id="plpgsql-description">
<!--   <title>Description</title> -->
   <title>説明</title>

   <!-- **** PL/pgSQL structure **** -->

   <sect2>
<!--    <title>Structure of PL/pgSQL</title> -->
    <title>PL/pgSQLの構造</title>
<indexterm><primary>PL/pgSQL</primary><secondary sortas="こうぞう">構造</secondary></indexterm>
    <para>
<!--     PL/pgSQL is a <emphasis>block structured</emphasis> language. All
     keywords and identifiers can be used in mixed upper and
     lower-case. A block is defined as: -->

     PL/pgSQLは、<emphasis>ブロック化構造</emphasis>言語です。すべてのキーワードと識別子は大文字と小文字を混ぜて使うことができます。ブロックは次のように定義します。<indexterm><primary>PL/pgSQL</primary><secondary sortas="ぶろっくかこうぞう">ブロック化構造</secondary></indexterm><indexterm><primary sortas="げんご">言語</primary><secondary sortas="ぶろっくかこうぞう">ブロック化構造</secondary></indexterm>
</para>

<synopsis>
<optional>&lt;&lt;label&gt;&gt;</optional>
<optional>DECLARE
    <replaceable>declarations</replaceable></optional>
BEGIN
    <replaceable>statements</replaceable>
END;
</synopsis>

    <para>
<!--     There can be any number of sub-blocks in the statement section
     of a block. Sub-blocks can be used to hide variables from outside a
     block of statements. -->

     ブロックの文節には副ブロックを複数持つことができます。副ブロックは、そのブロックの外部の文から変数を隠蔽することに使用できます。

    </para>

    <para>
<!--     The variables declared in the declarations section preceding a
     block are initialized to their default values every time the
     block is entered, not only once per function call. For example: -->

     ブロックの前の宣言節で宣言された変数は、関数呼び出しのたびではなく、そのブロックに処理が進むときに毎回そのデフォルト値に初期化されます。以下にその例を示します。
</para>

<programlisting>
CREATE FUNCTION somefunc() RETURNS INTEGER AS '
DECLARE
   quantity INTEGER := 30;
BEGIN
   RAISE NOTICE ''Quantity here is %'',quantity;  -- Quantity here is 30
   quantity := 50;
   --
   -- <!--Create a sub-block-->副ブロックの作成
   --
   DECLARE
      quantity INTEGER := 80;
   BEGIN
      RAISE NOTICE ''Quantity here is %'',quantity;  -- Quantity here is 80
   END;

   RAISE NOTICE ''Quantity here is %'',quantity;  -- Quantity here is 50

   RETURN quantity;
END;
' LANGUAGE 'plpgsql';
</programlisting>

    <para>
<!--     It is important not to confuse the use of BEGIN/END for
     grouping statements in PL/pgSQL with the database commands for
     transaction control.  PL/pgSQL's BEGIN/END are only for grouping;
     they do not start or end a transaction.  Functions and trigger procedures
     are always executed within a transaction established by an outer query
     - they cannot start or commit transactions, since
     <productname>Postgres</productname> does not have nested transactions. -->

     文をまとめるためのPL/pgSQL内のBEGIN/ENDとトランザクションを制御するデータベースコマンドであるBEGIN/ENDの意味を取り違えないようにしてください。関数とトリガプロシージャはトランザクションを始めたり、コミットしたりできませんし、<productname>Postgres</productname>は入れ子になったトランザクションをもちません。

    </para>
   </sect2>

   <sect2>
<!--    <title>Comments</title> -->
    <title>コメント</title>
<indexterm><primary>PL/pgSQL</primary><secondary sortas="こめんと">コメント</secondary></indexterm>
    <para>
<!--     There are two types of comments in PL/pgSQL. A double dash <literal>-</literal>
     starts a comment that extends to the end of the line. A <literal>/*</literal>
     starts a block comment that extends to the next occurrence of <literal>*/</literal>.
     Block comments cannot be nested, but double dash comments can be
     enclosed into a block comment and a double dash can hide
     the block comment delimiters <literal>/*</literal> and <literal>*/</literal>. -->

     PL/pgSQLには2種類のコメントがあります。2重ダッシュ「--」はその文の終わりまでをコメントとするコメントの始まりです。「/*」は次に「*/」が現れるまでのブロック型のコメントの始まりを示します。ブロック型のコメントは入れ子にはできませんが、二重ダッシュのコメントをブロック型のコメントの内側におくことはでき、また二重ダッシュをつかって、コメントを区切る「/*」と「*/」を無効にすることもできます。

    </para>
   </sect2>

   <!-- **** PL/pgSQL Variables and Constants **** -->
   <sect2>
<!--    <title>Variables and Constants</title> -->
    <title>変数と定数</title>
<indexterm><primary>PL/pgSQL</primary><secondary sortas="へんすう">変数</secondary></indexterm><indexterm><primary>PL/pgSQL</primary><secondary sortas="ていすう">定数</secondary></indexterm>
    <para>
<!--     All variables, rows and records used in a block or its
     sub-blocks must be declared in the declarations section of a block.
     The exception being the loop variable of a FOR loop iterating over a range
     of integer values.  -->

     ブロックまたはそのブロックの副ブロックで使われるすべての変数、行レコードはブロックの宣言節にて宣言されなければいけません。ただしFORのループにて整数値の範囲内を繰り返すループ変数は除きます。

    </para>

    <para>
<!--     PL/pgSQL variables can have any SQL datatype, such as
     <type>INTEGER</type>, <type>VARCHAR</type> and
     <type>CHAR</type>. All variables have as default value the
     <acronym>SQL</acronym> NULL value.  -->

     PL/pgSQLの変数は<type>INTEGER</type>、<type>VARCHAR</type>、<type>CHAR</type>といったSQLのデータ型を持つことができます。すべての変数はデフォルト値として<acronym>SQL</acronym>のNULL値が使用されます。

    </para>

    <para>
<!--     Here are some examples of variable declarations: -->
         変数宣言の例をいくつか示します。
</para>

<programlisting>
user_id INTEGER;
quantity NUMBER(5);
url VARCHAR;
</programlisting>

    <sect3 id="plpgsql-description-default-vars">
<!--     <title>Constants and Variables With Default Values</title> -->
     <title>デフォルト値を持つ定数と変数</title>
<indexterm><primary>PL/pgSQL</primary><secondary sortas="でふぉるとのあたい">デフォルトの値</secondary></indexterm>
     <para>
<!--      The declarations have the following syntax: -->
     宣言には以下の構文を使用します。
</para>

<synopsis>
<replaceable>name</replaceable> <optional> CONSTANT </optional> <replaceable>type</replaceable> <optional> NOT NULL </optional> <optional> { DEFAULT | := } <replaceable>value</replaceable> </optional>;
</synopsis>

     <para>
<!--      The value of variables declared as CONSTANT cannot be changed. If NOT NULL
      is specified, an assignment of a NULL value results in a runtime
      error. Since the default value of all variables is the
      <acronym>SQL</acronym> NULL value, all variables declared as NOT NULL
      must also have a default value specified. -->

      CONSTANTを付けて宣言された変数の値は変更することはできません。NOT NULLを指定した場合には、変数の値にNULLを割り当てるとランタイムエラーとなります。すべての変数のデフォルト値が<acronym>SQL</acronym>のNULLなので、NOT NULLとして宣言されるすべての変数はデフォルト値を指定しておかなければいけません。

     </para>

     <para>
<!--      The default value is evaluated every time the function is called. So
      assigning '<literal>now</literal>' to a variable of type
      <type>timestamp</type> causes the variable to have the
      time of the actual function call, not when the function was
      precompiled into its bytecode. -->

      デフォルト値は、関数が呼ばれるたびに評価されます。<type>timestamp</type>型の変数に「<literal>now</literal>」を割り当てておくと、変数には関数がバイトコードにプリコンパイルされたときではなくて実際に関数が呼び出された時間が渡されます。

     </para>

     <para>
<!--      Examples: -->
        例をいくつか示します。
</para>
          
<programlisting>
quantity INTEGER := 32;
url varchar := ''http://mysite.com'';
user_id CONSTANT INTEGER := 10;
</programlisting>
    </sect3>

    <sect3 id="plpgsql-description-passed-vars">
<!--     <title>Variables Passed to Functions</title> -->
     <title>関数に渡された変数</title>
<indexterm><primary>PL/pgSQL</primary><secondary sortas="ひきすう">引数</secondary></indexterm>
     <para>
<!--      Variables passed to functions are named with the identifiers
      <literal>$1</literal>, <literal>$2</literal>,
      etc. (maximum is 16). Some examples: -->

      関数に渡された変数は、<literal>$1</literal>、<literal>$2</literal>というように識別されます（最大16個）。いくつかの例を示します。
</para>

<programlisting>
CREATE FUNCTION sales_tax(REAL) RETURNS REAL AS '
DECLARE
    subtotal ALIAS FOR $1;
BEGIN
    return subtotal * 0.06;
END;
' LANGUAGE 'plpgsql';


CREATE FUNCTION instr(VARCHAR,INTEGER) RETURNS INTEGER AS '
DECLARE
    v_string ALIAS FOR $1;
    index ALIAS FOR $2;
BEGIN
    -- Some computations here
END;
' LANGUAGE 'plpgsql';
</programlisting>
    </sect3>

    <sect3 id="plpgsql-description-attributes">
<!--     <title>Attributes</title> -->
     <title>属性</title>
<indexterm><primary>PL/pgSQL</primary><secondary sortas="ぞくせい">属性</secondary></indexterm>
     <para>
<!--      Using the <type>%TYPE</type> and <type>%ROWTYPE</type>
      attributes, you can declare variables with the same
      datatype or structure of another database item (e.g: a
      table field).  -->

      <type>%TYPE</type>と<type>%ROWTYPE</type>属性を使用することで、もう1つのデータベース項目と同じデータ型もしくは構成で変数を宣言することができます（たとえば、テーブルのフィールド）。<indexterm><primary>PL/pgSQL</primary><secondary sortas="ぞくせい">属性</secondary><tertiary>%TYPE</tertiary></indexterm><indexterm><primary>PL/pgSQL</primary><secondary sortas="ぞくせい">属性</secondary><tertiary>%ROWTYPE</tertiary></indexterm><indexterm><primary>%TYPE</primary></indexterm><indexterm><primary>%ROWTYPE</primary></indexterm>

     </para>

     <variablelist>
      <varlistentry>
       <term>
        %TYPE
       </term>
       <listitem>
        <para>
<!--         <type>%TYPE</type> provides the datatype of a
         variable or database column. You can use this to
         declare variables that will hold database
         values. For example, let's say you have a column
         named <type>user_id</type> in your
         <type>users</type> table. To declare a variable with
         the same datatype as users you do: -->

         <type>%TYPE</type>は、変数のデータ型もしくはデータベースのカラムを提供します。データベース値をもつ変数を宣言するときにこれを使用することができます。たとえば、<type>users</type>テーブルというのがあって、<type>user_id</type>と名前の付けられたカラムがあるものとします。usersテーブルと同じデータ型の変数を宣言するには以下のようにします。
</para>

<programlisting>
user_id users.user_id%TYPE;
</programlisting>

        <para>
<!--         By using <type>%TYPE</type> you don't need to know
         the datatype of the structure you are referencing,
         and most important, if the datatype of the
         referenced item changes in the future (e.g: you
         change your table definition of user_id to become a
         REAL), you won't need to change your function
         definition. -->

         <type>%TYPE</type>を使うことで参照しているテーブルのデータ型を知っている必要があります、これは重要なことで、将来参照しているもののデータ変更されても（たとえば、user_idの定義をREALに変更する）関数定義を変更する必要がありません。

        </para>
       </listitem>
      </varlistentry>

      <varlistentry>
       <term>
        <replaceable>name</replaceable> <replaceable>table</replaceable>%ROWTYPE;
       </term>
       <listitem>
        <para>
<!--         Declares a row with the structure of the given
	 table. <replaceable>table</replaceable> must be an existing
	 table or view name of the database. The fields of the row are
	 accessed in the dot notation. Parameters to a function can be
	 composite types (complete table rows). In that case, the
	 corresponding identifier $n will be a rowtype, but it must be
	 aliased using the ALIAS command described above. -->

	指定テーブルの構造を持った行の宣言です。<replaceable>テーブル</replaceable>はデータベース内の既存のテーブルまたはビューの名前でなければいけません。行のフィールドはドット記述方法でアクセスされます。関数へのパラメータは複合型（完全なテーブルの行）でもかまいません。この場合、対応数識別子$nはrowtypeになりますが、後述のALIASコマンドを使って別名を付けなければいけません。

        </para>

        <para>
<!--         Only the user attributes of a table row are accessible in the
	 row, no OID or other system attributes (because the row could
	 be from a view).  The fields of the rowtype inherit the
	 table's field sizes or precision for <type>char()</type>
	 etc. data types. -->

	テーブルの行のうち、ユーザー用の行のみがアクセス可能で、oidやその他のシステム用の属性にはアクセスできません（なぜなら、ビューから行を持ってくることもあり得るからです）。rowtypeのフィールドは<type>char()</type>などのデータ型のフィールドサイズまたは精度を継承します。

        </para>
<programlisting>
DECLARE
    users_rec users%ROWTYPE;
  user_id users%TYPE;
BEGIN
    user_id := users_rec.user_id;
    ...

create function cs_refresh_one_mv(integer) returns integer as '
   DECLARE
        key ALIAS FOR $1;
        table_data cs_materialized_views%ROWTYPE;
   BEGIN
        SELECT INTO table_data * FROM cs_materialized_views
               WHERE sort_key=key;

        IF NOT FOUND THEN
           RAISE EXCEPTION ''View '' || key || '' not found'';
           RETURN 0;
        END IF;

        -- The mv_name column of cs_materialized_views stores view
        -- names.
 
        EXECUTE ''TRUNCATE TABLE '' || quote_ident(table_data.mv_name);
        EXECUTE ''INSERT INTO '' || quote_ident(table_data.mv_name) || '' '' || table_data.mv_query;
        return 1;
end;
' LANGUAGE 'plpgsql';
</programlisting>
       </listitem>
      </varlistentry>
     </variablelist>
    </sect3>

    <sect3 id="plpgsql-description-remaning-vars">
     <title>
      RENAME
     </title>
<indexterm><primary>RENAME</primary></indexterm><indexterm><primary>PL/pgSQL</primary><secondary>RENEME</secondary></indexterm>
     <para>
<!--      Using RENAME you can change the name of a variable, record
      or row. This is useful if NEW or OLD should be referenced
      by another name inside a trigger procedure. -->

      RENAMEを使用すると変数、レコード、行の名前を変更することができます。これは、トリガプロシージャ内でNEWまたはOLDを別の名前で参照すべき場合に有益です。

     </para>

     <para>
<!--      Syntax and examples: -->
          構文と使用例を示します。
</para>

<programlisting>
RENAME <replaceable>oldname</replaceable> TO <replaceable>newname</replaceable>;
RENAME id TO user_id;
RENAME this_var TO that_var;
</programlisting>
    </sect3>
   </sect2>

   <!-- **** PL/pgSQL expressions **** -->

   <sect2>
<!--    <title>Expressions</title> -->
    <title>式</title>
<indexterm><primary>PL/pgSQL</primary><secondary sortas="しき">式</secondary></indexterm>
    <para>
<!--     All expressions used in PL/pgSQL statements are processed using
     the backend's executor. Expressions that appear to contain
     constants may in fact require run-time evaluation
     (e.g. <literal>'now'</literal>  for the 
     <type>timestamp</type> type) so
     it is impossible for the PL/pgSQL parser
     to identify real constant values other than the NULL keyword. All
     expressions are evaluated internally by executing a query -->

     PL/pgSQLで使われる式はすべてバックエンドエクゼキュータを使用して処理されます。定数を含んだ式は実際には実行時に評価される必要がある場合もありますので（たとえば<type>timestamp</type>型の<literal>'now'</literal>）、PL/pgSQLパーサーによってNULLキーワード以外の定数値を識別することはできません。すべての式は、内部的に以下の問い合わせを<acronym>SPI</acronym>マネージャを使って実行することによって評価されます。
</para>

<synopsis>
<!-- SELECT <replaceable>expression</replaceable> -->
SELECT <replaceable>式</replaceable>
</synopsis>

<para>
<!--     using the <acronym>SPI</acronym> manager. In the expression, occurrences of variable
     identifiers are substituted by parameters and the actual values from
     the variables are passed to the executor in the parameter array. All
     expressions used in a PL/pgSQL function are only prepared and
     saved once.  The only exception to this rule is an EXECUTE statement
     if parsing of a query is needed each time it is encountered. -->

     <acronym>SPI</acronym>マネージャを使用してください。式の中では、変数の識別子の場所はパラメータに置き換えられ、パラメータ配列内の変数の実際の値はエクゼキュータに渡されます。PL/pgSQL関数内で使われるすべての式は1回だけ準備され保存されます。それが起こるたびに、問い合わせの構文解析が必要であるならば、このルールに対する唯一の例外はEXECUTE文です。

    </para>

    <para>
<!--     The type checking done by the <productname>Postgres</productname>
     main parser has some side
     effects to the interpretation of constant values. In detail there
     is a difference between what these two functions do: -->

     <productname>Postgres</productname>主パーサーによって行われる型チェックは定数値の解釈にいくつかの副作用があります。詳しくいうと、次の2つの関数が行うことには違いがあります。
</para>

<programlisting>
CREATE FUNCTION logfunc1 (text) RETURNS timestamp AS '
    DECLARE
        logtxt ALIAS FOR $1;
    BEGIN
        INSERT INTO logtable VALUES (logtxt, ''now'');
        RETURN ''now'';
    END;
' LANGUAGE 'plpgsql';
</programlisting>

<!--     and -->


<programlisting>
CREATE FUNCTION logfunc2 (text) RETURNS timestamp AS '
    DECLARE
        logtxt ALIAS FOR $1;
        curtime timestamp;
    BEGIN
        curtime := ''now'';
        INSERT INTO logtable VALUES (logtxt, curtime);
        RETURN curtime;
    END;
' LANGUAGE 'plpgsql';
</programlisting>

<para>
<!--     In the case of <function>logfunc1()</function>, the 
     <productname>Postgres</productname> main parser knows when 
     preparing the plan for the INSERT, that the string 
     <literal>'now'</literal> should be interpreted as 
     <type>timestamp</type> because the target field of logtable
     is of that type. Thus, it will make a constant from it at this
     time and this constant value is then used in all invocations of 
     <function>logfunc1()</function> during the lifetime of the
     backend. Needless to say that this isn't what the
     programmer wanted. -->

     <function>logfunc1()</function>の場合、<productname>Postgres</productname>主パーサーは、INSERT用のプランを準備する際に、logtableフィールドの対象フィールドが<type>timestamp</type>型であるので<literal>'now'</literal>という文字列は<type>timestamp</type>型として解釈すべきであることを判断します。したがって、この段階で定数を作成し、バックエンドの生存期間の間の<function>logfunc1()</function>のすべての呼び出しにおいて、この数値が使用されることになります。いうまでもないことですが、これはプログラマが予定したものではありません。

    </para>

    <para>
<!--     In the case of <function>logfunc2()</function>, the 
     <productname>Postgres</productname> main parser does not know
     what type <literal>'now'</literal> should become and therefore 
     it returns a data type of <type>text</type> containing the string 
     <literal>'now'</literal>. During the assignment
     to the local variable curtime, the PL/pgSQL interpreter casts this
     string to the timestamp type by calling the
     <function>text_out()</function> and <function>timestamp_in()</function>
     functions for the conversion. -->

     <function>logfunc2()</function>の場合、<productname>Postgres</productname>主パーサーは、<literal>'now'</literal>の型を何にすべきかを判断できませんので、<literal>'now'</literal>という文字列を持った<type>text</type>型を返します。ローカル変数curtimeに代入するときに、PL/pgSQLインタプリタは変換用に<function>text_out()</function>と<function>timestamp_in()</function>関数を呼び出して、この文字列をtimestap型にキャストします。

    </para>

    <para>
<!--     This type checking done by the <productname>Postgres</productname> main
     parser got implemented after PL/pgSQL was nearly done.
     It is a difference between 6.3 and 6.4 and affects all functions
     using the prepared plan feature of the <acronym>SPI</acronym> manager.
     Using a local
     variable in the above manner is currently the only way in PL/pgSQL to get
     those values interpreted correctly. -->

     この<productname>Postgres</productname>主パーサーによってなされる型チェックは、PL/pgSQLがほとんどできた後に実装されました。6.3と6.4では違いがあり、SPIマネージャの計画準備機能を使用するすべての関数に影響を与えます。上の方法でローカル変数を使うことが、PL/pgSQLでこれらの値を正しく解釈させる、現時点で唯一の方法です。

    </para>

    <para>
<!--     If record fields are used in expressions or statements, the data types of
     fields should not change between calls of one and the same expression.
     Keep this in mind when writing trigger procedures that handle events
     for more than one table. -->

     式や文でレコードフィールドを使用する場合は、そのフィールドのデータ型を関数呼び出しと式の間で変更すべきではありません。1つ以上のテーブルのイベントを扱うトリガプロシージャを記述するときには気をつけてください。

    </para>
   </sect2>

   <!-- **** PL/pgSQL statements **** -->

  <sect2>
<!--   <title>Statements</title> -->
   <title>文</title>
<indexterm><primary>PL/pgSQL</primary><secondary sortas="ぶん">文</secondary></indexterm>
   <para>
<!--    Anything not understood by the PL/pgSQL parser as specified below
    will be put into a query and sent down to the database engine
    to execute. The resulting query should not return any data. -->

    下で指定されたPL/pgSQLパーサーによって理解されないものはすべて、問い合わせ内に格納され、実行するためのデータベースエンジンに送られます。問い合わせの結果はデータをまったく返しません。

   </para>
   
   <sect3 id="plpgsql-statements-assignment">
<!--    <title>Assignment</title> -->
    <title>代入</title>
<indexterm><primary>PL/pgSQL</primary><secondary sortas="だいにゅう">代入</secondary></indexterm>
    <para>
<!--     An assignment of a value to a variable or row/record field is
     written as: -->

     変数や行/レコードフィールドへの値の代入は次のように記述されます。
</para>

<synopsis>
<replaceable>identifier</replaceable> := <replaceable>expression</replaceable>;
</synopsis>

<para>
<!--     If the expressions result data type doesn't match the variables
     data type, or the variable has a size/precision that is known
     (as for <type>char(20)</type>), the result value will be implicitly casted by
     the PL/pgSQL bytecode interpreter using the result types output- and
     the variables type input-functions. Note that this could potentially
     result in runtime errors generated by the types input functions. -->

     式の結果のデータ型が変数のデータ型と合わなかった場合、または、変数がサイズ/精度を持つことがわかっていた場合（char(20)となど）、PL/pgSQLバイトコードインタープリタが結果の型の出力関数と変数の型の入力関数を使用することによって、結果の値は暗黙的にキャストされます。型の入力関数によって生成される実行時のエラーの元になることに注意してください。

    </para>

<programlisting>
user_id := 20;
tax := subtotal * 0.06;
</programlisting>
   </sect3>

   <sect3 id="plpgsql-statements-calling-other-funcs">
<!--    <title>Calling another function</title> -->
    <title>他の関数の呼び出し</title>
<indexterm><primary>PL/pgSQL</primary><secondary sortas="かんすうのよびだし">関数の呼び出し</secondary></indexterm>
    <para>
<!--     All functions defined in a <productname>Postgres</productname>
     database return a value. Thus, the normal way to call a function
     is to execute a SELECT query or doing an assignment (resulting
     in a PL/pgSQL internal SELECT).  -->

     <productname>Postgres</productname>データベース内に定義されたすべての関数は値を返します。したがって、関数の通常の呼び出し方法は、SELECTを実行することか、（PL/pgSQL内部でSELECTを実行した結果である）代入を行うことです。

    </para>

    <para>
<!--     But there are cases where someone is not interested in the 
     function's result. In these cases, use the PERFORM
     statement. -->

     しかし、関数の結果には興味がない場合もあります。この場合はPERFORM文を使用しています。<indexterm><primary>PERFORM</primary></indexterm><indexterm><primary>PL/pgSQL</primary><secondary>PERFORM</secondary></indexterm>
</para>

<synopsis>
PERFORM <replaceable>query</replaceable>
</synopsis>

<para>
<!--     This executes a <literal>SELECT <replaceable>query</replaceable></literal> over the
     <acronym>SPI manager</acronym> and discards the result. Identifiers like local
     variables are still substituted into parameters. -->

     この実行は<acronym>SPIマネージャ</acronym>を通して<literal>SELECT <replaceable>問い合わせ</replaceable></literal>を実行し、その結果を捨てます。ローカル変数といった識別子はパラメータに置換されます。
</para>

<programlisting>
PERFORM create_mv(''cs_session_page_requests_mv'',''
     select   session_id, page_id, count(*) as n_hits,
              sum(dwell_time) as dwell_time, count(dwell_time) as dwell_count
     from     cs_fact_table
     group by session_id, page_id '');
</programlisting>
   </sect3>
   
   <sect3 id="plpgsql-statements-executing-dyn-queries">
<!--    <title>Executing dynamic queries</title> -->
    <title>動的問い合わせの実行</title>
<indexterm><primary sortas="どうてきなといあわせ">動的な問い合わせ</primary></indexterm><indexterm><primary>PL/pgSQL</primary><secondary sortas="どうてきなといあわせ">動的な問い合わせ</secondary></indexterm>
    <para>
<!--     Often times you will want to generate dynamic queries inside
     your PL/pgSQL functions. Or you have functions that will
     generate other functions. PL/pgSQL provides the EXECUTE
     statement for these occasions. -->

     PL/pgSQL関数を内部で動的問い合わせを行いたいということがあるかもしれません。もしくは他の関数を生成する関数を持っているかもしれません。PL/pgSQLは、EXECUTE文をこういう場合のために用意しています。<indexterm><primary>EXECUTE</primary></indexterm><indexterm><primary>PL/pgSQL</primary><secondary>EXECUTE</secondary></indexterm>

    </para>

<synopsis>
EXECUTE <replaceable class="command">query-string</replaceable>
</synopsis>

<para>
<!--     where <replaceable>query-string</replaceable> is a string of type
     <type>text</type> containing the <replaceable>query</replaceable>
     to be executed. -->

     <replaceable>query-string</replaceable>にはデータ型が<type>text</type>の文字列を含む実行される<replaceable>query</replaceable>を指定します。

    </para>

    <para>
<!--    When working with dynamic queries you will have to face
    escaping of single quotes in PL/pgSQL. Please refer to the
    table available at the "Porting from Oracle PL/SQL" chapter
    for a detailed explanation that will save you some effort. -->

    動的な問い合わせを行うとき、PL/pgSQLでは一重引用符をエスケープしなければいけません。詳細な説明として、<xref linkend="plpgsql-porting">で利用できるテーブルを参照すれば労力の節約になります。

    </para>
     
    <para>
<!--     Unlike all other queries in PL/pgSQL, a
     <replaceable>query</replaceable> run by an EXECUTE statement is
     not prepared and saved just once during the life of the server.
     Instead, the <replaceable>query</replaceable> is prepared each
     time the statement is run. The
     <replaceable>query-string</replaceable> can be dynamically
     created within the procedure to perform actions on variable
     tables and fields. -->

     PL/pgSQLでは他のすべての問い合わせとは異なり、EXECUTE文によって<replaceable>query</replaceable>を実行する場合は、サーバーの生存期間中一度だけ解釈、保存されるわけではありません。代わりに、<replaceable>query</replaceable>は文ば実行されるときに準備されます。<replaceable>query-string</replaceable>は、変数テーブルとフィールドに及ぼす働きを実行するために手続きの範囲内で動的につくられることができます。

    </para>
  
    <para>
<!--     The results from SELECT queries are discarded by EXECUTE, and
     SELECT INTO is not currently supported within EXECUTE.  So, the
     only way to extract a result from a dynamically-created SELECT is
     to use the FOR ... EXECUTE form described later. -->

     SELECT問い合わせのからの結果はEXECUTEによって捨てられます。そして、SELECT INTOはEXECUTE範囲内では現在サポートされません。そして、結果を動的に作成されたSELECTから抜き出す唯一の方法は後で述べるFOR ... EXECUTEを使用することです。

    </para>

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

<synopsis>
EXECUTE ''UPDATE tbl SET ''
        || quote_ident(fieldname)
        || '' = ''
        || quote_literal(newvalue)
        || '' WHERE ...'';
</synopsis>

    <para>
<!--     This example shows use of the functions
     <function>quote_ident</function>(<type>TEXT</type>) and
     <function>quote_literal</function>(<type>TEXT</type>).
     Variables containing field and table identifiers should be
     passed to function <function>quote_ident()</function>.
     Variables containing literal elements of the dynamic query
     string should be passed to
     <function>quote_literal()</function>.  Both take the
     appropriate steps to return the input text enclosed in single
     or double quotes and with any embedded special characters. -->

     この例は、<function>quote_ident</function>(<type>TEXT</type>)関数と<function>quote_literal</function>(<type>TEXT</type>)関数の使用方法を示しています。フィールドとテーブル識別子を含んでいる変数は関数<function>quote_ident()</function>を通らなければいけません。ダイナミックな問い合わせ文字列のリテラル要素を含んでいる変数は<function>quote_literal()</function>を通らなければいけません。両方とも一重引用符もしくは二重引用符で、そして、どんな埋め込まれた特殊文字ででも囲まれる入力テキストを返すために適切なステップをとっています。

    </para>

    <para>
<!--     Here is a much larger example of a dynamic query and EXECUTE: -->
        大きな動的問い合わせとEXECUTEの例を示します。
</para>
     
<programlisting>
CREATE FUNCTION cs_update_referrer_type_proc() RETURNS INTEGER AS '
DECLARE
    referrer_keys RECORD;  -- Declare a generic record to be used in a FOR
    a_output varchar(4000);
BEGIN 
    a_output := ''CREATE FUNCTION cs_find_referrer_type(varchar,varchar,varchar) 
                  RETURNS varchar AS '''' 
                     DECLARE 
                         v_host ALIAS FOR $1; 
                         v_domain ALIAS FOR $2; 
                         v_url ALIAS FOR $3; ''; 

    -- 
    -- <!--Notice how we scan through the results of a query in a FOR loop-->FOR lootpでFOR &lt;record&gt;構造を使ってクエリ結果をスキャンする
    -- <!--using the FOR &lt;record&gt; construct.-->方法に注意してください。
    --


    FOR referrer_keys IN select * from cs_referrer_keys order by try_order LOOP
        a_output := a_output || '' if v_'' || referrer_keys.kind || '' like '''''''''' 
                 || referrer_keys.key_string || '''''''''' then return '''''' 
                 || referrer_keys.referrer_type || ''''''; end if;''; 
    END LOOP; 
  
    a_output := a_output || '' return null; end; '''' language ''''plpgsql'''';''; 
 
    -- <!--This works because we are not substituting any variables-->これは、どの変数も置き換えていないのでうまくいきます。
    -- <!--Otherwise it would fail. Look at PERFORM for another way to run functions-->そうでなければ失敗します。
    -- 関数を実行する他の方法についてはPERFORMを参照してください。
    
    EXECUTE a_output; 
end; 
' LANGUAGE 'plpgsql';
</programlisting>
   </sect3>

   <sect3 id="plpgsql-statements-diagnostics">
<!--    <title>Obtaining other results status</title> -->
    <title>返り値ステータスの取得</title>
<indexterm><primary>PL/pgSQL</primary><secondary sortas="かえりち">返り値</secondary><tertiary sortas="すてーたす">ステータス</tertiary></indexterm><indexterm><primary>GET DIAGNOSTICS</primary></indexterm><indexterm><primary>PL/pgSQL</primary><secondary>GET DIAGNOSTICS</secondary></indexterm>
<synopsis>
GET DIAGNOSTICS <replaceable>variable</replaceable> = <replaceable>item</replaceable> <optional> , ... </optional>
</synopsis>

<para>

     <!--This command allows retrieval of system status indicators.  Each
     <replaceable>item</replaceable> is a keyword identifying a state
     value to be assigned to the specified variable (which should be
     of the right datatype to receive it).  The currently available
     status items are <varname>ROW_COUNT</>, the number of rows
     processed by the last <acronym>SQL</acronym> query sent down to
     the <acronym>SQL</acronym> engine; and <varname>RESULT_OID</>,
     the Oid of the last row inserted by the most recent
     <acronym>SQL</acronym> query.  Note that <varname>RESULT_OID</>
     is only useful after an INSERT query. -->

     このコマンドは、システムステータスインジケータの検索を許可します。それぞれの<replaceable>item</replaceable>は、指定された変数に割り当てられる状態を値識別するキーワードです（受信するために正しいデータ型でなければいけません）。現在利用できるステータス項目は<varname>ROW_COUNT</>です。最後の<acronym>SQL</acronym>問い合わせによって処理される行の番号が<acronym>SQL</acronym>エンジンに送られます。そして、<varname>RESULT_OID</>が、最も最近の<acronym>SQL</acronym>問い合わせによって挿入された最後の行のOIDです。<varname>RESULT_OID</>がINSERT問い合わせの後にだけ役に立つという点に注意してください。

    </para>
   </sect3>
   
   <sect3 id="plpgsql-statements-returning">
<!--    <title>Returning from a function</title> -->
    <title>関数からの返り値</title>
<indexterm><primary>PL/pgSQL</primary><secondary sortas="かえりち">返り値</secondary></indexterm><indexterm><primary>RETURN</primary></indexterm><indexterm><primary>PL/pgSQL</primary><secondary>RETURN</secondary></indexterm>
<synopsis>
<!-- RETURN <replaceable>expression</replaceable> -->
RETURN <replaceable>式</replaceable>
</synopsis>

<para>
<!--     The function terminates and the value of
     <replaceable>expression</replaceable> will be returned to the
     upper executor. The return value of a function cannot be
     undefined. If control reaches the end of the top-level block of
     the function without hitting a RETURN statement, a runtime error
     will occur. -->

     関数は終了し、<replaceable>式</replaceable>の値は上位のエクゼキュータに返されます。関数の戻り値を未定義にすることはできません。制御がRETURN文に到達せず関数の最上位ブロックの終わりに達した場合、実行時エラーが発生します。

    </para>

    <para>
<!--     The expressions result will be automatically casted into the
     function's return type as described for assignments. -->

     式の結果は自動的に、代入用に記述された関数の戻り値の型にキャストされます。

    </para>
   </sect3>
  </sect2>

   <!-- **** PL/pgSQL Control Structures **** -->

  <sect2 id="plpgsql-description-control-structures">

<!--   <title>Control Structures</title> -->
   <title>制御構造</title>
<indexterm><primary>PL/pgSQL</primary><secondary sortas="せいぎょこうぞう">制御構造</secondary></indexterm>
   <para>
<!--    Control structures are probably the most useful (and
    important) part of PL/SQL. With PL/pgSQL's control structures,
    you can manipulate <productname>PostgreSQL</> data in a very
    flexible and powerful way.  -->

    制御構造はおそらくPL/SQLの有益な（重要な）部分です。PL/pgSQLの制御構造で、あなたは非常に柔軟で強力な方法で<productname>PostgreSQL</>のデータを処理することができます。

   </para>

   <sect3 id="plpgsql-description-conditionals">
<!--    <title>Conditional Control: IF statements</title> -->
    <title>制御構造――IF文</title>
<indexterm><primary>PL/pgSQL</primary><secondary sortas="せいぎょこうぞう">制御構造</secondary><tertiary>IF</tertiary></indexterm>
    <para>
<!--     <function>IF</function> statements let you take action
     according to certain conditions. PL/pgSQL has three forms of
     IF: IF-THEN, IF-THEN-ELSE, IF-THEN-ELSE IF. NOTE: All
     PL/pgSQL IF statements need a corresponding <function>END
     IF</function> statement. In ELSE-IF statements you need two:
     one for the first IF and one for the second (ELSE IF). -->

     <function>IF</function>文は、特定の条件によって行動を起こすものです。PL/pgSQLにはIF-THEN、IF-THEN-ELSE、IF-THEN-ELSE IFの3つのIFの形式があります。すべてのPL/pgSQLでIF文は対応する<function>END IF</function>文を必要とすることに注意してください。ELSE-IF文では2つの文必要です。1つは最初のIFでもう1つは2番目のELSE IFです。

    </para>

    <variablelist>
     <varlistentry>
      <term>
       IF-THEN
      </term>

      <listitem>
       <para>
<!--        IF-THEN statements is the simplest form of an IF. The
        statements between THEN and END IF will be executed if
        the condition is true. Otherwise, the statements
        following END IF will be executed. -->

	IF-THEN文は最も単純なIFの形式です。この条件が真ならば、THENとEND IFの間の文が実行されます。偽の場合は、END IFに続いている文が実行されます。
</para>

<programlisting>
IF v_user_id &lt;&gt; 0 THEN
    UPDATE users SET email = v_email WHERE user_id = v_user_id;
END IF;
</programlisting>

      </listitem>
     </varlistentry>

     <varlistentry>
      <term>
       IF-THEN-ELSE
      </term>

      <listitem>
       <para>
<!--        IF-THEN-ELSE statements adds to IF-THEN by letting you
        specify the statements that should be executed if the
        condition evaluates to FALSE. -->

	IF-THEN-ELSE文はIF-THENに、条件式に評価してFALSEだった場合に実行すべき文を追加で指定します。
</para>


<programlisting>
IF parentid IS NULL or parentid = ''''
THEN 
    return fullname;
ELSE
    return hp_true_filename(parentid) || ''/'' || fullname;
END IF;


IF v_count > 0 THEN 
    INSERT INTO users_count(count) VALUES(v_count);
    return ''t'';
ELSE 
    return ''f'';
END IF;
</programlisting>

       <para>
<!--        IF statements can be nested and in the following
        example: -->

	IF文は次の例のようにネストさせることができます。
</para>

<programlisting>
IF demo_row.sex = ''m'' THEN
  pretty_sex := ''man'';
ELSE
  IF demo_row.sex = ''f'' THEN
    pretty_sex := ''woman'';
  END IF;
END IF;
</programlisting>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>
       IF-THEN-ELSE IF
      </term>

      <listitem>
       <para>
<!--        When you use the "ELSE IF" statement, you are actually
        nesting an IF statement inside the ELSE
        statement. Thus you need one END IF statement for each
        nested IF and one for the parent IF-ELSE. -->

	「ELSE-IF」文を使用するとき、実際にはELSE文の中にIF文を入れ子にしていきます。このため、END IF文が、入れ子になったIF文それぞれにつき1つ、上位のIF-ELSE用に1つ必要になります。

       </para>

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

<programlisting>
IF demo_row.sex = ''m'' THEN
   pretty_sex := ''man'';
ELSE IF demo_row.sex = ''f'' THEN
        pretty_sex := ''woman'';
     END IF;
END IF;
</programlisting>
      </listitem>
     </varlistentry>
    </variablelist>
   </sect3>

   <sect3 id="plpgsql-description-control-structures-loops">
<!--    <title>Iterative Control: LOOP, WHILE, FOR and EXIT</title> -->
    <title>繰り返し制御――LOOP、WHILE、FOR、EXIT</title>
<indexterm><primary>PL/pgSQL</primary><secondary sortas="せいぎょこうぞう">制御構造</secondary><tertiary>LOOP</tertiary></indexterm><indexterm><primary>PL/pgSQL</primary><secondary sortas="せいぎょこうぞう">制御構造</secondary><tertiary>WHILE</tertiary></indexterm><indexterm><primary>PL/pgSQL</primary><secondary sortas="せいぎょこうぞう">制御構造</secondary><tertiary>FOR</tertiary></indexterm><indexterm><primary>PL/pgSQL</primary><secondary sortas="せいぎょこうぞう">制御構造</secondary><tertiary>EXIT</tertiary></indexterm>
    <para>
     LOOP、WHILE、FORとEXIT文で、PL/pgSQLプログラムの実行の流れを制御することができます。
    </para>

    <variablelist>
     <varlistentry>
      <term>
       LOOP
      </term>

      <listitem>
<synopsis>
<optional>&lt;&lt;label&gt;&gt;</optional>
LOOP
    <replaceable>statements</replaceable>
END LOOP;
</synopsis>

<para>
<!--        An unconditional loop that must be terminated explicitly
        by an EXIT statement. The optional label can be used by
        EXIT statements of nested loops to specify which level of
        nesting should be terminated. -->

        無条件のループはEXIT文により明示的に終了されなければいけません。入れ子になったループのある特定の入れ子を終了させるために、EXIT文では、任意のラベルを使用して指定したレベルの入れ子を終了させることができます。
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>
       EXIT
      </term>

      <listitem>
<synopsis>
EXIT <optional> <replaceable>label</replaceable> </optional> <optional> WHEN <replaceable>expression</replaceable> </optional>;
</synopsis>

<para>
<!--        If no <replaceable>label</replaceable> is given,
        the innermost loop is terminated and the
        statement following END LOOP is executed next.
        If <replaceable>label</replaceable> is given, it
        must be the label of the current or an upper level of nested loop
        blocks. Then the named loop or block is terminated and control
        continues with the statement after the loops/blocks corresponding
        END. -->

	<replaceable>label</replaceable>が指定されていない場合は、最も内側にあるループを終了させ、END LOOPの後にある文を実行します。<replaceable>label</replaceable>が指定されている場合、そのラベルは現在の、または、入れ子になったループブロックの上位レベルのラベル名である必要があります。その後、その名前のループまたはブロックは終了され、制御はそのループ/ブロックに対応するENDに後の文に移動します。

       </para>

       <para>
<!--        Examples: -->
       例を示します。
</para>

<programlisting>
LOOP
    -- some computations
    IF count > 0 THEN
        EXIT;  -- exit loop
    END IF;
END LOOP;

LOOP
    -- some computations
    EXIT WHEN count > 0;
END LOOP;

BEGIN
    -- some computations
    IF stocks > 100000 THEN
        EXIT;  -- illegal. Can't use EXIT outside of a LOOP
    END IF;
END;
</programlisting>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>
       WHILE
      </term>

      <listitem>
       <para>
<!--        With the WHILE statement, you can loop through a
        sequence of statements as long as the evaluation of
        the condition expression is true. -->

    WHILE文で条件式の評価が真になる限り、文のシーケンスを通してループすることができます。
</para>

<synopsis>
<optional>&lt;&lt;label&gt;&gt;</optional>
WHILE <replaceable>expression</replaceable> LOOP
    <replaceable>statements</replaceable>
END LOOP;
</synopsis>

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

<programlisting>
WHILE amount_owed > 0 AND gift_certificate_balance > 0 LOOP
    -- some computations here
END LOOP;

WHILE NOT boolean_expression LOOP
    -- some computations here
END LOOP;
</programlisting>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>
       FOR
      </term>

      <listitem>
<synopsis>
<optional>&lt;&lt;label&gt;&gt;</optional>
FOR <replaceable>name</replaceable> IN <optional> REVERSE </optional> <replaceable>expression</replaceable> .. <replaceable>expression</replaceable> LOOP
    <replaceable>statements</replaceable>
END LOOP;
</synopsis>

<para>
<!--        A loop that iterates over a range of integer values. The variable
        <replaceable>name</replaceable> is automatically created as type
        integer and exists only inside the loop. The two expressions giving
        the lower and upper bound of the range are evaluated only when entering
        the loop. The iteration step is always 1. -->

    ループは整数値の範囲を繰り返すものです。変数の<replaceable>name</replaceable>はinteger型でループ内だけに存在するものとして自動的に作成されます。範囲の下限と上限を与える2つの式はループに入るときだけ評価されます。繰り返しステップは常に1です。

       </para>

       <para>
<!--        Some examples of FOR loops (see <xref
        linkend="plpgsql-description-records"> for iterating over
        records in FOR loops): -->

	FORループの例を示します（FORループがレコードについて繰り返しを行う例は<xref linkend="plpgsql-description-records">を参照してください）。
</para>

<programlisting>
FOR i IN 1..10 LOOP
  -- some expressions here

    RAISE NOTICE ''i is %'',i;
END LOOP;

FOR i IN REVERSE 1..10 LOOP
    -- some expressions here
END LOOP;
</programlisting>
      </listitem>
     </varlistentry>
    </variablelist>
      </sect3>
   </sect2>

   <!-- **** PL/pgSQL records **** -->

  <sect2 id="plpgsql-description-records">
<!--   <title>Working with RECORDs</title> -->
   <title>RECORDのはたらき</title>
<indexterm><primary>RECORD</primary></indexterm><indexterm><primary>PL/pgSQL</primary><secondary>RECORD</secondary></indexterm><indexterm><primary sortas="でーたがた">データ型</primary><secondary>RECORD</secondary></indexterm>
   <para>
<!--    Records are similar to rowtypes, but they have no predefined structure.
    They are used in selections and FOR loops to hold one actual
    database row from a SELECT operation. -->

    レコードはrowtypeと似ていますが、構造を事前に定義しません。SELECT操作で得た実際のデータベースの行を保持するための選択とFORループで使われます。

   </para>

   <sect3 id="plpgsql-description-records-declaration">
<!--    <title>Declaration</title> -->
    <title>宣言</title>

    <para>
<!--     One variables of type RECORD can be used for different
     selections. Accessing a record or an attempt to assign
     a value to a record field when there is no actual row in it results
     in a runtime error. They can be declared like this: -->

     RECORD型の1つの変数は、さまざまな選択に使うことができます。その中の行が終わる物がないときにはランタイムエラーが起こるので、レコードにアクセスするか1つのレコードフィールドに1つの値を割り当てることを試みてください。以下のように宣言することができます。

    </para>

<synopsis>
<replaceable>name</replaceable> RECORD;
</synopsis>
   </sect3>

   <sect3 id="plpgsql-description-records-assignment">
<!--    <title>Assignments</title> -->
    <title>代入</title>

    <para>
<!--     An assignment of a complete selection into a record or row can
     be done by: -->

     SELECT結果をすべてレコードや行に代入するには次のようにします。
</para>

<synopsis>
SELECT  INTO <replaceable>target</replaceable> <replaceable>expressions</replaceable> FROM ...;
</synopsis>

<para>
<!--     <replaceable>target</replaceable> can be a record, a row variable
     or a comma separated list of variables and
     record-/row-fields. Note that this is quite different from
     Postgres' normal interpretation of SELECT INTO, which is that the
     INTO target is a newly created table.  (If you want to create a
     table from a SELECT result inside a PL/pgSQL function, use the
     equivalent syntax <command>CREATE TABLE AS SELECT</command>.) -->

     <replaceable>target</replaceable>部分には、レコード、行変数、カンマで区切られた変数のリストとレコード/行列が入ることができます。これは通常のPostgresで実装されているSELECT INTOとはまったく異なることに注意してください。また、これはINTOのターゲットに指定されるものは新しいテーブルを作成することを意味します（PL/pgSQL関数内でSELECTの結果から新しいテーブルを作成したい場合には、同等の構文を使う<command>CREATE TABLE AS SELECT</command>を使ってください）。

    </para>

    <para>
<!--     If a row or a variable list is used as target, the selected values
     must exactly match the structure of the target(s) or a runtime error
     occurs. The FROM keyword can be followed by any valid qualification,
     grouping, sorting etc. that can be given for a SELECT statement. -->

     行や変数のリストをターゲットとして使用する場合には、SELECTの結果の値はターゲットの構造と完全に一致する必要があり、一致しない場合にはランタイムエラーが発生します。FROMキーワードの後にあらゆる有効な修飾、グループ分け、ソートなどを指定することができ、これらはSELECT文に引き渡すことができます。


    </para>

    <para>
<!--     Once a record or row has been assigned to a RECORD variable,
     you can use the "." (dot) notation to access fields in that
     record: -->

     レコードや行がRECORD変数に代入されたら、「.」（ドット）表記を使用してそのレコードのフィールドにアクセスすることができます。
</para>

<programlisting>
DECLARE
    users_rec RECORD;
    full_name varchar;
BEGIN
    SELECT INTO users_rec * FROM users WHERE user_id=3;

  full_name := users_rec.first_name || '' '' || users_rec.last_name;
</programlisting>

    <para>
<!--     There is a special variable named FOUND of type
     <type>boolean</type> that can be used immediately after a SELECT
     INTO to check if an assignment had success. -->

     FOUNDという特殊変数があります。これはSELECT INTOが実行されたらただちに使用可能で、SELECT INTO文が成功したかどうかの確認を行い<type>boolean</type>型を返します。
</para>

<programlisting>
SELECT INTO myrec * FROM EMP WHERE empname = myname;
IF NOT FOUND THEN
    RAISE EXCEPTION ''employee % not found'', myname;
END IF;
</programlisting>

<para>
<!--     You can also use the IS NULL (or ISNULL) conditionals to
     test for NULLity of a RECORD/ROW. If the selection returns
     multiple rows, only the first is moved into the target
     fields. All others are silently discarded. -->

     RECORD/ROWがNULLであるかどうかを検査するためにIS NULL（もしくはISNULL）条件文を使うこともできます。結果が複数行を返すならば、最初の行だけがターゲットフィールドに移動されます。それ以外は削除されます。

    </para>

<programlisting>
DECLARE
    users_rec RECORD;
    full_name varchar;
BEGIN
    SELECT INTO users_rec * FROM users WHERE user_id=3;

    IF users_rec.homepage IS NULL THEN
        -- <!--user entered no homepage, return "http://"-->ユーザーはホームページ以外を入力したので「http://」を返す。

        return ''http://'';
    END IF;
END;
</programlisting>
   </sect3>

   <sect3 id="plpgsql-description-records-iterating">
<!--    <title>Iterating Through Records</title> -->
    <title>レコード処理の繰り返し</title>

    <para>
<!--     Using a special type of FOR loop, you can iterate through
     the results of a query and manipulate that data
     accordingly. The syntax is as follow: -->

     FORループの特別な型を使用することにより、問い合わせの結果を繰り返し取り出し、順番にデータを処理することができます。構文は以下のとおりです。
</para>

<synopsis>
<optional>&lt;&lt;label&gt;&gt;</optional>
FOR <replaceable>record | row</replaceable> IN <replaceable>select_clause</replaceable> LOOP
    <replaceable>statements</replaceable>
END LOOP;
</synopsis>

<para>
<!--     The record or row is assigned all the rows 
     resulting from the select clause and the loop body executed 
     for each. Here is an example: -->

     レコードにSELECT文の結果すべてが代入されてループの本体がそれぞれのレコードまたは行のために実行されます。以下に例を示します。

    </para>

<programlisting>
create function cs_refresh_mviews () returns integer as '
DECLARE
     mviews RECORD;

     -- <!--Instead, if you did:-->もし代わりに以下のようにすると、
     -- mviews  cs_materialized_views%ROWTYPE;
     -- <!--this record would ONLY be usable for the cs_materialized_views table-->このレコードはcs_materialized_viewsテーブルでしか使えなくなります。

BEGIN
     PERFORM cs_log(''Refreshing materialized views...'');

     FOR mviews IN SELECT * FROM cs_materialized_views ORDER BY sort_key LOOP

         -- Now "mviews" has one record from cs_materialized_views

         PERFORM cs_log(''Refreshing materialized view '' || quote_ident(mviews.mv_name) || ''...'');
         EXECUTE ''TRUNCATE TABLE  '' || quote_ident(mviews.mv_name);
         EXECUTE ''INSERT INTO '' || quote_ident(mviews.mv_name) || '' '' || mviews.mv_query;
     END LOOP;

     PERFORM cs_log(''Done refreshing materialized views.'');
     return 1;
end;
' language 'plpgsql';
</programlisting>

<para>
<!--     If the loop is terminated with an EXIT statement, the last
     assigned row is still accessible after the loop. -->

     ループがEXIT文で終了された場合、最後に代入された行はループの後も引き続きアクセスできます。

    </para>

    <para>
<!--     The FOR-IN EXECUTE statement is another way to iterate over
     records: -->

     レコード処理の繰り返しのもう1つの方法として、FOR-IN EXECUTE文が使用できます。
</para>

<synopsis>
<optional>&lt;&lt;label&gt;&gt;</optional>
FOR <replaceable>record | row</replaceable> IN EXECUTE <replaceable>text_expression</replaceable> LOOP 
    <replaceable>statements</replaceable>
END LOOP;
</synopsis>

<para>
<!--     This is like the previous form, except that the source SELECT
     statement is specified as a string expression, which is evaluated
     and re-planned on each entry to the FOR loop.  This allows the
     programmer to choose the speed of a pre-planned query or the
     flexibility of a dynamic query, just as with a plain EXECUTE
     statement. -->

     これは元のSELECT文が文字列式として指定されていること以外は、以前の形式に似ています。つまり評価されて、それぞれFORループに再計画されているのです。プログラマあらかじめ計画された問い合わせの高速性あるいは動的問い合わせの柔軟性のどちらかも選ぶことができます。

    </para>
   </sect3>
  </sect2>

  <sect2 id="plpgsql-description-aborting-and-messages">
<!--   <title>Aborting and Messages</title> -->
   <title>アボートとメッセージ</title>
<indexterm><primary sortas="あぼーと">アボート</primary></indexterm><indexterm><primary>PL/pgSQL</primary><secondary sortas="あぼーと">アボート</secondary></indexterm>
   <para>
<!--    Use the RAISE statement to throw messages into the 
    <productname>Postgres</productname> elog mechanism. -->

    <productname>Postgres</productname>のelog機能にメッセージを投げ掛けるにはRAISE文を使用してください。
</para>

<synopsis>
<!-- RAISE <replaceable class="parameter">level</replaceable> '<replaceable class="parameter">format</replaceable>' <optional>, <replaceable class="parameter">identifier</replaceable> <optional>...</optional></optional>; -->

RAISE<!--<replaceable class="parameter">-->のレベルには、<!--</replaceable> -->'<replaceable class="parameter">format</replaceable>' <optional>, <replaceable class="parameter">identifier</replaceable> <optional>...</optional></optional>などがあります。
</synopsis>

<para>
<!--    Inside the format, <literal>%</literal> is used as a placeholder for the
    subsequent comma-separated identifiers. Possible levels are
    DEBUG (silently suppressed in production running databases), NOTICE 
    (written into the database log and forwarded to the client application)
    and EXCEPTION (written into the database log and aborting the transaction). -->

    フォーマット内の、<literal>%</literal>はその後のカンマで区切られた識別子用の場所を確保するものとして使われます。とりうるレベルはDEBUG（実行中のデータベースの出力は静かに抑えられます）、NOTICE（データベースログに出力され、クライアントアプリケーションにも転送されます）、EXCEPTION（データベースログに出力されトランザクションを中断します）です。

   </para>

<programlisting>
RAISE NOTICE ''Id number '' || key || '' not found!'';
RAISE NOTICE ''Calling cs_create_job(%)'',v_job_id;
</programlisting>

<para>
<!--    In this last example, v_job_id will replace the % in the
    string. -->

    この最後の例で、「%」はv_job_idに置き換えられます。

   </para>

<programlisting>
RAISE EXCEPTION ''Inexistent ID --> %'',user_id;
</programlisting>

<para>
<!--    This will abort the transaction and write to the database log. -->
   これはトランザクションをアボートさせて、データベースログに書き込みます。
   </para>
  </sect2>

   <!-- **** PL/pgSQL exceptions **** -->

   <sect2>
<!--    <title>Exceptions</title> -->
    <title>例外</title>
<indexterm><primary>PL/pgSQL</primary><secondary sortas="れいがい">例外</secondary></indexterm>
    <para>
<!--     <productname>Postgres</productname> does not have a very smart
     exception handling model. Whenever the parser, planner/optimizer
     or executor decide that a statement cannot be processed any longer,
     the whole transaction gets aborted and the system jumps back
     into the main loop to get the next query from the client application. -->

     <productname>Postgres</productname>の例外を扱う方式はあまり気の効いたものではありません。パーサー、プランナ、オプティマイザ、エクゼキュータがこれ以上文を実行することがでいないと判断すると、トランザクション全体を中断し、システムはクライアントアプリケーションからの次の問い合わせを受け付けるメインループに戻ります。

    </para>

    <para>
<!--     It is possible to hook into the error mechanism to notice that this
     happens. But currently it is impossible to tell what really
     caused the abort (input/output conversion error, floating point
     error, parse error). And it is possible that the database backend
     is in an inconsistent state at this point so returning to the upper
     executor or issuing more commands might corrupt the whole database.
     And even if, at this point the information, that the transaction
     is aborted, is already sent to the client application, so resuming
     operation does not make any sense. -->

     これが発生したことを通知するために、エラー機構に引っかけることができます。しかし、現時点では、（入出力変換エラー、浮動小数点エラー、分析エラーといったものの内）何がその中断を引き起こしたのかを通知することはできません。そして、この段階ではバックエンドは不整合状態にあるので上位のエクゼキュータに戻したり、データベース全体を壊してしまうかもしれないようなコマンドをさらに発行するとデータベース全体を壊してしまうかもしれません。また、トランザクションが中断されたとはいえ、この段階でトランザクションがアボートしたという情報はすでにクライアントアプリケーションに送られていますので、操作の再実行は意味がありません。

    </para>

    <para>
<!--     Thus, the only thing PL/pgSQL currently does when it encounters
     an abort during execution of a function or trigger
     procedure is to write some additional DEBUG level log messages
     telling in which function and where (line number and type of
     statement) this happened. -->

     したがって、現段階で関数やトリガプロシージャ実行中に中断が起きたときに、PL/pgSQLができることは、どの関数のどこ（行番号と文の型）で発生したのか知らせるといった追加的なDEBUGレベルのログメッセージを出力することだけです。

    </para>
   </sect2>
 </sect1>


   <!-- **** PL/pgSQL trigger procedures **** -->

 <sect1 id="plpgsql-trigger">
<!--  <title>Trigger Procedures</title> -->
  <title>トリガプロシージャ</title>
<indexterm><primary>PL/pgSQL</primary><secondary sortas="とりがぷろしーじゃ">トリガプロシージャ</secondary></indexterm><indexterm><primary sortas="とりが">トリガ</primary><secondary>PL/pgSQL</secondary></indexterm>
  <para>
<!--   PL/pgSQL can be used to define trigger procedures. They are created
   with the usual <command>CREATE FUNCTION</command> command as a function with no
   arguments and a return type of <type>OPAQUE</type>. -->

   PL/pgSQLはトリガプロシージャの定義に使用できます。トリガプロシージャは、普通のCREATE FUNCTIONコマンドを使って、引数なし、OPAQUEという戻り値の型をもった関数として作成されます。

  </para>

  <para>
<!--   There are some <productname>Postgres</productname> specific details
   in functions used as trigger procedures. -->

   トリガプロシージャとして使われる関数には、<productname>Postgres</productname>特有なことがいくつかあります。

  </para>

  <para>
<!--   First they have some special variables created automatically in the 
   top-level blocks declaration section. They are -->

   まず、最上位ブロックの宣言部に自動的に特別な変数がいくつか作成されることです。次のものがあります。
</para>

   <variablelist>
    <varlistentry>
     <term><varname>NEW</varname></term>
     <listitem>
      <para>
<!--       Data type <type>RECORD</type>; variable holding the new database row on INSERT/UPDATE
       operations on ROW level triggers. -->

       <type>RECORD</type>型。この変数は行レベルのトリガでのINSERT/UPDATE操作によって更新されたデータベースの行を保持します。

      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><varname>OLD</varname></term>
     <listitem>
      <para>
<!--       Data type <type>RECORD</type>; variable holding the old database row on UPDATE/DELETE
       operations on ROW level triggers. -->

       <type>RECORD</type>型。この変数は、行レベルのトリガでのINSERT/UPDATE操作によって更新される前のデータベースの行を保持します。

      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><varname>TG_NAME</varname></term>
     <listitem>
      <para>
<!--       Data type <type>name</type>; variable that contains the name of the trigger actually
       fired. -->

       <type>name</type>型。実際に発行されたトリガの名前を持つ変数。

      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><varname>TG_WHEN</varname></term>
     <listitem>
      <para>
<!--       Data type <type>text</type>; a string of either 
              <literal>BEFORE</literal> or <literal>AFTER</literal> 
              depending on the triggers definition. -->

       <type>text</type>型。トリガの定義に依存した<literal>BEFORE</literal>または<literal>AFTER</literal>という文字列。

      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><varname>TG_LEVEL</varname></term>
     <listitem>
      <para>
<!--       Data type <type>text</type>; a string of either 
              <literal>ROW</literal> or <literal>STATEMENT</literal> depending on the
       triggers definition. -->

       <type>text</type>型。トリガの定義に依存した<literal>ROW</literal>または<literal>STATEMENT</literal>という文字列。
       
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><varname>TG_OP</varname></term>
     <listitem>
      <para>
<!--       Data type <type>text</type>; a string of 
              <literal>INSERT</literal>, <literal>UPDATE</literal> 
              or <literal>DELETE</literal> telling
       for which operation the trigger is actually fired. -->

       <type>text</type>型。トリガを発行した操作を示す<literal>INSERT</literal>、<literal>UPDATE</literal>、<literal>DELETE</literal>などの文字列。

      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><varname>TG_RELID</varname></term>
     <listitem>
      <para>
<!--       Data type <type>oid</type>; the object ID of the table that caused the
       trigger invocation. -->

       <type>oid</type>型。このトリガの呼び出し元になるテーブルのオブジェクトID.

      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><varname>TG_RELNAME</varname></term>
     <listitem>
      <para>
<!--       Data type <type>name</type>; the name of the table that caused the trigger
       invocation. -->

       <type>name</type>型。このトリガの呼び出し元になるテーブルの名前。

      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><varname>TG_NARGS</varname></term>
     <listitem>
      <para>
<!--       Data type <type>integer</type>; the number of arguments given to the trigger
       procedure in the <command>CREATE TRIGGER</command> statement. -->

       <type>整数</type>型。<command>CREATE TRIGGER</command>文におけるトリガプロシージャに与えられる引数の数。

      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><varname>TG_ARGV[]</varname></term>
     <listitem>
      <para>
<!--       Data type array of <type>text</type>; the arguments from
              the <command>CREATE TRIGGER</command> statement.
       The index counts from 0 and can be given as an expression. Invalid
       indices (&lt; 0 or &gt;= tg_nargs) result in a NULL value. -->

       <type>text</type>型の配列型。<command>CREATE TRIGGER</command>文での引数。このインデックスは0から始まり、またインデックスを式で与えることもできます。無効なインデックス（&lt; 0や&gt;= tg_nargs）はNULL値という結果になります。
      </para>
     </listitem>
    </varlistentry>
   </variablelist>

   <para>
<!--    Second they must return either NULL or a record/row containing
    exactly the structure of the table the trigger was fired for.
    Triggers fired AFTER might always return a NULL value with no
    effect. Triggers fired BEFORE signal the trigger manager
    to skip the operation for this actual row when returning NULL.
    Otherwise, the returned record/row replaces the inserted/updated
    row in the operation. It is possible to replace single values directly
    in NEW and return that or to build a complete new record/row to
    return. -->

    次は、NULLまたは、トリガの発行元になったテーブルの構造を正確に持ったレコード/行を返さなければいけない点です。AFTERとして発行されたトリガは、常に、何も影響しないNULLを返すでしょう。BEFOREとして発行されたトリガがNULLを返す場合には、トリガマネージャに実際の行への操作を取りやめるように通知します。さもなければ、レコード/行を返す場合には、その操作で挿入/更新された行をその戻り値に置き換えます。NEWの個々の値を直接置き換え、そのNEWを返すことも、新しいレコード/行を完全に作成して返すことも可能です。

   </para>

   <example>
<!--    <title>A PL/pgSQL Trigger Procedure Example</title> -->
    <title>PL/pgSQLトリガプロシージャの例</title>


    <para>
<!--     This trigger ensures, that any time a row is inserted or updated
     in the table, the current user name and time are stamped into the
     row. And it ensures that an employees name is given and that the
     salary is a positive value. -->

     このトリガは、テーブルの行が挿入または更新されたときには必ず、現在のユーザー名と時刻がその行に入っていることを確実にします。そして、従業員名が与えられていることとその給料が正の値であることを確実にします。
</para>

<programlisting>
CREATE TABLE emp (
    empname text,
    salary integer,
    last_date timestamp,
    last_user text
);

CREATE FUNCTION emp_stamp () RETURNS OPAQUE AS '
    BEGIN
        -- <!--Check that empname and salary are given-->与えられたempnameとsalaryをチェック
        IF NEW.empname ISNULL THEN
            RAISE EXCEPTION ''empname cannot be NULL value'';
        END IF;
        IF NEW.salary ISNULL THEN
            RAISE EXCEPTION ''% cannot have NULL salary'', NEW.empname;
        END IF;

        -- <!--Who works for us when she must pay for?-->salaryが負の値になっていないかをチェック
        IF NEW.salary < 0 THEN
            RAISE EXCEPTION ''% cannot have a negative salary'', NEW.empname;
        END IF;

        -- <!--Remember who changed the payroll when-->誰がいつ変更を加えたかを記録
        NEW.last_date := ''now'';
        NEW.last_user := current_user;
        RETURN NEW;
    END;
' LANGUAGE 'plpgsql';

CREATE TRIGGER emp_stamp BEFORE INSERT OR UPDATE ON emp
    FOR EACH ROW EXECUTE PROCEDURE emp_stamp();
</programlisting>
   </example>
  </sect1>

  <!-- **** PL/pgSQL Examples **** -->

  <sect1 id="plpgsql-examples">
<!--   <title>Examples</title> -->
   <title>例</title>
<indexterm><primary>PL/pgSQL</primary><secondary sortas="れい">例</secondary></indexterm>
   <para>
<!--    Here are only a few functions to demonstrate how easy it is to
    write PL/pgSQL
    functions. For more complex examples the programmer
    might look at the regression test for PL/pgSQL. -->

    PL/pgSQL関数を記述することが簡単であることを示すいくつかの関数をここに示します。もっと複雑な例について知りたいプログラマは、PL/pgSQL用のリグレッションテストを参照してください。

   </para>

   <para>
<!--    One painful detail in writing functions in PL/pgSQL is the handling
    of single quotes. The function's source text on <command>CREATE FUNCTION</command> must
    be a literal string. Single quotes inside of literal strings must be
    either doubled or quoted with a backslash. We are still looking for
    an elegant alternative. In the meantime, doubling the single quotes
    as in the examples below should be used. Any solution for this
    in future versions of <productname>Postgres</productname> will be
    forward compatible. -->

    PL/pgSQL関数の記述での辛いところは、一重引用符の扱いです。<command>CREATE FUNCTION</command>上の関数のソーステキストはリテラルな文字列である必要があります。リテラルな文字列内でのシングルクォーテーションは二重にまたはバックスラッシュでクォートしなければいけません。もっと優雅な方法を探しています。当面は、下の例のように二重にした一重引用符を使うべきです。<productname>Postgres</productname>の将来のバージョンでのこの問題に対する解決方法は上位互換になるでしょう。

   </para>

   <para>
<!--    For a detailed explanation and examples of how to escape single
    quotes in different situations, please see <xref linkend="plpgsql-quote">. -->

    詳細な説明と、異なる状況での一重引用符をエスケープする方法の例は、<xref linkend="plpgsql-quote">を参照してください。

   </para>

   <example>
<!--    <title>A Simple PL/pgSQL Function to Increment an Integer</title> -->
    <title>整数値をインクリメントする簡単なPL/pgSQL関数</title>

    <para>
<!--     The following two PL/pgSQL functions are identical to their
     counterparts from the C language function discussion. This
     function receives an <type>integer</type> and increments it by
     one, returning the incremented value. -->

     次の2つのPL/pgSQL関数は、C言語関数の説明で対応するものと同じです。この関数は<type>整数</type>をとり、その値を1つ増やして、増やした値を返します。

    </para>

<programlisting>
CREATE FUNCTION add_one (integer) RETURNS integer AS '
    BEGIN
        RETURN $1 + 1;
    END;
' LANGUAGE 'plpgsql';
</programlisting>
   </example>

   <example>
<!--    <title>A Simple PL/pgSQL Function to Concatenate Text</title>  -->
    <title>文字列連結の簡単なPL/pgSQL関数</title>

    <para>
<!--     This function receives two <type>text</type> parameters and
     returns the result of concatenating them. -->

     この関数は2つの<type>text</type>型の引数をとり、それらを連結して返します。
    </para>

<programlisting>
CREATE FUNCTION concat_text (text, text) RETURNS text AS '
    BEGIN
        RETURN $1 || $2;
    END;
' LANGUAGE 'plpgsql';
</programlisting>
   </example>

   <example>
<!--    <title>A PL/pgSQL Function on Composite Type</title> -->
    <title>複合型を使ったPL/pgSQL関数</title>

    <para>
<!--     In this example, we take EMP (a table) and an
     <type>integer</type> as arguments to our function, which returns
     a <type>boolean</type>. If the "salary" field of the EMP table is
     <literal>NULL</literal>, we return "f". Otherwise we compare with
     that field with the <type>integer</type> passed to the function
     and return the <type>boolean</type> result of the comparison (t
     or f). This is the PL/pgSQL equivalent to the example from the C
     functions. -->

     この例では、EMP（テーブル）と<type>integer</type>型をとります。これは<type>boolean</type>型を返します。EMPテーブルのsalaryフィールドが<literal>NULL</literal>であるならば、「f」を返します。一方では、フィールドと<type>integer</type>を比較して、比較の結果（「t」もしくは「f」）を<type>boolean</type>型で返します。このPL/pgSQLもC関数の例と同じです。

    </para>

<programlisting>
CREATE FUNCTION c_overpaid (EMP, integer) RETURNS boolean AS '
    DECLARE
        emprec ALIAS FOR $1;
        sallim ALIAS FOR $2;
    BEGIN
        IF emprec.salary ISNULL THEN
            RETURN ''f'';
        END IF;
        RETURN emprec.salary > sallim;
    END;
' LANGUAGE 'plpgsql';
</programlisting>
   </example>
  </sect1>

  <!-- **** Porting from Oracle PL/SQL **** -->

 <sect1 id="plpgsql-porting">

  <sect1info>
   <date>
    February 2001
   </date>
   <author>
    <firstname>Roberto</firstname>
    <surname>Mello</surname>
    <affiliation>
     <address>
      <email>rmello@fslc.usu.edu</email>
     </address>
    </affiliation>
   </author>

   <legalnotice>
    <para>
<!--     Except for portions of this document quoted from other sources,
     this document is licensed under the BSD License. -->

     他のソースから引用した部分を除いて、このドキュメントはBSDライセンスの元でライセンスされています。

    </para>
   </legalnotice>
  </sect1info> 

<!--  <title>Porting from Oracle PL/SQL</title> -->
  <title>OracleのPL/SQLからの移植</title>
<indexterm><primary>Oracle</primary></indexterm><indexterm><primary>PL/SQL</primary></indexterm><indexterm><primary sortas="いしょく">移植</primary></indexterm><indexterm><primary>PL/pgSQL</primary><secondary sortas="いしょく">移植</secondary></indexterm>
  <note>
<!--   <title>Author</title> -->
   <title>著者</title>
   <para>
    Roberto Mello（<email>rmello@fslc.usu.edu</email>）
   </para>
  </note>

  <para>
<!--   This section explains differences between Oracle's PL/SQL and
   PostgreSQL's PL/pgSQL languages in the hopes of helping developers
   port applications from Oracle to PostgreSQL.  Most of the code here
   is from the <ulink url="http://www.arsdigita.com">ArsDigita</ulink>
   <ulink url="http://www.arsdigita.com/asj/clickstream">Clickstream
   module</ulink> that I ported to PostgreSQL when I took an
   internship with <ulink url="http://www.openforce.net">OpenForce
   Inc.</ulink> in the Summer of 2000. -->

   この節では、開発者のOracleからPostgreSQLへのアプリケーションの移植の手助けとなるようOracleのPL/SQLとPostgreSQLのPL/pgSQLの違いについて説明します。ここにあるコードの大部分は<ulink url="http://www.arsdigita.com">ArsDigita</ulink>の<ulink url="http://www.arsdigita.com/asj/clickstream">Clickstream module</ulink><![%book-publish;[（http://www.arsdigita.com/asj/clickstream）]]>にあります。私は2000年の夏に<ulink url="http://www.openforce.net/">OpenForce Inc.</ulink>でインターンシップを行った時にPostgreSQLに移植しました。
  </para>
 
  <para>
<!--   PL/pgSQL is similar to PL/SQL in many aspects. It is a block
   structured, imperative language (all variables have to be
   declared). PL/SQL has many more features than its PostgreSQL
   counterpart, but PL/pgSQL allows for a great deal of functionality
   and it is being improved constantly. -->

   PL/pgSQLは多くの点でPL/SQLに似ています。それはブロックで構成されていて、厳格な言語であるということです（すべての変数は宣言されなければいけないということです）。PL/SQLはPostgrSQLに対応するものより多くの機能があります、しかしPL/pgSQLには多くの機能があり、それは絶えず改善されています。

  </para>

  <sect2>
<!--   <title>Main Differences</title> -->
   <title>主な違い</title>

   <para>
<!--    Some things you should keep in mind when porting from Oracle to PostgreSQL: -->

      OracleからPostgreSQLに移植するとき注意すべき点がいくつかあります。
</para>

    <itemizedlist>
     <listitem>
      <para>
<!--       No default parameters in PostgreSQL. -->

      PostgreSQLにはデフォルトパラメータがありません。
      </para>
     </listitem>

     <listitem>
      <para>
<!--       You can overload functions in PostgreSQL. This is often used to work 
       around the lack of default parameters. -->

       PostgreSQLでは関数をオーバーロードすることができます。これはしばしばデフォルトパラメータの欠如を補うために使われます。

      </para>
     </listitem>

     <listitem>
      <para>
<!--       Assignments, loops and conditionals are similar.  -->
       割り当て、ループ、条件文は似ています。

      </para>
     </listitem>

     <listitem>
      <para>
<!--       No need for cursors in PostgreSQL, just put the query in the FOR 
       statement (see example below) -->

       PostgreSQLではカーソルは必要ありません、FOR文で問い合わせを出力するだけです（以下の例をみてください）。
      </para>
     </listitem>

     <listitem>
      <para>
<!--       In PostgreSQL you <emphasis>need</emphasis> to escape single
       quotes. See <xref linkend="plpgsql-quote">. -->

       PostgreSQLでは一重引用符をエスケープする<emphasis>必要があります</emphasis>。<xref linkend="plpgsql-quote">を参照してください。

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

   <sect3 id="plpgsql-quote">
<!--    <title>Quote Me on That: Escaping Single Quotes</title> -->
      <title><!--私をクォーテーションしてください――-->一重引用符のエスケープ</title>
<indexterm><primary sortas="いんようふ">引用符</primary></indexterm>
    <para>
<!--     In PostgreSQL you need to escape single quotes inside your
     function definition. This can lead to quite amusing code at
     times, especially if you are creating a function that generates
     other function(s), as in 
     <xref linkend="plpgsql-porting-nastyquote">.  
     One thing to keep in mind
     when escaping lots of single quotes is that, except for the
     beginning/ending quotes, all the others will come in even
     quantity. -->

     PostgreSQLでは、関数定義内では一重引用符をエスケープさせる必要があります。他の関数を生成するような関数を作成する場合に特に楽しいコードを書くことができます（<xref linkend="plpgsql-porting-nastyquote">を参照）。たくさんの一重引用符をエスケープする際に注意をしてほしいのは、最初と最後のクォーテーションは除かれることと、それ以外のすべては同じ数になることです。

    </para>

    <para>
<!--     <xref linkend="plpgsql-quoting-table"> gives the scoop.  (You'll
     love this little chart.) -->

     <xref linkend="plpgsql-quoting-table">はスクープです（この小さなチャートをきっと気に入ってくれることでしょう）。

    </para>

    <table id="plpgsql-quoting-table">
<!--     <title>Single Quotes Escaping Chart</title> -->
     <title>一重引用符のエスケープチャート</title>
<indexterm><primary sortas="いんようふ">引用符</primary><secondary sortas="えすけーぷ">エスケープ</secondary></indexterm>
     <tgroup cols="4">
      <thead>
       <row>
<!--        <entry>No. of Quotes</entry> -->
        <entry>番号</entry>
<!--        <entry>Usage</entry> -->
        <entry>使い方</entry> 
<!--        <entry>Example</entry> -->
        <entry>例</entry>
<!--        <entry>Result</entry> -->
        <entry>結果</entry>
       </row>
      </thead>

      <tbody>
       <row>
        <entry>1</entry>
<!--        <entry>To begin/terminate function bodies</entry> -->
        <entry>関数の中身の最初と最後</entry>
        <entry><programlisting>
CREATE FUNCTION foo() RETURNS INTEGER AS '...'
LANGUAGE 'plpgsql';
</programlisting></entry>
        <entry>そのまま</entry>
       </row>

       <row>
        <entry>2</entry>
<!--        <entry>In assignments, SELECTs, to delimit strings, etc.</entry> -->
        <entry>変数宣言や、SELECT文中で文字列を囲む場合</entry>
        <entry><programlisting>
a_output := ''Blah'';
SELECT * FROM users WHERE f_name=''foobar'';
</programlisting></entry>
        <entry><literal>SELECT * FROM users WHERE f_name='foobar';</literal></entry>
       </row>

       <row>
        <entry>4</entry>
        <entry><!--         When you need two single quotes in your resulting string
         without terminating that string. -->

	文字列が終了していないところで結果の文字列に2つの一重引用符が必要な場合
        </entry>
        <entry><programlisting>
a_output := a_output || '' AND name 
    LIKE ''''foobar'''' AND ...''
</programlisting></entry>
        <entry><literal>AND name LIKE 'foobar' AND ...</literal></entry>
       </row>

       <row>
        <entry>6</entry>
        <entry><!--         When you want double quotes in your resulting string
         <emphasis>and</emphasis> terminate that string. -->

	結果として生じる文字列で二重引用符が欲しい場合<emphasis>そして</emphasis>その文字列を終了したい場合

        </entry>
        <entry><programlisting>
a_output := a_output || '' AND name 
    LIKE ''''foobar''''''
</programlisting></entry>
        <entry><literal>AND name LIKE 'foobar'</literal>
        </entry>
       </row>

       <row>
        <entry>10</entry>
        <entry><!--         When you want two single quotes in the resulting string
         (which accounts for 8 quotes) <emphasis>and</emphasis>
         terminate that string (2 more).  You will probably only need
         that if you were using a function to generate other functions
         (like in <xref linkend="plpgsql-porting-nastyquote">). -->

	結果の文字列に2つの一重引用符が欲しい場合（8個の引用符が必要）<emphasis>そして</emphasis>はその文字列を終了させたい場合（もう2つ）、関数を使って他の関数を生成させる場合にだけ必要でしょう（<xref linkend="plpgsql-porting-nastyquote">を参照）。

        </entry>
        <entry><programlisting>
a_output := a_output || '' if v_'' || 
    referrer_keys.kind || '' like '''''''''' 
    || referrer_keys.key_string || '''''''''' 
    then return ''''''  || referrer_keys.referrer_type 
    || ''''''; end if;''; 
</programlisting></entry>
        <entry><literal>if v_<...> like ''<...>'' then return ''<...>''; end if;</literal>
        </entry>
       </row>
      </tbody>
     </tgroup>
    </table>
   </sect3>
  </sect2>  

  <sect2 id="plpgsql-porting-functions">
   <title>
<!--    Porting Functions -->
   関数の移植
   </title>
<indexterm><primary>PL/pgSQL</primary><secondary sortas="かんすうのいしょく">関数の移植</secondary></indexterm><indexterm><primary sortas="かんすう">関数</primary><secondary sortas="いしょく">移植</secondary></indexterm>
   <example>
    <title>
<!--     A Simple Function -->
     簡単な関数
    </title>

    <para>
<!--     Here is an Oracle function: -->
     これはOracleの関数です。
</para>

<programlisting>
CREATE OR REPLACE FUNCTION cs_fmt_browser_version(v_name IN varchar, v_version IN varchar)
RETURN varchar IS
BEGIN
    IF v_version IS NULL THEN
        RETURN v_name;
    END IF;
    RETURN v_name || '/' || v_version;
END;
/
SHOW ERRORS;
</programlisting>

    <para>
<!--     Let's go through this function and see the differences to PL/pgSQL: -->

      この関数を通じて、PL/pgSQLとの違いを見てみましょう。
</para>

     <itemizedlist>
      <listitem>
       <para>
<!--        The <literal>OR REPLACE</literal> clause is not allowed. You
        will have to explicitly drop the function before creating it
        to achieve similar results. -->

        <literal>OR REPLACE</literal>句は使用できません。関数を作成する前に明示的に関数を削除することで同じような結果を得ることができます。

       </para>
      </listitem>

      <listitem>
       <para>
<!--        <productname>PostgreSQL</productname> does not have named
        parameters. You have to explicitly alias them inside your
        function. -->

	<productname>PostgreSQL</productname>は引数に名前を付けられません。関数内で明示的にエイリアスしなければいけません。

       </para>
      </listitem>

      <listitem>
       <para>
<!--        Oracle can have <literal>IN</literal>, <literal>OUT</literal>,
        and <literal>INOUT</literal> parameters passed to functions.
        The <literal>INOUT</literal>, for example, means that the
        parameter will receive a value and return another. PostgreSQL
        only has <quote>IN</quote> parameters and functions can return
        only a single value. -->

        Oracleには<literal>IN</literal>、<literal>OUT</literal>、<literal>INOUT</literal>の引数を関数に渡すことができます。たとえば<literal>INOUT</literal>は引数は1つの値を受けてそのほかを返します。PostgreSQLでは<quote>IN</quote>引数だけがあり、単一の値だけ返すことができます。
       </para>
      </listitem>

      <listitem>
       <para>
<!--        The <literal>RETURN</literal> key word in the function
        prototype (not the function body) becomes
        <literal>RETURNS</literal> in PostgreSQL. -->

        関数プロトタイプ内の<literal>RETURN</literal>キーワード（関数の中ではありません）はPostgreSQLでは<literal>RETURNS</literal>になります。

       </para>
      </listitem>

      <listitem>
       <para>
<!--        On PostgreSQL functions are created using single quotes as
        delimiters, so you have to escape single quotes inside your
        functions (which can be quite annoying at times; see <xref
        linkend="plpgsql-quote">). -->

	PostgreSQL関数では一重引用符が区切り文字として使用されているので、関数内では一重引用符をエスケープしなければいけません（ときどきいらいらすることです。<xref linkend="plpgsql-quote">を参照してください）。

       </para>
      </listitem>

      <listitem>
       <para>
<!--        The <literal>/show errors</literal> command does not exist in
        PostgreSQL. -->

	PostgreSQLには<literal>/show errors</literal>コマンドはありません。

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

    <para>
<!--     So let's see how this function would be look like ported to
     PostgreSQL: -->

     それではこの関数がPostgreSQLに移植されるとどのようになるかみてみましょう。
</para>

<programlisting>
DROP FUNCTION cs_fmt_browser_version(varchar, varchar);
CREATE FUNCTION cs_fmt_browser_version(varchar, varchar)
RETURNS varchar AS '
DECLARE
    v_name ALIAS FOR $1;
    v_version ALIAS FOR $2;
BEGIN
    IF v_version IS NULL THEN
        return v_name;
    END IF;
    RETURN v_name || ''/'' || v_version;
END;
' LANGUAGE 'plpgsql';
</programlisting>
   </example>
 
   <example id="plpgsql-porting-nastyquote">
    <title>
<!--     A Function that Creates Another Function -->
     他の関数を作り出す関数
    </title>

    <para>
<!--     The following procedure grabs rows from a
     <literal>SELECT</literal> statement and builds a large function
     with the results in <literal>IF</literal> statements, for the
     sake of efficiency. Notice particularly the differences in
     cursors, <literal>FOR</literal> loops, and the need to escape
     single quotes in PostgreSQL.  -->

     以下の手続きは<literal>SELECT</literal>文からの行をとって、効率のために<literal>IF</literal>文で結果を巨大な関数に埋め込んでいます。PostgreSQLとはカーソル、<literal>FOR</literal>ループ、シングルクォーテーションをエスケープする必要があるというという違いに気がつくでしょう。
</para>

<programlisting>
create or replace procedure cs_update_referrer_type_proc is 
    cursor referrer_keys is 
        select * from cs_referrer_keys 
        order by try_order;

    a_output varchar(4000); 
begin 
    a_output := 'create or replace function cs_find_referrer_type(v_host IN varchar, v_domain IN varchar, 
v_url IN varchar) return varchar is begin'; 

    for referrer_key in referrer_keys loop 
        a_output := a_output || ' if v_' || referrer_key.kind || ' like ''' || 
referrer_key.key_string || ''' then return ''' || referrer_key.referrer_type || 
'''; end if;'; 
    end loop; 

    a_output := a_output || ' return null; end;'; 
    execute immediate a_output; 
end; 
/ 
show errors
</programlisting>

    <para>
<!--     Here is how this function would end up in PostgreSQL: -->

       この機能をPostgreSQLで記述すると以下のようになります。
</para>

<programlisting>
CREATE FUNCTION cs_update_referrer_type_proc() RETURNS integer AS '
DECLARE
    referrer_keys RECORD;  -- Declare a generic record to be used in a FOR
    a_output varchar(4000);
BEGIN 
    a_output := ''CREATE FUNCTION cs_find_referrer_type(varchar,varchar,varchar) 
                  RETURNS varchar AS '''' 
                     DECLARE 
                         v_host ALIAS FOR $1; 
                         v_domain ALIAS FOR $2; 
                         v_url ALIAS FOR $3; ''; 

    -- 
    -- <!--Notice how we scan through the results of a query in a FOR loop-->FOR lootpでFOR &lt;record&gt;構造を使ってクエリ結果をスキャンする
    -- <!--using the FOR &lt;record&gt; construct.-->方法に注意してください。
    --

    FOR referrer_keys IN select * from cs_referrer_keys order by try_order LOOP
        a_output := a_output || '' if v_'' || referrer_keys.kind || '' like '''''''''' 
                 || referrer_keys.key_string || '''''''''' then return '''''' 
                 || referrer_keys.referrer_type || ''''''; end if;''; 
    END LOOP; 
  
    a_output := a_output || '' return null; end; '''' language ''''plpgsql'''';''; 
 
    -- <!--This works because we are not substituting any variables-->これは、どの変数も置き換えていないのでうまくいきます。
    -- <!--Otherwise it would fail. Look at PERFORM for another way to run functions-->そうでなければ失敗します。
    -- 関数を実行する他の方法についてはPERFORMを参照してください。

    
    EXECUTE a_output; 
end; 
' LANGUAGE 'plpgsql';
</programlisting>
   </example>
 
   <example>
    <title>
<!--     A Procedure with a lot of String Manipulation and OUT Parameters -->
     たくさんの文字列操作手続きとOUT引数

    </title>

    <para>
<!--     The following Oracle PL/SQL procedure is used to parse a URL and
     return several elements (host, path and query). It is an
     procedure because in PL/pgSQL functions only one value can be returned
     (see <xref linkend="plpgsql-porting-procedures">).  In
     PostgreSQL, one way to work around this is to split the procedure
     in three different functions: one to return the host, another for
     the path and another for the query. -->

     以下のOracleのPL/SQL手続きは、URLをパースしていくつかの要素（ホスト、パス、問い合わせ）を返します。PL/pgSQL関数は1つの値のみを返すので1つの手続きとなります（<xref linkend="plpgsql-porting-procedures">を参照）。PostgreSQLではこの関数は3つの異なる手続きに分割する方法があります。1つはホストを返し、もう1つはパスを返し、もう1つを問い合わせを返します。

    </para>

<programlisting>
create or replace procedure cs_parse_url(
    v_url IN varchar,
    v_host OUT varchar,  -- This will be passed back
    v_path OUT varchar,  -- This one too
    v_query OUT varchar) -- And this one
is
    a_pos1 integer;
    a_pos2 integer;
begin
    v_host := NULL;
    v_path := NULL;
    v_query := NULL;
    a_pos1 := instr(v_url, '//'); -- <!-- PostgreSQL doesn't have an instr function --> PostgreSQLには insrt 関数はありません

    if a_pos1 = 0 then
        return;
    end if;
    a_pos2 := instr(v_url, '/', a_pos1 + 2);
    if a_pos2 = 0 then
        v_host := substr(v_url, a_pos1 + 2);
        v_path := '/';
        return;
    end if;

    v_host := substr(v_url, a_pos1 + 2, a_pos2 - a_pos1 - 2);
    a_pos1 := instr(v_url, '?', a_pos2 + 1);

    if a_pos1 = 0 then
        v_path := substr(v_url, a_pos2);
        return;
    end if;

    v_path := substr(v_url, a_pos2, a_pos1 - a_pos2);
    v_query := substr(v_url, a_pos1 + 1);
end;
/
show errors;
</programlisting>

    <para>
<!--     Here is how this procedure could be translated for PostgreSQL: -->
        PostgreSQLに移植したのがこのこの手続きです。
</para>

<programlisting>
drop function cs_parse_url_host(varchar); 
create function cs_parse_url_host(varchar) returns varchar as ' 
declare 
    v_url ALIAS FOR $1; 
    v_host varchar; 
    v_path varchar; 
    a_pos1 integer; 
    a_pos2 integer; 
    a_pos3 integer; 
begin 
    v_host := NULL; 
    a_pos1 := instr(v_url,''//''); 

    if a_pos1 = 0 then 
        return '''';  -- Return a blank
    end if; 

    a_pos2 := instr(v_url,''/'',a_pos1 + 2); 
    if a_pos2 = 0 then 
        v_host := substr(v_url, a_pos1 + 2); 
        v_path := ''/''; 
        return v_host; 
    end if; 

    v_host := substr(v_url, a_pos1 + 2, a_pos2 - a_pos1 - 2 ); 
    return v_host; 
end; 
' language 'plpgsql';
</programlisting>
   </example>

   <note>
    <para>
<!--     PostgreSQL does not have an <function>instr</function> function,
     so you can work around it using a combination of other functions.
     I got tired of doing this and created my own
     <function>instr</function> functions that behave exactly like
     Oracle's (it makes life easier). See the <xref
     linkend="plpgsql-porting-appendix"> for the code. -->

     PostgreSQLには<function>instr</function>関数はないので、そのほかの関数を組み合わせて使用することでその働きができます。私はこれにあきてしまい、Oracleのに似た（もっと簡単なものですが）独自の<function>instr</function>関数を作成しました。コードは<xref linkend="plpgsql-porting-appendix">を参照してください。

    </para>
   </note>
  </sect2>

  <sect2 id="plpgsql-porting-procedures">
   <title>
<!--    Procedures -->
    プロシージャ
   </title>
<indexterm><primary>PL/pgSQL</primary><secondary sortas="ぷろしーじゃ">プロシージャ</secondary></indexterm>
   <para>
<!--    Oracle procedures give a little more flexibility to the developer
    because nothing needs to be explicitly returned, but it can be
    through the use of INOUT or OUT parameters. -->

    明示的に返り値を持つ必要がなくOracleの手続きは開発者により柔軟性を与えています。INOUTかOUTパラメータを使うことができます。


   </para>

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

<programlisting>
create or replace procedure cs_create_job(v_job_id in integer)
is
    a_running_job_count integer;
    pragma autonomous_transaction;<co id="co.plpgsql-porting-pragma">
begin
    lock table cs_jobs in exclusive mode;<co id="co.plpgsql-porting-locktable">

    select count(*) into a_running_job_count from cs_jobs
    where end_stamp is null;

    if a_running_job_count > 0 then
        commit; -- free lock<co id="co.plpgsql-porting-commit">
        raise_application_error(-20000, 'Unable to create a new job: a job is currently running.');
    end if;

    delete from cs_active_job;
    insert into cs_active_job(job_id) values(v_job_id);

    begin
        insert into cs_jobs(job_id, start_stamp) values(v_job_id, sysdate);
        exception when dup_val_on_index then null; -- don't worry if it already exists<co id="co.plpgsql-porting-exception">
    end;
    commit;
end;
/
show errors
</programlisting>

   <para>
<!--    Procedures like this can be easily converted into PostgreSQL
    functions returning an <type>INTEGER</type>. This procedure in
    particular is interesting because it can teach us some things: -->

    このような手続きは<type>INTEGER</type>型を返すPostgreSQLの関数に簡単に変換することができます。これはいろいろな事を教えてくれることもあってこの手続きは特におもしろいです。
</para>

    <calloutlist>
     <callout arearefs="co.plpgsql-porting-pragma">
      <para>
<!--       There is no <literal>pragma</literal> statement in PostgreSQL. -->
      PostgreSQLには<literal>pragma</literal>文はありません。
      </para>
     </callout>

     <callout arearefs="co.plpgsql-porting-locktable">
      <para>
<!--       If you do a <literal>LOCK TABLE</literal> in PL/pgSQL, the lock
       will not be released until the calling transaction is finished.  -->

       PL/pgSQLで<literal>LOCK TABLE</literal>を使用するならば、トランザクションの終了を呼び出すまでロックが解放されません。
       
      </para>
     </callout>

     <callout arearefs="co.plpgsql-porting-commit">
      <para>
<!--       You also cannot have transactions in PL/pgSQL procedures. The
       entire function (and other functions called from therein) is
       executed in a transaction and PostgreSQL rolls back the results if
       something goes wrong. Therefore only one
       <literal>BEGIN</literal> statement is allowed. -->

       PL/pgSQL手続きではトランザクションを使用することができません。関数全体（とそこに呼ばれる他の関数）は1つのトランザクションで実行されます、そして、何か問題がおきたら、PostgreSQLはその結果をロールバックします。

      </para>
     </callout>

     <callout arearefs="co.plpgsql-porting-exception">
      <para>
<!--       The exception when would have to be replaced by an
       <literal>IF</literal> statement. -->

       <literal>IF</literal>文で置き換える必要のある例外

      </para>
     </callout>
    </calloutlist>

   <para>
<!--    So let's see one of the ways we could port this procedure to PL/pgSQL: -->

    それで、この手続きをPL/pgSQLに移植することができた方法の1つを見てみましょう。
</para>

<programlisting>
drop function cs_create_job(integer);
create function cs_create_job(integer) returns integer as ' declare
    v_job_id alias for $1;
    a_running_job_count integer;
    a_num integer;
    -- pragma autonomous_transaction;
begin
    lock table cs_jobs in exclusive mode;
    select count(*) into a_running_job_count from cs_jobs where end_stamp is null;

    if a_running_job_count > 0 then
        -- commit; -- free lock
        raise exception ''Unable to create a new job: a job is currently running.'';
    end if;

    delete from cs_active_job;
    insert into cs_active_job(job_id) values(v_job_id);

    SELECT count(*) into a_num FROM cs_jobs WHERE job_id=v_job_id;
    IF NOT FOUND THEN  -- If nothing was returned in the last query
        -- This job is not in the table so lets insert it.
        insert into cs_jobs(job_id, start_stamp) values(v_job_id, sysdate());
        return 1;
    ELSE
        raise NOTICE ''Job already running.'';<co id="co.plpgsql-porting-raise">
    END IF;

    return 0;
end;
' language 'plpgsql';
</programlisting>

    <calloutlist>
     <callout arearefs="co.plpgsql-porting-raise">
      <para>
<!--       Notice how you can raise notices (or errors) in PL/pgSQL. -->
        PL/pgSQLでnotice（もしくはerror）を起こすことができる方法があります。

      </para>
     </callout>
    </calloutlist>
  </sect2>

  <sect2 id="plpgsql-porting-packages">
   <title>
<!--    Packages -->
   パッケージ
   </title>
<indexterm><primary>PL/pgSQL</primary><secondary sortas="ぱっけーじ">パッケージ</secondary></indexterm>
   <note>
    <para>
<!--     I haven't done much with packages myself, so if there are
     mistakes here, please let me know. -->

     私はあまりパッケージを使ったことがないので、間違いがありましたら、私に知らせてください。
    </para>
   </note>

   <para>
<!--    Packages are a way Oracle gives you to encapsulate PL/SQL
    statements and functions into one entity, like Java classes, where
    you define methods and objects. You can access these
    objects/methods with a <quote><literal>.</literal></quote>
    (dot). Here is an example of an Oracle package from ACS 4 (the
    <ulink url="http://www.arsdigita.com/doc/">ArsDigita Community
    System</ulink>): -->

    パッケージはOracleが、Javaクラスのように、1つの実体にPL/SQL文と関数をカプセル化するための方法です。ここではメソッドとオブジェクトの定義をします。これらはオブジェクト/メソッドに<quote><literal>.</literal></quote>を使ってアクセスすることがでいます。ACS 4のOracleのパッケージの例を示します（<ulink url="http://www.arsdigita.com/doc/">ArsDigita Community System</ulink><![%book-publish;[、http://www.arsdigita.com/doc/]]>）。
</para>

<programlisting>
create or replace package body acs
as
  function add_user (
    user_id     in users.user_id%TYPE default null,
    object_type     in acs_objects.object_type%TYPE
               default 'user',
    creation_date   in acs_objects.creation_date%TYPE
               default sysdate,
    creation_user   in acs_objects.creation_user%TYPE
               default null,
    creation_ip     in acs_objects.creation_ip%TYPE default null,
  ...
  ) return users.user_id%TYPE
  is
    v_user_id       users.user_id%TYPE;
    v_rel_id        membership_rels.rel_id%TYPE;
  begin
    v_user_id := acs_user.new (user_id, object_type, creation_date,
                creation_user, creation_ip, email,
    ...
    return v_user_id;
  end;
end acs;
/
show errors
</programlisting>

   <para>
<!--    We port this to PostgreSQL by creating the different objects of
    the Oracle package as functions with a standard naming
    convention. We have to pay attention to some other details, like
    the lack of default parameters in PostgreSQL functions. The above
    package would become something like this: -->

    標準的な命令規則を持つ関数としてOracleパッケージの異なるオブジェクトを作成することでこれをPostgreSQLに移植します。PostgreSQL関数にはデフォルトパラメータが欠乏しているなどのいくつかの細かいことに注意を払わなければいけません、上記のパッケージは以下のようなものになるでしょう。
</para>
 
<programlisting>
CREATE FUNCTION acs__add_user(integer,integer,varchar,datetime,integer,integer,...)
RETURNS integer AS '
DECLARE
    user_id ALIAS FOR $1;
    object_type ALIAS FOR $2;
    creation_date ALIAS FOR $3;
    creation_user ALIAS FOR $4;
    creation_ip ALIAS FOR $5;
    ...
    v_user_id users.user_id%TYPE;
    v_rel_id membership_rels.rel_id%TYPE;
BEGIN
    v_user_id := acs_user__new(user_id,object_type,creation_date,creation_user,creation_ip, ...);
    ...

    return v_user_id;
END;
' LANGUAGE 'plpgsql';
</programlisting>
  </sect2>

  <sect2 id="plpgsql-porting-other">
   <title>
<!--    Other Things to Watch For -->
    注意すべきその他の点

   </title>

   <sect3>
    <title>EXECUTE</title>

    <para>
<!--     The PostgreSQL version of <literal>EXECUTE</literal> works
     nicely, but you have to remember to use
     <function>quote_literal(TEXT)</function> and
     <function>quote_string(TEXT)</function> as described in <xref
     linkend="plpgsql-statements-executing-dyn-queries">.  Constructs of the type
     <literal>EXECUTE ''SELECT * from $1'';</literal> will not work
     unless you use these functions. -->

     PostgreSQLの<literal>EXECUTE</literal>はよくできています。しかし<xref linkend="plpgsql-statements-executing-dyn-queries">で説明されている<function>quote_literal(TEXT)</function>と<function>quote_string(TEXT)</function>を使うことを覚えておかなければいけません。これらの関数を使用しな限り<literal>EXECUTE ''SELECT * from $1'';</literal>のコンストラクタはうまく動作しません。

    </para>
   </sect3>

   <sect3 id="plpgsql-porting-optimization">
<!--    <title>Optimizing PL/pgSQL Functions</title> -->
    <title>PL/pgSQL関数の最適化</title>
<indexterm><primary>PL/pgSQL</primary><secondary sortas="さいてきか">最適化</secondary></indexterm>
    <para>
<!--     PostgreSQL gives you two function creation modifiers to optimize
     execution: <literal>iscachable</literal> (function always returns
     the same result when given the same arguments) and
     <literal>isstrict</literal> (function returns NULL if any
     argument is NULL).  Consult the <command>CREATE
     FUNCTION</command> reference for details. -->

     PostgreSQLには、実行を最適化するために2つの機能生成モディファイアがあります。<literal>iscachable</literal>（同じ引数が与えられ常に同じ結果が返されます）と<literal>isstrict</literal>（引数はNULLでNULLを返します）です。詳細は<command>CREATE FUNCTION</command>のリファレンスを参照してください。
    </para>

    <para>
<!--     To make use of these optimization attributes, you have to use the
     <literal>WITH</literal> modifier in your <command>CREATE
     FUNCTION</command> statement.  Something like: -->

     これらの最適化属性を利用するためには、<command>CREATE FUNCTION</command>文に<literal>WITH</literal>モディファイアを使用しなければいけません。
</para>

<programlisting>
CREATE FUNCTION foo(...) RETURNS integer AS '
...
' LANGUAGE 'plpgsql'
WITH (isstrict, iscachable);
</programlisting>
   </sect3>
  </sect2>

  <sect2 id="plpgsql-porting-appendix">
   <title>
<!--    Appendix -->
    付録
   </title>

   <sect3>
    <title>
<!--     Code for my <function>instr</function> functions -->
     <function>instr</function>関数のコード
    </title>

    <comment>
<!--     This function should probably be integrated into the core. -->
     この関数はおそらくコアに組み込みむべきでしょう。
    </comment>

<programlisting>
--
-- <!--instr functions that mimic Oracle's counterpart-->Oracleのものと同じ動作をする instr 関数
-- <!--Syntax: instr(string1,string2,[n],[m]) where [] denotes optional params.-->構文：instr(string1,string2,[n],[m]) []はオプション
-- 
-- <!--Searches string1 beginning at the nth character for the mth-->string1内のn番目の文字からm番目の文字まででstring2を探す。
-- <!--occurrence of string2. If n is negative, search backwards. If m is-->nが負の数値の場合、逆方向に探します。
-- <!--not passed, assume 1 (search starts at first character).-->mが渡されなかった場合は1とみなされ、最初の文字から検索を始めます。
--
-- by Roberto Mello (rmello@fslc.usu.edu)
-- modified by Robert Gaszewski (graszew@poland.com)
-- <!--Licensed under the GPL v2 or later.-->GPL v2以降によってライセンス
--

DROP FUNCTION instr(varchar,varchar);
CREATE FUNCTION instr(varchar,varchar) RETURNS integer AS '
DECLARE
    pos integer;
BEGIN
    pos:= instr($1,$2,1);
    RETURN pos;
END;
' language 'plpgsql';


DROP FUNCTION instr(varchar,varchar,integer);
CREATE FUNCTION instr(varchar,varchar,integer) RETURNS integer AS '
DECLARE
    string ALIAS FOR $1;
    string_to_search ALIAS FOR $2;
    beg_index ALIAS FOR $3;
    pos integer NOT NULL DEFAULT 0;
    temp_str varchar;
    beg integer;
    length integer;
    ss_length integer;
BEGIN
    IF beg_index > 0 THEN

       temp_str := substring(string FROM beg_index);
       pos := position(string_to_search IN temp_str);

       IF pos = 0 THEN
             RETURN 0;
         ELSE
             RETURN pos + beg_index - 1;
         END IF;
    ELSE
       ss_length := char_length(string_to_search);
       length := char_length(string);
       beg := length + beg_index - ss_length + 2;

       WHILE beg > 0 LOOP

           temp_str := substring(string FROM beg FOR ss_length);
             pos := position(string_to_search IN temp_str);

             IF pos > 0 THEN
                   RETURN beg;
             END IF;

             beg := beg - 1;
       END LOOP;
       RETURN 0;
    END IF;
END;
' language 'plpgsql';

--
-- Written by Robert Gaszewski (graszew@poland.com)
-- Licensed under the GPL v2 or later.
--
DROP FUNCTION instr(varchar,varchar,integer,integer);
CREATE FUNCTION instr(varchar,varchar,integer,integer) RETURNS integer AS '
DECLARE
    string ALIAS FOR $1;
    string_to_search ALIAS FOR $2;
    beg_index ALIAS FOR $3;
    occur_index ALIAS FOR $4;
    pos integer NOT NULL DEFAULT 0;
    occur_number integer NOT NULL DEFAULT 0;
    temp_str varchar;
    beg integer;
    i integer;
    length integer;
    ss_length integer;
BEGIN
    IF beg_index > 0 THEN
        beg := beg_index;
        temp_str := substring(string FROM beg_index);

        FOR i IN 1..occur_index LOOP
            pos := position(string_to_search IN temp_str);

            IF i = 1 THEN
                beg := beg + pos - 1;
            ELSE
                beg := beg + pos;
            END IF;

            temp_str := substring(string FROM beg + 1);
        END LOOP;

        IF pos = 0 THEN
            RETURN 0;
        ELSE
            RETURN beg;
        END IF;
    ELSE
        ss_length := char_length(string_to_search);
        length := char_length(string);
        beg := length + beg_index - ss_length + 2;

        WHILE beg > 0 LOOP
            temp_str := substring(string FROM beg FOR ss_length);
            pos := position(string_to_search IN temp_str);

            IF pos > 0 THEN
                occur_number := occur_number + 1;

                IF occur_number = occur_index THEN
                    RETURN beg;
                END IF;
            END IF;

            beg := beg - 1;
        END LOOP;

        RETURN 0;
    END IF;
END;
' language 'plpgsql';
</programlisting>
   </sect3>
  </sect2>
  
 </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:
-->
