<!--
$Header: /usr/prj/pg/cvsroot/doc/doc/src/sgml/ref/create_function.sgml,v 1.7 2001/09/04 10:40:13 i-kaori Exp $
Postgres documentation
-->

<refentry id="SQL-CREATEFUNCTION">
 <refmeta>
  <refentrytitle id="sql-createfunction-title">
   CREATE FUNCTION
  </refentrytitle>
  <refmiscinfo>SQL<!-- Language Statements -->言語</refmiscinfo>
 </refmeta>
 <refnamediv>
  <refname>
   CREATE FUNCTION
  </refname>
  <refpurpose>
   <!-- Defines a new function -->新しい関数を定義します。<indexterm><primary>CREATE FUNCTION</primary></indexterm><indexterm><primary>SQL</primary><secondary>CREATE FUNCTION</secondary></indexterm><indexterm><primary sortas="かんすう">関数</primary><secondary sortas="ていぎ">定義</secondary></indexterm>
  </refpurpose>
 </refnamediv>
 <refsynopsisdiv>
  <refsynopsisdivinfo>
   <date>2000-03-25</date>
  </refsynopsisdivinfo>
<synopsis>
CREATE FUNCTION <replaceable class="parameter">name</replaceable> ( [ <replaceable class="parameter">ftype</replaceable> [, ...] ] )
    RETURNS <replaceable class="parameter">rtype</replaceable>
    AS <replaceable class="parameter">definition</replaceable>   
    LANGUAGE '<replaceable class="parameter">langname</replaceable>'
    [ WITH ( <replaceable class="parameter">attribute</replaceable> [, ...] ) ]
CREATE FUNCTION <replaceable class="parameter">name</replaceable> ( [ <replaceable class="parameter">ftype</replaceable> [, ...] ] )
    RETURNS <replaceable class="parameter">rtype</replaceable>
    AS <replaceable class="parameter">obj_file</replaceable> , <replaceable class="parameter">link_symbol</replaceable>  
    LANGUAGE 'langname'
    [ WITH ( <replaceable class="parameter">attribute</replaceable> [, ...] ) ]
</synopsis>
  
  <refsect2 id="R2-SQL-CREATEFUNCTION-1">
   <refsect2info>
    <date>2000-03-25</date>
   </refsect2info>
   <title>
    <!-- Inputs -->入力
   </title>

    <variablelist>
     <varlistentry>
      <term><replaceable class="parameter">name</replaceable></term>
      <listitem>
       <para>
	<!-- The name of a function to create. -->
        作成する関数の名前です。
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><replaceable class="parameter">ftype</replaceable></term>
      <listitem>
       <para>
        <!-- 
	The data type(s) of the function's arguments, if any.
	The input types may be base or complex types, or
	<firstterm>opaque</firstterm>.
	<literal>Opaque</literal> indicates that the function
	accepts arguments of a non-SQL type such as <type>char *</type>.
        -->

        もしあれば、関数の引数のデータ型です。入力型は基数型、複素数型、<firstterm>opaque</firstterm>型を使うことができます。<literal>Opaque</literal>はその関数が<type>char *</type>のような非SQL型の引数を受け付けることを示します。

       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><replaceable class="parameter">rtype</replaceable></term>
      <listitem>
       <para>
	<!-- The return data type.
	The output type may be specified as a base type, complex type, 
	<option>setof type</option>,
	or <option>opaque</option>.
	The <option>setof</option>
	modifier indicates that the function will return a set of items,
	rather than a single item. -->

        返されるデータ型です。出力の型は基数型、複素数型、<option>setof type</option>、<option>opaque</option>を返すことができます。修飾子<option>setof</option>はその関数が、1つのアイテムではなくアイテムの集合を返すことを示します。

       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><replaceable class="parameter">attribute</replaceable></term>
      <listitem>
       <para>
        <!-- 
        An optional piece of information about the function, used for
	optimization.  See below for details. -->

        最適化に使われる関数のオプション情報です。詳細は下記を参照してください。

       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><replaceable class="parameter">definition</replaceable></term>
      <listitem>
       <para>
        <!-- 
	A string defining the function; the meaning depends on the language.
	It may be an internal function name, the path to an object file,
	an SQL query, or text in a procedural language. -->

        関数を定義する文字列です。その意味は言語によって異なります。内部関数の名前、オブジェクトファイルへのパス、SQL問い合わせ、手続き言語のテキストなどを指定できます。

       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><replaceable class="parameter">obj_file</replaceable> , <replaceable class="parameter">link_symbol</replaceable></term>
      <listitem>
       <para>
	<!-- This form of the <command>AS</command> clause is used for
	dynamically linked, C language functions when the function name in
	the C language source code is not the same as the name of the SQL
	function. The string <replaceable
	class="parameter">obj_file</replaceable> is the name of the file
	containing the dynamically loadable object, and <replaceable
	class="parameter">link_symbol</replaceable> is the object's link
	symbol, that is the name of the function in the C
	language source code. -->

        この形式の<command>AS</command>句は、C言語のソースコード中の関数名がSQL関数の名前と同じでない場合、動的にリンクされたC言語関数に使われます。文字列<replaceable class="parameter">obj_file</replaceable>は動的にロードできるオブジェクトを含むファイルの名前で、<replaceable class="parameter">link_symbol</replaceable>はC言語ソースコード中の関数の名前であるオブジェクトのリンクシンボルです。

       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><replaceable class="parameter">langname</replaceable></term>
      <listitem>
       <para>
	<!-- May be '<literal>sql</literal>',
	'<literal>C</literal>', '<literal>internal</literal>',
	or '<replaceable class="parameter">plname</replaceable>',
	where '<replaceable class="parameter">plname</replaceable>'
	is the name of a created procedural language. See
	<xref linkend="sql-createlanguage" endterm="sql-createlanguage-title">
	for details. -->

        '<replaceable class="parameter">plname</replaceable>'が作成された手続き言語の名前であるときは、'<literal>sql</literal>'、'<literal>C</literal>'、'<literal>internal</literal>'、'<replaceable class="parameter">plname</replaceable>'を指定できます。詳細は<xref linkend="sql-createlanguage" endterm="sql-createlanguage-title">を参照してください。

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

  <refsect2 id="R2-SQL-CREATEFUNCTION-2">
   <refsect2info>
    <date>2000-03-25</date>
   </refsect2info>
   <title>
    <!-- Outputs -->出力
   </title>

    <variablelist>
     <varlistentry>
      <term><computeroutput>
CREATE
       </computeroutput></term>
      <listitem>
       <para>
	<!-- This is returned if the command completes successfully. -->
        コマンドが問題なく終了するとこのメッセージが返されます。
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
  </refsect2>
 </refsynopsisdiv>

 <refsect1 id="R1-SQL-CREATEFUNCTION-1">
  <refsect1info>
   <date>2000-03-25</date>
  </refsect1info>
  <title>
   <!-- Description -->説明
  </title>
  <para>
   <!-- <command>CREATE FUNCTION</command> allows a
   <productname>Postgres</productname> user
   to register a function
   with the database. Subsequently, this user is considered the
   owner of the function. -->

   <command>CREATE FUNCTION</command>によって<productname>Postgres</productname>ユーザーがデータベースに関数を登録することができます。同時に、このユーザーはその関数の所有者であるとみなされます。<indexterm><primary sortas="かんすう">関数</primary><secondary sortas="しょゆうしゃ">所有者</secondary></indexterm>

  </para>

  <refsect2 id="R2-SQL-CREATEFUNCTION-3">
   <refsect2info>
    <date>2000-08-24</date>
   </refsect2info>
   <title>
    <!-- Function Attributes -->関数の属性
   </title>
<indexterm><primary sortas="かんすう">関数</primary><secondary sortas="ぞくせい">属性</secondary></indexterm>

   <para>
    <!-- The following items may appear in the WITH clause: -->
    以下のものはWITH句の中で使われることがあります。
</para>

    <variablelist>
     <varlistentry>
      <term>iscachable</term>
      <listitem>
       <para>
        <!-- 
	<option>Iscachable</option> indicates that the function always
	returns the same result when given the same argument values (i.e.,
	it does not do database lookups or otherwise use information not
	directly present in its parameter list).  The optimizer uses
	<option>iscachable</option> to know whether it is safe to
	pre-evaluate a call of the function. -->

        <option>Iscachable</option>はその関数が同じ引数値を与えられると常に同じ結果を返すことを示します（つまり、データベース検索をしたり、そのパラメータリスト中に直接存在しない情報を使ったりはしません）。オプティマイザは関数の呼び出しを事前に評価することが安全かどうかを調べるために<option>iscachable</option>を使います。
        
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>isstrict</term>
      <listitem>
       <para>
        <!-- 
	<option>isstrict</option> indicates that the function always
	returns NULL whenever any of its arguments are NULL.  If this
	attribute is specified, the function is not executed when there
	are NULL arguments; instead a NULL result is assumed automatically.
	When <option>isstrict</option> is not specified, the function will
	be called for NULL inputs.  It is then the function author's
	responsibility to check for NULLs if necessary and respond
	appropriately. -->

        <option>isstrict</option>は、関数にNULLが引数として与えられるとその関数は常にNULLを返すことを示します。もしこの属性が指定されると、その関数にNULL引数がある場合実行されません。代わりにNULLという結果が自動的に仮定されます。<option>isstrict</option>が指定されないと、その関数はNULL入力で呼ばれます。その場合は必要に応じてNULLを確認し、適切な対応をすることが関数の作者の責任になります。

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

  </refsect2>

  <refsect2 id="R2-SQL-CREATEFUNCTION-4">
   <refsect2info>
    <date>2000-03-25</date>
   </refsect2info>
   <title>
    <!-- Notes -->注釈
   </title>

   <para>
    <!-- Refer to the chapter in the
    <citetitle>PostgreSQL Programmer's Guide</citetitle>
    on the topic of extending
    <productname>Postgres</productname> via functions 
    for further information on writing external functions. -->

    さらに詳しい外部関数の書き方については<citetitle>&programmer-guide;</citetitle>の関数を使った<productname>Postgres</productname>の拡張に関する章を参照してください。

   </para>

   <para>
    <!-- Use <command>DROP FUNCTION</command>
    to remove user-defined functions. -->

    ユーザー定義関数を削除するには、<command>DROP FUNCTION</command>を使います。

   </para>

   <para>
    <!-- 
    The full <acronym>SQL92</acronym> type syntax is allowed for
    input arguments and return value. However, some details of the
    type specification (e.g., the precision field for
    <type>numeric</type> types) are the responsibility of the
    underlying function implementation and are silently swallowed
    (i.e., not recognized or
    enforced) by the <command>CREATE FUNCTION</command> command.
    -->

    すべての<acronym>SQL92</acronym>の型の構文は入力引数と返り値に認められています。しかし、型指定のいくつかの細部（たとえば<type>numeric</type>型の精度フィールド）は、その関数の実装の仕方に責任があり、<command>CREATE FUNCTION</command>コマンドによって警告なく包含されます（つまり認識や強制はされません）。

   </para>

   <para>
    <!-- 
    <productname>Postgres</productname> allows function "overloading";
    that is, the same name can be used for several different functions
    so long as they have distinct argument types.  This facility must
    be used with caution for internal and C-language functions, however.    
    -->

    <productname>Postgres</productname>は関数の「オーバーロード」を許可します。これは、異なる引数の型を持っていれば別の関数が同じ名前を使うことができるということです。しかしこの機能は内部とC言語関数では注意して使わなくてはなりません。<indexterm><primary sortas="かんすう">関数</primary><secondary sortas="おーばーろーど">オーバーロード</secondary></indexterm>

   </para>

   <para>
    <!-- Two <literal>internal</literal>
    functions cannot have the same C name without causing
    errors at link time.  To get around that, give them different C names
    (for example, use the argument types as part of the C names), then
    specify those names in the AS clause of <command>CREATE FUNCTION</command>.
    If the AS clause is left empty, then <command>CREATE FUNCTION</command>
    assumes the C name of the function is the same as the SQL name. -->

    2つの<literal>内部</literal>関数が同じCの名前を持っていると、リンク時にエラーが発生します。これを回避するためには、2つの関数に異なるCの名前を与え（たとえば、Cの名前の一部として引数の型などを使います）、そしてそれらの名前を<command>CREATE FUNCTION</command>のAS句の中で指定します。もしそのAS句が空のままの場合は、<command>CREATE FUNCTION</command>はその関数のCの名前はSQLの名前と同じであると仮定します。

   </para>

   <para>
    <!-- 
    Similarly, when overloading SQL function names with multiple C-language
    functions, give
    each C-language instance of the function a distinct name, then use
    the alternative form of the <command>AS</command> clause in the
    <command>CREATE FUNCTION</command> syntax to select the appropriate
    C-language implementation of each overloaded SQL function. -->

    同様に、SQL関数名を複数のC言語関数でオーバーロードするときは、それぞれのC言語関数のインスタンスに異なる名前を与え、それぞれのオーバーロードされたSQL関数のふさわしいC言語実装を選択するために<command>CREATE FUNCTION</command>構文の中で<command>AS</command>句の代替形式を使います。

   </para>

  </refsect2>
 </refsect1>
  
 <refsect1 id="R1-SQL-CREATEFUNCTION-2">
  <title>
   <!-- Usage -->使用方法
  </title>
  <para>
   <!-- To create a simple SQL function: -->
   単純なSQL関数を作成するのは以下のようにします。
</para>

<programlisting>
CREATE FUNCTION one() RETURNS int4
    AS 'SELECT 1 AS RESULT'
    LANGUAGE 'sql';
SELECT one() AS answer;

<computeroutput> answer 
--------
      1</computeroutput>
</programlisting>

  <para>
   <!-- 
   This example creates a C function by calling a routine from a user-created
   shared library.  This particular routine calculates a check
   digit and returns TRUE if the check digit in the function parameters
   is correct. It is intended for use in a CHECK contraint.
   -->

   この例はユーザー作成の共有ライブラリからルーチンを呼び出すことによりC関数を作成します。この特定のルーチンは検査ディジットを計算し、もし関数パラメータ中の検査ディジットが正しければTRUEを返します。これはCHECK制約の中で使われることが意図されています。

  </para>
<programlisting>
CREATE FUNCTION ean_checkdigit(bpchar, bpchar) RETURNS boolean
    AS '/usr1/proj/bray/sql/funcs.so' LANGUAGE 'c';
    
CREATE TABLE product (
    id        char(8) PRIMARY KEY,
    eanprefix char(8) CHECK (eanprefix ~ '[0-9]{2}-[0-9]{5}')
                      REFERENCES brandname(ean_prefix),
    eancode   char(6) CHECK (eancode ~ '[0-9]{6}'),
    CONSTRAINT ean    CHECK (ean_checkdigit(eanprefix, eancode))
);
</programlisting>


  <para>
   <!-- 
   This example creates a function that does type conversion between the
   user-defined type complex, and the internal type point.  The
   function is implemented by a dynamically loaded object that was
   compiled from C source. For <productname>Postgres</productname> to
   find a type conversion function automatically, the sql function has
   to have the same name as the return type, and so overloading is
   unavoidable.  The function name is overloaded by using the second
   form of the <command>AS</command> clause in the SQL definition:
   -->

   この例は、ユーザー定義型complexと内部型point間での型変換を行う関数を作成します。その関数はCのソースからコンパイルされた動的にロードされるオブジェクトによって実装されています。<productname>Postgres</productname>が型変換関数を自動的に見つけるためには、SQL関数が返り値の型と同じ名前を持っていなければいけないため、オーバーロードは避けることができません。関数名はSQL定義中の<command>AS</command>句の2番目の形式を使ってオーバーロードされます。

  </para>
<programlisting>
CREATE FUNCTION point(complex) RETURNS point
    AS '/home/bernie/pgsql/lib/complex.so', 'complex_to_point'
    LANGUAGE 'c';
</programlisting>
  <para>
  <!-- The C declaration of the function is: -->
  関数のC宣言は以下です。 
  </para>
<programlisting>
Point * complex_to_point (Complex *z)
{
	Point *p;

	p = (Point *) palloc(sizeof(Point));
	p->x = z->x;
	p->y = z->y;
		
	return p;
}
</programlisting>

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

  <refsect2 id="R2-SQL-CREATEFUNCTION-5">
   <refsect2info>
    <date>2000-03-25</date>
   </refsect2info>
   <title>
    SQL92
   </title>

   <para>
    <!-- <command>CREATE FUNCTION</command> is
    a <productname>Postgres</productname> language extension. -->

    <command>CREATE FUNCTION</command>は<productname>Postgres</productname>の言語拡張です。
    
   </para>
  </refsect2>

  <refsect2 id="R2-SQL-CREATEFUNCTION-6">
   <refsect2info>
    <date>2000-03-25</date>
   </refsect2info>
   <title>
    SQL/PSM
   </title>

    <note>
     <para>
      <!-- 
      PSM stands for Persistent Stored Modules. It is a procedural
      language and it was originally hoped that PSM would be ratified
      as an official standard by late 1996. As of mid-1998, this
      has not yet happened, but it is hoped that PSM will
      eventually become a standard. -->

      PSMはPersistent Stored Modulesの略です。これは手続き言語であり、もともとはPSMは1996年までには公式な標準として批准されることが望まれていました。1998年の中頃の時点ではまだそうなっていませんが、PSMがいずれは標準になることが望まれています。<indexterm><primary>PSM</primary></indexterm>

     </para>
    </note>

<para>
    <!--
    SQL/PSM <command>CREATE FUNCTION</command> has the following syntax:
    -->
    SQL/PSM <command>CREATE FUNCTION</command>には、以下の構文があります。
</para>

<synopsis>
CREATE FUNCTION <replaceable class="parameter">name</replaceable>
    ( [ [ IN | OUT | INOUT ] <replaceable class="parameter">type</replaceable> [, ...] ] )
     RETURNS <replaceable class="parameter">rtype</replaceable>
     LANGUAGE '<replaceable class="parameter">langname</replaceable>'
     ESPECIFIC <replaceable class="parameter">routine</replaceable>
     <replaceable class="parameter">SQL-statement</replaceable>
</synopsis>
  </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:
-->
