<!--
$Header: /usr/prj/pg/cvsroot/doc/doc/src/sgml/ref/create_language.sgml,v 1.8 2001/09/04 11:22:11 i-kaori Exp $
Postgres documentation
-->

<refentry id="SQL-CREATELANGUAGE">
 <refmeta>
  <refentrytitle id="sql-createlanguage-title">
   CREATE LANGUAGE
  </refentrytitle>
  <refmiscinfo>SQL<!-- Language Statements -->言語</refmiscinfo>
 </refmeta>
 <refnamediv>
  <refname>
   CREATE LANGUAGE
  </refname>
  <refpurpose>
   <!-- Defines a new language for functions -->
   関数のための新しい言語を定義します。<indexterm><primary>CREATE LANGUAGE</primary></indexterm><indexterm><primary>SQL</primary><secondary>CREATE LANGUAGE</secondary></indexterm><indexterm><primary sortas="げんご">言語</primary><secondary sortas="ていぎ">定義</secondary></indexterm>
  </refpurpose>
 </refnamediv>
 <refsynopsisdiv>
  <refsynopsisdivinfo>
   <date>1999-07-20</date>
  </refsynopsisdivinfo>
<synopsis>
CREATE [ TRUSTED ] [ PROCEDURAL ] LANGUAGE '<replaceable class="parameter">langname</replaceable>'
    HANDLER <replaceable class="parameter">call_handler</replaceable>
    LANCOMPILER '<replaceable class="parameter">comment</replaceable>'
</synopsis>
  
  <refsect2 id="R2-SQL-CREATELANGUAGE-1">
   <refsect2info>
    <date>1998-09-09</date>
   </refsect2info>
   <title>
    <!-- Inputs -->入力
   </title>

    <variablelist>
     <varlistentry>
      <term>TRUSTED</term>
      <listitem>
       <para>
         <!-- 
	<function> TRUSTED</function> specifies that the call handler for
	the language is safe; that is, it offers an unprivileged user
	no functionality to bypass access restrictions. If
	this keyword is omitted when registering the language,
	only users with the <productname>Postgres</productname>
	superuser privilege can use
	this language to create new functions. -->

        <function>TRUSTED</function>は、その言語の呼び出しハンドラが安全であることを指定します。つまり、権限を持たないユーザーにはアクセス制限を無視する機能を何も与えないということです。もし言語を登録するときにこのキーワードが省略されると、<productname>Postgres</productname>のスーパーユーザー権限を持つユーザーのみが新しい関数を作るためにこの言語を使うことができるようになります。<indexterm><primary>TRUSTED</primary></indexterm><indexterm><primary sortas="げんご">言語</primary><secondary sortas="ていぎ">定義</secondary><tertiary>CREATE LANGUAGE</tertiary></indexterm>

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

     <varlistentry>
      <term><replaceable class="parameter">langname</replaceable></term>
      <listitem>
       <para>   
	<!-- The name of the new procedural language.
	The language name is case insensitive. A procedural 
	language cannot override one of the built-in languages of
	<productname>Postgres</productname>. -->

         新しい手続き言語の名前です。言語名は大文字/小文字の区別がありません。手続き言語はどの<productname>Postgres</productname>の組み込み言語をも上書きすることはできません。

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

     <varlistentry>
      <term>HANDLER <replaceable class="parameter">call_handler</replaceable></term>
      <listitem>
       <para>
        <!-- 
	<replaceable class="parameter">call_handler</replaceable> is the name
	of a previously
	registered function that will be called to execute the PL
	procedures. -->

        <replaceable class="parameter">call_handler</replaceable>は、以前登録されていた関数の名前で、PLプロシージャを実行するために呼び出されるものです。

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

     <varlistentry>
      <term><replaceable class="parameter">comment</replaceable></term>
      <listitem>
       <para>
	<!-- The <function>LANCOMPILER</function> argument is the
	string that will be
	inserted in the <literal>LANCOMPILER</literal> attribute
	of the new
	<filename>pg_language</filename> entry. At present,
	<productname>Postgres</productname> does not use
	this attribute in any way. -->

        <function>LANCOMPILER</function>引数は、新しい<filename>pg_language</filename>エントリの<literal>LANCOMPILER</literal>属性に挿入されるための文字列です。現時点では、<productname>Postgres</productname>はこの属性をどこにも使っていません。

       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   
  </refsect2>
  
  <refsect2 id="R2-SQL-CREATELANGUAGE-2">
   <refsect2info>
    <date>1998-09-09</date>
   </refsect2info>
   <title>
    <!-- Outputs -->出力
   </title>

    <variablelist>
     <varlistentry>
      <term><computeroutput>
CREATE
       </computeroutput></term>
      <listitem>
       <para>
	<!-- This message is returned if the language is successfully
	created. -->

        このメッセージは言語の作成に成功した場合に返されます。

       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><computeroutput>
ERROR:  PL handler function <replaceable class="parameter">funcname</replaceable>() doesn't exist
       </computeroutput></term>
      <listitem>
       <para>
	<!-- This error is returned if the function
	<replaceable class="parameter">funcname</replaceable>()
	is not found. -->

        このエラーは、関数<replaceable class="parameter">funcname</replaceable>()が見つからない場合に返されます。

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

 <refsect1 id="R1-SQL-CREATELANGUAGE-1">
  <refsect1info>
   <date>1998-09-09</date>
  </refsect1info>
  <title>
   <!-- Description -->説明
  </title>
  <para>
   <!-- Using <command>CREATE LANGUAGE</command>, a 
   <productname>Postgres</productname> user can register
   a new language with <productname>Postgres</productname>. 
   Subsequently, functions and
   trigger procedures can be defined in this new language.
   The user must have the <productname>Postgres</productname>
   superuser privilege to
   register a new language. -->

   <productname>Postgres</productname>ユーザーは、<command>CREATE LANGUAGE</command>を使って新しい言語を<productname>Postgres</productname>に登録することができます。これにより、関数とトリガプロシージャはこの新しい言語で定義可能になります。ユーザーは新しい言語を登録するためには<productname>Postgres</productname>のスーパーユーザー権限を持っていなければいけません。

  </para>

  <refsect2 id="R2-SQL-CREATELANGUAGE-3">
   <refsect2info>
    <date>1998-09-09</date>
   </refsect2info>
   <title>
    <!-- Writing PL handlers -->PLハンドラの書き方
   </title>
<indexterm><primary sortas="PLはんどら">PLハンドラ</primary></indexterm>
    <note>
     <para>
      <!-- 
      In <productname>Postgres</productname> 7.1 and later, call handlers
      must adhere to the "version 1" function manager interface, not the
      old-style interface. -->

      <productname>Postgres</productname> 7.1以降では、呼び出しハンドラは古い様式のインターフェイスではなく、「Version-1」関数マネージャインターフェイスに忠実でなければなりません。

     </para>
    </note>

   <para>
    <!-- 
    The call handler for a procedural language must be written
    in a compiled language such as C and registered with
    <productname>Postgres</productname> as a function taking
    no arguments and returning the
    <type>opaque</type> type, a placeholder for unspecified or 
    undefined types.
    This prevents the call handler from being called directly 
    as a function from queries.
    (However, arguments may be supplied in the actual call when a
    PL function in the language offered by the handler is to be 
    executed.) -->

    手続き言語の呼び出しハンドラは、C言語のようなコンパイラ型言語で書かれ、引数をとらず、未定義の型を意味する<type>opaque</type>型を返す関数として<productname>Postgres</productname>に登録されなければなりません。これは呼び出しハンドラが関数として直接問い合わせで呼び出されることを防ぐものです（しかし、言語内でハンドラによって提供されるPL関数が実行されるべき場合には、実際の呼び出しの際に引数が供給されることもあります）。
    
   </para>

   <para>
    <!-- 
    The call handler is called in the same way as any other
    function: it receives a pointer to a FunctionCallInfoData struct
    containing argument values and information about the called function,
    and it is expected to return a Datum result (and possibly set the
    <literal>isnull</literal> field of the FunctionCallInfoData struct,
    if it wishes to return an SQL NULL result).  The difference between
    a call handler and an ordinary callee function is that the
    <literal>flinfo-&gt;fn_oid</literal> field of the FunctionCallInfoData
    struct will contain the OID of the PL function to be called, not of
    the call handler itself.  The call handler must use this field to
    determine which function to execute.  Also, the passed argument list
    has been set up according to the declaration of the target PL function,
    not of the call handler. -->

    呼び出しハンドラは他の関数と同じように呼び出されます。呼び出される関数に関する情報と引数値を持つ構造体FunctionCallInfoDataへのポインタを受け取り、Datum結果を返すようになっています（SQL NULLの結果を返そうとする場合、できる限りFunctionCallInfoData構造体の<literal>isnull</literal>フィールドを設定します）。呼び出しハンドラと通常の呼び出される関数の違いはFunctionCallInfoData構造体の<literal>flinfo-&gt;fn_oid</literal>フィールドが、呼び出しハンドラ自身ではなく呼び出されるPL関数のOIDを持つということです。呼び出しハンドラはどの関数を実行するかを決定するためにこのフィールドを使わなければなりません。さらに、渡される引数のリストは呼び出しハンドラではなく目的のPL関数の宣言に基づいて設定されています。<indexterm><primary sortas="こうぞうたい">構造体</primary><secondary>FunctionCallInfoData</secondary></indexterm>

   </para>

   <para>
    <!-- It's up to the call handler to fetch the
    <filename>pg_proc</filename> entry and
    to analyze the argument and return types of the called
    procedure. The AS clause from the
    <command>CREATE FUNCTION</command> of
    the procedure will be found in the <literal>prosrc</literal>
    attribute of the
    <filename>pg_proc</filename> table entry. This may be the
    source text in the procedural
    language itself (like for PL/Tcl), a pathname to a
    file, or anything else that tells the call handler what to
    do in detail. -->

    <filename>pg_proc</filename>エントリを取り出し、呼び出されたプロシージャの引数と返り値を分析するのは呼び出しハンドラの責任です。プロシージャの<command>CREATE FUNCTION</command>からのAS句は<filename>pg_proc</filename>テーブルエントリの<literal>prosrc</literal>属性の中にあります。これは（PL/Tclのような）手続き言語自身の中のソーステキスト、ファイルへのパス名、もしくは呼び出しハンドラに何をすべきか詳細に指示するほかのものかもしれません。

   </para>

   <para>
    <!-- 
    Often, the same function is called many times per SQL statement.
    A call handler can avoid repeated lookups of information about the
    called function by using the <literal>flinfo-&gt;fn_extra</literal> field.
    This will initially be NULL, but can be set by the call handler to
    point at information about the PL function.  On subsequent calls,
    if <literal>flinfo-&gt;fn_extra</literal> is already non-NULL then it
    can be used and the information lookup step skipped.  The call handler
    must be careful that <literal>flinfo-&gt;fn_extra</literal> is made to
    point at memory that will live at least until the end of the current
    query, since an FmgrInfo data structure could be kept that long.
    One way to do this is to allocate the extra data in the memory context
    specified by <literal>flinfo-&gt;fn_mcxt</literal>; such data will
    normally have the same lifespan as the FmgrInfo itself.  But the handler
    could also choose to use a longer-lived context so that it can cache
    function definition information across queries. -->

    しばしば、SQL文ごとに同じ関数が何度も呼び出されることがあります。呼び出しハンドラは<literal>flinfo-&gt;fn_extra</literal>フィールドを使って呼び出される関数に関する情報が繰り返し検索することを回避できます。このフィールドの初期値はNULLですが、呼び出しハンドラによってPL関数に関する情報を指し示すように設定することができます。続く呼び出しでは、もし<literal>flinfo-&gt;fn_extra</literal>がすでに非NULLである場合はそれを使うことができ、情報検索が飛ばされます。FmgrInfoデータ構造体は現在の問い合わせが終了するまで保存されていなければならないので、呼び出しハンドラは<literal>flinfo-&gt;fn_extra</literal>が少なくともその問い合わせが終わるまでは存続中のメモリを指し示すようになっていなければならないことに注意しなければなりません。この目的のための1つの方法として、<literal>flinfo-&gt;fn_mcxt</literal>で指定されるメモリコンテキストに余分なデータを割り当てることです。そのようなデータは通常FmgrInfo自身と同じ寿命をもちます。しかしハンドラは、問い合わせを越えて関数定義情報をキャッシュできるように、さらに長く生きるコンテキストの使用を選ぶこともできます。<indexterm><primary sortas="こうぞうたい">構造体</primary><secondary>FmgrInfo</secondary></indexterm>

   </para>

   <para>
    <!-- 
    When a PL function is invoked as a trigger, no explicit arguments
    are passed, but the FunctionCallInfoData's
    <literal>context</literal> field points at a TriggerData node,
    rather than being NULL as it is in a plain function call.
    A PL handler should provide mechanisms for PL functions to get
    at the trigger information. -->

    PL関数がトリガとして呼び出されると、明示的な引数は何も渡されませんが、FunctionCallInfoDataの<literal>context</literal>フィールドは、普通の関数呼出しの中にあるためNULLではなくTriggerDataノードを指し示します。PLハンドラはPL関数がトリガ情報に到達するための仕組みを提供しなくてはなりません。

   </para>
  </refsect2>
   
  <refsect2 id="R2-SQL-CREATELANGUAGE-4">
   <refsect2info>
    <date>1998-09-09</date>
   </refsect2info>
   <title>
    <!-- Notes -->注釈
   </title>
   <para>
    <!-- Use <command>CREATE FUNCTION</command>
    to create a function. -->
    関数を作成するには<command>CREATE FUNCTION</command>を使います。

   </para>
   <para>
    <!-- Use <command>DROP LANGUAGE</command>  to drop procedural languages.
    -->

    手続き言語を削除するには<command>DROP LANGUAGE</command>を使います。

   </para>
   <para>
    <!-- Refer to the table <filename>pg_language</filename>
    for further information: -->

    さらに詳しい情報は、テーブル<filename>pg_language</filename>を参照してください。
</para>

<programlisting>
<computeroutput>        Table "pg_language"
   Attribute   |  Type   | Modifier
---------------+---------+----------
 lanname       | name    |
 lanispl       | boolean |
 lanpltrusted  | boolean |
 lanplcallfoid | oid     |
 lancompiler   | text    |

   lanname   | lanispl | lanpltrusted | lanplcallfoid | lancompiler
-------------+---------+--------------+---------------+-------------
 internal    | f       | f            |             0 | n/a
 C           | f       | f            |             0 | /bin/cc
 sql         | f       | f            |             0 | postgres</computeroutput>
</programlisting>

   <para>
    <!-- 
    The call handler for a procedural language must normally be written
    in C and registered as 'internal' or 'C' language, depending
    on whether it is linked into the backend or dynamically loaded.
    The call handler cannot use the old-style 'C' function interface.
    -->

    手続き言語の呼び出しハンドラは通常はC言語で書かれ、バックエンドにリンクされているか動的にロードされるかによって「内部」もしくは「C」として登録されなければなりません。呼び出しハンドラは古い様式の「C」関数インターフェイスを使うことはできません。

   </para>

   <para> 
    <!-- 
    At present, the definitions for a procedural language cannot be
    changed once they have been created. -->

    現時点では、手続き言語の定義は一度作成されると変えることはできません。

   </para>
  </refsect2>
 </refsect1>

 <refsect1 id="R1-SQL-CREATELANGUAGE-6">
  <title>
   <!--Usage-->使用方法
  </title>
  <para>
   <!-- This is a template for a PL handler written in C: -->
   Cで書かれたPLハンドラのテンプレートを以下に示します。
 </para>

<programlisting>
#include "executor/spi.h"
#include "commands/trigger.h"
#include "utils/elog.h"
#include "fmgr.h"
#include "access/heapam.h"
#include "utils/syscache.h"
#include "catalog/pg_proc.h"
#include "catalog/pg_type.h"

PG_FUNCTION_INFO_V1(plsample_call_handler);

Datum
plsample_call_handler(PG_FUNCTION_ARGS)
{
     Datum          retval;

     if (CALLED_AS_TRIGGER(fcinfo))
     {
         <!--  /*
           * Called as a trigger procedure
           */ -->
          /*
           * トリガプロシージャとして呼び出されます。
           */
  
          TriggerData    *trigdata = (TriggerData *) fcinfo->context;

          retval = ...
     } else {
          <!--/*
           * Called as a function
           */ -->
          /*
           * 関数として呼び出されます。
           */
           
          retval = ...
     }

     return retval;
}
</programlisting>

  <para>
   <!-- Only a few thousand lines of code have to be added instead
   of the dots to complete the PL call handler. 
   See <command>CREATE FUNCTION</command> for information on how to 
   compile it into a loadable module. -->

   PL呼び出しハンドラを完成させるには、上記テンプレートの中の「...」の所に、数千行のコードを追加するだけです。ロード可能なモジュールにコンパイルする方法は<command>CREATE FUNCTION</command>を見てください。

  </para>
  <para>
   <!-- 
   The following commands then register the sample procedural
   language: -->

   以下のコマンドはサンプルの手続き言語を登録します。
</para>

<programlisting>
CREATE FUNCTION plsample_call_handler () RETURNS opaque
    AS '/usr/local/pgsql/lib/plsample.so'
    LANGUAGE 'C';
CREATE PROCEDURAL LANGUAGE 'plsample'
    HANDLER plsample_call_handler
    LANCOMPILER 'PL/Sample'; 
</programlisting>
 </refsect1>

 <refsect1 id="R1-SQL-CREATELANGUAGE-7">
  <title>
   <!-- Compatibility -->互換性
  </title>

  <refsect2 id="R2-SQL-CREATELANGUAGE-5">
   <refsect2info>
    <date>1998-09-09</date>
   </refsect2info>
   <title>
    SQL92
   </title>

   <para>
    <!-- <command>CREATE LANGUAGE</command>
    is a <productname>Postgres</productname> extension.
    There is no <command>CREATE LANGUAGE</command> statement in
    <acronym>SQL92</acronym>. -->

    <command>CREATE LANGUAGE</command>は<productname>Postgres</productname>の拡張です。<acronym>SQL92</acronym>には<command>CREATE LANGUAGE</command>文はありません。

   </para>
  </refsect2>
 </refsect1>
</refentry>

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