doc/ref-clsql-sys.xml

   1 <?xml version='1.0' ?>
   2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3                "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
   4 <!ENTITY % myents SYSTEM "entities.inc">
   5 %myents;
   6 ]>
   7
   8 <reference id="clsql-sys">
   9   <title><symbol>CLSQL-SYS</symbol></title>
  10   <partintro>
  11       <para>This part gives a reference to the symbols exported from
  12       the package <symbol>CLSQL-SYS</symbol>, which are not exported
  13       from <symbol>CLSQL</symbol> package..  These symbols are part of
  14       the interface for database back-ends, but not part of the normal
  15       user-interface of &clsql;.</para>
  16     </partintro>
  17     <refentry id="database-initialize-database-type">
  18       <refnamediv>
  19         <refname>DATABASE-INITIALIZE-DATABASE-TYPE</refname>
  20         <refpurpose>Back-end part of <link
  21         linkend="initialize-database-type"><function>initialize-database-type</function></link>.</refpurpose>
  22         <refclass>Generic Function</refclass>
  23       </refnamediv>
  24       <refsect1>
  25         <title>Syntax</title>
  26         <synopsis><function>database-initialize-database-type</function> <replaceable>database-type</replaceable> => <returnvalue>result</returnvalue></synopsis>
  27       </refsect1>
  28       <refsect1>
  29         <title>Arguments and Values</title>
  30         <variablelist>
  31           <varlistentry>
  32             <term><parameter>database-type</parameter></term>
  33             <listitem>
  34               <para>A keyword indicating the database type to
  35                 initialize.</para>
  36             </listitem>
  37           </varlistentry>
  38           <varlistentry>
  39             <term><returnvalue>result</returnvalue></term>
  40             <listitem>
  41               <para>Either <symbol>t</symbol> if the initialization
  42                 succeeds or <symbol>nil</symbol> if it fails.</para>
  43             </listitem>
  44           </varlistentry>
  45         </variablelist>
  46       </refsect1>
  47       <refsect1>
  48         <title>Description</title>
  49         <para>This generic function implements the main part of the
  50           database type initialization performed by
  51           <function>initialize-database-type</function>.  After
  52           <function>initialize-database-type</function> has checked
  53           that the given database type has not been initialized
  54           before, as indicated by
  55           <symbol>*initialized-database-types*</symbol>, it will call
  56           this function with the database type as it's sole
  57           parameter.  Database back-ends are required to define a
  58           method on this generic function which is specialized via an
  59           eql-specializer to the keyword representing their database
  60           type.</para>
  61         <para>Database back-ends shall indicate successful
  62           initialization by returning <symbol>t</symbol> from their
  63           method, and <symbol>nil</symbol> otherwise.  Methods for
  64           this generic function are allowed to signal errors of type
  65           <errortype>clsql-error</errortype> or subtypes thereof.
  66           They may also signal other types of conditions, if
  67           appropriate, but have to document this.</para>
  68       </refsect1>
  69       <refsect1>
  70         <title>Examples</title>
  71         <para></para>
  72       </refsect1>
  73       <refsect1>
  74         <title>Side Effects</title>
  75         <para>All necessary side effects to initialize the database
  76           instance.</para>
  77       </refsect1>
  78       <refsect1>
  79         <title>Affected By</title>
  80         <para>None.</para>
  81       </refsect1>
  82       <refsect1>
  83         <title>Exceptional Situations</title>
  84         <para>Conditions of type <errortype>clsql-error</errortype>
  85           or other conditions may be signalled, depending on the
  86           database back-end.</para>
  87       </refsect1>
  88       <refsect1>
  89         <title>See Also</title>
  90         <para>
  91         <simplelist>
  92           <member><link
  93           linkend="initialize-database-type"><function>initialize-database-type</function></link></member>
  94           <member><link linkend="initialized-database-types"><symbol>*initialized-database-types*</symbol></link></member>
  95         </simplelist>
  96         </para>
  97       </refsect1>
  98       <refsect1>
  99         <title>Notes</title>
 100         <para>None.</para>
 101       </refsect1>
 102     </refentry>
 103   </reference>