diff options
Diffstat (limited to 'doc/src/sgml/ref/create_language.sgml')
| -rw-r--r-- | doc/src/sgml/ref/create_language.sgml | 314 |
1 files changed, 0 insertions, 314 deletions
diff --git a/doc/src/sgml/ref/create_language.sgml b/doc/src/sgml/ref/create_language.sgml deleted file mode 100644 index 1871da57e56..00000000000 --- a/doc/src/sgml/ref/create_language.sgml +++ /dev/null @@ -1,314 +0,0 @@ -<!-- -$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_language.sgml,v 1.25 2002/06/20 15:44:06 momjian Exp $ -PostgreSQL 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>define a new procedural language</refpurpose> - </refnamediv> - - <refsynopsisdiv> -<synopsis> -CREATE [ TRUSTED ] [ PROCEDURAL ] LANGUAGE <replaceable class="parameter">langname</replaceable> - HANDLER <replaceable class="parameter">call_handler</replaceable> [ VALIDATOR <replaceable>valfunction</replaceable> ] -</synopsis> - </refsynopsisdiv> - - <refsect1 id="sql-createlanguage-description"> - <title>Description</title> - - <para> - Using <command>CREATE LANGUAGE</command>, a - <productname>PostgreSQL</productname> user can register a new - procedural language with a <productname>PostgreSQL</productname> - database. Subsequently, functions and trigger procedures can be - defined in this new language. The user must have the - <productname>PostgreSQL</productname> superuser privilege to - register a new language. - </para> - - <para> - <command>CREATE LANGUAGE</command> effectively associates the - language name with a call handler that is responsible for executing - functions written in the language. Refer to the - <citetitle>Programmer's Guide</citetitle> for more information - about language call handlers. - </para> - - <para> - Note that procedural languages are local to individual databases. - To make a language available in all databases by default, it should - be installed into the <literal>template1</literal> database. - </para> - </refsect1> - - <refsect1 id="sql-createlanguage-parameters"> - <title>Parameters</title> - - <variablelist> - <varlistentry> - <term><literal>TRUSTED</literal></term> - - <listitem> - <para> - <literal>TRUSTED</literal> specifies that the call handler for - the language is safe, that is, it does not offer an - unprivileged user any functionality to bypass access - restrictions. If this keyword is omitted when registering the - language, only users with the - <productname>PostgreSQL</productname> superuser privilege can - use this language to create new functions. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>PROCEDURAL</literal></term> - - <listitem> - <para> - This is a noise word. - </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>PostgreSQL</productname>. - </para> - - <para> - For backward compatibility, the name may be enclosed by single - quotes. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>HANDLER</literal> <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 procedural language functions. The call - handler for a procedural language must be written in a compiled - language such as C with version 1 call convention and - registered with <productname>PostgreSQL</productname> as a - function taking no arguments and returning the - <type>opaque</type> type, a placeholder for unspecified or - undefined types. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>VALIDATOR</literal> <replaceable class="parameter">valfunction</replaceable></term> - - <listitem> - <para> - <replaceable class="parameter">valfunction</replaceable> is the - name of a previously registered function that will be called - when a new function in the language is created, to validate the - new function. The validator function must take one argument of - type <type>oid</type>, which will be the OID of the - to-be-created function, and can have any return type. If no - validator function is specified, then a new function will not - be checked when it is created. - </para> - - <para> - A validator function would typically inspect the function body - for syntactical correctness, but it can also look at other - properties of the function, for example if the language cannot - handle certain argument types. To signal an error, the - validator function should use the <function>elog()</function> - function. The return value of the function is ignored. - </para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1 id="sql-createlanguage-diagnostics"> - <title>Diagnostics</title> - - <msgset> - <msgentry> - <msg> - <msgmain> - <msgtext> -<screen> -CREATE LANGUAGE -</screen> - </msgtext> - </msgmain> - </msg> - - <msgexplan> - <para> - This message is returned if the language is successfully - created. - </para> - </msgexplan> - </msgentry> - - <msgentry> - <msg> - <msgmain> - <msgtext> -<screen> -ERROR: PL handler function <replaceable class="parameter">funcname</replaceable>() doesn't exist -</screen> - </msgtext> - </msgmain> - </msg> - - <msgexplan> - <para> - This error is returned if the function <replaceable - class="parameter">funcname</replaceable>() is not found. - </para> - </msgexplan> - </msgentry> - </msgset> - </refsect1> - - <refsect1 id="sql-createlanguage-notes"> - <title>Notes</title> - - <para> - This command normally should not be executed directly by users. - For the procedural languages supplied in the - <productname>PostgreSQL</productname> distribution, the <xref - linkend="app-createlang"> script should be used, which will also - install the correct call handler. (<command>createlang</command> - will call <command>CREATE LANGUAGE</command> internally.) - </para> - - <para> - Use the <xref linkend="sql-createfunction" endterm="sql-createfunction-title"> command to create a new - function. - </para> - - <para> - Use <xref linkend="sql-droplanguage" endterm="sql-droplanguage-title">, or better yet the <xref - linkend="app-droplang"> script, to drop procedural languages. - </para> - - <para> - The system catalog <classname>pg_language</classname> records - information about the currently installed procedural languages. - -<screen> - Table "pg_language" - Attribute | Type | Modifier ----------------+-----------+---------- - lanname | name | - lanispl | boolean | - lanpltrusted | boolean | - lanplcallfoid | oid | - lanvalidator | oid | - lancompiler | text | - lanacl | aclitem[] | - - lanname | lanispl | lanpltrusted | lanplcallfoid | lanvalidator | lancompiler | lanacl --------------+---------+--------------+---------------+--------------+-------------+-------- - internal | f | f | 0 | 2246 | n/a | - c | f | f | 0 | 2247 | /bin/cc | - sql | f | t | 0 | 2248 | postgres | {=U} -</screen> - </para> - - <para> - At present, with the exception of the permissions, the definition - of a procedural language cannot be changed once it has been created. - </para> - - <para> - To be able to use a procedural language, a user must be granted the - <literal>USAGE</literal> privilege. The - <command>createlang</command> program automatically grants - permissions to everyone if the language is known to be trusted. - </para> - </refsect1> - - <refsect1 id="sql-createlanguage-examples"> - <title>Examples</title> - - <para> - The following two commands executed in sequence will register a new - procedural language and the associated call handler. -<programlisting> -CREATE FUNCTION plsample_call_handler () RETURNS opaque - AS '$libdir/plsample' - LANGUAGE C; -CREATE LANGUAGE plsample - HANDLER plsample_call_handler; -</programlisting> - </para> - </refsect1> - - <refsect1 id="sql-createlanguage-compat"> - <title>Compatibility</title> - - <para> - <command>CREATE LANGUAGE</command> is a - <productname>PostgreSQL</productname> extension. - </para> - </refsect1> - - <refsect1> - <title>History</title> - - <para> - The <command>CREATE LANGUAGE</command> command first appeared in - <productname>PostgreSQL</productname> 6.3. - </para> - </refsect1> - - <refsect1> - <title>See Also</title> - - <para> - <simplelist type="inline"> - <member><xref linkend="app-createlang"></member> - <member><xref linkend="sql-createfunction"></member> - <member><xref linkend="app-droplang"></member> - <member><xref linkend="sql-droplanguage"></member> - <member><xref linkend="sql-grant"></member> - <member><xref linkend="sql-revoke"></member> - <member><citetitle>PostgreSQL Programmer's Guide</citetitle></member> - </simplelist> - </para> - </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: ---> |