--- a/doc/sqlscreens.sgml
+++ b/doc/sqlscreens.sgml
@@ -1,8 +1,17 @@
+<!-- Use this header for the FreeBSD sgml toolchain -->
+<!-- NOTE: the sgml version should be saved as ISO-8859-1. -->
<!DOCTYPE BOOK PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [
+
+<!-- Use this header for going XML -->
+<!-- <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ -->
+
<!ENTITY SQLSC "<application>SQLScreens</application>">
+<!ENTITY SQLSCVERSION "1.2.1">
<!ENTITY MYSQL "<application>MySQL</application>">
+<!ENTITY SQLITE "<application>SQLite</application>">
<!ENTITY SQLSCDOWN "http://www.lesbonscomptes.com/sqlscreens/sqlscdownload.html">
-
+<!ENTITY SQLSCRDMPS "http://lesbonscomptes.com/sqlscreens/sqlscdumps.html">
]>
<book lang="en">
<bookinfo>
@@ -20,15 +29,18 @@
<chapter>
<title>Preface</title>
- <para>This document describes &SQLSC; release 1.1.10</para>
+ <para>This document describes &SQLSC; release &SQLSCVERSION;</para>
<para>&SQLSC; is a TCL/TK package allowing the easy creation of
- screen forms, for querying and updating a relational
- database.</para>
-
- <para>&SQLSC; is primarily designed to work with &MYSQL; as a
- backend. It also works with ODBC. It might still work with
- INFORMIX and MSQL (untested for some time).</para>
+ screen forms, for querying and updating a relational
+ database.</para>
+
+ <para>&SQLSC; was primarily designed to work with &MYSQL; as a
+ backend. It also works with &SQLITE;,
+ and <application>ODBC</application>. It might still work
+ with <application>INFORMIX</application>
+ and <application>MSQL</application> (untested for a looong
+ time).</para>
<para>&SQLSC; is no match for commercial application development
tools. It is a very simple tool to create ad-hoc query screens. We
@@ -41,11 +53,11 @@
grant tables, you may find &SQLSC; useful :-)</para>
<para>Still interested ? Details
- <link linkend="sqlsc.preface.quickdescription">follow</link>. If you are
- reading this from the web site, you can have a look at the
- <ulink url="sqlscdumps.html">screen dumps</ulink>.</para>
-
- <sect1 id="sqlsc.preface.quickdescription">
+ <link linkend="PREFACE.QUICKDESCRIPTION">follow</link>. If you are
+ reading this online, you can have a look at the
+ <ulink url="&SQLSCRDMPS;">screen dumps</ulink>.</para>
+
+ <sect1 id="PREFACE.QUICKDESCRIPTION">
<title>Quick description</title>
<para>A typical &SQLSC; application will have a number of
@@ -150,8 +162,10 @@
to improve it.</para>
<para>If you want a quick idea of what it does, do the installation,
- have a look at the tablescreen.tcl file in the samples directory,
- set the host and user name, and point it to any table, like:</para>
+ have a look at the <filename>tablescreen.tcl</filename> file
+ in the samples directory, set the host and user name
+ (depending on the backend type), and point it to any table,
+ like:</para>
<programlisting>
tablescreen.tcl dbname tablename
@@ -163,10 +177,10 @@
</sect1>
</chapter>
- <chapter id="sqlsc.installation">
+ <chapter id="INSTALLATION">
<title>Installation</title>
- <sect1 id="sqlsc.installation.external">
+ <sect1 id="INSTALLATION.EXTERNAL">
<title>External software needed</title>
<para>To use &SQLSC;, you will need a number of external software
@@ -181,7 +195,7 @@
<ulink url="http://tcl.activestate.com/">the main TCL
site</ulink>
- . TCL and TK are very easy to compile.</para>
+ . TCL and TK are very easy to build.</para>
</listitem>
</itemizedlist>
@@ -224,7 +238,7 @@
<listitem>
<para>For INFORMIX you will need the isqltcl package by Srinivas
Kumar. It has become a little difficult to find lately and
- there is a copy on the <ulink url="&SQLSCDOWN">download
+ there is a copy on the <ulink url="&SQLSCDOWN;">download
page</ulink>.</para>
</listitem>
</itemizedlist>
@@ -232,8 +246,9 @@
<para>The &SQLSC; <ulink url="&SQLSCDOWN;">download page</ulink>
has pointers or copies for some of these elements.</para>
- <para>Only the direct &MYSQL; connection has been tested lately,
- and there may be minor problems with the others.</para>
+ <para>Only the direct &MYSQL; and &SQLITE; backends have been
+ tested lately, and there may be minor problems with the
+ others.</para>
</sect1>
@@ -256,39 +271,59 @@
tcl8.../unix; configure; make; make install, same for tk).</para>
<para>The next step is to add database-access capability to the
- standard TCL/TK wish interpreter. This can be done in two ways,
- either by statically linking the database access module (mysqltcl or
- isqltcl) with the interpreter or by using the TCL load facility and
- a shared library. The dynamic version sometimes need some manual
- tweaking to work.</para>
-
- <para>The <filename>Makefile</filename> in the &SQLSC; directory
- only supports &MYSQL; internally. For using
- <application>isqltcl</application> and INFORMIX, follow the
- installation instructions inside the
- <application>isqltcl</application> package to generate the
- interpreter.</para>
-
- <para>For ODBC, you should first install the driver manager, the
- driver(s) you need and the tclodbc TCL extension. Follow the
- instructions in each package.</para>
+ standard TCL/TK wish interpreter. This can be done in several
+ ways:
+ <itemizedlist>
+ <listitem>By statically linking the database access module
+ (e.g. mysqltcl or isqltcl) with the
+ interpreter.</listitem>
+ <listitem>By using the <application>TCL</application> load
+ facility and a shared library. The dynamic version sometimes
+ need some manual tweaking to work.</listitem>
+ <listitem>By loading an external package that itself does
+ whatever is needed (e.g. <literal>package require
+ sqlite3)</literal></listitem>
+ </itemizedlist>
+ </para>
+
+ <para>&MYSQL; support is managed by
+ the <filename>Makefile</filename> in the &SQLSC;
+ directory. You can disable &MYSQL; support (and the need to
+ install the client library) by using
+ option <literal>--disable-mysql</literal> to
+ the <command>configure</command> script.</para>
+
+ <para>For &SQLITE;, just install the &SQLITE; TCL package (which
+ may be named something
+ like <literal>libsqlite3-tcl</literal>).</para>
+
+ <para>For <application>ODBC</application>, you should first
+ install the driver manager, the driver(s) you need and the
+ tclodbc TCL extension. Follow the instructions in each
+ package.</para>
+
+ <para>For using <application>isqltcl</application> and INFORMIX,
+ follow the installation instructions inside
+ the <application>isqltcl</application> package to generate the
+ interpreter.</para>
<sect2>
<title>Generating a wish interpreter with &MYSQL; support:</title>
+ <para>You do not need this if you are working with &SQLITE;
+ only. Just give a <literal>--disable-mysql</literal>
+ argument to <command>configure</command>.</para>
+
<para>Both the static and dynamic load methods are supported by
- the &SQLSC; build tools. Only Linux, SOLARIS,
- and FreeBSD have been tested, things are not guaranteed to work on
- other systems. The Makefile generated by configure is small, it
- should be easy to adjust if needed.</para>
-
- <para>The configuration script only looks for the &MYSQL; library in
- <filename>/usr/local/mysql/lib</filename>,
- <filename>/usr/local/lib/mysql</filename>,
- <filename>/usr/lib/mysql</filename>, and
- <filename>/usr/lib</filename>.
- If your installation is different, please make symbolic
- links or modify the script.</para>
+ the &SQLSC; build tools. Only Linux, SOLARIS,
+ and FreeBSD have been tested, things are not guaranteed to work on
+ other systems. The Makefile generated by configure is small, it
+ should be easy to adjust if needed.</para>
+
+ <para>The configuration script use
+ the <command>mysql_config</command> command to locate the
+ &MYSQL; client library and include files. It should be
+ accessible in your <literal>PATH</literal>.</para>
<para>When you are ready:</para>
@@ -339,26 +374,20 @@
through this already. Have a look at the included
<filename>tkAppinit.c</filename></para>
- <para>Because the dynamic version is sometimes a pain to build,
- the sample scripts are now set up to be executed by
- <command>mysqlwish</command> by
- default (for &MYSQL;). If you managed to get the dynamic version to
- build, you will certainly find it easy to change the first line in
- the scripts...</para>
</sect2>
</sect1>
</chapter>
- <chapter id="sqlsc.using">
+ <chapter id="USING">
<title>Using &SQLSC;</title>
<para>The following is organized more like a reference manual, there
is little tutorial material. You may want to look at the
- <link linkend="sqlsc.samples">sample scripts</link>
+ <link linkend="SAMPLES">sample scripts</link>
to get a quick idea.</para>
- <sect1 id="sqlsc.using.envir">
+ <sect1 id="USING.ENVIR">
<title>Environment variables</title>
<para>The <literal>SQLDBTYPE</literal> environment variable
@@ -369,6 +398,13 @@
<listitem>
<para><literal>MYSQL</literal> to access a &MYSQL; database.</para>
</listitem>
+ <listitem>
+ <para><literal>SQLITE3</literal> to access a &SQLITE; database.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>ODBC</literal> to use an ODBC driver manager.</para>
+ </listitem>
<listitem>
<para><literal>INFORMIX</literal> to access an INFORMIX
@@ -379,9 +415,6 @@
<para><literal>MSQL</literal> to access an MSQL database.</para>
</listitem>
- <listitem>
- <para><literal>ODBC</literal> to use an ODBC driver manager.</para>
- </listitem>
</itemizedlist>
<para>The default if the variable is not set is to use &MYSQL;. Don't
@@ -393,7 +426,7 @@
inside the sample scripts). Of course, the value of this
variable must be consistent with what extensions are available
to the TCL interpreter (See <link
- linkend="sqlsc.installation">installation</link>).</para>
+ linkend="INSTALLATION">installation</link>).</para>
<para>The <literal>SQLSCLOG</literal> environment variable can
be set to the name of a file where &SQLSC; will log the SQL
@@ -461,7 +494,7 @@
<listitem>
<para>inserts the current values. There is special handling
for auto_increment fields, see
- <link linkend="sqlsc.sqlgeneration">SQL generation</link>
+ <link linkend="SQLGENERATION">SQL generation</link>
</para>
</listitem>
</varlistentry>
@@ -472,9 +505,10 @@
<listitem>
<para>updates the row according to the current values (how the
WHERE clause is built is described later, see
- <link linkend="sqlsc.programming.arrayentries.fattributes.updateindex">updateindex</link>
+ <link linkend="PROGRAMMING.ARRAYENTRIES.FATTRIBUTES.UPDATEINDEX">
+ updateindex</link>
and
- <link linkend="sqlsc.sqlgeneration">Sql generation</link>).</para>
+ <link linkend="SQLGENERATION">Sql generation</link>).</para>
</listitem>
</varlistentry>
@@ -493,12 +527,13 @@
screens may be set up only for querying).</para>
<para>Delete is not created by default (See
- <link linkend="sqlsc.programming.arrayentries.sattributes.allowdelete">allowdelete</link>
+ <link linkend="PROGRAMMING.ARRAYENTRIES.SATTRIBUTES.ALLOWDELETE">
+ allowdelete</link>
).</para>
<para>The
- <link linkend="sqlsc.sqlgeneration">SQL generation</link>
+ <link linkend="SQLGENERATION">SQL generation</link>
section describes how the SQL statements are generated for the
different actions.</para>
@@ -588,17 +623,17 @@
will be inserted in the WHERE clause. You could also enter
<literal>>10 AND quantity < 20</literal>, or whatever
condition you need. (See also
- <link linkend="sqlsc.sqlgeneration">the paragraph about SQL
+ <link linkend="SQLGENERATION">the paragraph about SQL
generation</link>
).</para>
</sect1>
</chapter>
- <chapter id="sqlsc.programming">
+ <chapter id="PROGRAMMING">
<title>Programming Interface</title>
- <sect1 id="sqlsc.programming.overview">
+ <sect1 id="PROGRAMMING.OVERVIEW">
<title>Overview</title>
<para>All exchanges between the package and the user application are
@@ -678,7 +713,7 @@
changed once a screen is created).</para>
</sect1>
- <sect1 id="sqlsc.programming.init">
+ <sect1 id="PROGRAMMING.INIT">
<title>Initialization and termination</title>
<sect2>
@@ -686,7 +721,7 @@
<para>To create a screen, you set values inside a TCL array
(See the following section:
- <link linkend="sqlsc.programming.arrayentries">Interface array entries</link>
+ <link linkend="PROGRAMMING.ARRAYENTRIES">Interface array entries</link>
), then perform creation as follows:</para>
@@ -715,7 +750,7 @@
second parameter. If the value is <literal>h</literal>, the
fields will be arranged horizontally instead of
vertically. There are other ways to do this(see
- <link linkend="sqlsc.programming.arrayentries.general.columns">columns</link>),
+ <link linkend="PROGRAMMING.ARRAYENTRIES.GENERAL.COLUMNS">columns</link>),
but it can still be useful in some cases.</para>
</sect2>
@@ -731,11 +766,11 @@
</programlisting>
</sect2>
- <sect2 id="sqlsc.programming.init.font">
+ <sect2 id="PROGRAMMING.INIT.FONT">
<title>Setting fonts for &SQLSC; applications</title>
<para>The font used by the screen can be set by
- <link linkend="sqlsc.programming.arrayentries.sattributes.font">
+ <link linkend="PROGRAMMING.ARRAYENTRIES.SATTRIBUTES.FONT">
setting the <literal>font</literal> array entry</link>. This
will only adjust the font for the specific screen. It may
be more convenient to set the font at the start of the
@@ -764,10 +799,10 @@
- <sect1 id="sqlsc.programming.arrayentries">
+ <sect1 id="PROGRAMMING.ARRAYENTRIES">
<title>Interface array entries</title>
- <sect2 id="sqlsc.programming.arrayentries.general">
+ <sect2 id="PROGRAMMING.ARRAYENTRIES.GENERAL">
<title>General parameters</title>
<sect3>
@@ -835,7 +870,7 @@
tables in one application, but each table will need a separate
screen, and the screen links will be through cascaded queries,
not join clauses - See
- <link linkend="sqlsc.programming.linking">Linking screens</link>
+ <link linkend="PROGRAMMING.LINKING">Linking screens</link>
).</para>
</sect3>
@@ -853,7 +888,7 @@
</programlisting>
</sect3>
- <sect3 id="sqlsc.programming.arrayentries.general.columns">
+ <sect3 id="PROGRAMMING.ARRAYENTRIES.GENERAL.COLUMNS">
<title>columns</title>
<para>This is a list to define the columns that you want
@@ -899,7 +934,7 @@
</sect3>
</sect2>
- <sect2 id="sqlsc.programming.arrayentries.sattributes">
+ <sect2 id="PROGRAMMING.ARRAYENTRIES.SATTRIBUTES">
<title>Screen attributes</title>
<sect3>
@@ -918,7 +953,7 @@
only.</para>
</sect3>
- <sect3 id="sqlsc.programming.arrayentries.sattributes.allowdelete">
+ <sect3 id="PROGRAMMING.ARRAYENTRIES.SATTRIBUTES.ALLOWDELETE">
<title>allowdelete</title>
<para>If this entry is set, and <literal>queryonly</literal>
@@ -926,13 +961,13 @@
created.</para>
</sect3>
- <sect3 id="sqlsc.programming.arrayentries.sattributes.font">
+ <sect3 id="PROGRAMMING.ARRAYENTRIES.SATTRIBUTES.FONT">
<title>font</title>
<para>If this entry is set, the value will be used as a font
definition for the screen elements. Any TK font definition
can be used. There are <link
- linkend="sqlsc.programming.init.font">several other
+ linkend="PROGRAMMING.INIT.FONT">several other
ways</link> to set the application font.</para>
</sect3>
@@ -962,7 +997,7 @@
</sect3>
</sect2>
- <sect2 id="sqlsc.programming.arrayentries.fattributes">
+ <sect2 id="PROGRAMMING.ARRAYENTRIES.FATTRIBUTES">
<title>Field attributes</title>
<sect3>
@@ -1137,7 +1172,7 @@
</sect3>
- <sect3 id="sqlsc.programming.arrayentries.fattributes.updateindex">
+ <sect3 id="PROGRAMMING.ARRAYENTRIES.FATTRIBUTES.UPDATEINDEX">
<title>updateindex</title>
<para>This defines a column name (or a list of column names)
@@ -1165,7 +1200,7 @@
button.</para>
<para>See
- <link linkend="sqlsc.sqlgeneration">Sql generation</link>
+ <link linkend="SQLGENERATION">Sql generation</link>
for a more complete discussion of update row selection.</para>
</sect3>
@@ -1225,7 +1260,7 @@
<para>This capability will only be available if an
<literal>updateindex</literal> list has been defined for the
screen (either implicitely or explicitely), see <link
- linkend="sqlsc.programming.arrayentries.fattributes.updateindex">the
+ linkend="PROGRAMMING.ARRAYENTRIES.FATTRIBUTES.UPDATEINDEX">the
updateindex section</link>. The
<literal>updateindex</literal> columns must be part of
<literal>list_columns</literal>, so that we can uniquely
@@ -1364,7 +1399,7 @@
<para>The package uses these entries to save the database values
when a query is performed. This is used to compute the UPDATE
statements (See the
- <link linkend="sqlsc.sqlgeneration">Sql generation</link>
+ <link linkend="SQLGENERATION">Sql generation</link>
section).</para>
</sect3>
@@ -1391,7 +1426,7 @@
</sect2>
</sect1>
- <sect1 id="sqlsc.programming.linking">
+ <sect1 id="PROGRAMMING.LINKING">
<title>Linking screens</title>
<para>It is possible to link two screens so that a change in one
@@ -1615,7 +1650,7 @@
</sect1>
</chapter>
- <chapter id="sqlsc.sqlgeneration">
+ <chapter id="SQLGENERATION">
<title>SQL generation</title>
<para>Every time the user presses a button like query or update, the
@@ -1991,7 +2026,7 @@
</sect1>
</chapter>
- <chapter id="sqlsc.samples">
+ <chapter id="SAMPLES">
<title>Sample scripts</title>
<para>Three sample scripts are provided with the package (in the