root/traduc/branches/bv747/manuel/ref/create_language.sgml

<!--
$Header: /var/lib/cvs/pgsql-fr/sgml/ref/create_language.sgml,v 1.6.2.3 2005/07/15 06:33:53 guillaume Exp $
PostgreSQL documentation
-->

<refentry id="SQL-CREATELANGUAGE">
 <refmeta>
  <refentrytitle id="sql-createlanguage-title">CREATE LANGUAGE</refentrytitle>
  <refmiscinfo>SQL - Instructions du langage</refmiscinfo>
 </refmeta>

 <refnamediv>
  <refname>CREATE LANGUAGE</refname>
  <refpurpose>définit un nouveau langage de procédures</refpurpose>
 </refnamediv>

 <indexterm zone="sql-createlanguage">
  <primary>CREATE LANGUAGE</primary>
 </indexterm>

 <refsynopsisdiv>
<synopsis>
CREATE [ TRUSTED ] [ PROCEDURAL ] LANGUAGE <replaceable
class="parameter">nom</replaceable>
    HANDLER <replaceable class="parameter">gestionnaire_appel</replaceable> [
VALIDATOR <replaceable>fonction_validation</replaceable> ]
</synopsis>
 </refsynopsisdiv>

 <refsect1 id="sql-createlanguage-description">
  <title>Description</title>

  <para>
   En utilisant <command>CREATE LANGUAGE</command>, un utilisateur
   <productname>PostgreSQL</productname> peut enregistrer un nouveau langage de
   procédure sur une base de données <productname>PostgreSQL</productname>. En
   conséquence, les fonctions et les procédures de déclencheurs peuvent être
   définies dans ce nouveau langage. L'utilisateur doit avoir les droits de
   superutilisateur de <productname>PostgreSQL</productname> pour enregistrer un
   nouveau langage.
  </para>

  <para>
   <command>CREATE LANGUAGE</command> associe réellement le nom du langage avec
   un gestionnaire d'appels qui est responsable de l'exécution des fonctions
   écrites dans le langage. Référez-vous à <xref linkend="xfunc"> pour plus
   d'informations sur les gestionnaires d'appels.
  </para>

  <para>
   Notez que les langages de procédures sont locaux au niveau des bases de
   données individuelles. Pour rendre disponible un langage dans toutes les
   bases de données par défaut, il devrait être installé dans la base de données
   <literal>template1</literal>.
  </para>
 </refsect1>

 <refsect1 id="sql-createlanguage-parameters">
  <title>Paramètres</title>

   <variablelist>
    <varlistentry>
     <term><literal>TRUSTED</literal></term>

     <listitem>
      <para>
       <literal>TRUSTED</literal> spécifie que le gestionnaire d'appels du
       langage est sûr, c'est-à-dire qu'il n'offre pas de fonctions surpassant
       les restrictions d'accès aux utilisateurs. Si ce mot clé est omis à
       l'enregistrement de ce langage, seuls les utilisateurs disposant du droit
       superutilisateur de <productname>PostgreSQL</productname> peuvent
       utiliser ce langage pour créer de nouvelles fonctions.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><literal>PROCEDURAL</literal></term>

     <listitem>
      <para>
       Aucune influence.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><replaceable class="parameter">nom</replaceable></term>

     <listitem>
      <para>
       Le nom du nouveau langage de procédures. Le nom du langage n'est pas
       sensible à la casse. Le nom doit être unique parmi les langages de la
       base de données.
      </para>

      <para>
       Pour une compatibilité descendante, le nom doit être entouré par des
       guillemets simples.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><literal>HANDLER</literal> <replaceable
       class="parameter">gestionnaire_appel</replaceable></term>

     <listitem>
      <para>
       <replaceable class="parameter">gestionnaire_appels</replaceable> est le
       nom d'une fonction précédemment enregistrée qui sera appelée pour
       exécuter les fonctions du langage de procédures. Le gestionnaire d'appels
       pour un langage de procédures doit être écrit dans un langage compilé
       comme le C avec la convention d'appel version 1 et enregistré sur 
       <productname>PostgreSQL</productname> comme une fonction ne prenant aucun
       argument et retournant le type <type>language_handler</type>, un type
       spécifiquement utilisé pour identifier la fonction comme gestionnaire
       d'appels.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><literal>VALIDATOR</literal> <replaceable
       class="parameter">fonction_validation</replaceable></term>

     <listitem>
      <para>
       <replaceable class="parameter">fonction_validation</replaceable> est le
       nom d'une fonction précédemment enregistrée qui sera appelée lorsqu'une
       nouveau fonction sera créée avec ce langage, pour valider la nouvelle
       fonction. Si aucune fonction de validation n'est spécifiée, alors une
       nouvelle fonction ne sera pas vérifiée à sa création. La fonction de
       validation prend un argument de type <type>oid</type>, qui sera l'OID de
       la fonction à créer, et renverra typiquement <type>void</>.
      </para>

      <para>
       Une fonction de validation inspecterait typiquement le corps de la
       fonction pour s'assurer de la justesse syntaxique mais il regarderait
       aussi d'autres propriétés de la fonction, par exemple si le langage ne
       peut pas gérer certains types d'argument. Pour signaler une erreur, la
       fonction de validation devrait utiliser la fonction
       <function>ereport()</function>. La valeur de retour de la fonction est
       ignorée.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
 </refsect1>

 <refsect1 id="sql-createlanguage-notes">
  <title>Notes</title>

  <para>
   Cette commande ne devrait normalement pas être exécutée directement par les
   utilisateurs. Pour les langages de procédure fournis dans la distribution
   <productname>PostgreSQL</productname>, le programme <xref
   linkend="app-createlang"> devrait être utilisé, qui installera aussi le bon
   gestionnaire d'appels. (<command>createlang</command> appellera
   <command>CREATE LANGUAGE</command> en interne.)
  </para>

  <para>
   Dans les versions de <productname>PostgreSQL</productname> antérieures à la
   7.3, il était nécessaire de déclarer les fonctions du gestionnaire comme
   renvoyant le type <type>opaque</>, plutôt que <type>language_handler</>.
   Pour supporter le chargement des anciens fichiers de sauvegarde,
   <command>CREATE LANGUAGE</> acceptera une fonction déclarée renvoyant le type
   <type>opaque</>, mais affichera un message d'avertissement et modifié le type
   renvoyé par la fonction en <type>language_handler</>.
  </para>

  <para>
   Utilisez la commande <xref linkend="sql-createfunction"
   endterm="sql-createfunction-title"> pour créer une nouvelle fonction.
  </para>

  <para>
   Utilisez <xref linkend="sql-droplanguage" endterm="sql-droplanguage-title">,
   ou encore mieux le programme  <xref linkend="app-droplang">, pour supprimer
   les langages de procédures.
  </para>

  <para>
   Le catalogue système <classname>pg_language</classname> (voir <xref
   linkend="catalog-pg-language">) enregistre des informations sur les langages
   actuellement installés. De plus, <command>createlang</command> a une option
   pour lister les langages installés.
  </para>

  <para>
   La définition d'un langage de procédures ne peut pas être modifiée une fois
   qu'il a été créé, à l'exception des droits.
  </para>

  <para>
   Pour être capable d'utiliser un langage de procédures, un utilisateur doit
   avoir le droit <literal>USAGE</literal>. Le programme
   <command>createlang</command> donne automatiquement les droits à toute
   personne si le langage est « de confiance ».
  </para>
 </refsect1>

 <refsect1 id="sql-createlanguage-examples">
  <title>Exemples</title>

  <para>
   Les deux commandes suivantes exécutées en séquence enregistreront un nouveau
   langage de procédures et le gestionnaire d'appels associé.
<programlisting>
CREATE FUNCTION plsample_call_handler() RETURNS language_handler
    AS '$libdir/plsample'
    LANGUAGE C;
CREATE LANGUAGE plsample
    HANDLER plsample_call_handler;
</programlisting>
  </para>
 </refsect1>

 <refsect1 id="sql-createlanguage-compat">
  <title>Compatibilité</title>

  <para>
   <command>CREATE LANGUAGE</command> est un extension de
   <productname>PostgreSQL</productname>.
  </para>
 </refsect1>

 <refsect1>
  <title>Voir aussi</title>

  <simplelist type="inline">
   <member><xref linkend="sql-alterlanguage" endterm="sql-alterlanguage-title"></member>
   <member><xref linkend="sql-createfunction" endterm="sql-createfunction-title"></member>
   <member><xref linkend="sql-droplanguage" endterm="sql-droplanguage-title"></member>
   <member><xref linkend="sql-grant" endterm="sql-grant-title"></member>
   <member><xref linkend="sql-revoke" endterm="sql-revoke-title"></member>
   <member><xref linkend="app-createlang"></member>
   <member><xref linkend="app-droplang"></member>
  </simplelist>
 </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:
-->