mirror of
https://github.com/postgres/postgres.git
synced 2025-07-28 23:42:10 +03:00
Fix markup for docbook2man man page generation.
No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
This commit is contained in:
Thomas G. Lockhart
@ -1,87 +1,80 @@
|
||||
<REFENTRY ID="SQL-CREATELANGUAGE">
|
||||
<REFMETA>
|
||||
<REFENTRYTITLE>
|
||||
<refentry id="SQL-CREATELANGUAGE">
|
||||
<refmeta>
|
||||
<refentrytitle>
|
||||
CREATE LANGUAGE
|
||||
</REFENTRYTITLE>
|
||||
<REFMISCINFO>SQL - Language Statements</REFMISCINFO>
|
||||
</REFMETA>
|
||||
<REFNAMEDIV>
|
||||
<REFNAME>
|
||||
</refentrytitle>
|
||||
<refmiscinfo>SQL - Language Statements</refmiscinfo>
|
||||
</refmeta>
|
||||
<refnamediv>
|
||||
<refname>
|
||||
CREATE LANGUAGE
|
||||
</REFNAME>
|
||||
<REFPURPOSE>
|
||||
</refname>
|
||||
<refpurpose>
|
||||
Defines a new language for functions
|
||||
</REFPURPOSE>
|
||||
</refpurpose>
|
||||
</refnamediv>
|
||||
<REFSYNOPSISDIV>
|
||||
<REFSYNOPSISDIVINFO>
|
||||
<DATE>1998-09-09</DATE>
|
||||
</REFSYNOPSISDIVINFO>
|
||||
<SYNOPSIS>
|
||||
<refsynopsisdiv>
|
||||
<refsynopsisdivinfo>
|
||||
<date>1998-09-09</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>
|
||||
</synopsis>
|
||||
|
||||
<REFSECT2 ID="R2-SQL-CREATELANGUAGE-1">
|
||||
<REFSECT2INFO>
|
||||
<DATE>1998-09-09</DATE>
|
||||
</REFSECT2INFO>
|
||||
<TITLE>
|
||||
<refsect2 id="R2-SQL-CREATELANGUAGE-1">
|
||||
<refsect2info>
|
||||
<date>1998-09-09</date>
|
||||
</refsect2info>
|
||||
<title>
|
||||
Inputs
|
||||
</TITLE>
|
||||
<PARA>
|
||||
<VARIABLELIST>
|
||||
<VARLISTENTRY>
|
||||
<TERM>
|
||||
<function>TRUSTED</function>
|
||||
</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
|
||||
(like the 'C' language).
|
||||
</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>.
|
||||
</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.
|
||||
</PARA>
|
||||
</LISTITEM>
|
||||
</VARLISTENTRY>
|
||||
<VARLISTENTRY>
|
||||
<TERM>
|
||||
<replaceable class="parameter">comment</replaceable>
|
||||
</TERM>
|
||||
<LISTITEM>
|
||||
<PARA>
|
||||
</title>
|
||||
<para>
|
||||
|
||||
<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
|
||||
(like the 'C' language).
|
||||
</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>.
|
||||
</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.
|
||||
</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
|
||||
@ -89,81 +82,82 @@ superuser privilege can use
|
||||
<filename>pg_language</filename> entry. At present,
|
||||
<productname>Postgres</productname> does not use
|
||||
this attribute in any way.
|
||||
</PARA>
|
||||
</LISTITEM>
|
||||
</VARLISTENTRY>
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</para>
|
||||
|
||||
</REFSECT2>
|
||||
</refsect2>
|
||||
|
||||
<REFSECT2 ID="R2-SQL-CREATELANGUAGE-2">
|
||||
<REFSECT2INFO>
|
||||
<DATE>1998-09-09</DATE>
|
||||
</REFSECT2INFO>
|
||||
<TITLE>
|
||||
<refsect2 id="R2-SQL-CREATELANGUAGE-2">
|
||||
<refsect2info>
|
||||
<date>1998-09-09</date>
|
||||
</refsect2info>
|
||||
<title>
|
||||
Outputs
|
||||
</TITLE>
|
||||
<PARA>
|
||||
<VARIABLELIST>
|
||||
<VARLISTENTRY>
|
||||
<TERM>
|
||||
<ReturnValue>CREATE</ReturnValue>
|
||||
</TERM>
|
||||
<LISTITEM>
|
||||
<PARA>
|
||||
This message is returned if the language is successfully
|
||||
created.
|
||||
</PARA>
|
||||
</LISTITEM>
|
||||
</VARLISTENTRY>
|
||||
<VARLISTENTRY>
|
||||
<TERM>
|
||||
<ReturnValue>ERROR: PL handler function <replaceable class="parameter">funcname</replaceable>() doesn't exist</ReturnValue>
|
||||
</TERM>
|
||||
<LISTITEM>
|
||||
<PARA>
|
||||
</title>
|
||||
<para>
|
||||
|
||||
<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.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</VARIABLELIST>
|
||||
</variablelist>
|
||||
</para>
|
||||
</REFSECT2>
|
||||
</REFSYNOPSISDIV>
|
||||
|
||||
<REFSECT1 ID="R1-SQL-CREATELANGUAGE-1">
|
||||
<REFSECT1INFO>
|
||||
<DATE>1998-09-09</DATE>
|
||||
</REFSECT1INFO>
|
||||
<TITLE>
|
||||
</refsect2>
|
||||
</refsynopsisdiv>
|
||||
|
||||
<refsect1 id="R1-SQL-CREATELANGUAGE-1">
|
||||
<refsect1info>
|
||||
<date>1998-09-09</date>
|
||||
</refsect1info>
|
||||
<title>
|
||||
Description
|
||||
</TITLE>
|
||||
<PARA>
|
||||
</title>
|
||||
<para>
|
||||
Using <command>CREATE LANGUAGE</command>, a
|
||||
<productname>Postgres</productname> user can register
|
||||
<productname>Postgres</productname> user can register
|
||||
a new language with <productname>Postgres</productname>.
|
||||
Subsequently, functions and
|
||||
Subsequently, functions and
|
||||
trigger procedures can be defined in this new language.
|
||||
The user must have the <productname>Postgres</productname>
|
||||
superuser privilege to
|
||||
superuser privilege to
|
||||
register a new language.
|
||||
</PARA>
|
||||
|
||||
<REFSECT2 ID="R2-SQL-CREATELANGUAGE-3">
|
||||
<REFSECT2INFO>
|
||||
<DATE>1998-09-09</DATE>
|
||||
</REFSECT2INFO>
|
||||
<TITLE>
|
||||
</para>
|
||||
|
||||
<refsect2 id="R2-SQL-CREATELANGUAGE-3">
|
||||
<refsect2info>
|
||||
<date>1998-09-09</date>
|
||||
</refsect2info>
|
||||
<title>
|
||||
Writing PL handlers
|
||||
</TITLE>
|
||||
<PARA>
|
||||
</title>
|
||||
<para>
|
||||
The call handler for a procedural language must be written
|
||||
in a compiler language such as 'C' and registered with
|
||||
<productname>Postgres</productname> as a function taking
|
||||
no arguments and returning the
|
||||
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.
|
||||
@ -196,7 +190,7 @@ Subsequently, functions and
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</PARA>
|
||||
</para>
|
||||
<para>
|
||||
It's up to the call handler to fetch the
|
||||
<filename>pg_proc</filename> entry and
|
||||
@ -213,14 +207,14 @@ Subsequently, functions and
|
||||
</para>
|
||||
</refsect2>
|
||||
|
||||
<REFSECT2 ID="R2-SQL-CREATELANGUAGE-4">
|
||||
<REFSECT2INFO>
|
||||
<DATE>1998-09-09</DATE>
|
||||
</REFSECT2INFO>
|
||||
<TITLE>
|
||||
<refsect2 id="R2-SQL-CREATELANGUAGE-4">
|
||||
<refsect2info>
|
||||
<date>1998-09-09</date>
|
||||
</refsect2info>
|
||||
<title>
|
||||
Notes
|
||||
</TITLE>
|
||||
<PARA>
|
||||
</title>
|
||||
<para>
|
||||
Use <command>CREATE FUNCTION</command>
|
||||
to create a function.
|
||||
</para>
|
||||
@ -230,8 +224,8 @@ Subsequently, functions and
|
||||
<para>
|
||||
Refer to the table <filename>pg_language</filename>
|
||||
for further information:
|
||||
<programlisting>
|
||||
<computeroutput>
|
||||
<programlisting>
|
||||
<computeroutput>
|
||||
Table = pg_language
|
||||
+--------------------------+--------------------------+-------+
|
||||
| Field | Type | Length|
|
||||
@ -246,130 +240,129 @@ internal|n/a
|
||||
lisp |/usr/ucb/liszt
|
||||
C |/bin/cc
|
||||
sql |postgres
|
||||
</computeroutput>
|
||||
</programlisting>
|
||||
</computeroutput>
|
||||
</programlisting>
|
||||
|
||||
</para>
|
||||
</refsect2>
|
||||
</refsect1>
|
||||
|
||||
<REFSECT1 ID="R1-SQL-CREATELANGUAGE-4">
|
||||
<TITLE>
|
||||
|
||||
<refsect1 id="R1-SQL-CREATELANGUAGE-4">
|
||||
<title>
|
||||
Restrictions
|
||||
</TITLE>
|
||||
<PARA>
|
||||
</title>
|
||||
<para>
|
||||
Since the call handler for a procedural language must be
|
||||
registered with <productname>Postgres</productname> in the 'C' language,
|
||||
it inherits
|
||||
it inherits
|
||||
all the capabilities and restrictions of 'C' functions.
|
||||
</para>
|
||||
</refsect1>
|
||||
<REFSECT1 ID="R1-SQL-CREATELANGUAGE-5">
|
||||
<TITLE>
|
||||
<refsect1 id="R1-SQL-CREATELANGUAGE-5">
|
||||
<title>
|
||||
Bugs
|
||||
</TITLE>
|
||||
<PARA>
|
||||
</title>
|
||||
<para>
|
||||
At present, the definitions for a procedural language cannot be
|
||||
changed once they have been created.
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
<REFSECT1 ID="R1-SQL-CREATELANGUAGE-6">
|
||||
<TITLE>
|
||||
<refsect1 id="R1-SQL-CREATELANGUAGE-6">
|
||||
<title>
|
||||
Usage
|
||||
</TITLE>
|
||||
<PARA>
|
||||
</title>
|
||||
<para>
|
||||
This is a template for a PL handler written in 'C':
|
||||
</PARA>
|
||||
<ProgramListing>
|
||||
#include "executor/spi.h"
|
||||
#include "commands/trigger.h"
|
||||
#include "utils/elog.h"
|
||||
#include "fmgr.h" /* for FmgrValues struct */
|
||||
#include "access/heapam.h"
|
||||
#include "utils/syscache.h"
|
||||
#include "catalog/pg_proc.h"
|
||||
#include "catalog/pg_type.h"
|
||||
|
||||
Datum
|
||||
plsample_call_handler(
|
||||
Oid prooid,
|
||||
int pronargs,
|
||||
FmgrValues *proargs,
|
||||
bool *isNull)
|
||||
{
|
||||
Datum retval;
|
||||
TriggerData *trigdata;
|
||||
<programlisting>
|
||||
#include "executor/spi.h"
|
||||
#include "commands/trigger.h"
|
||||
#include "utils/elog.h"
|
||||
#include "fmgr.h" /* for FmgrValues struct */
|
||||
#include "access/heapam.h"
|
||||
#include "utils/syscache.h"
|
||||
#include "catalog/pg_proc.h"
|
||||
#include "catalog/pg_type.h"
|
||||
|
||||
if (CurrentTriggerData == NULL) {
|
||||
/*
|
||||
* Called as a function
|
||||
*/
|
||||
Datum
|
||||
plsample_call_handler(
|
||||
Oid prooid,
|
||||
int pronargs,
|
||||
FmgrValues *proargs,
|
||||
bool *isNull)
|
||||
{
|
||||
Datum retval;
|
||||
TriggerData *trigdata;
|
||||
|
||||
retval = ...
|
||||
} else {
|
||||
/*
|
||||
* Called as a trigger procedure
|
||||
*/
|
||||
trigdata = CurrentTriggerData;
|
||||
CurrentTriggerData = NULL;
|
||||
if (CurrentTriggerData == NULL) {
|
||||
/*
|
||||
* Called as a function
|
||||
*/
|
||||
|
||||
retval = ...
|
||||
}
|
||||
retval = ...
|
||||
} else {
|
||||
/*
|
||||
* Called as a trigger procedure
|
||||
*/
|
||||
trigdata = CurrentTriggerData;
|
||||
CurrentTriggerData = NULL;
|
||||
|
||||
retval = ...
|
||||
}
|
||||
|
||||
*isNull = false;
|
||||
return retval;
|
||||
}
|
||||
</programlisting>
|
||||
</para>
|
||||
|
||||
*isNull = false;
|
||||
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
|
||||
.</para>
|
||||
See <command>CREATE FUNCTION</command> for information on how to compile
|
||||
it into a loadable module.
|
||||
</para>
|
||||
<para>
|
||||
The following commands then register the sample procedural
|
||||
language:
|
||||
<programlisting>
|
||||
CREATE FUNCTION plsample_call_handler () RETURNS opaque
|
||||
CREATE FUNCTION plsample_call_handler () RETURNS opaque
|
||||
AS '/usr/local/pgsql/lib/plsample.so'
|
||||
LANGUAGE 'C';
|
||||
|
||||
CREATE PROCEDURAL LANGUAGE 'plsample'
|
||||
CREATE PROCEDURAL LANGUAGE 'plsample'
|
||||
HANDLER plsample_call_handler
|
||||
LANCOMPILER 'PL/Sample';
|
||||
</programlisting>
|
||||
</para>
|
||||
</REFSECT1>
|
||||
|
||||
<REFSECT1 ID="R1-SQL-CREATELANGUAGE-7">
|
||||
<TITLE>
|
||||
</refsect1>
|
||||
|
||||
<refsect1 id="R1-SQL-CREATELANGUAGE-7">
|
||||
<title>
|
||||
Compatibility
|
||||
</TITLE>
|
||||
<PARA>
|
||||
</title>
|
||||
<para>
|
||||
CREATE LANGUAGE is a <productname>Postgres</productname> extension.
|
||||
</PARA>
|
||||
|
||||
<REFSECT2 ID="R2-SQL-CREATELANGUAGE-5">
|
||||
<REFSECT2INFO>
|
||||
<DATE>1998-09-09</DATE>
|
||||
</REFSECT2INFO>
|
||||
<TITLE>
|
||||
</para>
|
||||
|
||||
<refsect2 id="R2-SQL-CREATELANGUAGE-5">
|
||||
<refsect2info>
|
||||
<date>1998-09-09</date>
|
||||
</refsect2info>
|
||||
<title>
|
||||
SQL92
|
||||
</TITLE>
|
||||
<PARA>
|
||||
</title>
|
||||
<para>
|
||||
There is no <command>CREATE LANGUAGE</command> statement in
|
||||
<acronym>SQL92</acronym>.
|
||||
</PARA>
|
||||
<acronym>SQL92</acronym>.
|
||||
</para>
|
||||
</refsect2>
|
||||
</refsect1>
|
||||
</REFENTRY>
|
||||
|
||||
</refentry>
|
||||
|
||||
<!-- Keep this comment at the end of the file
|
||||
Local variables:
|
||||
mode: sgml
|
||||
sgml-omittag:t
|
||||
sgml-omittag:nil
|
||||
sgml-shorttag:t
|
||||
sgml-minimize-attributes:nil
|
||||
sgml-always-quote-attributes:t
|
||||
|
||||
Reference in New Issue
Block a user