/usr/share/doc/cl-sql/html/connect.html is in cl-sql 6.7.0-1build1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 | <?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>CONNECT</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1" /><link rel="home" href="index.html" title="CLSQL Users' Guide" /><link rel="up" href="ref-connect.html" title="Connection and Initialisation" /><link rel="prev" href="initialized-database-types.html" title="*INITIALIZED-DATABASE-TYPES*" /><link rel="next" href="connected-databases.html" title="CONNECTED-DATABASES" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">CONNECT</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="initialized-database-types.html">Prev</a> </td><th width="60%" align="center">Connection and Initialisation</th><td width="20%" align="right"> <a accesskey="n" href="connected-databases.html">Next</a></td></tr></table><hr /></div><div class="refentry"><a id="connect"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>CONNECT — create a connection to a database.<strong>Function</strong></p></div><div class="refsect1"><a id="idp67998800"></a><h2>Syntax</h2><pre class="synopsis"><code class="function">connect</code> <em class="replaceable"><code>connection-spec</code></em> &key <em class="replaceable"><code>if-exists</code></em> <em class="replaceable"><code>database-type</code></em> <em class="replaceable"><code>pool</code></em> <em class="replaceable"><code>make-default</code></em> => <span class="returnvalue">database</span></pre></div><div class="refsect1"><a id="idp68003504"></a><h2>Arguments and Values</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>connection-spec</code></em></span></dt><dd><p>A SQL backend specific connection specification
supplied as a list or as a string.</p><p>For the MySQL backend, this list includes an
optional associative list of connection options. The
options list is parsed and supplied to the MySQL API
using <code class="function">mysql_options</code> in between the
calls to <code class="function">mysql_init</code>
and <code class="function">mysql_real_connect</code>.</p></dd><dt><span class="term"><em class="parameter"><code>if-exists</code></em></span></dt><dd><p>This indicates the action to take if a connection
to the same database exists already. See below for the
legal values and actions. It defaults to the value of
<span class="symbol">*connect-if-exists*</span>.</p></dd><dt><span class="term"><em class="parameter"><code>database-type</code></em></span></dt><dd><p>A database type specifier, i.e. a keyword.
This defaults to the value of
<span class="symbol">*default-database-type*</span></p></dd><dt><span class="term"><em class="parameter"><code>pool</code></em></span></dt><dd><p>A boolean flag. If <code class="constant">T</code>, acquire connection from a
pool of open connections. If the pool is empty, a new
connection is created. The default is <code class="constant">NIL</code>.
</p></dd><dt><span class="term"><em class="parameter"><code>make-default</code></em></span></dt><dd><p>A boolean flag. If <code class="constant">T</code>,
<span class="symbol">*default-database*</span> is set to the new
connection, otherwise <span class="symbol">*default-database*</span>
is not changed. The default is <code class="constant">T</code>.
</p></dd><dt><span class="term"><span class="returnvalue">database</span></span></dt><dd><p>The database object representing the connection.</p></dd></dl></div></div><div class="refsect1"><a id="idp68024320"></a><h2>Description</h2><p>This function takes a connection specification and
a database type and creates a connection to the database
specified by those. The type and structure of the
connection specification depend on the database type.</p><p>The parameter <em class="parameter"><code>if-exists</code></em> specifies
what to do if a connection to the database specified exists
already, which is checked by calling
<code class="function">find-database</code> on the database name
returned by <code class="function">database-name-from-spec</code>
when called with the <em class="parameter"><code>connection-spec</code></em>
and <em class="parameter"><code>database-type</code></em> parameters. The
possible values of <em class="parameter"><code>if-exists</code></em> are:
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span class="symbol">:new</span></span></dt><dd><p>Go ahead and create a new connection.</p></dd><dt><span class="term"><span class="symbol">:warn-new</span></span></dt><dd><p>This is just like <span class="symbol">:new</span>, but
also signals a warning of type
<span class="errortype">clsql-exists-warning</span>,
indicating the old and newly created
databases.</p></dd><dt><span class="term"><span class="symbol">:error</span></span></dt><dd><p>This will cause <code class="function">connect</code> to
signal a correctable error of type
<span class="errortype">clsql-exists-error</span>. The
user may choose to proceed, either by indicating
that a new connection shall be created, via the
restart <span class="symbol">create-new</span>, or by
indicating that the existing connection shall be
used, via the restart
<span class="symbol">use-old</span>.</p></dd><dt><span class="term"><span class="symbol">:old</span></span></dt><dd><p>This will cause <code class="function">connect</code> to
use an old connection if one exists.</p></dd><dt><span class="term"><span class="symbol">:warn-old</span></span></dt><dd><p>This is just like <span class="symbol">:old</span>, but
also signals a warning of type
<span class="errortype">clsql-exists-warning</span>,
indicating the old database used, via the slots
<span class="symbol">old-db</span> and
<span class="symbol">new-db</span></p></dd></dl></div><p>
</p><p>The database name of the returned database object will
be the same under <code class="function">string=</code> as that which
would be returned by a call to
<code class="function">database-name-from-spec</code> with the given
<em class="parameter"><code>connection-spec</code></em> and
<em class="parameter"><code>database-type</code></em> parameters.</p></div><div class="refsect1"><a id="idp68049696"></a><h2>Examples</h2><pre class="screen">
(database-name-from-spec '("dent" "newesim" "dent" "dent") :mysql)
=> "dent/newesim/dent"
(connect '("dent" "newesim" "dent" "dent") :database-type :mysql)
=> #<CLSQL-MYSQL:MYSQL-DATABASE {48036F6D}>
(database-name *)
=> "dent/newesim/dent"
(connect '("dent" "newesim" "dent" "dent") :database-type :mysql)
>> In call to CONNECT:
>> There is an existing connection #<CLSQL-MYSQL:MYSQL-DATABASE {48036F6D}> to database dent/newesim/dent.
>>
>> Restarts:
>> 0: [CREATE-NEW] Create a new connection.
>> 1: [USE-OLD ] Use the existing connection.
>> 2: [ABORT ] Return to Top-Level.
>>
>> Debug (type H for help)
>>
>> (CONNECT ("dent" "newesim" "dent" "dent") :IF-EXISTS NIL :DATABASE-TYPE ...)
>> Source:
>> ; File: /prj/CLSQL/sql/sql.cl
>> (RESTART-CASE (ERROR 'CLSQL-EXISTS-ERROR :OLD-DB OLD-DB)
>> (CREATE-NEW NIL :REPORT "Create a new connection."
>> (SETQ RESULT #))
>> (USE-OLD NIL :REPORT "Use the existing connection."
>> (SETQ RESULT OLD-DB)))
>> 0] 0
=> #<CLSQL-MYSQL:MYSQL-DATABASE {480451F5}>
</pre></div><div class="refsect1"><a id="idp68052384"></a><h2>Side Effects</h2><p>A database connection is established, and the resultant
database object is registered, so as to appear in the list
returned by <code class="function">connected-databases</code>.
<span class="symbol">*default-database*</span> may be rebound to the
created object.</p></div><div class="refsect1"><a id="idp68055024"></a><h2>Affected by</h2><p>
</p><table border="0" summary="Simple list" class="simplelist"><tr><td>
<a class="link" href="default-database-type.html" title="*DEFAULT-DATABASE-TYPE*">
<span class="symbol">*default-database-type*</span>
</a>
</td></tr><tr><td>
<a class="link" href="connect-if-exists.html" title="*CONNECT-IF-EXISTS*">
<span class="symbol">*connect-if-exists*</span>
</a>
</td></tr></table><p>
</p></div><div class="refsect1"><a id="idp68060320"></a><h2>Exceptional Situations</h2><p>If the connection specification is not syntactically or
semantically correct for the given database type, an error of
type <span class="errortype">sql-user-error</span> is
signalled. If during the connection attempt an error is
detected (e.g. because of permission problems, network trouble
or any other cause), an error of type
<span class="errortype">sql-database-error</span> is signalled.</p><p>If a connection to the database specified by
<em class="parameter"><code>connection-spec</code></em> exists already,
conditions are signalled according to the
<em class="parameter"><code>if-exists</code></em> parameter, as described
above.</p></div><div class="refsect1"><a id="idp68064736"></a><h2>See Also</h2><table border="0" summary="Simple list" class="simplelist"><tr><td><a class="link" href="connected-databases.html" title="CONNECTED-DATABASES"><code class="function">connected-databases</code></a></td></tr><tr><td><a class="link" href="disconnect.html" title="DISCONNECT"><code class="function">disconnect</code></a></td></tr><tr><td><a class="link" href="reconnect.html" title="RECONNECT"><code class="function">reconnect</code></a></td></tr><tr><td><a class="link" href="connect-if-exists.html" title="*CONNECT-IF-EXISTS*"><code class="function">*connect-if-exists*</code></a></td></tr><tr><td><a class="link" href="find-database.html" title="FIND-DATABASE"><code class="function">find-database</code></a></td></tr><tr><td><a class="link" href="status.html" title="STATUS"><code class="function">status</code></a></td></tr></table></div><div class="refsect1"><a id="idp68073840"></a><h2>Notes</h2><p>The <em class="parameter"><code>pool</code></em> and
<em class="parameter"><code>make-default</code></em> keyword arguments to
<code class="function">connect</code> are <span class="application"><span class="emphasis"><em>CLSQL</em></span></span> extensions.</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="initialized-database-types.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ref-connect.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="connected-databases.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">*INITIALIZED-DATABASE-TYPES* </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> CONNECTED-DATABASES</td></tr></table></div></body></html>
|