Check in hsqldb 2.0.0
My changes:
- Copied docs/hypersonic_lic.txt to LICENSE.TXT
- Created Android.mk
Change-Id: Ib323babdd1057944aa65eaa4e86e89331931b550
diff --git a/Android.mk b/Android.mk
new file mode 100644
index 0000000..e749b5e
--- /dev/null
+++ b/Android.mk
@@ -0,0 +1,25 @@
+# Copyright (C) 2010 The Android Open Source Project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+LOCAL_PATH := $(call my-dir)
+
+include $(CLEAR_VARS)
+
+LOCAL_MODULE := hsqldb-2.0.0
+LOCAL_MODULE_TAGS := optional
+LOCAL_IS_HOST_MODULE := true
+LOCAL_PREBUILT_STATIC_JAVA_LIBRARIES := hsqldb-2.0.0:lib/hsqldb.jar
+
+include $(BUILD_MULTI_PREBUILT)
+
diff --git a/LICENSE.TXT b/LICENSE.TXT
new file mode 100644
index 0000000..1e674ea
--- /dev/null
+++ b/LICENSE.TXT
@@ -0,0 +1,70 @@
+/*
+ * For work developed by the HSQL Development Group:
+ *
+ * Copyright (c) 2001-2010, The HSQL Development Group
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * Redistributions of source code must retain the above copyright notice, this
+ * list of conditions and the following disclaimer.
+ *
+ * Redistributions in binary form must reproduce the above copyright notice,
+ * this list of conditions and the following disclaimer in the documentation
+ * and/or other materials provided with the distribution.
+ *
+ * Neither the name of the HSQL Development Group nor the names of its
+ * contributors may be used to endorse or promote products derived from this
+ * software without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL HSQL DEVELOPMENT GROUP, HSQLDB.ORG,
+ * OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+ * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+ * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+ * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ *
+ *
+ *
+ * For work originally developed by the Hypersonic SQL Group:
+ *
+ * Copyright (c) 1995-2000, The Hypersonic SQL Group.
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * Redistributions of source code must retain the above copyright notice, this
+ * list of conditions and the following disclaimer.
+ *
+ * Redistributions in binary form must reproduce the above copyright notice,
+ * this list of conditions and the following disclaimer in the documentation
+ * and/or other materials provided with the distribution.
+ *
+ * Neither the name of the Hypersonic SQL Group nor the names of its
+ * contributors may be used to endorse or promote products derived from this
+ * software without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE HYPERSONIC SQL GROUP,
+ * OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+ * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+ * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+ * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ *
+ * This software consists of voluntary contributions made by many individuals
+ * on behalf of the Hypersonic SQL Group.
+ */
+
+
diff --git a/bin/localhost_clientserver.html b/bin/localhost_clientserver.html
new file mode 100644
index 0000000..4168202
--- /dev/null
+++ b/bin/localhost_clientserver.html
@@ -0,0 +1,33 @@
+<html>
+<head><title>HSQL Database Engine</title></head>
+<body bgcolor=#FFFFFF>
+<h2>HSQL Database Engine Client/Server Demo</h2>
+<applet code="org.hsqldb.util.QueryTool" archive="hsqldb.jar" width="460" height="400" codebase="../lib/">
+<param name="database" value="http://localhost">
+</applet>
+
+<h3>Client/server version</h3>
+Currently, the applet is configured to connect to 'http://localhost',
+but this can be changed in the source code of this HTML page:
+The applet parameter 'database' is the path where the applet connects to.
+Close the database and stop the WebServer using the 'SHUTDOWN' command.
+<p>
+<h2>If it does not work</h2>
+On some browsers (Netscape 4.6?), the version compiled for
+JDK 1.2 does not work. In the Java Console (Communicator
+/ Extras / Java Console) you will get something like:
+<p>
+# Verifier error org/hsqldb/jdbcConnection.getTypeMap()Ljava/util/Map
+<p>
+This means the class java.util.Map was not found. In JDK 1.1,
+this class does not exist. When compiled for 1.2, there is
+a reference this class required to conform the JDBC 2.0 interface.
+This class itself is never used, but the reference is required anyway.
+It looks like most verifiers have no problem with this, but some
+have.
+<p>
+The (only) solution for this problem is to recompile (at least the
+client part) for JDK 1.1. You will need to install JDK 1.1 before
+you can do this, then see:
+<p><a href="doc/hsqlBuild.html">Build / How to switch to JDK 1.1</a>
+</body></html>
diff --git a/bin/memorydbmanager.html b/bin/memorydbmanager.html
new file mode 100644
index 0000000..ea688dd
--- /dev/null
+++ b/bin/memorydbmanager.html
@@ -0,0 +1,28 @@
+<html>
+<head><title>HSQL Database Engine</title></head>
+<body bgcolor=#FFFFFF>
+<h2>In-Memory Applet: Database Manager</h2>
+<applet code="org.hsqldb.util.DatabaseManager" archive="hsqldb.jar" width="0" height="0" codebase="../lib/">
+<param name="database" value=".">
+</applet>
+<p>
+In this demo, all data is kept in memory.<br>
+The data will be lost if the program is closed.<br>
+The Database Manager and the database are running<br>
+inside the internet browser.
+<p>
+<h2>If it does not work</h2>
+On some browsers (Netscape 4.6?), the version compiled for
+JDK 1.2 does not work. In the Java Console (Communicator
+/ Extras / Java Console) you will get something like:
+<p>
+# Verifier error org/hsqldb/jdbcConnection.getTypeMap()Ljava/util/Map
+<p> This means the class java.util.Map was not found. In JDK 1.1, this class does
+ not exist. When compiled for 1.2, there is a reference to this class required
+ to conform to the JDBC 2.0 interface. This class itself is never used, but the
+ reference is required anyway. It looks like most verifiers have no problem with
+ this, but some have.
+<p> The solution for this problem is to recompile (at least the client part) for
+ JDK 1.1. You will need to install JDK 1.1 before you can do this, then see:
+<p><a href="doc/hsqlBuild.html">Build / How to switch to JDK 1.1</a>
+</body></html>
diff --git a/bin/memoryquery.html b/bin/memoryquery.html
new file mode 100644
index 0000000..d478953
--- /dev/null
+++ b/bin/memoryquery.html
@@ -0,0 +1,29 @@
+<html>
+<head><title>HSQL Database Engine</title></head>
+<body bgcolor=#FFFFFF>
+<h2>In-Memory Applet: QueryTool</h2>
+<applet code="org.hsqldb.util.QueryTool" archive="hsqldb.jar" width="460" height="400" codebase="../lib/">
+<param name="database" value=".">
+</applet>
+<p>
+<h2>Description</h2>
+In this demo, all data is kept in memory.<br>
+The data will be lost if the program is closed.<br>
+The QueryTool and the database are running<br>
+inside the internet browser.
+<p>
+<h2>If it does not work</h2>
+On some browsers (Netscape 4.6?), the version compiled for
+JDK 1.2 does not work. In the Java Console (Communicator
+/ Extras / Java Console) you will get something like:
+<p>
+# Verifier error org/hsqldb/jdbcConnection.getTypeMap()Ljava/util/Map
+<p> This means the class java.util.Map was not found. In JDK 1.1, this class does
+ not exist. When compiled for 1.2, there is a reference to this class required
+ to conform to the JDBC 2.0 interface. This class itself is never used, but the
+ reference is required anyway. It looks like most verifiers have no problems
+ with this, but some have.
+<p> The solution for this problem is to recompile (at least the client part) for
+ JDK 1.1. You will need to install JDK 1.1 before you can do this, then see:
+<p><a href="doc/hsqlBuild.html">Build / How to switch to JDK 1.1</a>
+</body></html>
diff --git a/bin/runManager.bat b/bin/runManager.bat
new file mode 100755
index 0000000..d5d9a6c
--- /dev/null
+++ b/bin/runManager.bat
@@ -0,0 +1,2 @@
+cd ..\data
+@java -classpath ..\lib\hsqldb.jar org.hsqldb.util.DatabaseManager %1 %2 %3 %4 %5 %6 %7 %8 %9
diff --git a/bin/runManagerSwing.bat b/bin/runManagerSwing.bat
new file mode 100755
index 0000000..e79590b
--- /dev/null
+++ b/bin/runManagerSwing.bat
@@ -0,0 +1,2 @@
+cd ..\data
+@java -classpath ..\lib\hsqldb.jar org.hsqldb.util.DatabaseManagerSwing %1 %2 %3 %4 %5 %6 %7 %8 %9
diff --git a/bin/runServer.bat b/bin/runServer.bat
new file mode 100755
index 0000000..9a83ea3
--- /dev/null
+++ b/bin/runServer.bat
@@ -0,0 +1,2 @@
+cd ..\data
+@java -classpath ../lib/hsqldb.jar org.hsqldb.server.Server %1 %2 %3 %4 %5 %6 %7 %8 %9
diff --git a/bin/runUtil.bat b/bin/runUtil.bat
new file mode 100755
index 0000000..be87297
--- /dev/null
+++ b/bin/runUtil.bat
@@ -0,0 +1,2 @@
+cd ..\data
+@java -classpath ..\lib\hsqldb.jar org.hsqldb.util.%1 %2 %3 %4 %5 %6 %7 %8 %9
diff --git a/bin/runWebServer.bat b/bin/runWebServer.bat
new file mode 100755
index 0000000..211bfd7
--- /dev/null
+++ b/bin/runWebServer.bat
@@ -0,0 +1,2 @@
+cd ..\data
+@java -classpath ..\lib\hsqldb.jar org.hsqldb.WebServer %1 %2 %3 %4 %5 %6 %7 %8 %9
diff --git a/bin/servletdemo.html b/bin/servletdemo.html
new file mode 100644
index 0000000..4519832
--- /dev/null
+++ b/bin/servletdemo.html
@@ -0,0 +1,32 @@
+<html>
+<head><title>HSQL Database Engine</title></head>
+<body bgcolor=#FFFFFF>
+<h2>HSQL Database Engine Servlet Demo</h2>
+<applet code="org.hsqldb.util.QueryTool" archive="hsqldb.jar" width="460" height="400" codebase="../lib/">
+<param name="database" value="http://localhost:8080/examples/servlet/hsqlServlet">
+</applet>
+<p>
+In this demo, the DatabaseManager uses the Servlet to access the database. The QueryTool is running inside
+the internet browser as an Applet.
+<p>
+<h2>If it does not work</h2>
+<p>This demo requires a servlet engine to be running and listening to port 8080. The hsqlServlet.java servlet should be installed on the servlet engine in the /examples/servlet/ directory.</p>
+<p>On some browsers (Netscape 4.6?), the version compiled for
+JDK 1.2 does not work. In the Java Console (Communicator
+/ Extras / Java Console) you will get something like:
+</p>
+<p>
+# Verifier error org/hsqldb/jdbcConnection.getTypeMap()Ljava/util/Map
+<p>
+This means the class java.util.Map was not found. In JDK 1.1,
+this class does not exist. When compiled for 1.2, there is
+a reference this class required to conform the JDBC 2.0 interface.
+This class itself is never used, but the reference is required anyway.
+It looks like most verifiers have no problem with this, but some
+have.
+<p>
+The (only) solution for this problem is to recompile (at least the
+client part) for JDK 1.1. You will need to install JDK 1.1 before
+you can do this, then see:
+<p><a href="../doc/build.html">Build / How to switch to JDK 1.1</a>
+</body></html>
diff --git a/build/build-dist.xml b/build/build-dist.xml
new file mode 100644
index 0000000..6fa60c1
--- /dev/null
+++ b/build/build-dist.xml
@@ -0,0 +1,209 @@
+<?xml version="1.0"?>
+<project name="hsqldb-dist" default="dist" basedir="..">
+<!--
+$Id: build-dist.xml 3550 2010-03-19 17:45:16Z unsaved $
+-->
+
+<!--
+ This build file is separate from the main build.xml file specifically
+ because it is not intended for normal end-user or developer usage.
+ It is only for generating full distributable packages of the app.
+ This build file is NOT necessary to build a distributable jar file:
+ that is the purpose of several targets in the main build file.
+
+ PREP: Before building a public distribution, you must:
+ 1: Update property 'hsqldb.version' in file 'build.xml'.
+ 2: Execute target 'refresh-verbatim' to update code in our docs.
+ 3: Execute target 'update-readme' to substitute updated variables into
+ some doc file(s).
+ 4: Commit all of the work above.
+ 5: Verify that docs build successfully.
+ 6. Make a release tag.
+
+ USAGE:
+ 1: Set up your desired build environment (Ant in search path,
+ JAVA_HOME set, etc.).
+ 2: Do a Subversion export with the release tag to a NEW directory
+ 3: If you don't have a .properties file set up for this purpose
+ already, then make one outside of this work area (so you can
+ archive it and/or re-use it for future distribution builds).
+ IMPORTANT QUIRK: This file may not use ${} properties in values,
+ since that feature is incompatible with the "-propertyfile"
+ switch that we will use below.
+ This file must set Ant properties "build.label", "build.vendor",
+ "dbimage.path". (See following section about optional properties).
+ 4: Run
+ ant -propertyfile path/to/file.properties -f build-dist.xml
+ from the build directory.
+ If you don't have Ivy in your CLASSPATH, you will be instructed
+ how to satisfy that requirement.
+
+ OPTIONAL ANT PROPERTIS
+ To prevent Internet access for DocBook resources, set properties
+ nsstylebase.url, dbxirng.url, dbcentx.url in file
+ "local-docbook.properties" or "build.properties" (just depends on
+ whether you want to manage them separately from the primary
+ properties). This decreases document build time by about 70%.
+ These values point to DocBook-privided resources that you should
+ be able to figure out between the property name and the usage of
+ them in the "build-docbook.xml" file.
+ Add settings for build.debug and build.optimize to change the default
+ compilation settings.
+
+ You could just put these settings into "build.properties", drop the
+ "-propertyfile" switch, and things would work correctly. However, you are
+ advised to use a .properties file external to your export directory for
+ retension purposes.
+
+ You may add or edit some files without them being added to the
+ distribution that you build: build/build.properties,
+ build/local*.properties, tmp/*, classes/*, dist/*.
+ (But, as just noted, you are advised against making
+ "build/build.properties").
+ If you don't know if something will have an effect on the distribution
+ you are building, then *don't do it*.
+ If you were to add a "todo.txt" file to the main or build directory;
+ or run "ant hsqldbtest", artifacts would be added to the distro.
+ -->
+
+ <import file="build.xml"/>
+
+ <target name="state-check"
+ description="Verifies that the current directory + Ant build env. are acceptable for building a distribution">
+ <available property="_svn.exists" file=".svn"/>
+ <fail if="_svn.exists"
+ message="You need to 'export' the project to build distro"/>
+
+ <condition property="_label.ok">
+ <equals arg1="${hsqldb.version}" arg2="${build.label}"/>
+ </condition>
+ <fail unless="_label.ok">Ant properties 'build.label' and 'hsqldb.version' must be equal.
+I suggest setting the value(s) in an external properties file and using the Ant
+"-propertyfile" switch.</fail>
+ <condition property="_vendor.ok">
+ <equals arg1="${hsqldb.vendor}" arg2="${build.vendor}"/>
+ </condition>
+ <fail unless="_vendor.ok">Ant properties 'build.vendor' and 'hsqldb.vendor' must be equal.
+I suggest setting the value(s) in an external properties file and using the Ant
+"-propertyfile" switch.</fail>
+
+ <copy file="doc-src/readme-template.txt" tofile="tmp/readme-generated.txt"
+ overwrite="true">
+ <filterchain>
+ <expandproperties/>
+ <tokenfilter>
+ <!-- Intention is to strip out all RCS keywords, since their values
+ would cause false positives for our file comparison below. -->
+ <replaceregex pattern="\$[A-Z][a-z]+: .+? \$" flags="g"/>
+ </tokenfilter>
+ </filterchain>
+ </copy>
+ <copy file="readme.txt" tofile="tmp/readme-svn.txt" overwrite="true">
+ <filterchain>
+ <tokenfilter>
+ <!-- Intention is to strip out all RCS keywords, since their values
+ would cause false positives for our file comparison below. -->
+ <replaceregex pattern="\$[A-Z][a-z]+: .+? \$" flags="g"/>
+ </tokenfilter>
+ </filterchain>
+ </copy>
+ <condition property="_readme.ok">
+ <filesmatch textfile="true"
+ file1="tmp/readme-svn.txt" file2="tmp/readme-generated.txt"/>
+ </condition>
+ <fail unless="_readme.ok">The 'readme.txt' file in your Subversion export contains the wrong product
+version. You should verify this. If the version is indeed wrong, you should
+abort this export, commit an updated 'readme.txt' from a work area, then retag
+and re-export.</fail>
+ </target>
+
+ <target name="dist"
+ depends="state-check, clean-all, javadoc, gen-docs, hsqldb, sqltool"
+ description="Build joint binary + source distribution packages">
+ <mkdir dir="dist"/>
+ <property name="app.basedir" value="hsqldb-${hsqldb.version}"/>
+
+ <!-- Enforce platform-independent EOL policies on items that will be
+ packed. Generated docs and everything under classes/ already
+ have EOLs enforced.
+ To make maintenance easier, please order by srcdir, and put that
+ attribute first. Much easier to find what you are interested this
+ way.
+ -->
+ <fixcrlf srcdir="."
+ preservelastmodified='true' eol="crlf" includes="*.txt"/>
+ <fixcrlf srcdir="." preservelastmodified='true' eol="lf" includes="*.html"/>
+ <fixcrlf srcdir="bin" preservelastmodified='true' eol="crlf"
+ includes="**/*.txt, **/*.bat, **/*.cmd"/>
+ <fixcrlf srcdir="bin" preservelastmodified='true' eol="lf"
+ encoding="UTF-8" includes="**/*.sh, **/*.bash, **/*.html"/>
+ <fixcrlf srcdir="build" preservelastmodified='true' eol="crlf"
+ includes="**/*.txt, **/*.bat, **/*.cmd"/>
+ <fixcrlf srcdir="build" preservelastmodified='true' eol="lf"
+ encoding="ISO-8859-1" includes="**/*.properties"/>
+ <fixcrlf srcdir="build" preservelastmodified='true' eol="lf"
+ encoding="UTF-8" includes="**/*.xml, **/*.list"/>
+ <!-- Docbook or XSLT adds s on Windows. Remove them. -->
+ <replace dir="doc" includes="*/*.html" token="&#13;"/>
+ <fixcrlf srcdir="doc-src" preservelastmodified='true' eol="lf"
+ encoding="ISO-8859-1" includes="**/*.properties"/>
+ <fixcrlf srcdir="doc-src" preservelastmodified='true' eol="crlf"
+ includes="**/*.txt"/>
+ <fixcrlf srcdir="doc-src" preservelastmodified='true' eol="lf"
+ encoding="UTF-8"
+ includes="**/*.cfg, **/*.css, **/*.ent, **/*.java, **/*.rc,
+ **/*.sql, **/*.xml, **/*.html"/>
+ <fixcrlf srcdir="sample" preservelastmodified='true' eol="lf"
+ encoding="UTF-8" excludes="**/*.txt, **/*.properties"/>
+ <fixcrlf srcdir="sample" preservelastmodified='true' eol="crlf"
+ includes="**/*.txt"/>
+ <fixcrlf srcdir="sample" preservelastmodified='true' eol="lf"
+ encoding="ISO-8859-1" includes="**/*.properties"/>
+ <fixcrlf srcdir="src"
+ preservelastmodified='true' eol="lf" encoding="ISO-8859-1"
+ includes="**/*.properties, **/*.text"/>
+ <fixcrlf srcdir="src" preservelastmodified='true' eol="lf" encoding="UTF-8"
+ includes="**/*.flex, **/*.html, **/*.java"/>
+ <fixcrlf srcdir="stylesheets" preservelastmodified='true' eol="lf"
+ encoding="UTF-8"/>
+ <!-- Exclusing test-src from distros, for now
+ <fixcrlf srcdir="test-src"
+ preservelastmodified='true' eol="lf" encoding="ISO-8859-1"
+ includes="**/*.properties"/>
+ <fixcrlf srcdir="test-src" preservelastmodified='true' eol="lf"
+ encoding="UTF-8"
+ includes="**/*.java, **/*.dtd, **/*.ent, **/*.exp, **/*.inc,
+ **/*.sql, **/*.src, **/*.xml"/>
+ -->
+
+ <fixcrlf srcdir="testrun" preservelastmodified='true' eol="lf"
+ encoding="UTF-8" includes="**/*.bash"/>
+ <fixcrlf srcdir="testrun" preservelastmodified='true' eol="crlf"
+ includes="**/*.txt"/>
+ <!-- NOTE: The file testrun/hsqldb/TestSelf.txt has something in it that
+ causes any Ant filter (on UNIX) to corrupt an umlauted character.
+ The problem is not with the umlauted character, but is the side-effect
+ of something else in the file. I can pull the umlauted "Zürich"
+ string out of that file and put it into its own UTF-8 file, and Ant
+ can filter that just fine. -->
+ <fixcrlf srcdir="testrun"
+ preservelastmodified='true' eol="lf" encoding="UTF-8"
+ includes="**/*.sql, **/*.dsv, **/*.isql, **/*.nsql, **/*.inter"/>
+
+ <mkdir dir="data"/>
+ <zip destfile="dist/${app.basedir}.zip">
+ <zipfileset prefix="${app.basedir}/hsqldb" dir="."
+ includes="**/*.cmd, **/*.bat, **/*.bash, **/*.sh, **/*.pl,
+ **/*.php, **/*.init, **/*.py"
+ filemode="0755"
+ excludes="**/.*, build/local**, test-src/**
+ classes/**, dist/**, local*/**, tmp/**"/>
+ <zipfileset prefix="${app.basedir}/hsqldb" dir="."
+ excludes="**/.*, **/*.cmd, **/*.bat, **/*.bash, **/*.sh,
+ test-src/**, **/*.pl, **/*.php, **/*.init, **/*.py
+ build/build.properties, build/local**, build/ivysettings.xml,
+ classes/**, dist/**, local*/**, tmp/**, doc-src/images/db/**,
+ build/ivysettings.xml, stylesheets/rng-catalog.xml"/>
+ </zip>
+ </target>
+</project>
diff --git a/build/build-docbook.xml b/build/build-docbook.xml
new file mode 100644
index 0000000..af84396
--- /dev/null
+++ b/build/build-docbook.xml
@@ -0,0 +1,483 @@
+<?xml version="1.0"?>
+<project name="hsqldb-ant-docbook" default="gen-docs"
+ xmlns:ivy="antlib:org.apache.ivy.ant">
+ <!--
+ USAGE
+ Purpose of this build file is to generate Whole HTML, Chunked HTML,
+ and PDF DocBook output documents from DocBook source located under a
+ doc-src subdirectory.
+
+ Must have Ivy v. 2.0 or later in Ant invocation CLASSPATH.
+ We suggest that you change-control a copy if the Ivy jar file in
+ the bootstrap-libs subdirectory, so things will work according to the
+ displayed message below (search below for "bootstrap-libs").
+
+ Normally you will "import" this file into your main Ant build file like
+ <import file="build-docbook.xml"/>
+ or, you can invoke targets in this file directly like
+ ant -f build-docbook.xml...
+
+ OVERRIDING Ant properties used in this file:
+ See inline instructions below for properties that you want to effect
+ only this build file.
+ For more general changes (say you want "javac.debug" to effect your own
+ build file as well as this one), set them however you want in your
+ parent Ant build file (perhaps by loading a "build.properties" or
+ "local.properties" file).
+ -->
+
+ <!-- Since the main HSQLDB build file imports this one, relative property
+ file specifications must be relative to the project root, not build/ -->
+
+ <!-- Put local env property changes in this NON-CHANGE-CONTROLLED file: -->
+ <property file="build/local-docbook.properties"/>
+ <!-- For change-controlled (by your project) ant-docbook-specific props: -->
+ <property file="build/docbook.properties"/>
+
+ <property name="oasis.stylesheet.url"
+ value="http://docbook.sourceforge.net/release/xsl-ns/current"/>
+ <!-- IMPORTANT: This value must exactly match the network href values in
+ our *.xsl files! -->
+
+ <!-- See
+ http://xml.apache.org/commons/components/resolver/resolver-article.html#ctrlresolver
+ about these xml.catalog.* settings for the Xml Commons resolver.
+ The docs say to use values yes/no for booleans, instead of true/false.
+ -->
+ <property name="xml.catalog.verbosity" value="0"/>
+ <!-- BEWARE: The verbosity setting seems to not work for some combination
+ of settings. Haven't figured out what combo, but setting it to 10 has no
+ effect for our particular setup. -->
+ <property name="xml.catalog.files"
+ value="${basedir}/stylesheets/rng-catalog.xml"/>
+ <property name="xml.catalog.prefer" value="public"/>
+ <property name="xml.catalog.allowPI" value="yes"/>
+ <property name="xml.catalog.staticCatalog" value="yes"/>
+ <property name="ivy.dep.file" value="build/ivy.xml"/>
+ <property name="distro.baseurl" value="http://hsqldb.org/doc/2.0"/>
+
+ <property name="docoutput.path" value="doc"/>
+ <property name="javac.debug" value="true"/>
+ <property name="java.threadstacksize" value="1M"/>
+ <!-- TODO: Once our repository is set up, change the repos.url value here -->
+ <property name="repos.url" value="http://pub.admc.com/lib-repos"/>
+ <property name="dbxirng.url"
+ value="http://www.docbook.org/xml/5.0/rng/docbook.rng"/>
+ <!-- The "xi" variant supports Xinclude -->
+ <property name="html.path" value="stylesheets/html.xsl"/>
+ <property name="chunk.path" value="stylesheets/chunk.xsl"/>
+ <property name="fo.path" value="stylesheets/fo.xsl"/>
+ <!-- Set nsstylebase.url, in your .properties file, to your local filesystem
+ or local http server location for the DocBok style sheets.
+ That makes the XSLT transformations execute much faster than when
+ pulling the sheets from OASIS Internet site.
+ Example transform. times: 34 s. vs. 1:49.
+ -->
+ <property name="nsstylebase.url" value="UNSET_STYLEBASE"/>
+ <!-- Without setting a default value, some error messages could contain the
+ misleading string "${nsstylebase.url}" in cases where user does not set a
+ value and resolution fails (not that there will be a resolution failure,
+ since this setting is optional). -->
+ <property name="dbcentx.url" value="UNSET_STYLEBASE"/>
+ <!-- ditto about the default value -->
+
+ <target name="fetch-images"
+ description="Fetch stock DocBook image files from Internet">
+ <echo>Copy the images directory from the latest stable version of the
+docbook-xsl-ns package to
+'${basedir}/doc-src/images/db'. docbook-xsl-ns is
+available for download from the DocBook project at
+http://sourceforge.net/packages/docbook.
+We'll do this automatically for you once Ant has a task to transfer
+entire directories of files.</echo>
+ </target>
+
+ <target name="regen-docs"
+ description="Clean and regen project DocBook docs. N.b this wipes javadocs too!"
+ depends="clean-docs, gen-docs"/>
+
+ <property name="_for.automation.blurb"
+ value="If you want to automate the antcalls and you don't mind using
+Ant-contrib or Antelope, you can use one of their 'for' tasks with a DirSet."/>
+
+ <target name="gen-docs">
+ <fail>You must implement your own "gen-docs" target by editing
+"build-docbook.xml" or overriding it in your own build file which imports
+"build-docbook.xml".
+Your "gen-docs" target must depend on -gen-docs-setup, do an "antcall" of
+"docbook-transform" for each doc.name, then call -gen-docs-complete.
+
+${_for.automation.blurb}</fail>
+ </target>
+
+ <target name="validate-docs">
+ <fail>You must implement your own "validate-docs" target
+by editing "build-docbook.xml" or overriding it in your own build file which
+imports "build-docbook.xml".
+Your "validate-docs" target must do an "antcall" of "validate-doc" for each
+doc.name.
+
+${_for.automation.blurb}</fail>
+ </target>
+
+ <target name="-gen-docs-setup" depends="refresh-verbatim"/>
+
+ <target name="-gen-docs-complete">
+ <!-- This is the highest-maintenance target of this build file.
+ Must update the copy and fixcrlf filesets to copy exactly what
+ needs to go to doc output branch, and enforce EOLs in all text files.
+ The dependsets elsewhere in this file use targetfilesets, not
+ targetfilelists, so shouldn't need maintenance there.
+
+ IMPORTANT: FOR ALL copys and fixcrlfs, DO NOT USE
+ preservelastmodified, as that will defeat our dependsets.
+
+ Don't do anything with apidocs, since those are handled by
+ javadoc-specific tasks.
+ -->
+
+ <!-- First, just binaries. We enforce EOLs for all others -->
+ <copy todir="${docoutput.path}">
+ <!-- Fileset pretty simple, since the binaries always need to be
+ served to end users. -->
+ <fileset dir="doc-src"
+ excludes="**/.*, **/*.txt, **/entities/**, apidocs/**,
+ **/*.xml, **/*.java, **/*.sql, **/*.cfg, **/*.css,
+ **/*.ent, **/*.rc, **/*.html, **/*.properties"/>
+ </copy>
+
+ <!-- *.txt and *.xml because *.txt are speficially not copied from document
+ base dirs and *.xml not from root or document base dirs,
+ because these files are used for document authorship and management.-->
+ <fixcrlf destdir="${docoutput.path}" eol="crlf"
+ encoding="UTF-8" srcdir="doc-src"
+ includes="verbatim/**/*.txt, images/**/*.txt"
+ excludes="**/.*"/>
+ <fixcrlf destdir="${docoutput.path}" eol="crlf"
+ encoding="UTF-8" srcdir="doc-src"
+ excludes="**/.*, verbatim/**, images/**, **/entities/**,
+ */*.txt, apidocs/**, readme-template.txt"
+ includes="**/*.txt"/>
+ <fixcrlf destdir="${docoutput.path}" eol="lf"
+ encoding="UTF-8" srcdir="doc-src"
+ includes="verbatim/**/*.xml, images/**/*.xml"
+ excludes="**/.*"/>
+ <fixcrlf destdir="${docoutput.path}" eol="lf"
+ encoding="UTF-8" srcdir="doc-src"
+ excludes="**/.*, verbatim/**, images/**, **/entities/**,
+ *.xml, */*.xml"
+ includes="**/*.xml"/>
+
+ <!-- All remaining text files -->
+ <fixcrlf destdir="${docoutput.path}" eol="lf"
+ encoding="UTF-8" srcdir="doc-src"
+ excludes="**/.*, **/entities/**, apidocs/**"
+ includes="**/*.java, **/*.sql, **/*.cfg, **/*.css,
+ **/*.rc, **/*.properties"/>
+ <!-- To allow substitution of ant-variables like ${x} in any of the text
+ files above, just move that file type from the fixcrlf above to the
+ copy below. -->
+ <copy todir="${docoutput.path}">
+ <fileset dir="doc-src" excludes="**/.*, **/entities/**, apidocs/**"
+ includes="**/*.html"/>
+ <filterchain>
+ <expandproperties/>
+ <fixcrlf eol="lf" encoding="UTF-8"/>
+ </filterchain>
+ </copy>
+ </target>
+
+ <target name="docbook-transform" depends="-fop-setup"
+ description="Generate DocBook output for specified source doc">
+ <fail unless="doc.name"
+ message="Ant property 'doc.name' is required by target 'docbook-transform'."/>
+ <available property="_htmlstyle.present" type="file" file="${html.path}"/>
+ <available property="_chunkstyle.present" type="file" file="${chunk.path}"/>
+ <available property="_fostyle.present" type="file" file="${fo.path}"/>
+ <fail unless="_htmlstyle.present"
+ message="DocBook 5 HTML style sheet missing: ${html.path}"/>
+ <fail unless="_chunkstyle.present"
+ message="DocBook 5 Chunk HTML style sheet missing: ${chunk.path}"/>
+ <fail unless="_fostyle.present"
+ message="DocBook 5 FO style sheet missing: ${fo.path}"/>
+
+ <dependset>
+ <srcfileset dir="doc-src" excludes="**/.*, *_lic.txt, readme*, index.html"
+ includes="*.*, entities/**, images/**, verbatim/**"/>
+ <!-- Remove *_lic.txt from excludes above and below if we add any
+ reference to license files from any of our DocBook documents.
+ -->
+ <targetfileset dir="tmp/doc-work"/>
+ <targetfileset dir="${docoutput.path}"
+ excludes="zaurus/**, apidocs/**, readme*, index.html, *_lic.txt"/>
+ </dependset>
+ <dependset>
+ <srcfileset dir="doc-src/${doc.name}" excludes="**/.*"/>
+ <targetfileset dir="${docoutput.path}/${doc.name}"/>
+ <targetfilelist dir="tmp/doc-work/${doc.name}" files="${doc.name}.fo"/>
+ </dependset>
+ <dependset>
+ <srcfilelist dir="tmp/doc-work/${doc.name}" files="${doc.name}.fo"/>
+ <targetfilelist dir="${docoutput.path}/${doc.name}"
+ files="${doc.name}.pdf"/>
+ </dependset>
+ <available property="skip.html" type="file" value="transform.skip"
+ file="${docoutput.path}/${doc.name}/${doc.name}.html"/>
+ <available property="skip.chunk" type="file" value="transform.skip"
+ file="${docoutput.path}/${doc.name}/index.html"/>
+ <available property="skip.fo" type="file" value="transform.skip"
+ file="${docoutput.path}/${doc.name}/${doc.name}.fo"/>
+ <available property="skip.pdf" type="file" value="fop.skip"
+ file="${docoutput.path}/${doc.name}/${doc.name}.pdf"/>
+ <property name="skip.html" value="dummy"/>
+ <property name="skip.chuk" value="dummy"/>
+ <property name="skip.pdf" value="dummy"/>
+
+ <antcall target="-transform">
+ <param name="style.path" value="${html.path}"/>
+ <param name="output.base"
+ value="${docoutput.path}/${doc.name}/${doc.name}.html"/>
+ <param name="html.format" value="true"/>
+ <param name="${skip.html}" value="true"/>
+ </antcall>
+ <antcall target="-transform">
+ <param name="style.path" value="${chunk.path}"/>
+ <param name="output.base"
+ value="${docoutput.path}/${doc.name}/dummy.html"/>
+ <param name="html.format" value="true"/>
+ <param name="${skip.chunk}" value="true"/>
+ </antcall>
+ <fixcrlf eol="lf" encoding="UTF-8" srcdir="doc/${doc.name}"
+ includes="*.html"/> <!-- Make output platform-independent -->
+ <antcall target="-transform">
+ <param name="style.path" value="${fo.path}"/>
+ <param name="output.base" value="tmp/doc-work/${doc.name}/${doc.name}.fo"/>
+ <param name="fop.format" value="true"/>
+ <param name="${skip.fo}" value="true"/>
+ </antcall>
+ <antcall target="-fop">
+ <param name="${skip.pdf}" value="true"/>
+ </antcall>
+ </target>
+
+ <target name="-fop" unless="fop.skip">
+ <fop format="application/pdf" basedir="doc-src/${doc.name}"
+ fofile="tmp/doc-work/${doc.name}/${doc.name}.fo"
+ outfile="${docoutput.path}/${doc.name}/${doc.name}.pdf"/>
+ <!-- basedir tells base location of image files -->
+ <!-- The fop tasks goes out to http://docbook.sourceforge.net to
+ fetch stuff -->
+ </target>
+
+ <target name="-transform" depends="-ivy-setup" unless="transform.skip">
+ <fail unless="distro.baseurl"
+ message="Ant property 'distro.baseurl' is required by target '-transform'."/>
+ <fail unless="doc.name"
+ message="Ant property 'doc.name' is required by target '-transform'."/>
+ <available file="${style.path}" type="file" property="_sheet.present"/>
+ <fail unless="_sheet.present"
+ message="Missing style sheet '${style.path}'"/>
+ <available file="doc-src/${doc.name}/${doc.name}.xml" type="file"
+ property="_srcxml.present"/>
+ <fail unless="_srcxml.present"
+ message="Missing DocBook source document 'doc-src/${doc.name}/${doc.name}.xml'"/>
+
+ <mkdir dir="tmp/doc-work/${doc.name}"/>
+ <echo file="tmp/doc-work/${doc.name}/dynamic.ent"><!--Dynamically generated Entity Values loaded by a catalog for document
+'${doc.name}' -->
+
+<!ENTITY doc_basename "${doc.name}">
+<!ENTITY distro_baseurl "${distro.baseurl}">
+</echo>
+
+ <ivy:cachepath conf="xalan" pathid="xalan.cpref"/>
+ <xslt style="${style.path}" basedir="doc-src/${doc.name}"
+ in="doc-src/${doc.name}/${doc.name}.xml"
+ out="${output.base}" classpathref="xalan.cpref">
+ <xmlcatalog classpathref="xalan.cpref" id="cat.ref">
+ <!-- WOULD MUCH PREFER TO DEFINE CATALOG EXTERNALLY.
+ Unfortunately, Ant's xmlcatalog is not seeing Apache's XML resolver.
+ -->
+
+ <!-- IMPORTANT! ***************************************
+ You must define Catalog mappings/replacements used in all of
+ your DocBook source right here, plus those needed in the validation
+ step need a duplicate entry in stylesheets/rng-catalog.xml.
+ Ant's xmlcatalog task is pretty limiting. No support for prefixes,
+ and external XML Commons Resolver and external catalog files
+ support are broken.
+ IMPORTANT! *************************************** -->
+ <dtd publicId="-//OASIS/ENTITIES DocBook Character Entities V4.5//EN"
+ location="${dbcentx.url}"/>
+ <entity location="${nsstylebase.url}/html/docbook.xsl"
+ publicId="${oasis.stylesheet.url}/html/docbook.xsl"/>
+ <entity location="${nsstylebase.url}/html/chunk.xsl"
+ publicId="${oasis.stylesheet.url}/html/chunk.xsl"/>
+ <entity location="${nsstylebase.url}/fo/docbook.xsl"
+ publicId="${oasis.stylesheet.url}/fo/docbook.xsl"/>
+ <entity location="tmp/doc-work/${doc.name}/dynamic.ent"
+ publicId="-//HSQLDB/ENTITIES/DocSpecificDynamicEntities"/>
+ </xmlcatalog>
+ <!-- There is probably no reason to use if/unless to exclude
+ format-specific or feature-specific settings, since settings
+ that don't apply to a specific stylesheet will just be ignored. -->
+
+ <!-- N.b.: "use.extensions" turns on all other *.extension properties.
+ (The boolean *.extension ones, not *.*.extensions).
+ If you want any off with "use.extensions" on, you must
+ turn them off individually.
+ "fop1.extensions" an exception? See table at
+ http://www.sagehill.net/docbookxsl/InstallingAProcessor.html#SaxonExtensions
+ -->
+ <param name="use.extensions" expression="1"/>
+
+ <param name="admon.graphics" expression="1"/>
+ <param name="admon.graphics.path" expression="../images/db/"/>
+ <param name="admon.graphics.extension" expression=".png"/>
+ <param name="css.decoration" expression="1"/>
+ <param name="annotation.support" expression="1"/>
+ <param name="navig.graphics" expression="1"/>
+ <param name="navig.graphics.path" expression="../images/db/"/>
+ <param name="table.borders.with.css" expression="1"/>
+ <param name="callouts.gaphics" expression="1"/>
+ <param name="callouts.gaphics.path" expression="../images/db/callouts/"/>
+ <param name="graphic.default.extension" expression=".png"/>
+ <param name="callouts.gaphics.extension" expression=".png"/>
+ <param name="html.stylesheet" expression="../docbook.css"
+ if="html.format"/>
+ <param name="shade.verbatim" expression="1" unless="html.format"/>
+ <param name="textdata.default.encoding" expression="ISO-8859-1"/>
+ <param name="use.id.as.filename" expression="1"/>
+ <param name="variablelist.as.table" expression="1"/>
+ <param name="index.on.type" expression="1"/>
+ <param name="body.start.indent" expression="0" if="fop.format"/>
+ <param name="table.cell.border.thickness" expression="1pt"
+ if="fop.format"/>
+ <param name="html.cellspacing" expression="0" if="html.format"/>
+
+ <!-- With this on, formatting is terrible unless column content
+ lengths are symmetical -->
+ <param name="tablecolumns.extension" expression="0"/>
+
+ <!-- Docbook-supplied png nav icons suck -->
+ <param name="navig.graphics.extension" expression=".png"/>
+
+ <!-- "fop.extensions" for old FOP versions -->
+ <param name="fop1.extensions" expression="1" if="fop.format"/>
+
+ <!-- This tells sections shown in single HTML pages, not levels shown in
+ the TOC, which is governed by "toc.section.depth" -->
+ <param name="chunk.section.depth" expression="0"/>
+ <!-- Defaults to 1 -->
+
+ <!-- This has no effect, because the Docbook .xsl files specify the
+ output encoding literally.
+ <param name="chunker.output.encoding" expression="UTF-8"/>
+ -->
+
+ <outputproperty name="encoding" value="UTF-8"/>
+ <outputproperty name="indent" value="yes"/>
+ </xslt>
+ </target>
+
+ <target name="clean-docs" description="Remove all derived doc artifacts">
+ <delete dir="tmp/doc-work"/>
+ <delete includeemptydirs="true">
+ <fileset dir="${docoutput.path}" excludes="zaurus/**"/>
+ </delete>
+ </target>
+
+ <target name="-fop-setup" depends="-ivy-setup">
+ <ivy:cachepath conf="fop" pathid="fop.cpref"/>
+ <taskdef name="fop" classname="org.apache.fop.tools.anttasks.Fop"
+ classpathref="fop.cpref"/>
+ </target>
+
+ <target name="-ivy-setup">
+ <available property="_ivy.present" classname="org.apache.ivy.ant.IvyTask"/>
+ <fail unless="_ivy.present">
+Add Ivy jar file to Ant CLASSPATH.
+
+Obtain a 2.x version of an Apache Ivy jar file (perhaps at
+http://ant.apache.org/ivy/), and run a command like the following, changing the
+jar file path to wherever you have it saved. For any Bourne shell (incl. Bash):
+
+ export ANT_ARGS; ANT_ARGS='-lib $HOME/ivy-2.1.0.jar -noclasspath'
+
+OR for any CMD-like Windows shell:
+
+ SET ANT_ARGS=-lib "%HOMEDRIVE%%HOMEPATH%/ivy-2.1.0.jar" -noclasspath</fail>
+
+ <available property="_ivysettings.present" file="build/ivysettings.xml"
+ type="file"/>
+ <antcall target="-ensure-ivysettings"/>
+ <ivy:settings/>
+ </target>
+
+ <target name="-ensure-ivysettings" unless="_ivysettings.present">
+ <copy file="build/ivysettings-sample.xml" tofile="build/ivysettings.xml"/>
+ <echo>Just created a local 'ivysettings.xml' file for you.
+Customize this as you wish and/or set Ivy properties (or any other
+docbook-specific local build properties) in a 'local.properties'
+file.</echo>
+ </target>
+
+ <target name="validate-doc" unless="validation.skip"
+ depends="-validation-setup, -ivy-setup"
+ description="Validate specified DocBook source document">
+ <fail unless="doc.name"
+ message="Ant property 'doc.name' is required by target 'validate'."/>
+ <ivy:resolve conf="msv"/>
+ <!-- The resolve downloads and makes the 3rd party libs accessed by
+ our admc-rs-msv jar file through its manifests classpath entry. -->
+ <ivy:cachepath conf="admc-rs-msv" pathid="admc-rs-msv.cpref"/>
+ <pathconvert property="jar.file" refid="admc-rs-msv.cpref"/>
+ <java fork="true" failonerror="true"
+ jar="${jar.file}" dir="doc-src/${doc.name}">
+ <sysproperty key="xml.catalog.verbosity"
+ value="${xml.catalog.verbosity}"/>
+ <sysproperty key="xml.catalog.files" value="${xml.catalog.files}"/>
+ <sysproperty key="xml.catalog.prefer" value="${xml.catalog.prefer}"/>
+ <sysproperty key="xml.catalog.allowPI" value="${xml.catalog.allowPI}"/>
+ <sysproperty key="xml.catalog.staticCatalog"
+ value="${xml.catalog.staticCatalog}"/>
+ <jvmarg value="-Xss${java.threadstacksize}"/>
+ <arg value="-v"/>
+ <arg value="${dbxirng.url}"/>
+ <arg value="${doc.name}.xml"/>
+ </java>
+ </target>
+
+ <target name="validation-help" depends="-ivy-setup"
+ description="Display advice about validating files manually">
+ <ivy:resolve conf="msv"/>
+ <!-- The resolve downloads and makes the 3rd party libs accessed by
+ our admc-rs-msv jar file through its manifests classpath entry. -->
+ <ivy:cachepath conf="admc-rs-msv" pathid="admc-rs-msv.cpref"/>
+ <pathconvert property="jar.file" refid="admc-rs-msv.cpref"/>
+ <echo>'cd' to the directory containing the XML source files, and run
+something like
+java -Xss${java.threadstacksize} -Dxml.catalog.files=${xml.catalog.files} -jar ${jar.file} -v ${dbxirng.url} file.xml...
+
+See the XML Commons docs about the Java System Properties to
+use for XML catalog resolution:
+http://xml.apache.org/commons/components/resolver/resolver-article.html#ctrlresolver
+</echo>
+ </target>
+
+ <target name="refresh-verbatim"
+ description="Update files under doc-src/verbatim">
+ <!-- It's good to apply preservelastmodified to stuff under doc-src/,
+ but be very careful if applying it to doc/..., since that could
+ break our dependsets. -->
+ <copy todir="doc-src/verbatim" preservelastmodified="true">
+ <fileset dir=".">
+ <present targetdir="doc-src/verbatim"/>
+ </fileset>
+ </copy>
+ </target>
+
+ <target name="-validation-setup">
+ <fail message="Something is wrong. '-validation-setup' is abstract"/>
+ </target>
+</project>
diff --git a/build/build.hsqldb.cmd b/build/build.hsqldb.cmd
new file mode 100755
index 0000000..86fc108
--- /dev/null
+++ b/build/build.hsqldb.cmd
@@ -0,0 +1,2 @@
+call setenv.cmd
+ant clean hsqldb
diff --git a/build/build.hsqldbtest.cmd b/build/build.hsqldbtest.cmd
new file mode 100755
index 0000000..8d7b760
--- /dev/null
+++ b/build/build.hsqldbtest.cmd
@@ -0,0 +1,2 @@
+call setenv.cmd
+ant clean hsqldb hsqldbtest
diff --git a/build/build.test.suite.cmd b/build/build.test.suite.cmd
new file mode 100755
index 0000000..855ae16
--- /dev/null
+++ b/build/build.test.suite.cmd
@@ -0,0 +1,2 @@
+call setenv.cmd
+ant -f test.xml clean.test.suite make.test.suite
diff --git a/build/build.xml b/build/build.xml
new file mode 100644
index 0000000..f99aa1b
--- /dev/null
+++ b/build/build.xml
@@ -0,0 +1,1077 @@
+<?xml version="1.0"?>
+<!-- $Id: build.xml 3621 2010-06-04 15:33:36Z fredt $ -->
+<!-- author fredt@users.sourceforge.net 2001 - 2009 -->
+<!-- additional targets 2004-2009: blaine (dot) simpson (at) admc (dot) com -->
+<project name="hsqldb" default="help" basedir="../">
+ <!-- This loads properties in the same exact way as if you ran
+ "ant -Dprop1name=val1 -Dprop2name=val2...", etc. To use all
+ defaults, you should have no 'build.properties' file.
+ If you don't understand this or want to know about precedence or
+ how to use an Ant properties file, look up an Ant manual or an
+ Ant expert.
+ If you want to know, "Can I set property 'x' in 'build.properties'",
+ rephrase the question to yourself as "Can I run 'ant -Dx=...?"
+ Do not address questions about property file(s) to the
+ hsqldb community. -->
+
+ <!-- TODO:
+ Use multiple class directories (javac dest dirs).
+ Current tactic requires tons of complicated includes and exludes
+ and still often bundles arbitrary extra stuff (determined by what
+ happened to be built previously).
+ -->
+
+ <property file='build/build.properties'/>
+ <property name="hsqldb.version" value="2.0.0"/>
+
+ <tstamp>
+ <format property="_tmpstamp" pattern="yyyy/MM/dd-HH:mm:ss"
+ locale="en"/>
+ </tstamp>
+
+ <property name="build.label" value="private-${_tmpstamp}"/>
+ <property name="build.vendor" value="${user.name}"/>
+ <property name="hsqldb.title" value="HSQLDB"/>
+ <property name="hsqldb.vendor" value="The HSQL Development Group"/>
+ <property name="swsrc" value="tmp/switchedsrc"/>
+ <condition property="switch.inplace">
+ <equals arg1="${swsrc}" arg2="src"/>
+ </condition>
+
+ <!-- It is safe to override these with settings in your own
+ build.properties file. -->
+ <property name="build.debug" value="true"/>
+ <property name="build.optimize" value="false"/>
+ <!-- N.b. Compilation optimization only has effect with JDK 1.1 and 1.2 -->
+
+ <property name="servletapi.lib" value="lib/servlet-2_3-fcs-classfiles.zip"/>
+ <property name="junit38.lib" value="lib/junit.jar"/>
+ <property name='jflex.lib' value='lib/JFlex.jar'/>
+
+ <target name="init"/>
+
+ <target name='explainjars'
+ description="List description of jars that you can build">
+ <echo>Ant version: ${ant.version} </echo>
+ <echo>jar filename build command explanation
+-------------- ------------- -----------------------------------
+hsqldb.jar ant hsqldb Default distribution jar
+hsqljdbc.jar ant hsqljdbc JDBC network client JDBC Driver.
+ (Can connect to HyperSQL Servers)
+hsqldbmain.jar ant hsqldbmain No utility programs
+hsqldbutil.jar ant hsqldbutil Utility programs only. No JDBC
+ driver. (Includes SqlTool and
+ DatabaseManagers)
+hsqldbmin.jar ant hsqldbmin No utility or server programs.
+ (Includes in-process JDBC driver,
+ but no support for HyperSQL
+ Servers)
+hsqldbtest.jar ant hsqldbtest All, including test classes
+sqltool.jar ant sqltool SqlTool app (no JDBC driver)</echo>
+ </target>
+
+ <!-- Deprecated targets. New naming convention is:
+ Target name is always the same as the desired jar file name, less
+ the ".jar" extension. -->
+ <target name='jar' depends='hsqldb'/>
+ <target name='jarclient' depends='hsqljdbc'/>
+ <target name='jarmain' depends='hsqldbmain'/>
+ <target name='jarmin' depends='hsqldbmin'/>
+ <target name='jartest' depends='hsqldbtest'/>
+ <target name='jarutil' depends='hsqldbutil'/>
+
+ <target name="help" description="Top-level help message">
+ <echo>Ant version: ${ant.version} </echo>
+ <echo>usage:
+ ant -help Display ant help screen
+ ant -projecthelp Display all invocable targets
+ ant explainjars List all targets which build jar files
+ ant ANYTHING ELSE Run 'ant -projecthelp' for details
+
+examples:
+ ant jar
+ ant clean</echo>
+ </target>
+
+ <target name="-javajsse">
+ <available classname="javax.net.ssl.SSLSession" property="ant.java.hasjsse"/>
+ <echo message="ant.java.hasjsse=${ant.java.hasjsse}" />
+ </target>
+
+ <target name="-set-jvmvars">
+ <!-- Besides this one target taking the place of 4 targets (-javaversionX),
+ this target eliminates the redundancy in those methods by making a
+ single class-existence-test definitively responsible for determining if
+ JVM X is supported.
+ It is sufficient for this purposes if the test classes used are
+ verified to be present in version X and in all newer versions (> X)
+ (i.e. that the class is not removed from some higher JVM). -->
+ <available classname="java.lang.ref.Reference" property="ant.java.iscjava12"/>
+ <available classname="java.lang.ref.Reference" property="ant.java.iscjavamodern"/>
+ <available classname="java.nio.Buffer" property="ant.java.iscjava14"/>
+ <available classname="java.util.EnumSet" property="ant.java.iscjava15"/>
+ <available classname="java.net.IDN" property="ant.java.iscjava16"/>
+ </target>
+
+ <target name="-prepare" depends="init,-set-jvmvars">
+ <mkdir dir="classes" />
+ </target>
+
+ <target name="-prepare-javadoc" depends="init">
+ <delete dir="doc/apidocs"/>
+ <!-- Must be vigilant about cleaning up from previous runs, since this
+ same directory is used for both public API spec, and the full
+ code-base API spec.
+ There is no performance penalty, since the javadoc task regenerates
+ everything each run.
+ -->
+ <copy todir="doc/apidocs">
+ <!-- IMPORTANT:
+ Add a fixcrlf if we add non-binary files to doc-src/apidocs. -->
+ <fileset dir="doc-src/apidocs"/>
+ </copy>
+ </target>
+
+
+ <target name="reinit"
+ description="Just like 'clean' target, except overwrites switched source files to prevent need for a complete re-copy">
+ <!-- Beware this will retain a copy of removed artifcats under src.
+ You must use the real 'clean' target to really purge everything. -->
+ <fail message="Just use 'clean' for inplace-switching setups"
+ if="switch.inplace"/>
+ <delete dir="classes"/>
+ <copy todir='${swsrc}' preservelastmodified='true'>
+ <fileset dir='src' includes='**/*.java'/>
+ </copy>
+ </target>
+
+ <target name="clean" depends="-clean, -clean-switch-branch"
+ description="Delete the /classes and work directories created by ant tasks">
+ <echo message="Use the 'clean-all' target to also purge generated doc and .jar files"/>
+ </target>
+
+ <target name="-clean">
+ <delete dir="classes"/>
+ </target>
+
+ <target name="clean-all" depends="-clean, -clean-switch-branch, clean-docs"
+ description="Same as clean but delete the jar and doc files as well">
+ <delete>
+ <fileset dir="lib" includes="sqltool*.jar, hsql*.jar, testsuite.jar"/>
+ </delete>
+ </target>
+
+ <target name="codeswitcher" depends="-prepare"
+ description="uses +-JAVA2 +-JAVA4 +-JAVA5 +-JAVA6">
+ <javac destdir="classes">
+ <src path="src"/>
+ <include name="org/hsqldb/util/CodeSwitcher.java"/>
+ </javac>
+ <antcall target="-update-switch-branch"/>
+ </target>
+
+ <target name="switchtojava1target" depends="codeswitcher"
+ description="self explanatory">
+ <java classname="org.hsqldb.util.CodeSwitcher" classpath="classes" >
+ <arg file="${swsrc}/org/hsqldb/lib/java/JavaSystem.java"/>
+ <arg file="${swsrc}/org/hsqldb/util/DatabaseManager.java"/>
+ <arg file="${swsrc}/org/hsqldb/util/ConnectionDialogCommon.java"/>
+ <arg value="-JAVA2FULL"/>
+ </java>
+ </target>
+
+ <target name="switchoffjava1target" depends="codeswitcher"
+ description="self explanatory">
+ <java classname="org.hsqldb.util.CodeSwitcher" classpath="classes" >
+ <arg file="${swsrc}/org/hsqldb/lib/java/JavaSystem.java"/>
+ <arg file="${swsrc}/org/hsqldb/util/DatabaseManager.java"/>
+ <arg file="${swsrc}/org/hsqldb/util/ConnectionDialogCommon.java"/>
+ <arg value="+JAVA2FULL"/>
+ </java>
+ </target>
+
+ <target name="switchtodeprecatedjdbc" depends="codeswitcher"
+ description="self explanatory">
+ <java classname="org.hsqldb.util.CodeSwitcher" classpath="classes" >
+ <arg file="${swsrc}/org/hsqldb/jdbc/JDBCCallableStatement.java"/>
+ <arg file="${swsrc}/org/hsqldb/jdbc/JDBCPreparedStatement.java"/>
+ <arg file="${swsrc}/org/hsqldb/jdbc/JDBCResultSet.java"/>
+ <arg value="+DEPRECATEDJDBC"/>
+ </java>
+ </target>
+
+ <target name="switchoffdeprecatedjdbc" depends="codeswitcher"
+ description="self explanatory">
+ <java classname="org.hsqldb.util.CodeSwitcher" classpath="classes" >
+ <arg file="${swsrc}/org/hsqldb/jdbc/JDBCCallableStatement.java"/>
+ <arg file="${swsrc}/org/hsqldb/jdbc/JDBCPreparedStatement.java"/>
+ <arg file="${swsrc}/org/hsqldb/jdbc/JDBCResultSet.java"/>
+ <arg value="-DEPRECATEDJDBC"/>
+ </java>
+ </target>
+
+ <!-- If this should not be called externally, rename to -switches
+ and remove the description attribute -->
+ <target name="switches" depends="codeswitcher"
+ description="Execute code switchers, other than for JVM version">
+ </target>
+
+ <target name="switchtojdk12" depends="switches" unless="ant.java.iscjava14"
+ description="self explanatory" if="ant.java.iscjava12">
+ <java classname="org.hsqldb.util.CodeSwitcher" classpath="classes" >
+ <arg value="+JAVA2"/>
+ <arg value="-JAVA4"/>
+ <arg value="-JAVA5"/>
+ <arg value="-JAVA6"/>
+ <arg value="--pathlist=jdkcodeswitch.list"/>
+ <arg value="--basedir=../${swsrc}"/>
+ <!-- Since these paths are interpreted by the JVM, not ant,
+ the path must be relative to run dir (build), not the
+ Ant basedir -->
+ </java>
+ </target>
+
+ <target name="switchtojdk14" depends="switches" unless="ant.java.iscjava15"
+ description="self explanatory" if="ant.java.iscjava14">
+ <java classname="org.hsqldb.util.CodeSwitcher" classpath="classes" >
+ <arg value="+JAVA2"/>
+ <arg value="+JAVA4"/>
+ <arg value="-JAVA5"/>
+ <arg value="-JAVA6"/>
+ <arg value="--pathlist=jdkcodeswitch.list"/>
+ <arg value="--basedir=../${swsrc}"/>
+ <!-- Since these paths are interpreted by the JVM, not ant,
+ the path must be relative to run dir (build), not the
+ Ant basedir -->
+ </java>
+ </target>
+
+ <target name="switchtojdk15" depends="switches" unless="ant.java.iscjava16"
+ description="self explanatory" if="ant.java.iscjava15">
+ <java classname="org.hsqldb.util.CodeSwitcher" classpath="classes" >
+ <arg value="+JAVA2"/>
+ <arg value="+JAVA4"/>
+ <arg value="+JAVA5"/>
+ <arg value="-JAVA6"/>
+ <arg value="--pathlist=jdkcodeswitch.list"/>
+ <arg value="--basedir=../${swsrc}"/>
+ <!-- Since these paths are interpreted by the JVM, not ant,
+ the path must be relative to run dir (build), not the
+ Ant basedir -->
+ </java>
+ </target>
+
+ <target name="switchtojdk16" depends="switches"
+ description="self explanatory" if="ant.java.iscjava16">
+ <java classname="org.hsqldb.util.CodeSwitcher" classpath="classes" >
+ <arg value="+JAVA2"/>
+ <arg value="+JAVA4"/>
+ <arg value="+JAVA5"/>
+ <arg value="+JAVA6"/>
+ <arg value="--pathlist=jdkcodeswitch.list"/>
+ <arg value="--basedir=../${swsrc}"/>
+ <!-- Since these paths are interpreted by the JVM, not ant,
+ the path must be relative to run dir (build), not the
+ Ant basedir -->
+ </java>
+ </target>
+
+ <target name="store" description="compiles the /store folder"
+ depends="switchtojdk12,switchtojdk14,
+ switchtojdk15,switchtojdk16">
+ <javac srcdir="${swsrc}"
+ destdir="classes"
+ debug="${build.debug}"
+ optimize="${build.optimize}"
+ >
+ <include name="org/hsqldb/store/**"/>
+ </javac>
+ </target>
+
+ <target name="lib" depends="store"
+ description="compiles the JVM-independent lib classes">
+ <javac srcdir="${swsrc}"
+ destdir="classes"
+ debug="${build.debug}"
+ optimize="${build.optimize}"
+ >
+ <exclude name="org/hsqldb/lib/AppendableException.java"/>
+ <exclude name="org/hsqldb/lib/RefCapablePropertyResourceBundle.java"/>
+ <exclude name="org/hsqldb/lib/RefCapableRBInterface.java"/>
+ <exclude name="org/hsqldb/lib/ValidatingResourceBundle.java"/>
+ <exclude name="org/hsqldb/lib/tar/**"/>
+ <include name="org/hsqldb/lib/**"/>
+ </javac>
+ </target>
+
+ <target name="classes" depends="lib,-javajsse"
+ description="compiles JVM-independent non-lib/util/cmdline classes">
+ <available property='_servlet_available' classpath='${servletapi.lib}'
+ classname='javax.servlet.ServletException'/>
+ <fail unless='_servlet_available'
+ message="Place Jar file for Servlet API at '${servletapi.lib}', or set property 'servletapi.lib'"/>
+ <javac srcdir="${swsrc}"
+ destdir="classes"
+ debug="${build.debug}"
+ optimize="${build.optimize}"
+ >
+ <classpath>
+ <pathelement location="${servletapi.lib}"/>
+ </classpath>
+ <include name="*.java"/>
+ <include name="org/hsqldb/*.java"/>
+ <include name="org/hsqldb/dbinfo/*.java"/>
+ <include name="org/hsqldb/index/*.java"/>
+ <include name="org/hsqldb/jdbc/*.java"/>
+ <include name="org/hsqldb/navigator/*.java"/>
+ <include name="org/hsqldb/persist/*.java"/>
+ <include name="org/hsqldb/resources/*.java"/>
+ <include name="org/hsqldb/result/*.java"/>
+ <include name="org/hsqldb/rowio/*.java"/>
+ <include name="org/hsqldb/scriptio/*.java"/>
+ <include name="org/hsqldb/server/*.java"/>
+ <include name="org/hsqldb/store/*.java"/>
+ <include name="org/hsqldb/types/*.java"/>
+ <exclude name="org/hsqldb/server/HsqlSocketFactorySecure.java" unless="ant.java.hasjsse"/>
+ <exclude name="org/hsqldb/jdbc/JDBCArray.java"/>
+ <exclude name="org/hsqldb/jdbc/JDBCBlob.java"/>
+ <exclude name="org/hsqldb/jdbc/JDBCClob.java"/>
+ <exclude name="org/hsqldb/jdbc/JDBCDataSource*.java"/>
+ <exclude name="org/hsqldb/jdbc/JDBCParameterMetaData.java"/>
+ <exclude name="org/hsqldb/jdbc/JDBCSavepoint.java"/>
+<!-- BEGIN JDBC 4-->
+ <exclude name="org/hsqldb/jdbc/JDBCNClob.java"/>
+ <exclude name="org/hsqldb/jdbc/JDBCRowId.java"/>
+ <exclude name="org/hsqldb/jdbc/JDBCSQLXML.java"/>
+<!-- TODO
+ <exclude name="org/hsqldb/jdbc/jdbcConflictingRowImpl.java"/>
+ <exclude name="org/hsqldb/jdbc/jdbcDataSetImpl.java"/>
+ <exclude name="org/hsqldb/jdbc/jdbcDataSetResolverImpl.java"/>
+ <exclude name="org/hsqldb/jdbc/jdbcQueryObjectGeneratorImpl.java"/>
+ <exclude name="org/hsqldb/jdbc/jdbcRowSet.java"/>
+-->
+<!-- end JDBC 4 -->
+ <exclude name="org/hsqldb/persist/NIOLockFile.java"/>
+ <exclude name="org/hsqldb/persist/NIOScaledRAFile.java"/>
+ </javac>
+ <fixcrlf destdir="classes" preservelastmodified='true' eol="lf"
+ encoding="ISO-8859-1" srcdir="src"
+ includes="**/*.properties, **/*.text, **/*.sql"/>
+ </target>
+
+ <target name="classes12" depends="classes" if="ant.java.iscjavamodern"
+ description="compiles 1.2 specific classes">
+ <javac srcdir="${swsrc}"
+ destdir="classes"
+ debug="${build.debug}"
+ optimize="${build.optimize}"
+ >
+ <include name="org/hsqldb/jdbc/JDBCArray.java"/>
+ <include name="org/hsqldb/jdbc/JDBCBlob.java"/>
+ <include name="org/hsqldb/jdbc/JDBCClob.java"/>
+ </javac>
+ </target>
+
+ <target name="classes14" depends="classes12" if="ant.java.iscjava14"
+ description="compiles 1.4 specific classes">
+ <javac srcdir="${swsrc}" destdir="classes" debug="${build.debug}"
+ optimize="${build.optimize}" >
+ <include name="org/hsqldb/jdbc/pool/*.java"/>
+ <include name="org/hsqldb/jdbc/JDBCDataSource*.java"/>
+ <include name="org/hsqldb/jdbc/JDBCParameterMetaData.java"/>
+ <include name="org/hsqldb/jdbc/JDBCSavepoint.java"/>
+ <include name="org/hsqldb/persist/NIOLockFile.java"/>
+ <include name="org/hsqldb/persist/NIOScaledRAFile.java"/>
+ </javac>
+ </target>
+
+ <target name="classes15" depends="classes14" if="ant.java.iscjava15"
+ description="compiles 1.5 specific classes">
+ <javac srcdir="${swsrc}" destdir="classes" debug="${build.debug}"
+ optimize="${build.optimize}" >
+ <include name="org/hsqldb/lib/AppendableException.java"/>
+ <include name="org/hsqldb/lib/RefCapablePropertyResourceBundle.java"/>
+ <include name="org/hsqldb/lib/RefCapableRBInterface.java"/>
+ <include name="org/hsqldb/lib/ValidatingResourceBundle.java"/>
+ <include name="org/hsqldb/lib/tar/**"/>
+ </javac>
+ </target>
+
+ <target name="classes16" depends="classes15" if="ant.java.iscjava16"
+ description="compiles 1.6 specific classes">
+ <javac srcdir="${swsrc}" destdir="classes" debug="${build.debug}"
+ optimize="${build.optimize}" >
+ <include name="org/hsqldb/jdbc/JDBCNClob.java"/>
+ <include name="org/hsqldb/jdbc/JDBCRowId.java"/>
+ <include name="org/hsqldb/jdbc/JDBCSQLXML.java"/>
+<!-- TODO
+ <include name="org/hsqldb/jdbc/jdbcConflictingRowImpl.java"/>
+ <include name="org/hsqldb/jdbc/jdbcDataSetImpl.java"/>
+ <include name="org/hsqldb/jdbc/jdbcDataSetResolverImpl.java"/>
+ <include name="org/hsqldb/jdbc/jdbcQueryObjectGeneratorImpl.java"/>
+ <include name="org/hsqldb/jdbc/jdbcRowSet.java"/>
+-->
+ </javac>
+ </target>
+
+ <!-- Don't both use name beginning with - AND supply a 'description'.
+ If this should be externally callable, then remove the leading -
+ and change the following description to a description attribute:
+ - blaine
+
+ compiles 1.4-specific test classes
+ -->
+ <target name="-test14" if="ant.java.iscjava14" depends='switches'>
+ <antcall inheritall='true' target='-requireJunit'/>
+ <!-- using antcall instead of depends so that it is not called if the
+ target "if" above is false. -->
+ <javac srcdir="${swsrc}"
+ destdir="classes"
+ debug="${build.debug}"
+ optimize="${build.optimize}"
+ classpath="${junit38.lib}"
+ >
+ <include name="org/hsqldb/test/TestJDBCSavepoints.java"/>
+ </javac>
+ </target>
+
+ <target name="util" depends="lib, -cmdline"
+ description="compiles the util and cmdline folders">
+ <javac srcdir="${swsrc}"
+ destdir="classes"
+ debug="${build.debug}"
+ optimize="${build.optimize}"
+ >
+ <include name="org/hsqldb/util/**"/>
+ <exclude name="org/hsqldb/util/*Swing.java"/>
+ <exclude name="org/hsqldb/util/preprocessor/**"/>
+ <exclude name="org/hsqldb/util/TableSorter.java"/>
+ </javac>
+ <copy todir="classes/org/hsqldb/util" preservelastmodified='true'>
+ <fileset dir="src/org/hsqldb/util" includes='*.gif, *.png'/>
+ </copy>
+ </target>
+
+ <target name="-cmdline" if="ant.java.iscjava15"
+ description="compiles the cmdline classes">
+ <antcall target="-sqlfile-scanner"/>
+ <!-- antcall instead of depends, because we don't want it to be run
+ if the 'if' is false -->
+ <javac srcdir="${swsrc}"
+ destdir="classes"
+ debug="${build.debug}"
+ optimize="${build.optimize}"
+ >
+ <include name="org/hsqldb/cmdline/**"/>
+ </javac>
+ </target>
+
+
+ <target name="swing" depends="util" unless="noswing"
+ description="compiles the swing based classes in the util folder">
+ <javac srcdir="${swsrc}"
+ destdir="classes"
+ debug="${build.debug}"
+ optimize="${build.optimize}"
+ >
+ <include name="org/hsqldb/util/*Swing.java"/>
+ <include name="org/hsqldb/util/TableSorter.java"/>
+ </javac>
+ </target>
+
+ <target name='-requireJunit'>
+ <available property='_junit_available' classpath='${junit38.lib}'
+ classname='junit.swingui.TestRunner'/>
+ <fail unless='_junit_available'
+ message="Place Jar file for v. 3.8.x of Junit at '${junit38.lib}', or set property 'junit38.lib'"/>
+ </target>
+
+ <target name="scanner-driver" depends="util">
+ <!-- Purposefully no description -->
+ <javac srcdir="${swsrc}"
+ includes="org/hsqldb/test/SqlFileScannerDriver.java"
+ destdir="classes"
+ debug="${build.debug}"
+ optimize="${build.optimize}"
+ />
+ </target>
+
+ <target name="test" depends="-requireJunit, classes16"
+ description="compiles the test package classes">
+ <javac srcdir="${swsrc}"
+ destdir="classes"
+ debug="${build.debug}"
+ optimize="${build.optimize}"
+ >
+ <classpath>
+ <pathelement location="${junit38.lib}"/>
+ <pathelement location="lib/dbunit.jar"/>
+ </classpath>
+ <include name="org/hsqldb/test/**"/>
+ <exclude name="org/hsqldb/test/TestJDBCSavepoints.java"/>
+ <exclude name="org/hsqldb/test/SqlFileScannerDriver.java"/>
+ </javac>
+ <antcall inheritall='true' target='-test14'/>
+ </target>
+
+ <target name="hsqldbtest" depends="test,swing, -prep-license-files"
+ description="Build the hsqldbtest.jar (default plus test classes)">
+ <jar jarfile="lib/hsqldbtest.jar"
+ basedir="classes"
+ >
+ <metainf dir="doc" includes="*_lic.txt"/>
+ <service type="java.sql.Driver" provider="org.hsqldb.jdbc.JDBCDriver"/>
+ <manifest>
+ <attribute name='Specification-Title' value='${hsqldb.title}'/>
+ <attribute name='Specification-Version' value='${hsqldb.version}'/>
+ <attribute name='Specification-Vendor' value='${hsqldb.vendor}'/>
+ <attribute name='Implementation-Title'
+ value='Test runtime'/>
+ <attribute name='Implementation-Version' value='${build.label}'/>
+ <attribute name='Implementation-Vendor' value='${build.vendor}'/>
+ </manifest>
+ <exclude name="org/hsqldb/jmx/**"/>
+ <exclude name="org/hsqldb/sample/*"/>
+ </jar>
+ </target>
+
+ <!--
+ Sat Nov 19 17:52:33 EST 2005 Blaine changing this description,
+ because I see no Swing classes in hsqldbmain.jar when I build
+ it... why would anybody ever want them in a no-util jar anyways?
+
+ description="Build the hsqldbmain.jar (no utilities) (use ant switch '-Dnoswing=true' to exclude swing classes)">
+ -->
+ <target name="hsqldbmain" depends="classes16, -prep-license-files"
+ description="Build the hsqldbmain.jar (no utilities)">
+ <jar jarfile="lib/hsqldbmain.jar"
+ basedir="classes"
+ >
+ <metainf dir="doc" includes="*_lic.txt"/>
+ <service type="java.sql.Driver" provider="org.hsqldb.jdbc.JDBCDriver"/>
+ <manifest>
+ <attribute name='Specification-Title' value='${hsqldb.title}'/>
+ <attribute name='Specification-Version' value='${hsqldb.version}'/>
+ <attribute name='Specification-Vendor' value='${hsqldb.vendor}'/>
+ <attribute name='Implementation-Title'
+ value='Runtime without utilities'/>
+ <attribute name='Implementation-Version' value='${build.label}'/>
+ <attribute name='Implementation-Vendor' value='${build.vendor}'/>
+ </manifest>
+ <exclude name="org/hsqldb/jmx/**"/>
+ <exclude name="org/hsqldb/util/**"/>
+ <exclude name="org/hsqldb/cmdline/**"/>
+ <exclude name="org/hsqldb/test/**"/>
+ <exclude name="org/hsqldb/sample/**"/>
+ </jar>
+ </target>
+
+ <target name="hsqldbmin" depends="classes16, -prep-license-files"
+ description="Build the hsqldbmin.jar (no connection pooling or servers)">
+ <jar jarfile="lib/hsqldbmin.jar"
+ basedir="classes"
+ >
+ <metainf dir="doc" includes="*_lic.txt"/>
+ <service type="java.sql.Driver" provider="org.hsqldb.jdbc.JDBCDriver"/>
+ <manifest>
+ <attribute name='Specification-Title' value='${hsqldb.title}'/>
+ <attribute name='Specification-Version' value='${hsqldb.version}'/>
+ <attribute name='Specification-Vendor' value='${hsqldb.vendor}'/>
+ <attribute name='Implementation-Title'
+ value='Runtime without utilities, connection pooling and servers'/>
+ <attribute name='Implementation-Version' value='${build.label}'/>
+ <attribute name='Implementation-Vendor' value='${build.vendor}'/>
+ </manifest>
+ <!-- Without this, some ANT/Java combinations may get confused and
+ include nothing in the jar -->
+ <include name="**/*"/>
+ <!-- -->
+ <exclude name="org/hsqldb/jdbc/pool/**"/>
+ <exclude name="org/hsqldb/jmx/**"/>
+ <exclude name="org/hsqldb/util/**"/>
+ <exclude name="org/hsqldb/cmdline/**"/>
+ <exclude name="org/hsqldb/test/**"/>
+ <exclude name="org/hsqldb/sample/**"/>
+ <exclude name="**/*.properties"/>
+ <include name="org/hsqldb/resources/sql-error-messages.properties"/>
+ <exclude name="hsqlServlet.class"/>
+ <exclude name="org/hsqldb/Servlet.class"/>
+ <exclude name="org/hsqldb/Server.class"/>
+ <exclude name="org/hsqldb/server/HsqlSocketFactory.class"/>
+ <exclude name="org/hsqldb/server/HsqlSocketFactorySecure.class"/>
+ <exclude name="org/hsqldb/srever/HsqlServerFactory.class"/>
+ <exclude name="org/hsqldb/srever/HsqlServerProperties.class"/>
+ <exclude name="org/hsqldb/server/HsqlSocketRequestHandler.class"/>
+ <exclude name="org/hsqldb/server/HsqlSocketRequestHandlerImpl.class"/>
+ <exclude name="org/hsqldb/server/Server.class"/>
+ <exclude name="org/hsqldb/server/Server$ServerThread.class"/>
+ <exclude name="org/hsqldb/server/ServerConnection.class"/>
+ <exclude name="org/hsqldb/server/ServerConfiguration.class"/>
+ <exclude name="org/hsqldb/server/WebServer.class"/>
+ <exclude name="org/hsqldb/server/WebServerConnection.class"/>
+ <exclude name="org/hsqldb/dbinfo/DatabaseInformationFull.class"/>
+ <exclude name="org/hsqldb/rowio/RowInputLegacy.class"/>
+ <exclude name="org/hsqldb/rowio/RowOutputLegacy.class"/>
+ <exclude name="org/hsqldb/dbinfo/DIProcedureInfo.class"/>
+ <exclude name="org/hsqldb/HSQLClientConnection.class"/>
+ <exclude name="org/hsqldb/HTTPClientConnection.class"/>
+ </jar>
+ </target>
+
+ <target name="hsqldb" depends="classes16, util, swing, -prep-license-files"
+ description="Build the default hsqldb.jar">
+ <jar jarfile="lib/hsqldb.jar"
+ basedir="classes"
+ compress="true"
+ >
+ <metainf dir="doc" includes="*_lic.txt"/>
+ <service type="java.sql.Driver" provider="org.hsqldb.jdbc.JDBCDriver"/>
+ <manifest>
+ <attribute name='Specification-Title' value='${hsqldb.title}'/>
+ <attribute name='Specification-Version' value='${hsqldb.version}'/>
+ <attribute name='Specification-Vendor' value='${hsqldb.vendor}'/>
+ <attribute name='Implementation-Title'
+ value='Standard runtime'/>
+ <attribute name='Implementation-Version' value='${build.label}'/>
+ <attribute name='Implementation-Vendor' value='${build.vendor}'/>
+ <!-- This attribute is completely ignored unless the user
+ uses the jar like "java -jar .../hsqldb.jar" -->
+ <attribute name='Main-Class' value='org.hsqldb.util.DatabaseManagerSwing'/>
+ </manifest>
+ <exclude name="org/hsqldb/jmx/**"/>
+ <exclude name="org/hsqldb/util/*Swing.*" if="noswing"/>
+ <exclude name="org/hsqldb/util/*Transfer*"/>
+ <exclude name="org/hsqldb/util/DataAccess*"/>
+ <exclude name="org/hsqldb/util/*Helper*"/>
+ <exclude name="org/hsqldb/util/JDBCTypes.*"/>
+ <exclude name="org/hsqldb/util/SQLStatements.*"/>
+ <exclude name="org/hsqldb/util/QueryTool.*"/>
+ <exclude name="org/hsqldb/util/Zaurus*"/>
+ <exclude name="org/hsqldb/test/*.class"/>
+ <exclude name="org/hsqldb/sample/*.class"/>
+ <exclude name="org/hsqldb/cmdline/**"/>
+ </jar>
+ </target>
+
+ <fileset id='jdbcclasses' dir='classes'
+ includes='
+ org/hsqldb/error/*,
+ org/hsqldb/navigator/*,
+ org/hsqldb/result/*,
+ org/hsqldb/lib/ArrayUtil*,
+ org/hsqldb/lib/CountdownInputStream*,
+ org/hsqldb/lib/HsqlByte*,
+ org/hsqldb/lib/IntValueHashMap*,
+ org/hsqldb/lib/InOutUtil*,
+ org/hsqldb/lib/Iterator*,
+ org/hsqldb/lib/HsqlHeap*,
+ org/hsqldb/lib/HsqlArray*,
+ org/hsqldb/lib/ObjectComparator*,
+ org/hsqldb/lib/IntKeyHashMap*,
+ org/hsqldb/lib/Collection*,
+ org/hsqldb/lib/*List*,
+ org/hsqldb/lib/Set*,
+ org/hsqldb/lib/Hash*,
+ org/hsqldb/lib/HsqlTimer*,
+ org/hsqldb/lib/StringConverter*,
+ org/hsqldb/lib/StringInputStream*,
+ org/hsqldb/lib/java/JavaSystem*,
+ org/hsqldb/lib/FileAccess*,
+ org/hsqldb/ClientConnection*,
+ org/hsqldb/SchemaObject*,
+ org/hsqldb/Collation*,
+ org/hsqldb/HsqlNameManager*,
+ org/hsqldb/SqlInvariants*,
+ org/hsqldb/Constraint*,
+ org/hsqldb/TableBase*,
+ org/hsqldb/Table.*,
+ org/hsqldb/lib/IntKeyIntValueHashMap*,
+ org/hsqldb/lib/DataOutputStream*,
+ org/hsqldb/lib/ReaderInputStream*,
+ org/hsqldb/Scanner*,
+ org/hsqldb/lib/StringUtil*,
+ org/hsqldb/lib/OrderedIntHashSet*,
+ org/hsqldb/Token*,
+ org/hsqldb/lib/CharArrayWriter*,
+ org/hsqldb/resources/sql-state-messages.properties,
+ org/hsqldb/jdbc/JDBC*,
+ org/hsqldb/jdbc/Util*,
+ org/hsqldb/jdbc/pool/*,
+ org/hsqldb/rowio/RowOutputBase*,
+ org/hsqldb/rowio/RowInputBase*,
+ org/hsqldb/rowio/RowOutputBinary*,
+ org/hsqldb/rowio/RowInputBinary*,
+ org/hsqldb/rowio/RowOutputInterface*,
+ org/hsqldb/rowio/RowInputInterface*,
+ org/hsqldb/persist/HsqlDatabaseProperties*,
+ org/hsqldb/persist/HsqlProperties*,
+ org/hsqldb/store/ValuePool*,
+ org/hsqldb/store/HashIndex*,
+ org/hsqldb/store/BaseHashMap*,
+ org/hsqldb/types/*,
+ org/hsqldb/Column*,
+ org/hsqldb/DatabaseURL*,
+ org/hsqldb/HSQLClient*,
+ org/hsqldb/HsqlDateTime*,
+ org/hsqldb/HsqlException*,
+ org/hsqldb/server/HsqlSocketFactory*,
+ org/hsqldb/HTTPClientConnection*,
+ org/hsqldb/jdbcDriver*,
+ org/hsqldb/Row*,
+ org/hsqldb/SessionInterface*,
+ org/hsqldb/types/Types*,
+ org/hsqldb/resources/BundleHandler*,
+ org/hsqldb/resources/sql-error-messages*
+ '/>
+
+ <fileset id='utilclasses' dir='classes' includes='
+ org/hsqldb/util/**
+ org/hsqldb/lib/*Log*
+ '/>
+
+ <fileset id='sqltoolclasses' dir='classes'
+ includes='org/hsqldb/cmdline/**/*.class
+ org/hsqldb/lib/RCData*
+ org/hsqldb/lib/RefCapablePropertyResourceBundle*
+ org/hsqldb/lib/RefCapableRBInterface*
+ org/hsqldb/lib/ValidatingResourceBundle*
+ org/hsqldb/lib/AppendableException*
+ org/hsqldb/lib/FileAccess*
+ org/hsqldb/lib/StringUtil*
+ org/hsqldb/lib/BasicTextJdkLogFormatter*
+ org/hsqldb/lib/FrameworkLogger*
+ org/hsqldb/resources/jdklogging-default.properties
+ '/>
+ <fileset id='sqltoolres' dir='classes'
+ includes='org/hsqldb/cmdline/**/*.text
+ org/hsqldb/cmdline/**/*.properties
+ '/>
+
+ <target name="sqltool" depends="classes15, -cmdline, -prep-license-files"
+ description="Build 'sqltool.jar' file">
+ <fail unless="ant.java.iscjava15"
+ message="Can't build sqltool with JVM less than v. 1.5"/>
+ <jar jarfile="lib/sqltool.jar" compress="true" filesonly="true">
+ <metainf dir="doc" includes="*_lic.txt"/>
+ <manifest>
+ <attribute name='Specification-Title' value='${hsqldb.title}'/>
+ <attribute name='Specification-Version' value='${hsqldb.version}'/>
+ <attribute name='Specification-Vendor' value='${hsqldb.vendor}'/>
+ <attribute name='Implementation-Title' value='SqlTool Client'/>
+ <attribute name='Implementation-Version' value='${build.label}'/>
+ <attribute name='Implementation-Vendor' value='${build.vendor}'/>
+ <attribute name='Main-Class' value='org.hsqldb.cmdline.SqlTool'/>
+ <attribute name='Class-Path'
+ value='hsqldb-2.0.0.jar hsqljdbc-2.0.0.jar hsqldbmain.jar-2.0.0.jar hsqldb.jar hsqljdbc.jar hsqldbmain.jar'/>
+ </manifest>
+ <fileset refid='sqltoolclasses'/>
+ <fileset refid='sqltoolres'/>
+ </jar>
+ </target>
+
+<!-- classes referenced by the org.hsqldb.jdbc package classes -->
+<!-- or the org.hsqldb.jdbcDriver class are included here with some -->
+<!-- ommissions where the calling methods are not actually used -->
+ <target name="hsqljdbc" depends="classes16, -prep-license-files"
+ description="Build the hsqljdbc.jar for network clients">
+ <jar jarfile="lib/hsqljdbc.jar" compress="true">
+ <service type="java.sql.Driver" provider="org.hsqldb.jdbc.JDBCDriver"/>
+ <metainf dir="doc" includes="*_lic.txt"/>
+ <manifest>
+ <attribute name='Specification-Title' value='${hsqldb.title}'/>
+ <attribute name='Specification-Version' value='${hsqldb.version}'/>
+ <attribute name='Specification-Vendor' value='${hsqldb.vendor}'/>
+ <attribute name='Implementation-Title'
+ value='JDBC client runtime'/>
+ <attribute name='Implementation-Version' value='${build.label}'/>
+ <attribute name='Implementation-Vendor' value='${build.vendor}'/>
+ </manifest>
+ <fileset refid='jdbcclasses'/>
+ </jar>
+ </target>
+
+ <target name="hsqldbutil" depends="util, swing, -prep-license-files"
+ description="Build the utility hsqldbutil.jar">
+ <jar jarfile="lib/hsqldbutil.jar" compress="true">
+ <metainf dir="doc" includes="*_lic.txt"/>
+ <manifest>
+ <attribute name='Specification-Title' value='${hsqldb.title}'/>
+ <attribute name='Specification-Version' value='${hsqldb.version}'/>
+ <attribute name='Specification-Vendor' value='${hsqldb.vendor}'/>
+ <attribute name='Implementation-Title'
+ value='Utilities runtime, without JDBC driver'/>
+ <attribute name='Implementation-Version' value='${build.label}'/>
+ <attribute name='Implementation-Vendor' value='${build.vendor}'/>
+ <attribute name='Main-Class' value='org.hsqldb.cmdline.SqlTool'/>
+ <attribute name='Class-Path'
+ value='hsqldb-2.0.0.jar hsqldbmain.jar hsqldb.jar'/>
+ </manifest>
+ <fileset refid='utilclasses'/>
+ <fileset refid='sqltoolclasses'/>
+ <fileset refid='sqltoolres'/>
+ </jar>
+ </target>
+
+ <target name="-doclink-1.6" if="ant.java.iscjava16">
+ <!-- CHANGEME: use official jdk 1.6 and JEE 5 links
+ when glassfish/mustang are finalized -->
+ <property name="jse.doc.link"
+ value="http://java.sun.com/javase/6/docs/api/"/>
+ <property name="jee.doc.link"
+ value="http://java.sun.com/j2ee/1.4/docs/api/"/>
+ </target>
+
+ <target name="-doclink-1.4"
+ depends="-doclink-1.6"
+ if="ant.java.iscjava14"
+ unless="ant.java.iscjava16">
+ <property name="jse.doc.link"
+ value="http://java.sun.com/j2se/1.4.2/docs/api/"/>
+ <property name="jee.doc.link"
+ value="http://java.sun.com/j2ee/1.4/docs/api/"/>
+ </target>
+
+ <target name="-doclink-1.2"
+ depends="-doclink-1.4"
+ if="ant.java.iscjava12"
+ unless="ant.java.iscjava14">
+ <property name="jse.doc.link"
+ value="http://java.sun.com/j2se/1.3/docs/api/"/>
+ <property name="jee.doc.link"
+ value="http://java.sun.com/j2ee/sdk_1.3/techdocs/api/"/>
+ </target>
+
+ <target name="javadoc" depends="-prepare-javadoc,-set-jvmvars,-doclink-1.2"
+ description="Create javadoc for the distribution package">
+ <!-- TODO: Find out why JDBCDriver class is listed twice in the lass
+ list pane, but only when All Classes selected
+ only listed once if jdbc package is selected). -->
+ <javadoc
+ sourcefiles="src/org/hsqldb/jdbc/JDBCDriver.java,
+ src/org/hsqldb/Trigger.java,
+ src/org/hsqldb/server/Server.java,
+ src/org/hsqldb/server/WebServer.java,
+ src/org/hsqldb/server/ServerAcl.java,
+ src/org/hsqldb/sample/TriggerSample.java,
+ src/org/hsqldb/sample/SqlFileEmbedder.java,
+ src/org/hsqldb/lib/RCData.java,
+ src/org/hsqldb/lib/tar/DbBackup.java,
+ src/org/hsqldb/test/TestScriptRunner.java,
+ src/org/hsqldb/cmdline/SqlFile.java,
+ src/org/hsqldb/util/MainInvoker.java,
+ src/org/hsqldb/cmdline/SqlTool.java"
+ destdir="doc/apidocs"
+ stylesheetfile="doc-src/apidocs/javadoc.css"
+ docencoding="UTF-8"
+ charset="UTF-8"
+ author="true"
+ version="false"
+ use="true"
+ public="true"
+ failonerror="true"
+ windowtitle="${hsqldb.title} ${hsqldb.version} API"
+ doctitle="${hsqldb.title} ${hsqldb.version}"
+ bottom="<i>Copyright © 2001 - 2009 HSQL Development Group.</i>">
+ <classpath>
+ <pathelement location="${servletapi.lib}"/>
+ <pathelement location="${junit38.lib}"/>
+ </classpath>
+ <packageset dir='src'>
+ <include name='org/hsqldb/jdbc'/>
+ </packageset>
+ <link href="${jse.doc.link}"/>
+ <link href="${jee.doc.link}"/>
+ <tag name="todo" enabled="false"/>
+ <tag name="revised" enabled="false"/>
+ <tag name="jboss.xmbean" enabled="false"/>
+ <tag name="jmx.mbean" enabled="false"/>
+ <tag name="jmx.managed-attribute" enabled="false"/>
+ <tag name="jmx.managed-operation" enabled="false"/>
+ <tag name="jmx.managed-operation-parameter" enabled="false"/>
+ </javadoc>
+ <fixcrlf preservelastmodified='true' eol="lf" encoding="UTF-8"
+ srcdir="doc/apidocs" includes="**/*.css, **/*.html, **/package-list"/>
+ </target>
+
+ <target name="javadocdev"
+ depends="-prepare-javadoc,-set-jvmvars,-doclink-1.2"
+ description="Create javadoc for all HSQLDB code-base classes">
+ <javadoc
+ destdir="doc/apidocs"
+ docencoding="UTF-8"
+ stylesheetfile="doc-src/apidocs/javadoc.css"
+ charset="UTF-8"
+ linksource="true"
+ author="true"
+ version="true"
+ use="true"
+ package="true"
+ failonerror="true"
+ windowtitle="${hsqldb.title} ${hsqldb.version} Product Dev. API"
+ doctitle="${hsqldb.title} ${hsqldb.version} Product"
+ bottom="<i>Copyright © 2001 - 2009 HSQL Development Group.</i>">
+ <fileset dir="src" includes="**/*.java"/>
+ <!-- Fileset is really good for maintenance and control purposes,
+ but it makes the generator produce an incredible amount of
+ output when there are no errors. The verbose attribute
+ doesn't help at all. -->
+ <classpath>
+ <pathelement path="${java.class.path}"/>
+ <pathelement location="${junit38.lib}"/>
+ <pathelement location="${servletapi.lib}"/>
+ </classpath>
+ <link href="${jse.doc.link}"/>
+ <link href="${jee.doc.link}"/>
+ <tag name="todo"/>
+ <tag name="revised"/>
+ <tag name="jboss.xmbean"/>
+ <tag name="jmx.mbean"/>
+ <tag name="jmx.managed-attribute"/>
+ <tag name="jmx.managed-operation"/>
+ <tag name="jmx.managed-operation-parameter"/>
+ </javadoc>
+ <fixcrlf preservelastmodified='true' eol="lf" encoding="UTF-8"
+ srcdir="doc/apidocs" includes="**/*.css, **/*.html, **/package-list"/>
+ </target>
+
+ <target name="sqlfile-scanner"
+ description="Run JFlex to regenerate SqlFileScanner.java">
+ <delete file="src/org/hsqldb/cmdline/sqltool/SqlFileScanner.java"/>
+ <antcall target="-sqlfile-scanner"/>
+ </target>
+
+ <target name="-sqlfile-scanner">
+ <!-- Prepares SqlFileScanner.java, running Jflex only if needed.
+ Purpose here is to require jflex library only if user modifies
+ the *.flex file.
+ -->
+
+ <!-- We no longer remove SqlFileScanner.java automatically.
+ We can't depend on file timestamps, because Subversion doesn't
+ preserve them, so we must depend on the user to manually remove
+ SqlFileScanner.java if they want it regenerated.
+ <dependset>
+ <srcfilelist dir="src/org/hsqldb/cmdline">
+ <file name="sqltool.flex"/>
+ </srcfilelist>
+ <targetfilelist dir="src/org/hsqldb/cmdline/sqltool">
+ <file name="SqlFileScanner.java"/>
+ </targetfilelist>
+ </dependset>
+ -->
+ <available property="skip.jflex" type="file"
+ file="src/org/hsqldb/cmdline/sqltool/SqlFileScanner.java"/>
+ <antcall target="-condl-jflex"/>
+ <!-- JFlex will only run if SqlFileScanner.java does not exist -->
+ <copy todir="${swsrc}/org/hsqldb/cmdline/sqltool"
+ file="src/org/hsqldb/cmdline/sqltool/SqlFileScanner.java"/>
+ </target>
+
+ <target name="-init-jflex">
+ <available property='_jflex_available' classpath='${jflex.lib}'
+ classname='JFlex.anttask.JFlexTask'/>
+ <fail unless='_jflex_available'
+ message="Place JFlex library at '${jflex.lib}', or set property 'jflex.lib' (available from http://sourceforge.net/projects/jflex/)"/>
+ <taskdef classname="JFlex.anttask.JFlexTask" name="jflex"
+ classpath='${jflex.lib}'/>
+ </target>
+
+ <target name="-condl-jflex" unless="skip.jflex">
+ <!-- Only reason for this method is that target dependencies (if/unless)
+ get executed BEFORE the main target -->
+ <antcall target="jflex"/>
+ </target>
+
+ <target name="jflex" depends="-init-jflex">
+ <jflex file="src/org/hsqldb/cmdline/sqltool.flex" destdir="src"/>
+ <!-- A limitation of the jflex task is that you must specify the .flex
+ files individually and explicitly. No filesets, etc. -->
+ </target>
+
+ <target name="-update-switch-branch" unless="switch.inplace">
+ <mkdir dir='${swsrc}'/>
+ <copy todir='${swsrc}' preservelastmodified='true'>
+ <fileset dir='src' includes='**/*.java'/>
+ </copy>
+ </target>
+
+ <target name="-clean-switch-branch" unless="switch.inplace">
+ <delete dir="${swsrc}"/>
+ </target>
+
+ <target name="update-readme"
+ description="Update the version number in the root readme.txt file">
+ <!-- Want to have this target depended upon by some other target that
+ is always run after changing the version yet before tagging a
+ release.
+ Unfortunately, there is no such target, since somebody could do all
+ testing, then change the version number right before tagging. :(
+ Therefore, instead of automating, we just have the distribution
+ assembly task fail if the readme.txt is not up to date w/ version.
+ (Can't actually change readme.txt when assembling, since tagging
+ must be completed before-hand).
+ -->
+ <copy file="doc-src/readme-template.txt" tofile="readme.txt"
+ overwrite="true">
+ <filterchain> <expandproperties/> </filterchain>
+ </copy>
+ </target>
+
+ <!-- ***********************************************************
+ ************* DOCBOOK v.5 BUILD SYSTEM *********************
+ *************************************************************-->
+ <!-- See the file doc-src/readme-docauthors.txt for details about out DocBook
+ build system. -->
+ <import file="build-docbook.xml"/>
+
+ <target name="-prep-images">
+ <fail unless="dbimage.path">Ant property 'dbimage.path' is
+required. This is normally the "images" subdirectory of a DocBook v.5 NS Style
+Sheet distribution. The docbook-xsl-ns distro can be downloaded from
+'http://docbook.sourceforge.net/projects/docbook'. Set property 'dbimage.path'
+to the local path to the images subdirectory (perhaps in file
+'build.properties').</fail>
+ <copy todir="doc-src/images/db">
+ <fileset dir="${dbimage.path}"/>
+ </copy>
+ </target>
+
+ <target name="gen-docs" description="Generate Docbook documents for project"
+ depends="validate-docs, -prep-images, -gen-docs-setup">
+ <antcall target="docbook-transform">
+ <param name="doc.name" value="guide"/>
+ </antcall>
+ <antcall target="docbook-transform">
+ <param name="doc.name" value="util-guide"/>
+ </antcall>
+ <antcall target="-gen-docs-complete"/>
+ </target>
+
+ <target name="validate-docs"
+ description="Validate project DocBook source files using a modified version of Sun's MSV Validator">
+ <antcall target="validate-doc">
+ <param name="doc.name" value="guide"/>
+ </antcall>
+ <antcall target="validate-doc">
+ <param name="doc.name" value="util-guide"/>
+ </antcall>
+ </target>
+
+ <target name="-ensure-catalog" unless="_catalog.present">
+ <copy file="build/rng-catalog-sample.xml"
+ tofile="stylesheets/rng-catalog.xml"/>
+ <echo>Just created a local 'stylesheets/rng-catalog.xml' file for you.
+To speed up XML validations, you should edit this file.</echo>
+ </target>
+
+ <target name="-validation-setup">
+ <available property="_catalog.present" file="stylesheets/rng-catalog.xml"
+ type="file"/>
+ <antcall target="-ensure-catalog"/>
+ </target>
+
+ <target name="-prep-license-files">
+ <fixcrlf destdir="doc" preservelastmodified='true' eol="crlf"
+ srcdir="doc-src" includes="*_lic.txt"/>
+ </target>
+</project>
diff --git a/build/cfdistro.bash b/build/cfdistro.bash
new file mode 100755
index 0000000..0907de0
--- /dev/null
+++ b/build/cfdistro.bash
@@ -0,0 +1,119 @@
+#!/bin/bash -p
+PROGNAME="${0##*/}"
+
+# Copyright (c) 2001-2009, The HSQL Development Group
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+# Redistributions of source code must retain the above copyright notice, this
+# list of conditions and the following disclaimer.
+#
+# Redistributions in binary form must reproduce the above copyright notice,
+# this list of conditions and the following disclaimer in the documentation
+# and/or other materials provided with the distribution.
+#
+# Neither the name of the HSQL Development Group nor the names of its
+# contributors may be used to endorse or promote products derived from this
+# software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL HSQL DEVELOPMENT GROUP, HSQLDB.ORG,
+# OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+# EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+# PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+# LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+# ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+# This script generates a concise listing of differences between two
+# distributions.
+# This script obviously requires Bash. I don't know whether it works on Cygwin.
+
+# You run this script against two directory branches.
+# If you are starting with two zip distributions, you must extract them first.
+# If you are going to investigate differences, then set up the distribution
+# directories so that the highest directories of interest are peers, like
+# cd /tmp/me
+# mkdir cfdir
+# unzip -q /tmp/hsqldb-x1.zip
+# mv hsqldb-x1/hsqldb cfdir/x1
+# unzip -q /tmp/hsqldb-x2.zip
+# mv hsqldb-x2/hsqldb cfdir/x2
+# cd cfdir
+# /path/to/cfdistro.bash x1 x2
+# It is then very easy to view differences between the distributions textually
+# or graphically. If your file difference report (".../files.diff") contains
+# < hsqldb/testrun/hsqldb/TestSelf.txt -rw-r--r-- 1 blaine blaine 52585
+# > hsqldb/testrun/hsqldb/TestSelf.txt -rw-r--r-- 1 blaine blaine 52587
+# then you use vim to check encodings and fileformat (EOLs), diff for
+# differences in text, or gvimdiff for diffrences graphically.
+# gvim */hsqldb/testrun/hsqldb/TestSelf.txt # Check encoding + fileformat
+# diff */hsqldb/testrun/hsqldb/TestSelf.txt # See differences in text
+# gvimdiff */hsqldb/testrun/hsqldb/TestSelf.txt # See differences graphically
+
+# This script can easily be enhanced to do the extraction and directory setup
+# steps.
+# We purposefully ignore directory and file modification timestamps.
+# Modify the perl regular expressions to include or exclude other items in
+# the "ls -l" listings.
+# The generation timestamps and version labels inside of generated JavaDoc
+# output will make these files differ. I usually manually compare an index
+# file and an actual class HTML file, then exclude the rest from the summary
+# file with a command like
+# perl -ni -we 'print unless m:^. doc/apidocs/:;' /tmp/cfdistro-13756/files.diff
+
+shopt -s xpg_echo
+set +u
+
+Failout() {
+ echo "Aborting $PROGNAME: $*" 1>&2
+ exit 1
+}
+[ -n "$TMPDIR" ] || TMPDIR=/tmp
+WORKDIR="$TMPDIR/${PROGNAME%.*}-$$"
+mkdir "$WORKDIR" || Failout "Failed to make work director '$WORKDIR'"
+
+type -t perl >&- || Failout "'$PROGNAME' requires 'perl' in your search path"
+
+[ $# -ne 2 ] && Failout "SYNTAX: $PROGNAME dir1/path dir2/path"
+BASE1="$1"; shift
+BASE2="$1"; shift
+
+STARTDIR="$PWD"
+cd "$BASE1" || Failout "Failed to cd to first base dir: $BASE1"
+find * -type d | xargs ls -ld |
+ perl -nwe 'm/(.+?)200\d-\d\d-\d\d \d\d:\d\d\s+(.+)/; print "$2 $1\n";' |
+ sort > $WORKDIR/dirs.1
+find * -type f | xargs ls -ld |
+ perl -nwe 'm/(.+?)200\d-\d\d-\d\d \d\d:\d\d\s+(.+)/; print "$2 $1\n";' |
+ sort > $WORKDIR/files.1
+
+cd "$STARTDIR"
+cd "$BASE2" || Failout "Failed to cd to first base dir: $BASE2"
+find * -type d | xargs ls -ld |
+ perl -nwe 'm/(.+?)200\d-\d\d-\d\d \d\d:\d\d\s+(.+)/; print "$2 $1\n";' |
+ sort > $WORKDIR/dirs.2
+find * -type f | xargs ls -ld |
+ perl -nwe 'm/(.+?)200\d-\d\d-\d\d \d\d:\d\d\s+(.+)/; print "$2 $1\n";' |
+ sort > $WORKDIR/files.2
+
+cd "$STARTDIR"
+cd "$WORKDIR" || Failout "Failed to cd to work dir: $WORKDIR"
+declare -i retval=0
+cmp -s dirs.1 dirs.2 || {
+ ((retval = retval + 1))
+ diff dirs.1 dirs.2 | egrep '^[<>]' > dirs.diff
+ echo "See dir diffs at $WORKDIR/dirs.diff"
+}
+cmp -s files.1 files.2 || {
+ ((retval = retval + 1))
+ diff files.1 files.2 | egrep '^[<>]' > files.diff
+ echo "See dir diffs at $WORKDIR/files.diff"
+}
+
+exit $retval
diff --git a/build/ivy.xml b/build/ivy.xml
new file mode 100644
index 0000000..be04d78
--- /dev/null
+++ b/build/ivy.xml
@@ -0,0 +1,60 @@
+<ivy-module version="2.0">
+ <!-- $Id: ivy.xml 727 2009-01-08 00:19:48Z unsaved $ -->
+ <info organisation="admc" module="docbook"/>
+ <configurations>
+ <conf name="baseconf" visibility="private"/> <!-- basic XML -->
+ <conf name="admc-rs-msv"
+ description="Single Catalog-Resolving Schematron-Capable MSV jar file"/>
+ <conf name="msv" description="Sun MSV" extends="baseconf"/>
+ <conf name="xalan" description="Xalan Xslt" extends="baseconf"/>
+ <conf name="fop" description="FOP"/>
+ </configurations>
+ <dependencies>
+ <dependency name="relames" rev="20060319"
+ transitive="false" conf="msv->default"/>
+ <dependency name="msv" rev="20081113"
+ transitive="false" conf="msv->default"/>
+ <dependency name="relaxngDatatype" rev="20081113"
+ transitive="false" conf="msv->default"/>
+ <dependency name="xsdlib" rev="20081113"
+ transitive="false" conf="msv->default"/>
+ <dependency name="isorelax" rev="20081113"
+ transitive="false" conf="msv->default"/>
+ <dependency name="fop" rev="0.94"
+ transitive="false" conf="fop->default"/>
+ <dependency name="fop-hyph" rev="1.2"
+ transitive="false" conf="fop->default"/>
+ <dependency name="jai_codec" rev="1.1.3"
+ transitive="false" conf="fop->default"/>
+ <dependency name="jai_core" rev="1.1.3"
+ transitive="false" conf="fop->default"/>
+ <dependency name="xmlgraphics-commons" rev="1.2"
+ transitive="false" conf="fop->default"/>
+ <dependency name="avalon-framework" rev="4.2.0"
+ transitive="false" conf="fop->default"/>
+ <dependency name="batik-all" rev="1.6"
+ transitive="false" conf="fop->default"/>
+ <dependency name="commons-io" rev="1.3.1"
+ transitive="false" conf="fop->default"/>
+ <dependency name="commons-logging" rev="1.1.1"
+ transitive="false" conf="fop->default"/>
+ <dependency name="xalan" rev="2.7.1"
+ transitive="false" conf="xalan->default; msv->default"/>
+ <dependency name="serializer" rev="2.7.1"
+ transitive="false" conf="xalan->default"/>
+ <dependency name="docbook-ext-xalan2" rev="1.73.2"
+ transitive="false" conf="xalan->default"/>
+ <dependency name="xml-apis" rev="1.3"
+ transitive="false" conf="baseconf->default"/>
+ <dependency name="xercesImpl" rev="2.9.0"
+ transitive="false" conf="baseconf->default"/>
+ <dependency name="resolver" rev="1.2"
+ transitive="false" conf="msv->default"/>
+ <dependency name="admc-rs-msv" rev="1.0" transitive="false"
+ conf="admc-rs-msv->default; xalan->default"/>
+ <!-- Primary purpose of this jar is for the MSV validator.
+ It is also added to the XSLT CLASSPATH only to add the XInclude
+ settings file to the CLASSPATH. Needed by Xalan during XSLT.
+ -->
+ </dependencies>
+</ivy-module>
diff --git a/build/ivysettings-sample.xml b/build/ivysettings-sample.xml
new file mode 100644
index 0000000..e6091c0
--- /dev/null
+++ b/build/ivysettings-sample.xml
@@ -0,0 +1,21 @@
+<ivysettings>
+<!--
+$Id: ivysettings-sample.xml 643 2008-12-29 07:08:49Z unsaved $
+
+Edit your copy of this file (named "ivysettings.xml"), or replace it completely.
+This file will work with any directory on any web server which
+holds the plain jar files with names like BASENAME-VERSION.jar.
+-->
+
+ <caches checkUpToDate="false" resolutionCacheDir="${user.home}/.ivycache"
+ ivyPattern="[module]-[revision].xml"
+ defaultCacheDir="${user.home}/.ivycache"
+ repositoryCacheDir="${user.home}/lib-repos"
+ artifactPattern="[artifact]-[revision].[ext]"/>
+ <settings defaultResolver="default"/>
+ <resolvers>
+ <url name="default">
+ <artifact pattern="${repos.url}/[artifact]-[revision].[ext]"/>
+ </url>
+ </resolvers>
+</ivysettings>
diff --git a/build/jdkcodeswitch.list b/build/jdkcodeswitch.list
new file mode 100644
index 0000000..87296c7
--- /dev/null
+++ b/build/jdkcodeswitch.list
@@ -0,0 +1,31 @@
+# Files listed here will be code-switched
+# This eliminates the need for CodeSwitcher to scan all source files.
+
+org/hsqldb/HsqlDateTime.java
+org/hsqldb/lib/tar/TarFileOutputStream.java
+org/hsqldb/lib/tar/TarGenerator.java
+org/hsqldb/lib/tar/TarReader.java
+org/hsqldb/jdbc/JDBCCallableStatement.java
+org/hsqldb/jdbc/JDBCConnection.java
+org/hsqldb/jdbc/JDBCDatabaseMetaData.java
+org/hsqldb/jdbc/JDBCDataSource.java
+org/hsqldb/jdbc/JDBCDriver.java
+org/hsqldb/jdbc/JDBCNClob.java
+org/hsqldb/jdbc/JDBCParameterMetaData.java
+org/hsqldb/jdbc/JDBCPreparedStatement.java
+org/hsqldb/jdbc/JDBCResultSet.java
+org/hsqldb/jdbc/JDBCResultSetMetaData.java
+org/hsqldb/jdbc/JDBCStatement.java
+org/hsqldb/jdbc/Util.java
+org/hsqldb/jdbc/pool/BaseConnectionWrapper.java
+org/hsqldb/jdbc/pool/JDBCConnectionPoolDataSource.java
+org/hsqldb/jdbc/pool/JDBCPooledConnection.java
+org/hsqldb/jdbc/pool/ManagedPoolDataSource.java
+org/hsqldb/jdbc/Util.java
+org/hsqldb/lib/java/JavaSystem.java
+org/hsqldb/lib/SimpleLog.java
+org/hsqldb/lib/StringConverter.java
+org/hsqldb/server/PgType.java
+org/hsqldb/test/TestBug778213.java
+org/hsqldb/util/ConnectionDialogCommon.java
+org/hsqldb/persist/Logger.java
diff --git a/build/rng-catalog-sample.xml b/build/rng-catalog-sample.xml
new file mode 100644
index 0000000..f442456
--- /dev/null
+++ b/build/rng-catalog-sample.xml
@@ -0,0 +1,23 @@
+<?xml version="1.0"?>
+<!-- $Id: rng-catalog-sample.xml 826 2009-01-17 05:04:52Z unsaved $ -->
+
+<!-- IMPORTANT: To set up your build environment, edit the copy of this file
+ at "stylesheets/rng-catalog.xml", not the one at
+ "build/rng-catalog-sample.xml". -->
+
+<!DOCTYPE catalog PUBLIC "-//OASIS//DTD Entity Resolution XML Catalog V1.0//EN"
+ "http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd">
+
+<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog" prefer="public">
+ <public publicId="-//OASIS/ENTITIES DocBook Character Entities V4.5//EN"
+ uri="file:../local/db4-entities/dbcentx.mod"/>
+ <!-- Set the uri value above to match the your local setting of property
+ "dbcentx.url" (perhapse in "local-docbook.properties" or
+ "build.properties"). This will eliminate the Internet dependency and
+ speed up validations.
+ Relative paths must be relative to this file.
+ If the designated hostname or file DOES NOT EXIST, the setting will
+ be ignored. Make sure to not set to http URL for a host name that
+ does exist, with a wrong path, or the server error message will be
+ parsed! -->
+</catalog>
diff --git a/build/run.test.suite.cmd b/build/run.test.suite.cmd
new file mode 100755
index 0000000..374aa98
--- /dev/null
+++ b/build/run.test.suite.cmd
@@ -0,0 +1,2 @@
+call setenv.cmd
+ant -f test.xml run.test.suite
diff --git a/build/setenv.cmd b/build/setenv.cmd
new file mode 100755
index 0000000..1a8d12e
--- /dev/null
+++ b/build/setenv.cmd
@@ -0,0 +1,7 @@
+REM basic environment setup
+REM change as needed
+
+set JAVA_HOME=C:\Program Files\Java\jdk1.6.0
+set ANT_HOME=C:\java\lib\ant
+set ANT_OPTS=-Xmx512m
+set PATH=%JAVA_HOME%\bin;%ANT_HOME%\bin;%PATH%
diff --git a/build/test.dbmd.convert.properties b/build/test.dbmd.convert.properties
new file mode 100644
index 0000000..8fab5cb
--- /dev/null
+++ b/build/test.dbmd.convert.properties
@@ -0,0 +1,7 @@
+## Note:
+##
+## Most test.dbmd.convert properties have been moved to /org/hsqldb/resources
+## under the test source folder and are now read using the bundle handler facility.
+##
+## System properties now take precedence, so you can use this file
+## to override the values in the default test.dbmd.convert properties file.
diff --git a/build/test.properties b/build/test.properties
new file mode 100644
index 0000000..bd3cba6
--- /dev/null
+++ b/build/test.properties
@@ -0,0 +1,7 @@
+## Note:
+##
+## Most test properties have been moved to /org/hsqldb/resources
+## under the test source folder and are now read using the bundle handler facility.
+##
+## System properties now take precedence, so you can use this file
+## to override the values in the default test.properties file.
diff --git a/build/test.xml b/build/test.xml
new file mode 100644
index 0000000..adb4fb5
--- /dev/null
+++ b/build/test.xml
@@ -0,0 +1,307 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project name="hsqldb.test.suite"
+ default="run.test.suite"
+ basedir="..">
+
+ <!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->
+ <!-- B U I L D T I M E S T A M P -->
+ <!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->
+ <tstamp>
+ <format property="_tmpstamp"
+ pattern="yyyy/MM/dd-hh:mm:ss"
+ locale="en"/>
+ </tstamp>
+
+ <!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->
+ <!-- U S E R B U I L D P R O P E R T I E S O V E R R I D E S -->
+ <!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->
+ <property file="${basedir}/build/build.properties"/>
+
+ <!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->
+ <!-- D E F A U L T B U I L D P R O P E R T I E S -->
+ <!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->
+ <property name="test.suite.version"
+ value="1.9.0"/>
+
+ <property name="test.suite.title"
+ value="HSQLDB Test Suite"/>
+
+ <property name="test.suite.vendor"
+ value="The HSQL Development Group"/>
+
+ <property name="test.suite.implementation.title"
+ value="JDBC 4 Test Cases and Utilities"/>
+
+ <property name="test.suite.implementation.label"
+ value="private-${_tmpstamp}"/>
+
+ <property name="test.suite.implementation.vendor"
+ value="${user.name}"/>
+
+ <property name="sqltool.jar"
+ value="${basedir}/lib/sqltool.jar" />
+
+ <property name="hsqldb.jar"
+ value="${basedir}/lib/hsqldb.jar" />
+
+ <property name="hsqldbtest.jar"
+ value="${basedir}/lib/hsqldbtest.jar" />
+
+ <property name="junit.jar"
+ value="${basedir}/lib/junit.jar" />
+
+ <property name="test.suite.jar"
+ value="${basedir}/lib/testsuite.jar" />
+
+ <property name="test.src.dir"
+ value="${basedir}/test-src" />
+
+ <property name="test.classes.dir"
+ value="${basedir}/test-classes" />
+
+ <property name="test.results.dir"
+ value="${basedir}/test-results" />
+
+ <property name="build.debug"
+ value="true" />
+
+ <property name="build.optimize"
+ value="false" />
+
+ <!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->
+ <!-- B U I L D C L A S S P A T H -->
+ <!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->
+ <path id="test.suite.javac.classpath">
+ <pathelement location="${hsqldb.jar}"/>
+ <pathelement location="${sqltool.jar}"/>
+ <pathelement location="${junit.jar}" />
+ </path>
+
+ <path id="test.all.classpath">
+ <pathelement location="${hsqldbtest.jar}"/>
+ <pathelement location="${junit.jar}" />
+ </path>
+
+ <!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->
+ <!-- S H A R E D I N I T I A L I Z A T I O N -->
+ <!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->
+ <target name="-init">
+ <available classname="java.net.IDN"
+ property="ant.java.iscjava16"/>
+
+ <fail unless='ant.java.iscjava16'
+ message="JDK must be 1.6 or greater"/>
+
+ <available file="${hsqldb.jar}"
+ type='file'
+ property="hsqldb.available"/>
+
+ <fail unless='hsqldb.available'
+ message="'hsqldb.jar' must reside at ${hsqldb.jar}"/>
+
+ <available file="${sqltool.jar}"
+ type='file'
+ property="sqltool.available"/>
+
+ <fail unless='sqltool.available'
+ message="'sqltool.jar' must reside at ${sqltool.jar}"/>
+
+ <available file="${junit.jar}"
+ type='file'
+ property="junit.available"/>
+
+ <fail unless='junit.available'
+ message="'junit.jar' must reside at ${junit.jar}"/>
+
+ </target>
+
+ <!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->
+ <!-- M A K E T E S T S U I T E -->
+ <!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->
+ <target name="make.test.suite"
+ description="Builds test classes and creates test suite jar"
+ depends="-init">
+ <mkdir dir="${test.classes.dir}"/>
+
+ <!-- Compile Classes -->
+ <javac srcdir="${test.src.dir}"
+ destdir="${test.classes.dir}"
+ debug="${build.debug}"
+ optimize="${build.optimize}"
+ >
+ <classpath refid="test.suite.javac.classpath"/>
+ <exclude name="**/TestWrapperInvocationHandler.java"/>
+ <!-- Temporarily excluding TestWrapperInvocationHandler until have
+ time to figure out how to resolve missing java.sql.* classes -->
+ <include name="**/*.java"/>
+ </javac>
+
+ <!-- Build Jar -->
+ <jar jarfile="${test.suite.jar}"
+ basedir="${test.classes.dir}">
+ <manifest>
+ <attribute name='Specification-Title'
+ value='${test.suite.title}'/>
+
+ <attribute name='Specification-Version'
+ value='${test.suite.version}'/>
+
+ <attribute name='Specification-Vendor'
+ value='${test.suite.vendor}'/>
+
+ <attribute name='Implementation-Title'
+ value='${test.suite.implementation.title}'/>
+
+ <attribute name='Implementation-Version'
+ value='${test.suite.implementation.label}'/>
+
+ <attribute name='Implementation-Vendor'
+ value='${test.suite.implementation.vendor}'/>
+ </manifest>
+ <include name="**/*"/>
+ </jar>
+ </target>
+
+ <!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->
+ <!-- R U N T E S T S U I T E -->
+ <!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->
+ <target name="run.test.suite"
+ description="Runs the test suite and generates test result reports"
+ depends="-init">
+
+ <available file="${test.suite.jar}"
+ type='file'
+ property="test.suite.jar.available"/>
+
+ <fail unless='test.suite.jar.available'
+ message="The test suite jar must reside at ${test.suite.jar}"/>
+
+ <mkdir dir="${test.results.dir}"/>
+ <mkdir dir="${test.results.dir}/resources"/>
+ <mkdir dir="${test.results.dir}/resources/org"/>
+ <mkdir dir="${test.results.dir}/resources/org/hsqldb"/>
+ <mkdir dir="${test.results.dir}/resources/org/hsqldb/util"/>
+ <mkdir dir="${test.results.dir}/resources/org/hsqldb/util/preprocessor"/>
+
+ <copy todir="${test.results.dir}/resources/org/hsqldb/util/preprocessor">
+ <fileset dir="${test.src.dir}/org/hsqldb/util/preprocessor"
+ includes="*.exp"/>
+ </copy>
+ <copy todir="${test.results.dir}/resources/org/hsqldb/util/preprocessor">
+ <fileset dir="${test.src.dir}/org/hsqldb/util/preprocessor"
+ includes="*.inc"/>
+ </copy>
+ <copy todir="${test.results.dir}/resources/org/hsqldb/util/preprocessor">
+ <fileset dir="${test.src.dir}/org/hsqldb/util/preprocessor"
+ includes="*.src"/>
+ </copy>
+
+ <mkdir dir="${test.results.dir}/resources/org/hsqldb/jdbc"/>
+
+ <copy todir="${test.results.dir}/resources/org/hsqldb/jdbc">
+ <fileset dir="${test.src.dir}/org/hsqldb/jdbc"
+ includes="*.sql"/>
+ </copy>
+
+ <mkdir dir="${test.results.dir}/resources/org/hsqldb/jdbc/resources"/>
+ <mkdir dir="${test.results.dir}/resources/org/hsqldb/jdbc/resources/xml"/>
+
+ <copy todir="${test.results.dir}/resources/org/hsqldb/jdbc/resources/xml">
+ <fileset dir="${test.src.dir}/org/hsqldb/jdbc/resources/xml"
+ includes="*.*"/>
+ </copy>
+
+ <mkdir dir="${test.results.dir}/resources/org/hsqldb/jdbc/resources/sql"/>
+
+ <copy todir="${test.results.dir}/resources/org/hsqldb/jdbc/resources/sql">
+ <fileset dir="${test.src.dir}/org/hsqldb/jdbc/resources/sql"
+ includes="*.*"/>
+ </copy>
+
+ <mkdir dir="${test.results.dir}/resources/org/hsqldb/resources"/>
+
+ <copy todir="${test.results.dir}/resources/org/hsqldb/resources">
+ <fileset dir="${test.src.dir}/org/hsqldb/resources" includes="*.*"/>
+ </copy>
+
+ <!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->
+ <!-- U S E R T E S T P R O P E R T I E S -->
+ <!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->
+ <!-- Now using BundleHandler facility as primary properties loader, but -->
+ <!-- System properties still work (e.g. on command line -Dfoo=xyz or -->
+ <!-- using Ant to load properties files) and now take precedence over -->
+ <!-- bundle handler resources. -->
+ <!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->
+ <!-- In this way, the bulk of the standard properties (that will probably -->
+ <!-- never need to be overriden) stay under the test source folder, hence -->
+ <!-- only specific property overrides need to be placed in the build -->
+ <!-- folder properties files or on the command line as -Dx=y directives. -->
+ <!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->
+ <!-- The only (minor) disadvantage of this new scheme is that the bulk of -->
+ <!-- the test properties will no longer show up in the test report output -->
+ <!-- as environment settings -->
+ <!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->
+ <property file="${basedir}/build/test.properties"/>
+ <property file="${basedir}/build/test.dbmd.convert.properties"/>
+
+ <!-- Execute JUNIT Tests -->
+ <junit showoutput="true"
+ fork="false"
+ failureproperty="tests.failed"
+ errorproperty="tests.failed" >
+ <batchtest todir="${test.results.dir}">
+ <fileset dir="${test.src.dir}"
+ includes="**/*Test.java"/>
+ </batchtest>
+ <classpath>
+ <pathelement location="${test.results.dir}/resources"/>
+ <path path="${hsqldb.jar}"/>
+ <path path="${junit.jar}"/>
+ <path path="${test.suite.jar}"/>
+ </classpath>
+ <syspropertyset id="test.suite.system.properties">
+ <propertyref prefix="hsqldb.test.suite."/>
+ </syspropertyset>
+ <formatter type="xml"/>
+ </junit>
+
+ <mkdir dir="${test.results.dir}/reports"/>
+ <mkdir dir="${test.results.dir}/reports/html"/>
+
+ <!-- Generate Test Reports -->
+ <junitreport todir="${test.results.dir}/reports">
+ <fileset dir="${test.results.dir}">
+ <include name="TEST-*.xml"/>
+ </fileset>
+ <report format="frames"
+ todir="${test.results.dir}/reports/html"/>
+ </junitreport>
+ </target>
+
+ <!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->
+ <!-- R U N T E S T A L L -->
+ <!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->
+ <target name="run.test.all"
+ description="Runs the org.hsqldb.test.TestAll set of tests.">
+
+ <available file="${hsqldbtest.jar}"
+ type='file'
+ property="hsqldbtest.jar.available"/>
+
+ <java classname="org.hsqldb.test.TestAll"
+ classpathref="test.all.classpath"
+ dir="${basedir}/testrun/hsqldb"
+ fork="true"/>
+ </target>
+
+ <!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->
+ <!-- C L E A N T E S T S U I T E -->
+ <!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->
+ <target name="clean.test.suite"
+ description="Deletes compiled classes, test results and suite jar">
+ <delete dir="${test.classes.dir}" />
+ <delete dir="${test.results.dir}" />
+ <delete file="${test.suite.jar}" />
+ </target>
+
+</project>
diff --git a/doc-src/altformats-sect.xml b/doc-src/altformats-sect.xml
new file mode 100644
index 0000000..7d54756
--- /dev/null
+++ b/doc-src/altformats-sect.xml
@@ -0,0 +1,79 @@
+<?xml version="1.0"?>
+<!-- This file is included into docbook source files. -->
+<!-- $Id: altformats-sect.xml 738 2009-01-08 20:19:53Z unsaved $ -->
+
+<!DOCTYPE section [
+ <!ENTITY % dummy24 SYSTEM "entities/global.ent"> %dummy24;
+]>
+
+<section xmlns="http://docbook.org/ns/docbook" version="5.0"
+ xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="altformats-sect">
+ <title>Available formats for this document</title>
+ <simpara>This document is available in several formats.</simpara>
+ <simpara>
+ You may be reading this document right now at &distro_baseurl;, or in
+ a distribution somewhere else.
+ I hereby call the document distribution from which you are reading
+ this, your <emphasis>current distro</emphasis>.
+ </simpara>
+ <simpara>
+ &distro_baseurl; hosts the latest production versions of all available formats.
+ If you want a different format of the same <emphasis>version</emphasis>
+ of the document you are reading now, then you should try your
+ current distro.
+ If you want the latest production version, you should try &distro_baseurl;.
+ </simpara>
+ <simpara>
+ Sometimes, distributions other than &distro_baseurl; do not host all
+ available formats.
+ So, if you can't access the format that you want in your current
+ distro, you have no choice but to use the newest production version at
+ &distro_baseurl;.
+ </simpara>
+
+ <para>
+ <table xml:id="altformats-tbl" frame="all" tocentry="1">
+ <title>Available formats of this document</title>
+ <!-- <tgroup cols="3" align="left" colsep="1" rowsep="1"> -->
+ <tgroup cols="3" align="left">
+ <colspec colwidth="3cm"/>
+ <colspec colwidth="4cm"/>
+ <colspec/>
+ <thead><row>
+ <entry>format</entry>
+ <entry>your distro</entry>
+ <entry>at &distro_baseurl;</entry>
+ </row></thead>
+ <tbody>
+ <row>
+ <entry>
+ Chunked HTML
+ </entry><entry>
+ <link xlink:href="index.html"/>
+ </entry><entry>
+ <link xlink:href="&distro_baseurl;/&doc_basename;/"/>
+ </entry>
+ </row><row>
+ <entry>
+ All-in-one HTML
+ </entry><entry>
+ <link xlink:href="&doc_basename;.html"/>
+ </entry><entry>
+ <link xlink:href="&distro_baseurl;/&doc_basename;/&doc_basename;.html"/>
+ </entry>
+ </row><row>
+ <entry>
+ PDF
+ </entry><entry>
+ <link xlink:href="&doc_basename;.pdf"/>
+ </entry><entry>
+ <link xlink:href="&distro_baseurl;/&doc_basename;/&doc_basename;.pdf"/>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ If you are reading this document now with a standalone PDF reader, the
+ <guilabel>your distro</guilabel> links may not work.
+ </para>
+</section>
diff --git a/doc-src/apidocs/hsqldb.gif b/doc-src/apidocs/hsqldb.gif
new file mode 100644
index 0000000..3585222
--- /dev/null
+++ b/doc-src/apidocs/hsqldb.gif
Binary files differ
diff --git a/doc-src/apidocs/javadoc.css b/doc-src/apidocs/javadoc.css
new file mode 100644
index 0000000..5b3fb93
--- /dev/null
+++ b/doc-src/apidocs/javadoc.css
@@ -0,0 +1,91 @@
+/* Javadoc style sheet */
+
+/* Define colors, fonts and other style attributes here to override the defaults */
+
+/* Page background color, width % */
+body { background-color: #FFFFFF; padding-right: 1em; }
+
+/* Table colors */
+.TableHeadingColor { background: #CCCCFF } /* Dark mauve */
+.TableSubHeadingColor { background: #EEEEFF } /* Light mauve */
+.TableRowColor { background: #FFFFFF } /* White */
+
+/* Font used in left-hand frame lists */
+.FrameTitleFont { font-size: 10pts; font-family: Helvetica, Arial, san-serif }
+.FrameHeadingFont { font-size: 10pts; font-family: Helvetica, Arial, san-serif }
+.FrameItemFont { font-size: 10pts; font-family: Helvetica, Arial, san-serif }
+
+/* Example of smaller, sans-serif font in frames */
+/* .FrameItemFont { font-size: 10pt; font-family: Helvetica, Arial, sans-serif } */
+
+/* Navigation bar fonts and colors */
+.NavBarCell1 { background-color: #EEEEFF;}/* Light mauve */
+.NavBarCell1Rev { background-color: #00008B;}/* Dark Blue */
+.NavBarFont1 { font-family: Arial, Helvetica, sans-serif; color: #000000;}
+.NavBarFont1Rev { font-family: Arial, Helvetica, sans-serif; color: #FFFFFF;}
+
+.NavBarCell2 { font-family: Arial, Helvetica, sans-serif; background-color: #FFFFFF;}
+.NavBarCell3 { font-family: Arial, Helvetica, sans-serif; background-color: #FFFFFF;}
+
+.GenericDocumentation { color: #000000; }
+
+DIV.ReleaseSpecificDocumentation {
+ color: #006A00;
+ background-color: #EEEEFF;
+ border: 2px ridge white;
+ padding-top: 5px;
+ padding-right: 10px;
+ padding-bottom: 5px;
+ padding-left: 10px;
+ text-align: justify;
+}
+
+DIV.ReleaseSpecificDocumentation h3 {
+ margin-top: 0px;
+ margin-left: 0px;
+ margin-right: 0px;
+ padding-top: 14px;
+ padding-right: 0px;
+ padding-bottom: 15px;
+ padding-left: 50px;
+ border-top: 1px dashed rgb(120,172,255);
+ border-bottom: 1px dashed rgb(120,172,255);
+ background: url(hsqldb.gif) #E6E6FF no-repeat left center;
+}
+
+PRE.JavaCodeExample {
+ color: #000000;
+ background-color: #EEEEEE;
+ border: 1px ridge white;
+ padding-top: 1em;
+ padding-right: 1em;
+ padding-bottom: 0em;
+ padding-left: 1em;
+}
+
+.JavaStringLiteral { color: #99006B; }
+.JavaNumericLiteral { color: #780000; }
+.JavaKeyWord { color: #000099; font-weight: bold; }
+
+PRE.SqlCodeExample {
+ /*color: #550022;*/
+ color: #601030;
+ background-color: #EEEEEE;
+ border: 1px ridge white;
+ font-weight: bold;
+ padding-top: 1em;
+ padding-right: 1em;
+ padding-bottom: 0em;
+ padding-left: 1em;
+ line-height: 150%;
+}
+
+PRE.GeneralExample {
+ color: #000000;
+ background-color: #EEEEEE;
+ border: 1px ridge white;
+ padding-top: 1em;
+ padding-right: 1em;
+ padding-bottom: 0em;
+ padding-left: 1em;
+}
diff --git a/doc-src/branding-frag.xhtml b/doc-src/branding-frag.xhtml
new file mode 100644
index 0000000..5f30c34
--- /dev/null
+++ b/doc-src/branding-frag.xhtml
@@ -0,0 +1,5 @@
+<!-- $Id: branding-frag.xhtml 3510 2010-03-08 17:38:55Z unsaved $ -->
+
+<div class="branding">
+ <img src="../images/hypersql_logo.png"/>
+</div>
diff --git a/doc-src/docbook.css b/doc-src/docbook.css
new file mode 100644
index 0000000..0890083
--- /dev/null
+++ b/doc-src/docbook.css
@@ -0,0 +1,106 @@
+/* COMMENT: The shared.css stylesheet for the hsqldb/docs directory and elsewhere *?
+/* This material is published under the Copyrights and Licenses listed at */
+/* and in the directory /hsqldb/docs/hsqldb_lic.txt */
+
+a:visited { color: #000080; }
+a:link { color: #0000BB; }
+a:active { color: #0000FF; }
+
+span.guibutton, span.guilabel, span.guimenu, span.guimenuitem, span.guisubmenu {
+ color: #000080;
+ font-family:sans-serif;
+}
+span.guibutton, span.guilabel {
+ font-weight:bold;
+}
+span.guimenu, span.guimenuitem, span.guisubmenu {
+ font-style:italic;
+}
+
+div.caption { font-size: 80%; }
+
+/********** Admonitions *****************/
+div.tip, div.note {
+ background-color:#FFE4E1;
+ border:2px solid gray;
+}
+div.warning, div.caution, div.important {
+ background-color:#FFE4E1;
+ border:2px solid black;
+}
+/****************************************/
+
+pre.screen {
+ background-color:#F5F5F5;
+ border:1px solid gray;
+ padding:5px;
+ font-family:monospace;
+}
+
+pre.programlisting {
+ background-color:#F0F8FF;
+ border:1px solid gray;
+ padding:5px;
+ font-family:monospace;
+}
+
+div.variablelist {
+ border:1px solid gray;
+ padding:2px;
+}
+
+span.term { /* in a variablelist, also in dl dt */
+ font-weight:bold;
+ padding-left:3px; padding-right:3px;
+ color:#000080;
+}
+
+div.itemizedlist ul.disc li {
+ margin-bottom:3px;
+}
+
+h1.title {
+ font-size: 200%; /* Book title */
+ color:#000080;
+}
+h2.subtitle { font-size: 140%; } /* Book subtitle */
+div.chapter h2.title, div.preface h2.title, div.appendix h2.title, div.index h2.title {
+ /* All components */
+ font-size: 170%;
+ font-weight: bold;
+ color: #000080;
+}
+div.chapter h2.subtitle, div.preface h2.subtitle, div.appendix h2.subtitle, div.index h2.subtitle {
+ font-size: 130%;
+}
+div.section h2.title {
+ /* level1 sections */
+ font-size: 150%;
+ font-weight: bold;
+ color: #000080;
+}
+div.section h3.title {
+ /* level2 sections */
+ font-size: 130%;
+ font-weight: bold;
+}
+div.section h4.title {
+ /* level3 sections */
+ font-size: 123%;
+ font-weight: bold;
+}
+div.section h5.title {
+ /* level4 sections */
+ font-size: 116%;
+ font-weight: bold;
+}
+
+span.remark {
+ background-color:#32cd32;
+ font:normal bold 12px sans-serif;
+ border:2px solid green; padding-left:2px; padding-right:2px;
+}
+
+img { border:0; padding:0; margin:0; }
+
+p.copyright { font-family:sans-serif; }
diff --git a/doc-src/entities/global.ent b/doc-src/entities/global.ent
new file mode 100644
index 0000000..8962206
--- /dev/null
+++ b/doc-src/entities/global.ent
@@ -0,0 +1,26 @@
+<!-- Project-specific entities which should be loaded into every source file -->
+<!-- $Id: global.ent 826 2009-01-17 05:04:52Z unsaved $ -->
+
+<!ENTITY % dummy33 PUBLIC
+ "-//HSQLDB/ENTITIES/DocSpecificDynamicEntities"
+ "validation_only.ent"> %dummy33;
+<!-- validation_only.ent contains dummy values. Catalog-switched by XSLT. -->
+
+<!-- These two settings are used by some of OASIS's multi-language
+ documents. If you are only using entity files that you have written,
+ you won't need to set these. -->
+<!ENTITY % sgml.features "IGNORE">
+<!ENTITY % xml.features "INCLUDE">
+
+<!ENTITY % dummy31 PUBLIC
+ "-//OASIS/ENTITIES DocBook Character Entities V4.5//EN"
+ "http://www.docbook.org/xml/4.5/dbcentx.mod"> %dummy31;
+<!-- Load a named resource. Where these are loaded from may be dynamically
+ overridden with "catalogs".
+ Since these entities are needed both for validation and for XSLT
+ transormation, we must specify the overriding value both in our catalog
+ file and in the xmlcatalog element in build.xml.
+ The example here is rather useful, because this pulls in the standard
+ DocBook character entities, and allows to dynamically pull the entities
+ from a http server or a local DocBook installation, for example.
+-->
diff --git a/doc-src/entities/validation_only.ent b/doc-src/entities/validation_only.ent
new file mode 100644
index 0000000..cea6a99
--- /dev/null
+++ b/doc-src/entities/validation_only.ent
@@ -0,0 +1,17 @@
+<!-- $Id: validation_only.ent 826 2009-01-17 05:04:52Z unsaved $ -->
+
+<!-- Dummy value defintions.
+ These settings are fine for GUI editors and Validation, but this file
+ should definitely be overridden with a catalog for generating
+ production-ready output documents.
+
+ The real, document-specific, production values for these entities are set
+ at "tmp/doc-work/<DOCNAME>/dyanamic.ent".
+-->
+
+<!-- These entities are "project global", in that the entities may be used in
+ any document of the project. The value of doc_basename will certainly vary
+ for each document, and distro_baseurl may. -->
+<!ENTITY doc_basename "doc_basename_DEFAULTVAL">
+<!ENTITY distro_baseurl "distro_baseurl_DEFAULTVAL">
+<!-- distro_baseurl is the canonical download source for the doc -->
diff --git a/doc-src/guide/accesscontrol.xml b/doc-src/guide/accesscontrol.xml
new file mode 100644
index 0000000..0d94c71
--- /dev/null
+++ b/doc-src/guide/accesscontrol.xml
@@ -0,0 +1,669 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter version="5.0" xml:id="accesscontrol-chapt"
+ xmlns="http://docbook.org/ns/docbook"
+ xmlns:xlink="http://www.w3.org/1999/xlink"
+ xmlns:xi="http://www.w3.org/2001/XInclude"
+ xmlns:ns5="http://www.w3.org/1998/Math/MathML"
+ xmlns:ns4="http://www.w3.org/2000/svg"
+ xmlns:ns3="http://www.w3.org/1999/xhtml"
+ xmlns:ns="http://docbook.org/ns/docbook">
+ <title xml:id="accesscontrol-title">Access Control</title>
+
+ <info>
+ <authorgroup>
+ <author>
+ <personname><firstname>Fred</firstname><surname>Toussi</surname></personname>
+
+ <affiliation>
+ <orgname>The HSQL Development Group</orgname>
+ </affiliation>
+ </author>
+ </authorgroup>
+
+ <releaseinfo>$Revision: 3096 $</releaseinfo>
+
+ <pubdate>$Date: 2009-08-09 17:50:39 +0100 (Sun, 09 Aug 2009) $</pubdate>
+
+ <keywordset>
+ <keyword>Hsqldb</keyword>
+
+ <keyword>HyperSQL</keyword>
+
+ <keyword>SQL</keyword>
+ </keywordset>
+
+ <legalnotice>
+ <para>Copyright 2010 Fred Toussi. Permission is granted to distribute
+ this document without any alteration under the terms of the HSQLDB
+ license. Additional permission is granted to the HSQL Development Group
+ to distribute this document with or without alterations under the terms
+ of the HSQLDB license.</para>
+ </legalnotice>
+ </info>
+
+ <section>
+ <title>Overview</title>
+
+ <para>Apart from schemas and their object, each HyperSQL catalog has USER
+ and ROLE objects. These objects are collectively called
+ <emphasis>authorizations</emphasis>. Each AUTHORIZATION has some access
+ rights on some of the schemas or the objects they contain. The persistent
+ elements of an SQL environment are database objects</para>
+
+ <para>Each database object has a name. A name is an identifier and is
+ unique within its name-space. Authorizations names follow the rules
+ described below and the case-normal form is stored in the database. When
+ connecting to a database, the user name and password must match the case
+ of the case-normal form.</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>identifier definition</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">identifier</emphasis></simpara>
+
+ <simpara><emphasis>definition of identifier</emphasis></simpara>
+
+ <simpara><literal><identifier> ::= <regular identifier> |
+ <delimited identifier> | <SQL language identifier>
+ </literal></simpara>
+
+ <simpara><literal><delimited identifier> ::= <double quote>
+ <character sequence> <double quote></literal></simpara>
+
+ <simpara><literal><regular identifier> ::= <special character
+ sequence></literal></simpara>
+
+ <simpara><literal><SQL language identifier> ::= <special
+ character sequence></literal></simpara>
+
+ <simpara>A <literal><delimited identifier></literal> is a sequence
+ of characters enclosed with double-quote symbols. All characters are
+ allowed in the character sequence.</simpara>
+
+ <simpara>A <literal><regular identifier></literal> is a special
+ sequence of characters. It consists of letters, digits and the underscore
+ characters. It must begin with a letter.</simpara>
+
+ <simpara>A <literal><SQL language identifier></literal> is similar
+ to <literal><regular identifier></literal> but the letters can range
+ only from A-Z in the ASCII character set. This type of identifier is used
+ for names of CHARACTER SET objects.</simpara>
+
+ <simpara>If the character sequence of a delimited identifier is the same
+ as an undelimited identifier, it represents the same identifier. For
+ example "JOHN" is the same identifier as JOHN. In a <literal><regular
+ identifier></literal> the case-normal form is considered for
+ comparison. This form consists of the upper-case of equivalent of all the
+ letters.</simpara>
+
+ <simpara>The character sequence length of all identifiers must be between
+ 1 and 128 characters.</simpara>
+
+ <simpara>A reserved word is one that is used by the SQL Standard for
+ special purposes. It is similar to a <literal><regular
+ identifier></literal> but it cannot be used as an identifier for user
+ objects. If a reserved word is enclosed in double quote characters, it
+ becomes a quoted identifier and can be used for database
+ objects.</simpara>
+ </section>
+
+ <section>
+ <title>Authorizations and Access Control</title>
+
+ <para>In general, ROLE and USER objects simply control access to schema
+ objects. This is the scope of the SQL Standard. However, there are special
+ roles that allow the creation of USER and ROLE objects and also allow some
+ special operations on the database as a whole. These roles are not defined
+ by the Standard, which has left it to implementors to define such roles as
+ they are needed for the particular SQL implementation.</para>
+
+ <para>A ROLE has a name a collection of zero or more other roles, plus
+ some privileges (access rights). A USER has a name and a password. It
+ similarly has a collection of zero or more roles plus some
+ privileges.</para>
+
+ <para>USER objects existed in the SQL-92, but ROLE objects were introduced
+ in SQL:1999. Originally it was intended that USER objects would normally
+ be the same as the operating system USER objects and their authentication
+ would be handled outside the SQL environment. The co-existence of ROLE and
+ USER objects results in complexity. With the addition of ROLE objects,
+ there is no rationale, other than legacy support, for granting privileges
+ to USER objects directly. It is better to create roles and grant
+ privileges to them, then grant the roles to USER objects.</para>
+
+ <para>The Standard effectively defines a special ROLE, named PUBLIC. All
+ authorization have the PUBLIC role, which cannot be removed from them.
+ Therefore any access right assigned to the PUBLIC role applies to all
+ authorizations in the database. For many simple databases, it is adequate
+ to create a single, non-admin user, then assign access rights to the
+ pre-existing PUBLIC role. Access to INFORMATION_SCHEMA views is granted to
+ PUBLIC, therefore these views are accessible to all. However, the contents
+ of each view depends on the ROLE or USER (AUTHORIZATION) that is in force
+ while accessing the view.</para>
+
+ <para>Each schema has a single AUTHORIZATION. This is commonly known as
+ the <emphasis>owner</emphasis> of the schema. All the objects in the
+ schema inherit the schema owner. The schema owner can add objects to the
+ schema, drop them or alter them.</para>
+
+ <para>By default, the objects in a schema can only be accessed by the
+ schema owner. The schema owner can grant access rights on the objects to
+ other users or roles.</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>AUTHORIZATION IDENTIFIER</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">authorization
+ identifier</emphasis></simpara>
+
+ <simpara><emphasis>authorization identifier</emphasis></simpara>
+
+ <simpara><literal><authorization identifier> ::= <role name> |
+ <user name></literal></simpara>
+
+ <simpara>Authorization identifiers share the same name-space within the
+ database. The same name cannot be used for a USER and a ROLE.</simpara>
+
+ <section>
+ <title>Built-In Roles and Users</title>
+
+ <para>There are some pre-defined roles in each database; some defined by
+ the SQL Standard, some by HyperSQL. These roles can be assigned to users
+ (directly or via other, user-defined roles). In addition, there is the
+ default initial user, SA, created with each new database.</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>PUBLIC ROLE</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">PUBLIC</emphasis></simpara>
+
+ <simpara><emphasis>the PUBLIC role</emphasis></simpara>
+
+ <simpara>The role that is assigned to all authorizations (roles and
+ users) in the database. This role has access rights to all objects in
+ the INFORMATION_SCHEMA. Any roles or rights granted to this role, are in
+ effect granted to all users of the database.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>_SYSTEM ROLE</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">_SYSTEM</emphasis></simpara>
+
+ <simpara><emphasis>the _SYSTEM role</emphasis></simpara>
+
+ <simpara>This role is the authorization for the pre-defined (system)
+ objects in the database, including the INFORMATION_SCHEMA. This role
+ cannot be assigned to any authorization.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>DBA ROLE</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">DBA</emphasis></simpara>
+
+ <simpara><emphasis>the DBA role (HyperSQL-specific)</emphasis></simpara>
+
+ <simpara>This is a special role in HyperSQL. A user that has this role
+ can perform all possible administrative tasks on the database. The DBA
+ role can also act as a proxy for all the roles and users in the
+ database. This means it can do everything the authorization for a schema
+ can do, including dropping the schema or its objects, or granting rights
+ on the schema objects to a grantee.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>CREATE_SCHEMA ROLE</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">CREATE_SCHEMA</emphasis></simpara>
+
+ <simpara><emphasis>the CREATE_SCHEMA role
+ (HyperSQL-specific)</emphasis></simpara>
+
+ <simpara>An authorization that has this role, can create schemas. The
+ DBA authorization has this role and can grant it to other
+ authorizations.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>CHANGE_AUTHORIZATION</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">CHANGE_AUTHORIZATION</emphasis></simpara>
+
+ <simpara><emphasis>the CHANGE_AUTHORIZATION role
+ (HyperSQL-specific)</emphasis></simpara>
+
+ <simpara>A user that has this role, can change the authorization for the
+ current session to another user. The DBA authorization has this role and
+ can grant it to other authorizations.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>SA USER</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">SA</emphasis></simpara>
+
+ <simpara><emphasis>the SA user (HyperSQL-specific)</emphasis></simpara>
+
+ <simpara>This user is automatically created with a new database and has
+ the DBA role. Initially, the password for this user is an empty string.
+ After connecting to the new database as this user, it is possible to
+ change the password, create other users and created new schema objects.
+ The SA user can be dropped by another user that has the DBA
+ role.</simpara>
+ </section>
+
+ <section>
+ <title>Access Rights</title>
+
+ <para>By default, the objects in a schema can only be accessed by the
+ schema owner. But the schema owner can grant privileges (access rights)
+ on the objects to other users or roles.</para>
+
+ <para>Things can get far more complex, because the grant of privileges
+ can be made WITH GRANT OPTION. In this case, the role or user that has
+ been granted the privilege can grant the privilege to other roles and
+ users.</para>
+
+ <para>Privileges can also be revoked from users or roles.</para>
+
+ <para>The statements for granting and revoking privileges normally
+ specify which privileges are granted or revoked. However, there is a
+ shortcut, ALL PRIVILEGES, which means all the privileges that the
+ <literal><grantor></literal> has on the schema object. The
+ <literal><grantor></literal> is normally the CURRENT_USER of the
+ session that issues the statement.</para>
+
+ <para>The user or role that is granted privileges is referred to as
+ <literal><grantee></literal> for the granted privileges.</para>
+
+ <simpara><emphasis role="bold">Table</emphasis></simpara>
+
+ <simpara>For tables, including views, privileges can be granted with
+ different degrees of granularity. It is possible to grant a privilege on
+ all columns of a table, or on specific columns of the table.</simpara>
+
+ <simpara>The DELETE privilege applies to the table, rather than its
+ columns. It applies to all DELETE statements.</simpara>
+
+ <simpara>The SELECT, INSERT and UPDATE privileges may apply to all
+ columns or to individual columns. These privileges determine whether the
+ <literal><grantee></literal> can execute SQL data statements on
+ the table.</simpara>
+
+ <simpara>The SELECT privilege designates the columns that can be
+ referenced in SELECT statements, as well as the columns that are read in
+ a DELETE or UPDATE statement, including the search condition.</simpara>
+
+ <simpara>The INSERT privilege designates the columns into which explicit
+ values can be inserted. To be able to insert a row into the table, the
+ user must therefore have the INSERT privilege on the table, or at least
+ all the columns that do not have a default value.</simpara>
+
+ <simpara>The UPDATE privilege simply designates the table or the
+ specific columns that can be updated.</simpara>
+
+ <simpara>The REFERENCES privilege allows the
+ <literal><grantee></literal> to define a FOREIGN KEY constraint on
+ a different table, which references the table or the specific columns
+ designated for the REFERENCES privilege.</simpara>
+
+ <simpara>The TRIGGER privilege allows adding a trigger to the
+ table.</simpara>
+
+ <simpara><emphasis role="bold">Sequence, Type, Domain, Character Set,
+ Collation, Transliteration,</emphasis></simpara>
+
+ <simpara>For these objects, only USAGE can be granted. The USAGE
+ privilege is needed when object is referenced directly in an SQL
+ statement.</simpara>
+
+ <simpara><emphasis role="bold">Routine</emphasis></simpara>
+
+ <simpara>For routines, including procedures or functions, only EXECUTE
+ privilege can be granted. This privilege is needed when the routine is
+ used directly in an SQL statement.</simpara>
+
+ <simpara><emphasis role="bold">Other Objects</emphasis></simpara>
+
+ <simpara>Other objects such as constraints and assertions are not used
+ directly and there is no grantable privilege that refers to
+ them.</simpara>
+ </section>
+ </section>
+
+ <section>
+ <title xml:id="accesscontrol-statements-title">Statements for
+ Authorization and Access Control</title>
+
+ <para>The statements listed below allow creation and destruction of USER
+ and ROLE objects. The GRANT and REVOKE statements allow roles to be
+ assigned to other roles or to users. The same statements are also used in
+ a different form to assign privileges on schema objects to users and
+ roles.</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>CREATE USER</primary>
+ </indexterm>
+
+ <simpara xml:id="create_user-sql"><emphasis role="bold">CREATE
+ USER</emphasis></simpara>
+
+ <simpara><emphasis>user definition (HyperSQL)</emphasis></simpara>
+
+ <simpara><literal><user definition> ::= CREATE USER <user
+ name> PASSWORD <password> [ ADMIN ]</literal></simpara>
+
+ <simpara>Define a new user and its password. <literal><user
+ name></literal> is an SQL identifier. If it is double-quoted it is
+ case-sensitive, otherwise it is turned to uppercase.
+ <literal><password></literal> is a string enclosed with single quote
+ characters and is case-sensitive. If <literal>ADMIN</literal> is
+ specified, the DBA role is granted to the new user. Only a user with the
+ DBA role can execute this statement.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>DROP USER</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">DROP USER</emphasis></simpara>
+
+ <simpara><emphasis>drop user statement (HyperSQL)</emphasis></simpara>
+
+ <simpara><literal><drop user statement> ::= DROP USER <user
+ name></literal></simpara>
+
+ <simpara>Drop (destroy) an existing user. If the specified user is the
+ authorization for a schema, the schema is destroyed. Only a user with the
+ DBA role can execute this statement.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>ALTER USER ... SET PASSWORD</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">ALTER USER ... SET
+ PASSWORD</emphasis></simpara>
+
+ <simpara><emphasis>set the password for a user
+ (HyperSQL)</emphasis></simpara>
+
+ <simpara><literal><alter user set password statement> ::= ALTER USER
+ <user name> SET PASSWORD <password></literal></simpara>
+
+ <simpara>Change the password of an existing user. <literal><user
+ name></literal> is an SQL identifier. If it is double-quoted it is
+ case-sensitive, otherwise it is turned to uppercase.
+ <literal><password></literal> is a string enclosed with single quote
+ characters and is case-sensitive. Only a user with the DBA role can
+ execute this command.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>ALTER USER ... SET INITIAL SCHEMA</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">ALTER USER ... SET INITIAL
+ SCHEMA</emphasis></simpara>
+
+ <simpara><emphasis>set the initial schema for a user
+ (HyperSQL)</emphasis></simpara>
+
+ <simpara><literal><alter user set initial schema statement> ::=
+ ALTER USER <user name> SET INITIAL SCHEMA <schema name> |
+ DEFAULT</literal></simpara>
+
+ <simpara>Change the initial schema for a user. The initial schema is the
+ schema used by default for SQL statements issued during a session. If
+ <literal>DEFAULT</literal> is used, the default initial schema for all
+ users is used as the initial schema for the user. The SET SCHEMA command
+ allows the user to change the schema for the duration of the session. Only
+ a user with the DBA role can execute this statement.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>SET PASSWORD</primary>
+ </indexterm>
+
+ <simpara xml:id="set_password-sql"><emphasis role="bold">SET
+ PASSWORD</emphasis></simpara>
+
+ <simpara><emphasis>set password statement (HyperSQL)</emphasis></simpara>
+
+ <simpara><literal><set password statement> ::= SET PASSWORD
+ <password></literal></simpara>
+
+ <simpara>Set the password for the current user.
+ <literal><password></literal> is a string enclosed with single quote
+ characters and is case-sensitive.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>SET INITIAL SCHEMA*</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">SET INITIAL SCHEMA</emphasis></simpara>
+
+ <simpara><emphasis>set the initial schema for the current user
+ (HyperSQL)</emphasis></simpara>
+
+ <simpara><literal><set initial schema statement> ::= SET INITIAL
+ SCHEMA <schema name> | DEFAULT</literal></simpara>
+
+ <simpara>Change the initial schema for the current user. The initial
+ schema is the schema used by default for SQL statements issued during a
+ session. If <literal>DEFAULT</literal> is used, the default initial schema
+ for all users is used as the initial schema for the current user. The
+ separate SET SCHEMA command allows the user to change the schema for the
+ duration of the session. See also the <link endterm="sessions-title"
+ xlink:arcrole="" xlink:href="#sessions-chapt"></link> chapter.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>SET DATABASE DEFAULT INITIAL SCHEMA</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">SET DATABASE DEFAULT INITIAL
+ SCHEMA</emphasis></simpara>
+
+ <simpara><emphasis>set the default initial schema for all users
+ (HyperSQL)</emphasis></simpara>
+
+ <simpara><literal><set database default initial schema statement>
+ ::= SET DATABASE DEFAULT INITIAL SCHEMA <schema
+ name></literal></simpara>
+
+ <simpara>Sets the initial schema for new users. This schema can later be
+ changed with the <literal><set initial schema statement></literal>
+ command.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>CREATE ROLE</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">CREATE ROLE</emphasis></simpara>
+
+ <simpara><emphasis>role definition</emphasis></simpara>
+
+ <simpara><literal><role definition> ::= CREATE ROLE <role
+ name> [ WITH ADMIN <grantor> ]</literal></simpara>
+
+ <simpara>Defines a new role. Initially the role has no rights, except
+ those of the PUBLIC role. Only a user with the DBA role can execute this
+ command.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>DROP ROLE</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">DROP ROLE</emphasis></simpara>
+
+ <simpara><emphasis>drop role statement</emphasis></simpara>
+
+ <simpara><literal><drop role statement> ::= DROP ROLE <role
+ name></literal></simpara>
+
+ <simpara>Drop (destroy) a role. If the specified role is the authorization
+ for a schema, the schema is destroyed. Only a user with the DBA role can
+ execute this statement.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>GRANTED BY</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">GRANTED BY</emphasis></simpara>
+
+ <simpara><emphasis>grantor determination</emphasis></simpara>
+
+ <simpara><literal>GRANTED BY <grantor></literal></simpara>
+
+ <simpara><literal><grantor> ::= CURRENT_USER |
+ CURRENT_ROLE</literal></simpara>
+
+ <simpara>The authorization that is granting or revoking a role or
+ privileges. The optional <literal>GRANTED BY <grantor></literal>
+ clause can be used in various statements that perform GRANT or REVOKE
+ actions. If the clause is not used, the authorization is CURRENT_USER.
+ Otherwise, it is the specified authorization.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>GRANT privilege</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">GRANT</emphasis></simpara>
+
+ <simpara><emphasis>grant privilege statement</emphasis></simpara>
+
+ <simpara><literal><grant privilege statement> ::= GRANT
+ <privileges> TO <grantee> [ { <comma> <grantee>
+ }... ] [ WITH GRANT OPTION ] [ GRANTED BY <grantor>
+ ]</literal></simpara>
+
+ <simpara>Assign privileges on schema objects to roles or users. Each
+ <literal><grantee></literal> is a role or a user. If <literal>[ WITH
+ GRANT OPTION ]</literal> is specified, then the
+ <literal><grantee></literal> can assign the privileges to other
+ <literal><grantee></literal> objects.</simpara>
+
+ <simpara><literal><privileges> ::= <object privileges> ON
+ <object name></literal></simpara>
+
+ <simpara><literal><object name> ::= [ TABLE ] <table name> |
+ DOMAIN <domain name> | COLLATION <collation name> | CHARACTER
+ SET <character set name> | TRANSLATION <transliteration name>
+ | TYPE <user-defined type name> | SEQUENCE <sequence generator
+ name> | <specific routine designator> | ROUTINE <routine
+ name> | FUNCTION <function name> | PROCEDURE <procedure
+ name></literal></simpara>
+
+ <simpara><literal><object privileges> ::= ALL PRIVILEGES |
+ <action> [ { <comma> <action> }... ]</literal></simpara>
+
+ <simpara><literal><action> ::= SELECT | SELECT <left paren>
+ <privilege column list> <right paren> | DELETE | INSERT [
+ <left paren> <privilege column list> <right paren> ] |
+ UPDATE [ <left paren> <privilege column list> <right
+ paren> ] | REFERENCES [ <left paren> <privilege column
+ list> <right paren> ] | USAGE | TRIGGER |
+ EXECUTE</literal></simpara>
+
+ <simpara><literal><privilege column list> ::= <column name
+ list></literal></simpara>
+
+ <simpara><literal><grantee> ::= PUBLIC | <authorization
+ identifier></literal></simpara>
+
+ <simpara>The <literal><object privileges></literal> that can be used
+ depend on the type of the <literal><object name></literal>. These
+ are discussed in the previous section. For a table, if
+ <literal><privilege column list></literal> is not specified, then
+ the privilege is granted on the table, which includes all of its columns
+ and any column that may be added to it in the future. For routines, the
+ name of the routine can be specified in two ways, either as the generic
+ name as the specific name. HyperSQL allows referencing all overloaded
+ versions of a routine at the same time, using its name. This differs from
+ the SQL Standard which requires the use of <literal><specific routine
+ designator></literal> to grant privileges separately on each different
+ signature of the routine.</simpara>
+
+ <simpara>Each <literal><grantee></literal> is the name of a role or
+ a user. Examples of GRANT statement are given below:</simpara>
+
+ <informalexample>
+ <programlisting>GRANT ALL ON SEQUENCE aSequence TO roleOrUser
+GRANT SELELCT ON aTable TO roleOrUser
+GRANT SELECT, UPDATE ON aTABLE TO roleOrUser1, roleOrUser2
+GRANT SELECT(columnA, columnB), UPDATE(columnA, columnB) ON TABLE aTable TO roleOrUser
+GRANT EXECUTE ON SPECIFIC ROUTINE aroutine_1234 TO rolOrUser
+</programlisting>
+ </informalexample>
+
+ <simpara>As mentioned in the general discussion, it is better to define a
+ role for the collection of all the privileges required by an application.
+ This role is then granted to any user. If further changes are made to the
+ privileges of this role, they are automatically reflected in all the users
+ that have the role.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>GRANT role</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">GRANT</emphasis></simpara>
+
+ <simpara><emphasis>grant role statement</emphasis></simpara>
+
+ <simpara><literal><grant role statement> ::= GRANT <role name>
+ [ { <comma> <role name> }... ] TO <grantee> [ {
+ <comma> <grantee> }... ] [ WITH ADMIN OPTION ] [ GRANTED BY
+ <grantor> ]</literal></simpara>
+
+ <simpara>Assign roles to roles or users. One or more roles can be assigned
+ to one or more <literal><grantee></literal> objects. A
+ <literal><grantee></literal> is a user or a role. If the <literal>[
+ WITH ADMIN OPTION ]</literal> is specified, then each
+ <literal><grantee></literal> can grant the newly assigned roles to
+ other grantees. An example of user and role creation with grants is given
+ below:</simpara>
+
+ <informalexample>
+ <programlisting>CREATE USER appuser
+CREATE ROLE approle
+GRANT approle TO appuser
+GRANT SELECT, UPDATE ON TABLE atable TO approle
+GRANT USAGE ON SEQUENCE asequence to approle
+GRANT EXECUTE ON ROUTINE aroutine TO approle
+</programlisting>
+ </informalexample>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>REVOKE</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">REVOKE privilege</emphasis></simpara>
+
+ <simpara><emphasis>revoke statement</emphasis></simpara>
+
+ <simpara><literal><revoke privilege statement> ::= REVOKE [ GRANT
+ OPTION FOR ] <privileges> FROM <grantee> [ { <comma>
+ <grantee> }... ] [ GRANTED BY <grantor> ] RESTRICT |
+ CASCADE</literal></simpara>
+
+ <simpara>Revoke privileges from a user or role.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>REVOKE ROLE</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">REVOKE role</emphasis></simpara>
+
+ <simpara><emphasis>revoke role statement</emphasis></simpara>
+
+ <simpara><literal><revoke role statement> ::= REVOKE [ ADMIN OPTION
+ FOR ] <role revoked> [ { <comma> <role revoked> }... ]
+ FROM <grantee> [ { <comma> <grantee> }... ] [ GRANTED BY
+ <grantor> ] RESTRICT | CASCADE</literal></simpara>
+
+ <simpara><literal><role revoked> ::= <role
+ name></literal></simpara>
+
+ <simpara>Revoke a role from users or roles.</simpara>
+ </section>
+</chapter>
diff --git a/doc-src/guide/building-app.xml b/doc-src/guide/building-app.xml
new file mode 100644
index 0000000..1a7512d
--- /dev/null
+++ b/doc-src/guide/building-app.xml
@@ -0,0 +1,371 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- $Id: building-app.xml 3556 2010-03-26 23:09:40Z fredt $ -->
+<!DOCTYPE book [
+<!ENTITY % dummy22 SYSTEM "../entities/global.ent">
+%dummy22;
+]>
+<appendix version="5.0" xml:id="building-app"
+ xmlns="http://docbook.org/ns/docbook"
+ xmlns:xlink="http://www.w3.org/1999/xlink"
+ xmlns:xi="http://www.w3.org/2001/XInclude"
+ xmlns:ns5="http://www.w3.org/2000/svg"
+ xmlns:ns4="http://www.w3.org/1998/Math/MathML"
+ xmlns:ns3="http://www.w3.org/1999/xhtml"
+ xmlns:ns="http://docbook.org/ns/docbook">
+ <!-- We declare the default namespace + those for prefixes xlink: and xi: in
+ the root element, so we can use them anywhere in this file. -->
+
+ <info>
+ <title xml:id="building-title">Building HyperSQL Jars</title>
+
+ <subtitle>How to build customized or specialized jar files</subtitle>
+
+ <author>
+ <personname><firstname>Fred</firstname>
+ <surname>Toussi</surname></personname>
+
+ <affiliation>
+ <orgname>The HSQL Development Group</orgname>
+ </affiliation>
+ </author>
+
+ <releaseinfo>$Revision: 3556 $</releaseinfo>
+
+ <pubdate>$Date: 2010-03-26 19:09:40 -0400 (Fri, 26 Mar 2010) $</pubdate>
+
+ <keywordset>
+ <keyword>HSQLDB</keyword>
+
+ <keyword>HyperSQL</keyword>
+
+ <keyword>Building</keyword>
+
+ <keyword>Ant</keyword>
+ </keywordset>
+ </info>
+
+ <section>
+ <title>Purpose</title>
+
+ <simpara>From 2.0, the supplied <filename>hsqldb.jar</filename> file is
+ built with Java 1.6. If you want to run with a 1.5 or older JVM, or if you
+ want to use an alternative jar (<filename>hsqldb-min.jar</filename>, etc.)
+ you must build the desired jar with a Java JDK and Ant version
+ 1.7.</simpara>
+ </section>
+
+ <section xml:id="building-ant-sect">
+ <title>Building with Apache Ant</title>
+
+ <titleabbrev>Building with Ant</titleabbrev>
+
+ <indexterm significance="preferred">
+ <primary>Ant</primary>
+ </indexterm>
+
+ <simpara>You should use version 1.7.x of Ant (Another Neat Tool) to do
+ builds with HyperSQL.</simpara>
+
+ <section>
+ <title>Obtaining Ant</title>
+
+ <simpara>Ant is a part of the Jakarta/Apache Project.</simpara>
+
+ <itemizedlist>
+ <listitem>
+ <simpara><link xlink:href="http://ant.apache.org">Home of the Apache
+ Ant project</link></simpara>
+ </listitem>
+
+ <listitem>
+ <simpara>The <link
+ xlink:href="http://ant.apache.org/manual/install.html#installing">
+ Installing Ant</link> page of the <link
+ xlink:href="http://ant.apache.org/manual">Ant Manual</link>. Follow
+ the directions for your platform.</simpara>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title>Building Hsqldb with Ant</title>
+
+ <simpara>Once you have unpacked the zip package for hsqldb, under the
+ <filename>/hsqldb</filename> folder, in <filename>/build</filename>
+ there is a <filename>build.xml</filename> file that builds the
+ <filename>hsqldb.jar</filename> with Ant (Ant must be already
+ installed). To use it, change to <filename>/build</filename> then
+ type:</simpara>
+
+ <informalexample>
+ <screen> ant -projecthelp</screen>
+ </informalexample>
+
+ <simpara>This displays the available ant targets, which you can supply
+ as command line arguments to ant. These include</simpara>
+
+ <variablelist>
+ <varlistentry>
+ <term>hsqldb</term>
+
+ <listitem>
+ <simpara>to build the <filename>hsqldb.jar</filename>
+ file</simpara>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>explainjars</term>
+
+ <listitem>
+ <simpara>Lists all targets which build jar files, with an
+ explanation of the purposes of the different jars.</simpara>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>clean</term>
+
+ <listitem>
+ <simpara>to clean up the /classes directory that is
+ created</simpara>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>clean-all</term>
+
+ <listitem>
+ <simpara>to remove the old jar and doc files as well</simpara>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>javadoc</term>
+
+ <listitem>
+ <simpara>to build javadoc</simpara>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>hsqldbmain</term>
+
+ <listitem>
+ <simpara>to build a smaller jar for HSQLDB that does not contain
+ utilities</simpara>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>hsqljdbc</term>
+
+ <listitem>
+ <simpara>to build an extremely small jar containing only the
+ client-side JDBC driver (can connect only to a HyperSQL
+ Server).</simpara>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>hsqldbmin</term>
+
+ <listitem>
+ <simpara>to build a small jar that supports
+ <emphasis>in-process</emphasis> catalogs, but neither running nor
+ connecting to HyperSQL Servers.</simpara>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>sqltool</term>
+
+ <listitem>
+ <simpara>to build sqltool.jar, which contains only the SqlTool
+ classes.</simpara>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>...</term>
+
+ <listitem>
+ <simpara>Many more targets are available. Run <literal>ant
+ -p</literal> and <literal>ant explainjars</literal>.</simpara>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <simpara>HSQLDB can be built in any combination of two JRE (Java Runtime
+ Environment) versions and many jar file sizes.</simpara>
+
+ <simpara>A jar built with an older JRE is compatible for use with a
+ newer JRE (you can compile with Java 1.5 and run with 1.6). But the
+ newer JDBC capabilities of the JRE will be not be available.</simpara>
+
+ <simpara>The client jar (<filename>hsqljdbc.jar</filename>) contains
+ only the HSQLDB JDBC Driver client. The smallest engine jar
+ (<filename>hsqldbmin.jar</filename>) contains the engine and the HSQLDB
+ JDBC Driver client. The default size (<filename>hsqldb.jar</filename>)
+ also contains server mode support and the utilities. The largest size
+ (<filename>hsqldbtest.jar</filename>)includes some test classes as well.
+ Before building the <filename>hsqldbtest.jar</filename> package, you
+ should download the junit jar from <link
+ xlink:href="http://www.junit.org"></link> and put it in the
+ <filename>/lib</filename> directory, alongside
+ <filename>servlet.jar</filename>, which is included in the .zip
+ package.</simpara>
+
+ <para>If you want your code built for high performance, as opposed to
+ debugging (in the same way that we make our production distributions),
+ make a file named <filename>build.properties</filename> in your build
+ directory with the contents <informalexample>
+ <screen>build.debug: false</screen>
+ </informalexample>The resulting Java binaries will be faster and
+ smaller, at the cost of exception stack traces not identifying source
+ code locations (which can be extremely useful for debugging).</para>
+
+ <simpara>After installing Ant on your system use the following command
+ from the <filename>/build</filename> directory. Just run <literal>ant
+ explainjars</literal> for a concise list of all available jar
+ files.</simpara>
+
+ <informalexample>
+ <screen>ant explainjars</screen>
+ </informalexample>
+
+ <simpara>The command displays a list of different options for building
+ different sizes of the HSQLDB Jar. The default is built using:</simpara>
+
+ <example>
+ <title>Buiding the standard Hsqldb jar file with Ant</title>
+
+ <screen>ant hsqldb</screen>
+ </example>
+
+ <simpara>The Ant method always builds a jar with the JDK that is used by
+ Ant and specified in its JAVA_HOME environment variable.</simpara>
+ </section>
+
+ <section>
+ <title>Building for Older JDKs</title>
+
+ <para>HyperSQL version 2.0 cannot be directly compiled or used with JDK
+ 1.4. It may be possible to use the RetroTranslator tool to achieve this.
+ The suggested procedure is as follows: First use Ant with JDK 1.5 and
+ build the jar. Then translate the jar using RetroTranslator with
+ backport (which bundles replacement classes for concurrency control).
+ This translation should cover the concurrency features that are specific
+ to version 1.5 and later.<informalexample>
+ <screen>ant switchtojdk14
+ant hsqldb
+-- translate the jar
+</screen>
+ </informalexample></para>
+ </section>
+ </section>
+
+ <section>
+ <title>Building with IDE's</title>
+
+ <simpara>All HyperSQL source files are supplied ready to compile. There is
+ no complex pre-compile stage. It is therefore possible to compile the
+ sources with an IDE, without using ant. Only if compilation with Java 1.5
+ is required, you should first run the Ant code switcher task before
+ compiling and remove from the source directories a few source files that
+ are specific to Java 6 (these are listed in the build.xml file).</simpara>
+ </section>
+
+ <section>
+ <title>Hsqldb CodeSwitcher</title>
+
+ <simpara>CodeSwitcher is a tool to manage different version of Java source
+ code. It allows to compile HyperSQL for different JDKs. It is something
+ like a precompiler in C but it works directly on the source code and does
+ not create intermediate output or extra files.</simpara>
+
+ <simpara>CodeSwitcher is used internally in the Ant build. You do not have
+ to use it separately to compile HyperSQL.</simpara>
+
+ <simpara>CodeSwitcher reads the source code of a file, removes comments
+ where appropriate and comments out the blocks that are not used for a
+ particular version of the file. This operation is done for all files of a
+ defined directory, and all subdirectories.</simpara>
+
+ <example>
+ <title>Example source code before CodeSwitcher is run</title>
+
+ <programlisting>
+ ...
+
+ //#ifdef JAVA2
+
+ properties.store(out,"hsqldb database");
+
+ //#else
+
+ /*
+
+ properties.save(out,"hsqldb database");
+
+ */
+
+ //#endif
+
+ ...</programlisting>
+ </example>
+
+ <simpara>The next step is to run CodeSwitcher.</simpara>
+
+ <example>
+ <title>CodeSwitcher command line invocation</title>
+
+ <screen>
+ java org.hsqldb.util.CodeSwitcher . -JAVA2</screen>
+ </example>
+
+ <simpara>The '.' means the program works on the current directory (all
+ subdirectories are processed recursively). <literal>-JAVA2</literal> means
+ the code labelled with JAVA2 must be switched off.</simpara>
+
+ <example>
+ <title>Source code after CodeSwitcher processing</title>
+
+ <programlisting>
+ ...
+
+ //#ifdef JAVA2
+
+ /*
+
+ pProperties.store(out,"hsqldb database");
+
+ */
+
+ //#else
+
+ pProperties.save(out,"hsqldb database");
+
+ //#endif
+
+ ...</programlisting>
+ </example>
+
+ <simpara>For detailed information on the command line options run
+ <classname>java org.hsqldb.util.CodeSwitcher</classname>. Usage examples
+ can be found in the build.xml file in the <filename>/build</filename>
+ directory.</simpara>
+ </section>
+
+ <section>
+ <title>Building documentation</title>
+
+ <simpara>The JavaDoc can be built simply by invoking the javadoc
+ target.</simpara>
+
+ <simpara>The two Guides are in DocBook XML source format. To rebuild, run
+ the Ant target <literal>gen-docs</literal>. Instructions will be
+ displayed. See the file <filename>doc-src/readme-docauthors.txt</filename>
+ for tips.</simpara>
+ </section>
+</appendix>
diff --git a/doc-src/guide/builtinfunctions.xml b/doc-src/guide/builtinfunctions.xml
new file mode 100644
index 0000000..c453327
--- /dev/null
+++ b/doc-src/guide/builtinfunctions.xml
@@ -0,0 +1,1918 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter version="5.0" xml:id="builtinfunctions-chapt"
+ xmlns="http://docbook.org/ns/docbook"
+ xmlns:xlink="http://www.w3.org/1999/xlink"
+ xmlns:xi="http://www.w3.org/2001/XInclude"
+ xmlns:ns5="http://www.w3.org/1999/xhtml"
+ xmlns:ns4="http://www.w3.org/2000/svg"
+ xmlns:ns3="http://www.w3.org/1998/Math/MathML"
+ xmlns:ns="http://docbook.org/ns/docbook">
+ <title xml:id="builtinfunctions-title">Built In Functions</title>
+
+ <info>
+ <authorgroup>
+ <author>
+ <personname><firstname>Fred</firstname><surname>Toussi</surname></personname>
+
+ <affiliation>
+ <orgname>The HSQL Development Group</orgname>
+ </affiliation>
+ </author>
+ </authorgroup>
+
+ <releaseinfo>$Revision: 3601 $</releaseinfo>
+
+ <pubdate>$Date: 2010-05-31 20:17:47 -0400 (Mon, 31 May 2010) $</pubdate>
+
+ <keywordset>
+ <keyword>Hsqldb</keyword>
+
+ <keyword>HyperSQL</keyword>
+
+ <keyword>SQL</keyword>
+ </keywordset>
+
+ <legalnotice>
+ <para>Copyright 2010 Fred Toussi. Permission is granted to distribute
+ this document without any alteration under the terms of the HSQLDB
+ license. Additional permission is granted to the HSQL Development Group
+ to distribute this document with or without alterations under the terms
+ of the HSQLDB license.</para>
+ </legalnotice>
+ </info>
+
+ <section xml:id="builtin_functions_intro-sect">
+ <title>Overview</title>
+
+ <para>HyperSQL supports a wide range of built-in functions and allows
+ user-defined functions written in SQL and Java languages. User defined
+ functions are covered in a separate chapter. If a built-in function is not
+ available, you can write your own using SQL. Aggregate functions are
+ discussed in chapters that cover SQL in general.</para>
+
+ <para>The built-in functions fall into three groups:</para>
+
+ <para><itemizedlist>
+ <listitem>
+ <para>SQL Standard Functions</para>
+
+ <para>A wide rang of functions defined by SQL/Foundation are
+ supported. SQL/Foundation functions that have no parameter are
+ called without empty parentheses. Functions with multiple parameters
+ often use keywords instead of commas to separate the parameters.
+ Many functions are overloaded. Among these, some have one or more
+ optional parameters that can be omitted, while the return type of
+ some functions is dependent upon the type of one of the parameters.
+ The usage of SQL Standard Functions (where they can be used) is
+ covered more extensively in the <link endterm="dataaccess-title"
+ xlink:href="#dataaccess-chapt"></link> chapter</para>
+ </listitem>
+
+ <listitem>
+ <para>JDBC Open Group CLI Functions</para>
+
+ <para>These functions were defined as an extension to the CLI
+ standard, which is the basis for ODBC and JDBC and supported by many
+ database products. JDBC supports an escape mechanism to specify
+ function calls in SQL statements in a manner that is independent of
+ the function names supported by the target database engine. For
+ example <literal>SELECT {fn DAYOFMONTH (dateColumn)} FROM
+ myTable</literal> can be used in JDBC and is translated to Standard
+ SQL as <literal>SELECT EXTRACT (DAY_OF_MONTH FROM dateColumn) FROM
+ myTable</literal> if a database engine supports the Standard syntax.
+ If a database engine does not support Standard SQL, then the
+ translation will be different. HyperSQL supports all the function
+ names specified in the JDBC specifications as native functions.
+ Therefore, there is no need to use the <literal>{fn FUNC_NAME ( ...
+ ) }</literal> escape with HyperSQL. If a JDBC function is supported
+ by the SQL Standard in a different form, the SQL Standard form is
+ the preferred form to use.</para>
+ </listitem>
+
+ <listitem>
+ <para>HyperSQL Built-In Functions</para>
+
+ <para>Several additional built-in functions are available for some
+ useful operations. Some of these functions return the current
+ setting for the session and the database. The General Functions
+ accept arguments of different types and return values based on
+ comparison between the arguments.</para>
+ </listitem>
+ </itemizedlist></para>
+
+ <para>In the BNF specification used here, words in capital letters are
+ actual tokens. Syntactic elements such as expressions are enclosed in
+ angle brackets. The <literal><left paren></literal> and
+ <literal><right paren></literal> tokens are represented with the
+ actual symbol. Optional elements are enclosed with square brackets (
+ <literal><left bracket></literal> and <literal><right
+ bracket></literal> ). Multiple options for a required element are
+ enclosed with braces (<literal> <left brace></literal> and
+ <literal><right brace></literal> )<literal>.</literal> Alternative
+ tokens are separated with the vertical bar ( <literal><vertical
+ bar></literal> ). At the end of each function definition, the standard
+ which specifies the function is noted in parentheses as JDBC or HyperSQL,
+ unless the function is in the SQL/Foundation part of the SQL
+ Standard.</para>
+ </section>
+
+ <section xml:id="builtin_functions_string-sect">
+ <title>String and Binary String Functions</title>
+
+ <para>In SQL, there are three kinds of string: character, binary and bit.
+ The units are respectively characters, octets, and bits. Each kind of
+ string can be in different data types. CHAR, VARCHAR and CLOB are the
+ character data types. BINARY, VARBINARY and BLOB are the binary data
+ types. BIT and BIT VARYING are the bit string types. In all string
+ functions, the position of a unit of the string within the whole string is
+ specified from 1 to the length of the whole string. In the BNF,
+ <literal><char value expr> </literal>indicates any valid SQL
+ expression that evaluates to a character type. Likewise,
+ <literal><binary value expr> </literal>indicates a binary type
+ and<literal> <num value expr> </literal>indicates a numeric
+ type.</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>ASCII function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">ASCII</emphasis></simpara>
+
+ <para><literal>ASCII ( <char value expr> )</literal></para>
+
+ <para>Returns an INTEGER equal to the ASCII code value of the first
+ character of <literal><char value expr></literal>. (JDBC)</para>
+
+ <para><literal>CHAR ( <UNICODE code> ) </literal></para>
+
+ <para>The argument is an INTEGER. Returns a character string containing a
+ single character that has the specified<literal> <UNICODE
+ code></literal>, which is an integer. ASCII codes are a subset of the
+ allowed values for <literal><UNICODE code></literal>. (JDBC)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>CONCAT function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">CONCAT</emphasis></simpara>
+
+ <para><literal>CONCAT ( <char value expr 1>, <char value expr
+ 2> )</literal></para>
+
+ <para><literal>CONCAT ( <binary value expr 1>, <binary value expr
+ 2> )</literal></para>
+
+ <para>The arguments are character strings or binary strings. Returns a
+ string formed by concatenation of the arguments. Equivalent to the SQL
+ concatenation expression <literal><value expr 1> || <value expr
+ 2></literal>. (JDBC)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>DIFFERENCE function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">DIFFERENCE</emphasis></simpara>
+
+ <para><literal>DIFFERENCE ( <char value expr 1>, <char value expr
+ 2> )</literal></para>
+
+ <para>The arguments are character strings. Converts the arguments into
+ SOUNDEX codes, and returns an INTEGER between 0-4 which indicates how
+ similar the two SOUNDEX value are. If the values are the same, it returns
+ 4, if the values have no similarity, it returns 0. In-between values are
+ returned for partial similarity. (JDBC)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>INSERT function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">INSERT</emphasis></simpara>
+
+ <para><literal>INSERT ( <char value expr 1>, <offset>,
+ <length>, <char value expr 2> )</literal></para>
+
+ <para>Returns a character string based on <literal><char value expr
+ 1></literal> in which <literal><length></literal> characters have
+ been removed from the <literal><offset></literal> position and in
+ their place, the whole <literal><char value expr 2></literal> is
+ copied. Equivalent to SQL/Foundation <literal>OVERLAY( <char value
+ expr1> PLACING < char value expr2> FROM <offset> FOR
+ <length> )</literal> . (JDBC)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>HEXTORAW function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">HEXTORAW</emphasis></simpara>
+
+ <para><literal>HEXTORAW( <char value expr> )</literal></para>
+
+ <para>Returns a BINARY string formed by translation of hexadecimal digits
+ and letters in the <<literal>char value expr></literal>. Each
+ character of the <literal><char value expr></literal> must be a
+ digit or a letter in the A | B | C | D | E | F set. Each byte of the
+ retired binary string is formed by translating two hex digits into one
+ byte. (HyperSQL)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>LCASE function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">LCASE</emphasis></simpara>
+
+ <para><literal>LCASE ( <char value expr> ) </literal></para>
+
+ <para>Returns a character string that is the lower case version of the
+ <literal><char value expr></literal>. Equivalent to SQL/Foundation
+ <literal>LOWER (<char value expr>)</literal>. (JDBC)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>LEFT function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">LEFT</emphasis></simpara>
+
+ <para><literal>LEFT ( <char value expr>, <length> )
+ </literal></para>
+
+ <para>Returns a character string consisting of the first
+ <literal><length></literal> characters of <literal><char value
+ expr></literal>. Equivalent to SQL/Foundation<literal>
+ SUBSTRING(<char value expr> FROM 0 FOR <length>)</literal>.
+ (JDBC)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>LENGTH function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">LENGTH</emphasis></simpara>
+
+ <para><literal>LENGTH ( <char value expr> ) </literal></para>
+
+ <para>Returns as a BIGINT value the number of characters in
+ <literal><char value expr></literal>. Equivalent to SQL/Foundation
+ <literal>CHAR_LENGTH(<char value expr>)</literal>. (JDBC)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>LOCATE function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">LOCATE</emphasis></simpara>
+
+ <para><literal>LOCATE ( <char value expr 1>, <char value expr
+ 2> [ , <offset> ] ) </literal></para>
+
+ <para>Returns as a BIGINT value the starting position of the first
+ occurrence of <literal><char value expr 1></literal> within
+ <literal><char value expr 2></literal>. If
+ <literal><offset</literal>> is specified, the search begins with the
+ position indicated by <literal><offset></literal>. If the search is
+ not successful, 0 is returned. Equivalent to SQL/Foundation
+ <literal>POSITION(<char value expr 1> IN <char value expr
+ 2>)</literal>. (JDBC)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>LTRIM function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">LTRIM</emphasis></simpara>
+
+ <para><literal>LTRIM ( <char value expr> ) </literal></para>
+
+ <para>Returns a character string based on <literal><char value
+ expr></literal> with the leading space characters removed. Equivalent
+ to SQL/Foundation <literal>TRIM( LEADING ' ' FROM <char value expr>
+ )</literal>. (JDBC)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>RAWTOHEX function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">RAWTOHEX</emphasis></simpara>
+
+ <para><literal>RAWTOHEX( <binary value expr> )</literal></para>
+
+ <para>Returns a character string composed of hexadecimal digits
+ representing the bytes in the <literal><binary value
+ expr></literal>. Each byte of the <literal><binary value
+ expr></literal> is translated into two hex digits. (HyperSQL)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>REGEXP_MATCHES function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">REGEXP_MATCHES</emphasis></simpara>
+
+ <para><literal>REGEXP_MATCHES ( <char value expr>, <regular
+ expression> ) </literal></para>
+
+ <para>Returns true if the <char value expr> matches the <regular
+ expression>. The <regular expression> is defined according to
+ Java language rules. (HyperSQL)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>REPEAT function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">REPEAT</emphasis></simpara>
+
+ <para><literal>REPEAT ( <char value expr>, <count> )
+ </literal></para>
+
+ <para>Returns a character string based on<literal> <char value
+ expr></literal>, repeated <literal><count></literal> times.
+ (JDBC)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>REPLACE function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">REPLACE</emphasis></simpara>
+
+ <para><literal>REPLACE ( <char value expr 1>, <char value expr
+ 2>, <char value expr 3> )</literal></para>
+
+ <para>Returns a character string based on <literal><char value expr
+ 1></literal> where each occurrence of <literal><char value expr
+ 2></literal> has been replaced with a copy of <literal><char value
+ expr 3></literal>. (JDBC)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>REVERSE function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">REVERSE</emphasis></simpara>
+
+ <para><literal>REVERSE ( <char value expr> )</literal></para>
+
+ <para>Returns a character string based on <literal><char value
+ expr></literal> with characters in the reverse order. (HyperSQL)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>RIGHT function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">RIGHT</emphasis></simpara>
+
+ <para><literal>RIGHT ( <char value expr>, <count> )
+ </literal></para>
+
+ <para>Returns a character string consisting of the last
+ <literal><count></literal> characters of <literal><char value
+ expr></literal>. (JDBC)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>RTRIM function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">RTRIM</emphasis></simpara>
+
+ <para><literal>RTRIM ( <char value expr> ) </literal></para>
+
+ <para>Returns a character string based on <literal><char value
+ expr></literal> with the trailing space characters removed. Equivalent
+ to SQL/Foundation <literal>TRIM(TRAILING ' ' FROM <character
+ string>)</literal>. (JDBC)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>SOUNDEX function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">SOUNDEX</emphasis></simpara>
+
+ <para><literal>SOUNDEX ( <char value expr> ) </literal></para>
+
+ <para>Returns a four character code representing the sound of
+ <literal><char value expr></literal>. The US census algorithm is
+ used. For example the soundex value for Washington is W252. (JDBC)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>SPACE function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">SPACE</emphasis></simpara>
+
+ <para><literal>SPACE ( <count> ) </literal></para>
+
+ <para>Returns a character string consisting of <literal><count>
+ </literal>spaces. (JDBC)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>SUBSTR function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">SUBSTR</emphasis></simpara>
+
+ <para><literal>{ SUBSTR | SUBSTRING } ( <char value expr>,
+ <offset>, <length> )</literal></para>
+
+ <para>The JDBC version of SQL/Foundation <literal>SUBSTRING</literal>
+ returns a character string that consists of
+ <literal><length></literal> characters from <literal><char value
+ expr> </literal>starting at the <literal><offset></literal>
+ position. (JDBC)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>UCASE function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">UCASE</emphasis></simpara>
+
+ <para><literal>UCASE ( <char value expr> ) </literal></para>
+
+ <para>Returns a character string that is the lower case version of the
+ <literal><char value expr></literal>. Equivalent to SQL/Foundation
+ <literal>UPPER( <char value expr> )</literal> . (JDBC)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>CHARACTER_LENGTH</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">CHARACTER_LENGTH</emphasis></simpara>
+
+ <para><literal>{ CHAR_LENGTH | CHARACTER_LENGTH } ( <char value
+ expression> [ USING { CHARACTERS | OCTETS } ] )</literal></para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>OCTET_LENGTH function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">OCTET_LENGTH</emphasis></simpara>
+
+ <para><literal>OCTET_LENGTH ( <string value expression>
+ )</literal></para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>BIT_LENGTH function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">BIT_LENGTH</emphasis></simpara>
+
+ <para><literal>BIT_LENGTH ( <string value expression>
+ )</literal></para>
+
+ <para>The CHAR_LENGTH or CHARACTER_LENGTH function can be used with
+ character strings, while OCTET_LENGTH can be used with character or binary
+ strings and BIT_LENGTH can be used with character, binary and bit
+ strings.</para>
+
+ <para>All functions return a BIGINT value that measures the length of the
+ string in the given unit. CHAR_LENGTH counts characters, OCTET_LENGTH
+ counts octets and BIT_LENGTH counts bits in the string. For CHAR_LENGTH,
+ if <literal>[ USING OCTETS ] </literal>is specified, the octet count is
+ returned. (Foundation)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>OVERLAY function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">OVERLAY</emphasis></simpara>
+
+ <para><literal>OVERLAY ( <char value expr 1> PLACING <char value
+ expr 2></literal></para>
+
+ <para><literal>FROM <start position> [ FOR <string length> ] [
+ USING CHARACTERS ] )</literal></para>
+
+ <para><literal>OVERLAY ( <binary value expr 1> PLACING <binary
+ value expr 2></literal></para>
+
+ <para><literal>FROM <start position> [ FOR <string length> ]
+ )</literal></para>
+
+ <para>The character version of OVERLAY returns a character string based on
+ <literal><char value expr 1></literal> in which <literal><string
+ length></literal> characters have been removed from the
+ <literal><start position></literal> and in their place, the whole
+ <literal><char value expr 2></literal> is copied.</para>
+
+ <para>The binary version of OVERLAY returns a binary string formed in the
+ same manner as the character version. (Foundation)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>POSITION function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">POSITION</emphasis></simpara>
+
+ <para><literal>POSITION ( <char value expr 1> IN <char value expr
+ 2> [ USING CHARACTERS ] )</literal></para>
+
+ <para><literal>POSITION ( <binary value expr 1> IN <binary value
+ expr 2> )</literal></para>
+
+ <para>The character and binary versions of POSITION search the string
+ value of the second argument for the first occurrence of the first
+ argument string. If the search is successful, the position in the string
+ is returned as a BIGINT. Otherwise zero is returned.</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>SUBSTRING function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">SUBSTRING</emphasis></simpara>
+
+ <para><literal>SUBSTRING ( <char value expr> FROM <start
+ position> [ FOR <string length> ] [ USING CHARACTERS ]
+ )</literal></para>
+
+ <para><literal>SUBSTRING ( <binary value expr> FROM <start
+ position> [ FOR <string length> ] )</literal></para>
+
+ <para>The character version of SUBSTRING returns a character string that
+ consists of the characters of the <literal><char value expr>
+ </literal>from <literal><start position></literal>. If the
+ optional<literal> <string length></literal> is specified, only
+ <literal><string length> </literal>characters are returned.</para>
+
+ <para>The binary version of SUBSTRING returns a binary string in the same
+ manner. (Foundation)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>TRIM function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">TRIM</emphasis></simpara>
+
+ <para><literal>TRIM ([ [ LEADING | TRAILING | BOTH ] [ <trim
+ character> ] FROM ] <char value expr> )</literal></para>
+
+ <para><literal>TRIM ([ [ LEADING | TRAILING | BOTH ] [ <trim octet>
+ ] FROM ] <binary value expr> )</literal></para>
+
+ <para>The character version of TRIM returns a character string based on
+ <literal><char value expr></literal>. Consecutive instances of
+ <literal><trim character> </literal>are removed from the beginning,
+ the end or both ends of the<literal><char value expr>
+ </literal>depending on the value of the optional first qualifier
+ <literal>[ LEADING | TRAILING | BOTH ]</literal>. If no qualifier is
+ specified, <literal>BOTH </literal>is used as default. If <literal>[
+ <trim character> ]</literal> is not specified, the space character
+ is used as default.</para>
+
+ <para>The binary version of TRIM returns a binary string based on
+ <literal><binary value expr></literal>. Consecutive instances of
+ <literal><trim octet> </literal>are removed in the same manner as in
+ the character version. If<literal> [ <trim octet> ]</literal> is not
+ specified, the 0 octet is used as default. (Foundation)</para>
+ </section>
+
+ <section xml:id="builtin_functions_numeric-sect">
+ <title>Numeric Functions</title>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>ABS function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">ABS</emphasis></simpara>
+
+ <para><literal>ABS ( <num value expr> | <interval value expr>
+ ) </literal></para>
+
+ <para>Returns the absolute value of the argument as a value of the same
+ type. (JDBC and Foundation)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>ACOS function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">ACOS</emphasis></simpara>
+
+ <para><literal>ACOS ( <num value expr> ) </literal></para>
+
+ <para>Returns the arc-cosine of the argument in radians as a value of
+ DOUBLE type. (JDBC)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>ASIN function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">ASIN</emphasis></simpara>
+
+ <para><literal>ASIN ( <num value expr> ) </literal></para>
+
+ <para>Returns the arc-sine of the argument in radians as a value of DOUBLE
+ type. (JDBC)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>ATAN function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">ATAN</emphasis></simpara>
+
+ <para><literal>ATAN ( <num value expr> ) </literal></para>
+
+ <para>Returns the arc-tangent of the argument in radians as a value of
+ DOUBLE type. (JDBC)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>ATAN2 function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">ATAN2</emphasis></simpara>
+
+ <para><literal>ATAN2 ( <num value expr 1>, <num value expr 2>
+ ) </literal></para>
+
+ <para>The <literal><num value expr 1></literal> and <literal><num
+ value expr 2></literal> express the <varname>x</varname> and
+ <varname>y</varname> coordinates of a point. Returns the angle, in
+ radians, representing the angle coordinate of the point in polar
+ coordinates, as a value of DOUBLE type. (JDBC)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>CEIL function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">CEILING</emphasis></simpara>
+
+ <para><literal>{ CEIL | CEILING } ( <num value expr> )
+ </literal></para>
+
+ <para>Returns the smallest integer greater than or equal to the argument.
+ If the argument is exact numeric then the result is exact numeric with a
+ scale of 0. If the argument is approximate numeric, then the result is of
+ DOUBLE type. (JDBC and Foundation)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>BITAND function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">BITAND</emphasis></simpara>
+
+ <para><literal>BITAND ( <num value expr 1>, <num value expr 2>
+ )</literal></para>
+
+ <para><literal>BITAND ( <bit value expr 1>, <bit value expr 2>
+ )</literal></para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>BITOR function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">BITOR</emphasis></simpara>
+
+ <para><literal>BITOR ( <num value expr 1>, <num value expr 2>
+ )</literal></para>
+
+ <para><literal>BITOR ( <bit value expr 1>, <bit value expr 2>
+ )</literal></para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>BITXOR function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">BITXOR</emphasis></simpara>
+
+ <para><literal>BITXOR ( <num value expr 1>, <num value expr 2>
+ )</literal></para>
+
+ <para><literal>BITXOR ( <bit value expr 1>, <bit value expr 2>
+ )</literal></para>
+
+ <para>These three functions perform the bit operations: OR, AND, XOR, on
+ two values. The values are either integer values, or bit strings. The
+ result is an integer value of the same type as the arguments, or a bit
+ string of the same length as the argument. Each bit of the result is
+ formed by performing the operation on corresponding bits of the arguments.
+ (HyperSQL)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>COS function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">COS</emphasis></simpara>
+
+ <para><literal>COS ( <num value expr> ) </literal></para>
+
+ <para>Returns the cosine of the argument (an angle expressed in radians)
+ as a value of DOUBLE type. (JDBC)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>COT function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">COT</emphasis></simpara>
+
+ <para><literal>COT ( <num value expr> ) </literal></para>
+
+ <para>Returns the cotangent of the argument as a value of DOUBLE type. The
+ <literal><num value expr></literal> represents an angle expressed in
+ radians. (JDBC)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>DEGREES function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">DEGREES</emphasis></simpara>
+
+ <para><literal>DEGREES ( <num value expr> ) </literal></para>
+
+ <para>Converts the argument (an angle expressed in<literal>
+ radians</literal>) into degrees and returns the value in the DOUBLE type.
+ (JDBC)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>EXP function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">EXP</emphasis></simpara>
+
+ <para><literal>EXP ( <num value expr> ) </literal></para>
+
+ <para>Returns the exponential value of the argument as a value of DOUBLE
+ type. (JDBC and Foundation)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>FLOOR function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">FLOOR</emphasis></simpara>
+
+ <para><literal>FLOOR ( <num value expr> ) </literal></para>
+
+ <para>Returns the largest integer that is less than or equal to the
+ argument. If the argument is exact numeric then the result is exact
+ numeric with a scale of 0. If the argument is approximate numeric, then
+ the result is of DOUBLE type. (JDBC and Foundation)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>LN function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">LN</emphasis></simpara>
+
+ <para><literal>LN ( <num value expr> ) </literal></para>
+
+ <para>Returns the natural logarithm of the argument, as a value of DOUBLE
+ type. (Foundation)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>LOG function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">LOG</emphasis></simpara>
+
+ <para><literal>LOG ( <num value expr> ) </literal></para>
+
+ <para>Returns the natural logarithm of the argument, as a value of DOUBLE
+ type. (JDBC)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>LOG10 function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">LOG10</emphasis></simpara>
+
+ <para><literal>LOG10 ( <num value expr> ) </literal></para>
+
+ <para>Returns the base 10 logarithm of the argument as a value of DOUBLE
+ type. (JDBC)</para>
+
+ <para><literal>MOD ( <num value expr 1>, <num value expr 2> )
+ </literal></para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>MOD function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">MOD</emphasis></simpara>
+
+ <para>Returns the remainder (modulus) of <literal><num value expr
+ 1></literal> divided by <literal><num value expr 2>.</literal>
+ The data type of the returned value is the same as the second argument.
+ (JDBC and Foundation)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>PI function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">PI</emphasis></simpara>
+
+ <para><literal>PI () </literal></para>
+
+ <para>Returns the constant pi as a value of DOUBLE type. (JDBC)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>POWER function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">POWER</emphasis></simpara>
+
+ <para><literal>POWER ( <num value expr 1>, <num value expr 2>
+ ) </literal></para>
+
+ <para>Returns the value of <literal><num value expr 1></literal>
+ raised to the power of <literal><int value expr 2></literal> as a
+ value of DOUBLE type. (JDBC and Foundation)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>RADIANS function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">RADIANS</emphasis></simpara>
+
+ <para><literal>RADIANS ( <num value expr> ) </literal></para>
+
+ <para>Converts the argument (an angle expressed in<literal>
+ degrees</literal>) into radians and returns the value in the DOUBLE type.
+ (JDBC)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>RAND function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">RAND</emphasis></simpara>
+
+ <para><literal>RAND ( [ <int value expr> ] ) </literal></para>
+
+ <para>Returns a random value in the DOUBLE type. The optional <literal>[
+ <int value expr> ]</literal> is used as seed value. In HyperSQL each
+ session has a separate random number generator. The first call that uses a
+ seed parameter sets the seed for subsequent calls that do not include a
+ parameter. (JDBC)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>ROUND function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">ROUND</emphasis></simpara>
+
+ <para><literal>ROUND ( <num value expr>, <int value expr> )
+ </literal></para>
+
+ <para>The <literal><num value expr> </literal>is of the DOUBLE type.
+ The function returns a DOUBLE value which is the value of the argument
+ rounded to <literal><int value expr></literal> places right of the
+ decimal point. If <literal><int value expr></literal> is negative,
+ the first argument is rounded to <literal><int value expr></literal>
+ places to the left of the decimal point. (JDBC)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>SIGN function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">SIGN</emphasis></simpara>
+
+ <para><literal>SIGN ( <num value expr> ) </literal></para>
+
+ <para>Returns an INTEGER, indicating the sign of the argument. If the
+ argument is negative then -1 is returned. If it is equal to zero then 0 is
+ returned. If the argument is positive then 1 is returned. (JDBC)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>SIN function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">SIN</emphasis></simpara>
+
+ <para><literal>SIN ( <num value expr> ) </literal></para>
+
+ <para>Returns the sine of the argument (an angle expressed in radians) as
+ a value of DOUBLE type. (JDBC)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>SQRT function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">SQRT</emphasis></simpara>
+
+ <para><literal>SQRT ( <num value expr> ) </literal></para>
+
+ <para>Returns the square root of the argument as a value of DOUBLE type.
+ (JDBC and Foundation)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>TAN function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">TAN</emphasis></simpara>
+
+ <para><literal>TAN ( <num value expr> ) </literal></para>
+
+ <para>Returns the tangent of the argument (an angle expressed in radians)
+ as a value of DOUBLE type. (JDBC)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>TRUNCATE function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">TRUNCATE</emphasis></simpara>
+
+ <para><literal>TRUNCATE ( <num value expr>, <int value expr> )
+ </literal></para>
+
+ <para>Returns a value in the same type as <literal><num value
+ expr></literal>. The value is rounded by replacing digits with zeros
+ from <literal><int value expr></literal> places right of the decimal
+ point to the end. If <literal><int value expr></literal> is
+ negative, <literal>ABS( <int value expr> )</literal> digits to left
+ of the decimal point and all digits to the right of the decimal points are
+ replaced with zeros. Results of calling TRUNCATE with 12345.6789 with (-2,
+ 0, 2, 4) are (12300.0000, 12345.0000, 12345.6700, 12345.6789).
+ (JDBC)</para>
+ </section>
+
+ <section xml:id="builtin_functions_datetime-sect">
+ <title>Date Time and Interval Functions</title>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>TIMEZONE function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">TIMEZONE</emphasis></simpara>
+
+ <para><literal>TIMEZONE()</literal></para>
+
+ <para>Returns the current time zone for the session. Returns an INTERVAL
+ HOUR TO MINUTE value. (HyperSQL)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>SESSION_TIMEZONE function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">SESSION_TIMEZONE</emphasis></simpara>
+
+ <para><literal>SESSION_TIMEZONE()</literal></para>
+
+ <para>Returns the default time zone for the current session. Returns an
+ INTERVAL HOUR TO MINUTE value. (HyperSQL)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>DATABASE_TIMEZONE function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">DATABASE_TIMEZONE</emphasis></simpara>
+
+ <para><literal>DATABASE_TIMEZONE()</literal></para>
+
+ <para>Returns the time zone for the database engine. This is based on
+ where the database server process is located. Returns an INTERVAL HOUR TO
+ MINUTE value. (HyperSQL)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>EXTRACT function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">EXTRACT</emphasis></simpara>
+
+ <para><literal>EXTRACT ( <extract field> FROM <extract source>
+ )</literal></para>
+
+ <para><literal><extract field> ::= YEAR | MONTH | DAY | HOUR |
+ MINUTE | DAY_OF_WEEK | WEEK_OF_YEAR | QUARTER | DAY_OF_YEAR | DAY_OF_MONTH
+ |</literal></para>
+
+ <para><literal>TIMEZONE_HOUR | TIMEZONE_MINUTE | SECOND |
+ SECONDS_SINCE_MIDNIGHT |</literal></para>
+
+ <para><literal>DAY_NAME | MONTH_NAME</literal></para>
+
+ <para><literal><extract source> ::= <datatime value expr> |
+ <interval value expr></literal></para>
+
+ <para>The EXTRACT function returns a field or element of the
+ <literal><extract source></literal>. The <literal><extract
+ source></literal> is a datetime or interval expression. The type of the
+ return value is BIGINT for most of the<literal> <extract
+ field></literal> options. The exceptions is <literal>SECOND
+ </literal>where a DECIMAL value is returned which has the same precision
+ as the datetime or interval expression. The field values <literal>DAY_NAME
+ </literal>or<literal> MONTH_NAME </literal>result in a character string.
+ When <literal>MONTH_NAME</literal> is specified, a string in the range
+ January - December is returned. When <literal>DAY_NAME </literal>is
+ specified, a string in the range Sunday -Saturday is returned.</para>
+
+ <para>If the <literal><extract source></literal> is <literal>FROM
+ <datatime value expr></literal>, different groups of
+ <literal><extract source></literal> can be used depending on the
+ data type of the expression. The <literal>TIMEZONE_HOUR |
+ TIMEZONE_MINUTE</literal> options are valid only for TIME WITH TIMEZONE
+ and TIMESTAMP WITH TIMEZONE data types. The <literal>HOUR | MINUTE |
+ SECOND | SECONDS_MIDNIGHT</literal> options, are valid for TIME and
+ TIMESTAMP types. The rest of the fields are valid for DATE and TIMESTAMP
+ types.</para>
+
+ <para>If the <literal><extract source></literal> is <literal>FROM
+ <interval value expr></literal>, the <literal><extract
+ field></literal> must be one of the fields of the INTERVAL type of the
+ expressions. The <literal>YEAR | MONTH</literal> options may be valid for
+ INTERVAL types based on months. The <literal>DAY | HOUR | MINUTE | SECOND
+ | SECONDS_MIDNIGHT</literal> options may be valid for INTERVAL types based
+ on seconds. For example,<literal> DAY | HOUR | MINUTE</literal> are the
+ only valid fields for the INTERVAL DAY TO MINUTE data type. (Foundation
+ with HyperSQL extensions)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>CURRENT_DATE function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">CURRENT_DATE</emphasis></simpara>
+
+ <para><literal>CURRENT_DATE</literal></para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>CURRENT_TIME function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">CURRENT_TIME</emphasis></simpara>
+
+ <para><literal>CURRENT_TIME [ ( <time precision> )
+ ]</literal></para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>LOCALTIME function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">LOCALTIME</emphasis></simpara>
+
+ <para><literal>LOCALTIME [ ( <time precision> ) ]</literal></para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>CURRENT_TIMESTAMP function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">CURRENT_TIMESTAMP</emphasis></simpara>
+
+ <para><literal>CURRENT_TIMESTAMP [ ( <timestamp precision> )
+ ]</literal></para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>LOCALTIMESTAMP function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">LOCALTIMESTAMP</emphasis></simpara>
+
+ <para><literal>LOCALTIMESTAMP [ ( <timestamp precision> )
+ ]</literal></para>
+
+ <para>These datetime functions return the datetime value representing the
+ moment the function is called. CURRENT_DATE returns a value of DATE type.
+ CURRENT_TIME returns a value of TIME WITH TIME ZONE type. LOCALTIME
+ returns a value of TIME type. CURRENT_TIMESTAMP returns a value of
+ TIMESTAMP WITH TIME ZONE type. LOCALTIMESTAMP returns a value of TIMESTAMP
+ type. If the optional <literal>[ ( <time precision> ) ]</literal>
+ or<literal> [ ( <timestamp precision> ) ]</literal> is used, then
+ the returned value has the specified fraction of the second precision.
+ (Foundation)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>CURDATE function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">CURDATE</emphasis></simpara>
+
+ <para><literal>CURDATE ()</literal></para>
+
+ <para>This function is equivalent to<literal> CURRENT_DATE.
+ </literal>(JDBC)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>CURTIME function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">CURTIME</emphasis></simpara>
+
+ <para><literal>CURTIME ()</literal></para>
+
+ <para>This function is equivalent to<literal> LOCALTIME</literal>.
+ (JDBC)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>DAYNAME function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">DAYNAME</emphasis></simpara>
+
+ <para><literal>DAYNAME ( <datatime value expr> )</literal></para>
+
+ <para>This function is equivalent to<literal> EXTRACT ( DAY_NAME FROM ...
+ ) </literal>Returns a string in the range of Sunday - Saturday.
+ (JDBC)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>DAYOFMONTH function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">DAYOFMONTH</emphasis></simpara>
+
+ <para><literal>DAYOFMONTH ( <datetime value expr> )</literal></para>
+
+ <para>This function is equivalent to<literal> EXTRACT ( DAY_OF_MONTH FROM
+ ... ) </literal>Returns an integer value in the range of 1-31.
+ (JDBC)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>DAYOFWEEK function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">DAYOFWEEK</emphasis></simpara>
+
+ <para><literal>DAYOFWEEK ( <datetime value expr> )</literal></para>
+
+ <para>This function is equivalent to <literal>EXTRACT ( DAY_OF_WEEK FROM
+ ... ) </literal>Returns an integer value in the range of 1-7. The first
+ day of the week is Sunday. (JDBC)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>DAYOFYEAR function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">DAYOFYEAR</emphasis></simpara>
+
+ <para><literal>DAYOFYEAR ( <datetime value expr> )</literal></para>
+
+ <para>This function is equivalent to <literal>EXTRACT ( DAY_OF_YEAR FROM
+ ... ) </literal>Returns an integer value in the range of 1-366.
+ (JDBC)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>HOUR function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">HOUR</emphasis></simpara>
+
+ <para><literal>HOUR ( <datetime value expr> )</literal></para>
+
+ <para>This function is equivalent to <literal>EXTRACT ( HOUR FROM ... )
+ </literal>Returns an integer value in the range of 0-23. (JDBC)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>MINUTE function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">MINUTE</emphasis></simpara>
+
+ <para><literal>MINUTE ( <datetime value expr> )</literal></para>
+
+ <para>This function is equivalent to<literal> EXTRACT ( MINUTE FROM ... )
+ </literal>Returns an integer value in the range of 0 - 59. (JDBC)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>MONTH function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">MONTH</emphasis></simpara>
+
+ <para><literal>MONTH ( <datetime value expr> )</literal></para>
+
+ <para>This function is equivalent to <literal>EXTRACT ( MONTH FROM ... )
+ </literal>Returns an integer value in the range of 1-12. (JDBC)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>MONTHNAME function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">MONTHNAME</emphasis></simpara>
+
+ <para><literal>MONTHNAME ( <datetime value expr> )</literal></para>
+
+ <para>This function is equivalent to <literal>EXTRACT ( NAME_OF_MONTH FROM
+ ... ) </literal>Returns a string in the range of January - December.
+ (JDBC)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>NOW function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">NOW</emphasis></simpara>
+
+ <para><literal>NOW ()</literal></para>
+
+ <para>This function is equivalent to
+ <literal>LOCAL_TIMESTAMP.</literal></para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>QUARTER function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">QUARTER</emphasis></simpara>
+
+ <para><literal>QUARTER ( <datetime value expr> )</literal></para>
+
+ <para>This function is equivalent to <literal>EXTRACT ( QUARTER FROM ... )
+ </literal>Returns an integer in the range of 1 - 4. (JDBC)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>SECOND function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">SECOND</emphasis></simpara>
+
+ <para><literal>SECOND ( <datetime value expr> )</literal></para>
+
+ <para>This function is equivalent to <literal>EXTRACT ( SECOND FROM ... )
+ </literal>Returns an integer or decimal in the range of 0 - 59, with the
+ same precision as the <datetime value expr>. (JDBC)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>SECONDS_SINCE_MIDNIGHT function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">SECONDS_SINCE_MIDNIGHT</emphasis></simpara>
+
+ <para><literal>SECONDS_SINCE_MIDNIGHT ( <datetime value expr>
+ )</literal></para>
+
+ <para>This function is equivalent to<literal> EXTRACT (
+ SECONDS_SINCE_MIDNIGHT FROM ... ) </literal>Returns an integer in the
+ range of 0 - 86399. (HyperSQL)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>WEEK function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">WEEK</emphasis></simpara>
+
+ <para><literal>WEEK ( <datetime value expr> )</literal></para>
+
+ <para>This function is equivalent to<literal> EXTRACT ( WEEK_OF_YEAR FROM
+ ... ) </literal>Returns an integer in the range of 1 - 54. (JDBC)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>YEAR function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">YEAR</emphasis></simpara>
+
+ <para><literal>YEAR ( <datetime value expr> )</literal></para>
+
+ <para>This function is equivalent to<literal> EXTRACT ( YEAR FROM ... )
+ </literal>Returns an integer in the range of 1 - 9999. (JDBC)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>TIMESTAMPADD function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">TIMESTAMPADD</emphasis></simpara>
+
+ <para><literal>TIMESTAMPADD ( <tsi datetime field>, <numeric
+ value expression>, <datetime value expr>)</literal></para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>TIMESTAMPDIFF function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">TIMESTAMPDIFF</emphasis></simpara>
+
+ <para><literal>TIMESTAMPDIFF ( <tsi datetime field>, <datetime
+ value expr 1>, <datetime value expr 2>)</literal></para>
+
+ <para><literal><tsi datetime field> ::= SQL_TSI_FRAC_SECOND |
+ SQL_TSI_SECOND | SQL_TSI_MINUTE | SQL_TSI_HOUR | SQL_TSI_DAY |
+ SQL_TSI_WEEK | SQL_TSI_MONTH | SQL_TSI_QUARTER |
+ SQL_TSI_YEAR</literal></para>
+
+ <para>HyperSQL supports full SQL Standard datetime features. It supports
+ adding integers representing units of time directly to datetime values
+ using the arithmetic plus operator. It also supports subtracting one
+ <literal><datetime value expr></literal> from another in the given
+ units of days using the minus operator. An example of
+ <literal><datetime value expr> + <numeric value expression>
+ <datetime field> </literal>is <literal>LOCAL_TIMESTAMP + 5
+ DAY</literal>. An example of <literal>( <datetime value expr> -
+ <numeric value expression> ) <datetime field> </literal>is
+ <literal>(CURRENT_DATE - DATE '2008-08-8') MONTH </literal>which returns
+ the number of calendar months between the two dates.</para>
+
+ <para>The two JDBC functions, <literal>TIMESTAMPADD </literal>and
+ <literal>TIMESTAMPDIFF</literal> perform the same function as above SQL
+ expressions. The field names are keywords and are different from those
+ used in the EXTRACT functions. These names are valid for use only when
+ calling these two functions. The return value for TIMESTAMPADD is of the
+ same type as the datetime argument used. The return type for TIMESTAMPDIFF
+ is always BIGINT, regardless of the type of arguments. The two datetime
+ arguments of TIMESTAMPDIFF should be of the same type. (JDBC)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>DATEADD function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">DATEADD</emphasis></simpara>
+
+ <para><literal>DATEADD ( <field>, <numeric value expr>,
+ <datetime value expr> )</literal></para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>DATEDIFF function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">DATEDIFF</emphasis></simpara>
+
+ <para><literal>DATEDIFF ( <field>, <datetime value expr 1>,
+ datetime value expr 2> )</literal></para>
+
+ <para><literal><field> ::= 'yy' | 'mm' | 'dd' | 'hh' | 'mi' | 'ss' |
+ 'ms'</literal></para>
+
+ <para>The DATEADD and DATEDIFF functions are alternatives to TIMESTAMPADD
+ and TIMESTAMPDIFF, with fewer available field options. The field names are
+ specified as strings, rather than keywords. The fields translate to YEAR,
+ MONTH, DAY, HOUR, MINUTE, SECOND and MILLISECOND. (HyperSQL}</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>TO_CHAR function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">TO_CHAR</emphasis></simpara>
+
+ <para><literal>TO_CHAR( <datetime value expr>, <char value
+ expr> )</literal></para>
+
+ <para>This function formats a datetime or numeric value to the format
+ specified by the pattern given in the second argument. The pattern can
+ contain pattern elements from the list given below, plus punctuation and
+ space characters. An example, including the result, is given below:</para>
+
+ <programlisting>TO_CHAR ( TIMESTAMP'2008-02-01 20:30:40', 'YYYY BC MONTH, DAY HH')
+
+2008 AD February, Friday 8
+</programlisting>
+
+ <para>The format is internally translated to a
+ <classname>java.text.SimpleDateFormat</classname> format string. Any
+ character sequences not listed below are included in the Java format
+ string and may cause unexpected results or errors. Therefore unsupported
+ format strings should not be used. The supported format components are as
+ follows:</para>
+
+ <table colsep="1" frame="all" pgwide="0">
+ <title>TO CHAR Values</title>
+
+ <tgroup cols="2">
+ <colspec colwidth="5cm" />
+
+ <colspec />
+
+ <tbody>
+ <row>
+ <entry><literal>BC | B.C. | AD | A.D.</literal></entry>
+
+ <entry>Returns <literal>AD</literal> for common era and
+ <literal>BC</literal> for before common era</entry>
+ </row>
+
+ <row>
+ <entry><literal>RRRR</literal></entry>
+
+ <entry><para>4-digit year</para></entry>
+ </row>
+
+ <row>
+ <entry><literal>YYYY</literal></entry>
+
+ <entry><para>4-digit year</para></entry>
+ </row>
+
+ <row>
+ <entry><literal>IYYY</literal></entry>
+
+ <entry><para>4-digit year</para></entry>
+ </row>
+
+ <row>
+ <entry><literal>YY</literal></entry>
+
+ <entry><para>2 digit year</para></entry>
+ </row>
+
+ <row>
+ <entry><literal>IY</literal></entry>
+
+ <entry><para>2 digit year</para></entry>
+ </row>
+
+ <row>
+ <entry><literal>IYYY</literal></entry>
+
+ <entry><para>4-digit year</para></entry>
+ </row>
+
+ <row>
+ <entry><literal>MM</literal></entry>
+
+ <entry><para>Month (01-12)</para></entry>
+ </row>
+
+ <row>
+ <entry><literal>MON</literal></entry>
+
+ <entry><para>Short three-letter name of month</para></entry>
+ </row>
+
+ <row>
+ <entry><literal>MONTH</literal></entry>
+
+ <entry><para>Name of month</para></entry>
+ </row>
+
+ <row>
+ <entry><literal>WW</literal></entry>
+
+ <entry><para>Week of year (1-53) where week 1 starts on the first
+ day of the year and continues to the seventh day of the
+ year.</para></entry>
+ </row>
+
+ <row>
+ <entry><literal>W</literal></entry>
+
+ <entry><para>Week of month (1-5) where week 1 starts on the first
+ day of the month and ends on the seventh.</para></entry>
+ </row>
+
+ <row>
+ <entry><literal>IW</literal></entry>
+
+ <entry><para>Week of year (1-52 or 1-53) based on the ISO
+ standard.</para></entry>
+ </row>
+
+ <row>
+ <entry><literal>DAY</literal></entry>
+
+ <entry><para>Name of day.</para></entry>
+ </row>
+
+ <row>
+ <entry><literal>DD</literal></entry>
+
+ <entry><para>Day of month (1-31).</para></entry>
+ </row>
+
+ <row>
+ <entry><literal>DDD</literal></entry>
+
+ <entry><para>Day of year (1-366).</para></entry>
+ </row>
+
+ <row>
+ <entry><literal>DY</literal></entry>
+
+ <entry><para>Short three-letter name of day.</para></entry>
+ </row>
+
+ <row>
+ <entry><literal>HH</literal></entry>
+
+ <entry><para>Hour of day (0-11).</para></entry>
+ </row>
+
+ <row>
+ <entry><literal>HH12</literal></entry>
+
+ <entry><para>Hour of day (0-11).</para></entry>
+ </row>
+
+ <row>
+ <entry><literal>HH24</literal></entry>
+
+ <entry><para>Hour of day (0-23).</para></entry>
+ </row>
+
+ <row>
+ <entry><literal>MI</literal></entry>
+
+ <entry><para>Minute (0-59).</para></entry>
+ </row>
+
+ <row>
+ <entry><literal>SS</literal></entry>
+
+ <entry><para>Second (0-59).</para></entry>
+ </row>
+
+ <row>
+ <entry><literal>FF</literal></entry>
+
+ <entry><para>Fractional seconds.</para></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </section>
+
+ <section>
+ <title>Array Functions</title>
+
+ <para>Array functions are specialised functions with ARRAY
+ parameters.</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>CARDINALITY function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">CARDINALITY</emphasis></simpara>
+
+ <para><literal>CARDINALITY( <array value expr> )</literal></para>
+
+ <para>Returns the element count for the given array argument.
+ (Foundation)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>MAX_CARDINALITY function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">MAX_CARDINALITY</emphasis></simpara>
+
+ <para><literal>MAX_CARDINALITY( <array value expr>
+ )</literal></para>
+
+ <para>Returns the maximum allowed element count for the given array
+ argument. (Foundation)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>TRIM_ARRAY function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">TRIM_ARRAY</emphasis></simpara>
+
+ <para><literal>TRIM_ARRAY( <array value expr>, <num value
+ expr> )</literal></para>
+
+ <para>Returns a new array that contains the elements of the
+ <literal><array value expr></literal> minus the number of elements
+ specified by the <literal><num value expr>. </literal>Elements are
+ discarded from the end of the array. (Foundation)</para>
+ </section>
+
+ <section>
+ <title>General Functions</title>
+
+ <para>General functions can take different types of arguments. Some
+ General Functions accept a variable number of arguments.</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>COALESCE function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">COALESCE</emphasis></simpara>
+
+ <para><literal>COALESCE( <value expr 1>, <value expr 2> [,
+ ...] )</literal></para>
+
+ <para>Returns <literal><value expr 1></literal> if it is not null,
+ otherwise returns <literal><value expr 2></literal> if not null and
+ so on. The type of both arguments must be comparable. (Foundation)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>CONVERT function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">CONVERT</emphasis></simpara>
+
+ <para><literal>CONVERT ( <value expr> , <data type>
+ )</literal></para>
+
+ <para><literal><data type> ::= { SQL_BIGINT | SQL_BINARY | SQL_BIT
+ |SQL_BLOB | SQL_BOOLEAN | SQL_CHAR | SQL_CLOB | SQL_DATE | SQL_DECIMAL |
+ SQL_DATALINK |SQL_DOUBLE | SQL_FLOAT | SQL_INTEGER | SQL_LONGVARBINARY |
+ SQL_LONGNVARCHAR | SQL_LONGVARCHAR | SQL_NCHAR | SQL_NCLOB | SQL_NUMERIC |
+ SQL_NVARCHAR | SQL_REAL | SQL_ROWID | SQL_SQLXML | SQL_SMALLINT | SQL_TIME
+ | SQL_TIMESTAMP | SQL_TINYINT | SQL_VARBINARY | SQL_VARCHAR} [ (
+ <precision, length or scale parameters> ) ]</literal></para>
+
+ <para>The CONVERT function is a JDBC escape function, equivalent to the
+ SQL standard CAST expression. It converts the <literal><value
+ expr></literal> into the given <literal><data type></literal> and
+ returns the value. The <literal><data type></literal> options are
+ synthetic names made by prefixing type names with <literal>SQL_</literal>.
+ Some of the <literal><data type></literal> options represent valid
+ SQL types, but some are based on non-standard type names, namely
+ <literal>{ SQL_LONGNVARCHAR | SQL_LONGVARBINARY |SQL_LONGVARCHAR |
+ SQL_TINYINT }</literal>. None of the synthetic names can be used in any
+ other context than the CONVERT function.</para>
+
+ <para>The definition of CONVERT in the JDBC Standard does not allow the
+ precision, scale or length to be specified. This is required by the SQL
+ standard for BINARY, BIT, BLOB, CHAR, CLOB, VARBINARY and VARCHAR types
+ and is often needed for DECIMAL and NUMERIC. Therefore, HyperSQL allows
+ the use of precision, scale or length for the type definition when they
+ are valid for the type definition. HyperSQL also allows the use of real
+ type names (without the <literal>SQL_</literal> prefix). (JDBC)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>DECODE function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">DECODE</emphasis></simpara>
+
+ <para><literal>DECODE( <value expr main>, <value expr match
+ 1>, <value expr result 1> [...,] [, <value expr default>]
+ )</literal></para>
+
+ <para>DECODE takes at least 3 arguments. The <literal><value expr
+ main></literal> is compared with <literal><value expr match
+ 1></literal> and if it matches, <literal><value expr result
+ 1></literal> is returned. If there are additional pairs of
+ <literal><value expr match n></literal> and <literal><value expr
+ result n></literal>, comparison is repeated until a match is found the
+ result is returned. If no match is found, the <literal><value expr
+ default></literal> is returned if it is specified, otherwise NULL is
+ returned. The type of the return value is a combination of the types of
+ the <literal><value expr result ... ></literal> arguments.
+ (HyperSQL)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>GREATEST function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">GREATEST</emphasis></simpara>
+
+ <para><literal>GREATEST( <value expr 1>, [<value expr ...>,
+ ...] )</literal></para>
+
+ <para>The GREATEST function takes one or more arguments. It compares the
+ arguments with each other and returns the greatest argument. The return
+ type is the combined type of the arguments. Arguments can be of any type,
+ so long as they are comparable. (HyperSQL)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>IFNULL function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">IFNULL</emphasis></simpara>
+
+ <para><literal>IFNULL( <value expr 1>, <value expr 2>
+ )</literal></para>
+
+ <para>Returns <literal><value expr 1></literal> if it is not null,
+ otherwise returns <literal><value expr 2></literal>. The type of
+ both arguments must be the same. Equivalent to SQL Standard
+ <literal>COALESCE(<value expr 1>, <value expr 2>)</literal>
+ function. (JDBC)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>LEAST function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">LEAST</emphasis></simpara>
+
+ <para><literal>LEAST( <value expr 1>, [<value expr ...>, ...]
+ )</literal></para>
+
+ <para>The LEAST function takes one or more arguments. It compares the
+ arguments with each other and returns the smallest argument. The return
+ type is the combined type of the arguments. Arguments can be of any type,
+ so long as they are comparable. (HyperSQL)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>NULLIF function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">NULLIF</emphasis></simpara>
+
+ <para><literal>NULLIF( <value expr 1>, <value expr 2>
+ )</literal></para>
+
+ <para>Returns <literal><value expr 1></literal> if it is not equal
+ to <literal><value expr 2></literal>, otherwise returns null. The
+ type of both arguments must be the same. This function is a shorthand for
+ a specific CASE expression. (Foundation)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>NVL function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">NVL</emphasis></simpara>
+
+ <para><literal>NVL( <value expr 1>, <value expr 2>
+ )</literal></para>
+
+ <para>Returns <literal><value expr 1></literal> if it is not null,
+ otherwise returns <literal><value expr 2></literal>. The type of the
+ return value is the combined type of the two value expressions. For
+ example, if <value expr 1> is an INTEGER column and
+ <literal><value expr 2></literal> is a DOUBLE constant, the return
+ type is DOUBLE. This function is the same as IFNULL and COALESCE
+ (HyperSQL)</para>
+ </section>
+
+ <section xml:id="builtin_functions_sysfunc-sect">
+ <title>System Functions</title>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>CRYPT_KEY function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">CRYPT_KEY</emphasis></simpara>
+
+ <para><literal>CRYPT_KEY( <value expr 1>, <value expr 2>
+ )</literal></para>
+
+ <para>Returns a binary string representation of a cryptography key for the
+ given cipher and cyptography provider. The cipher specification is
+ specified by <literal><value expr 1></literal> and the provider by
+ <literal><value expr 2></literal>. To use the default provider,
+ specify null for <literal><value expr 2></literal>.
+ (HyperSQL)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>IDENTITY function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">IDENTITY</emphasis></simpara>
+
+ <para><literal>IDENTITY ()</literal></para>
+
+ <para>Returns the last IDENTITY value inserted into a row by the current
+ session. The statement, CALL IDENTITY() can be made after an INSERT
+ statement that inserts a row into a table with an IDENTITY column. The
+ CALL IDENTITY() statement returns the last IDENTITY value that was
+ inserted into a table by the current session. Each session manages this
+ function call separately and is not affected by inserts in other sessions.
+ The statement can be executed as a direct statement or a prepared
+ statement. (HyperSQL)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>DATABASE function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">DATABASE</emphasis></simpara>
+
+ <para><literal>DATABASE ()</literal></para>
+
+ <para>Returns the file name (without directory information) of the
+ database. (JDBC)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>DATABASE_VERSION function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">DATABASE_VERSION</emphasis></simpara>
+
+ <para><literal>DATABASE_VERSION ()</literal></para>
+
+ <para>Returns the full version string for the database engine. For
+ example, 2.0.1. (JDBC)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>USER function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">USER</emphasis></simpara>
+
+ <para><literal>USER ()</literal></para>
+
+ <para>Equivalent to the SQL function <literal>CURRENT_USER</literal>.
+ (JDBC)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>CURRENT_USER function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">CURRENT_USER</emphasis></simpara>
+
+ <para><literal>CURRENT_USER</literal></para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>CURRENT_ROLE function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">CURRENT_ROLE</emphasis></simpara>
+
+ <para><literal>CURRENT_ROLE</literal></para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>SESSION_USER function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">SESSION_USER</emphasis></simpara>
+
+ <para><literal>SESSION_USER</literal></para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>SYSTEM_USER function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">SYSTEM_USER</emphasis></simpara>
+
+ <para><literal>SYSTEM_USER</literal></para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>CURRENT_SCHEMA function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">CURRENT_SCHEMA</emphasis></simpara>
+
+ <para><literal>CURRENT_SCHEMA</literal></para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>CURRENT_CATALOG function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">CURRENT_CATALOG</emphasis></simpara>
+
+ <para><literal>CURRENT_CATALOG</literal></para>
+
+ <para>These functions return the named current session attribute. They are
+ all SQL Standard functions.</para>
+
+ <para>The CURRENT_USER is the user that connected to the database, or a
+ user subsequently set by the SET AUTHORIZATION statement.</para>
+
+ <para>SESSION_USER is the same as CURRENT_USER</para>
+
+ <para>SYSTEM_USER is the user that connected to the database. It is not
+ changed with any command until the session is closed.</para>
+
+ <para>CURRENT_SCHEMA is default schema of the user, or a schema
+ subsequently set by the SET SCHEMA command.</para>
+
+ <para>CURRENT_CATALOG is always the same within a given HyperSQL database
+ and indicates the name of the catalog.</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>ISAUTOCOMMIT function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">ISAUTOCOMMIT</emphasis></simpara>
+
+ <para><literal>ISAUTOCOMMIT()</literal></para>
+
+ <para>Returns TRUE if the session is in autocommit mode. (HyperSQL)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>ISREADONLYSESSION function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">ISREADONLYSESSION</emphasis></simpara>
+
+ <para><literal>ISREADONLYSESSION()</literal></para>
+
+ <para>Returns TRUE if the session is in read only mode. (HyperSQL)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>ISREADONLYDATABASE function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">ISREADONLYDATABASE</emphasis></simpara>
+
+ <para><literal>ISREADONLYDATABASE()</literal></para>
+
+ <para>Returns TRUE if the database is a read only database.
+ (HyperSQL)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>ISREADONLYDATABASEFILES function</primary>
+ </indexterm>
+
+ <simpara><emphasis
+ role="bold">ISREADONLYDATABASEFILES</emphasis></simpara>
+
+ <para><literal>ISREADONLYDATABASEFILES()</literal></para>
+
+ <para>Returns TRUE if the database is a read-only files database. In this
+ kind of database, it is possible to modify the data, but the changes are
+ not persisted to the database files. (HyperSQL)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>ISOLATION_LEVEL function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">ISOLATION_LEVEL</emphasis></simpara>
+
+ <para><literal>ISOLATION_LEVEL()</literal></para>
+
+ <para>Returns the current transaction isolation level for the session.
+ Returns either READ COMMITTED or SERIALIZABLE as a string.
+ (HyperSQL)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>SESSION_ISOLATION_LEVEL function</primary>
+ </indexterm>
+
+ <simpara><emphasis
+ role="bold">SESSION_ISOLATION_LEVEL</emphasis></simpara>
+
+ <para><literal>SESSION_ISOLATION_LEVEL()</literal></para>
+
+ <para>Returns the default transaction isolation level for the current
+ session. Returns either READ COMMITTED or SERIALIZABLE as a string.
+ (HyperSQL)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>DATABASE_ISOLATION_LEVEL function</primary>
+ </indexterm>
+
+ <simpara><emphasis
+ role="bold">DATABASE_ISOLATION_LEVEL</emphasis></simpara>
+
+ <para><literal>DATABASE_ISOLATION_LEVEL()</literal></para>
+
+ <para>Returns the default transaction isolation level for the database.
+ Returns either READ COMMITTED or SERIALIZABLE as a string.
+ (HyperSQL)</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>TRANSACTION_CONTROL function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">TRANSACTION_CONTROL</emphasis></simpara>
+
+ <para><literal>TRANSACTION_CONTROL()</literal></para>
+
+ <para>Returns the current transaction model for the database. Returns
+ LOCKS, MVLOCKS or MVCC as a string. (HyperSQL)</para>
+ </section>
+</chapter>
diff --git a/doc-src/guide/dataaccess.xml b/doc-src/guide/dataaccess.xml
new file mode 100644
index 0000000..51d7240
--- /dev/null
+++ b/doc-src/guide/dataaccess.xml
@@ -0,0 +1,3127 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter version="5.0" xml:id="dataaccess-chapt"
+ xmlns="http://docbook.org/ns/docbook"
+ xmlns:xlink="http://www.w3.org/1999/xlink"
+ xmlns:xi="http://www.w3.org/2001/XInclude"
+ xmlns:ns5="http://www.w3.org/2000/svg"
+ xmlns:ns4="http://www.w3.org/1998/Math/MathML"
+ xmlns:ns3="http://www.w3.org/1999/xhtml"
+ xmlns:ns="http://docbook.org/ns/docbook">
+ <title xml:id="dataaccess-title">Data Access and Change</title>
+
+ <info>
+ <authorgroup>
+ <author>
+ <personname><firstname>Fred</firstname><surname>Toussi</surname></personname>
+
+ <affiliation>
+ <orgname>The HSQL Development Group</orgname>
+ </affiliation>
+ </author>
+ </authorgroup>
+
+ <releaseinfo>$Revision: 3601 $</releaseinfo>
+
+ <pubdate>$Date: 2010-05-31 20:17:47 -0400 (Mon, 31 May 2010) $</pubdate>
+
+ <keywordset>
+ <keyword>Hsqldb</keyword>
+
+ <keyword>HyperSQL</keyword>
+
+ <keyword>SQL</keyword>
+ </keywordset>
+
+ <legalnotice>
+ <para>Copyright 2010 Fred Toussi. Permission is granted to distribute
+ this document without any alteration under the terms of the HSQLDB
+ license. Additional permission is granted to the HSQL Development Group
+ to distribute this document with or without alterations under the terms
+ of the HSQLDB license.</para>
+ </legalnotice>
+ </info>
+
+ <section>
+ <title>Overview</title>
+
+ <para>HyperSQL data access and data change statements are fully compatible
+ with the latest SQL:2008 Standard. There are a few extensions and some
+ relaxation of rules, but these do not affect statements that are written
+ to the Standard syntax. There is full support for classic SQL, as
+ specified by SQL-92, and many enhancements added in later versions of the
+ standard.</para>
+ </section>
+
+ <section>
+ <title>Cursors And Result Sets</title>
+
+ <para>An SQL statement can executed in two ways. One way is to use the
+ <classname>java.sql.Statement</classname> interface. The Statement object
+ can be reused to execute completely different SQL statements.
+ Alternatively a <classname>PreparedStatment</classname> can be used to
+ execute an SQL statement repeatedly, and the statements can be
+ parameterized. Using either form, if the SQL statement is a query
+ expression, a <classname>ResultSet</classname> is returned.</para>
+
+ <para>In SQL, when a query expression (SELECT or similar SQL statement) is
+ executed, an ephemeral table is created. When this table is returned to
+ the application program, it is returned as a result set, which is accessed
+ row-by-row by a cursor. A JDBC <classname>ResultSet</classname> represents
+ an SQL result set and its cursor.</para>
+
+ <para>The minimal definition of a cursor is a list of rows with a position
+ that can move forward. Some cursors also allow the position to move
+ backwards or jump to any position in the list.</para>
+
+ <para>An SQL cursor has several attributes. These attributes depend on the
+ query expression. Some of these attributes can be overridden by specifying
+ qualifiers in the SQL statement or by specifying values for the parameters
+ of the JDBC <classname>Statement</classname> or
+ <classname>PreparedStatement</classname>.</para>
+
+ <section>
+ <title>Columns and Rows</title>
+
+ <para>The columns of the rows of the result set are determined by the
+ query expression. The number of columns and the type and name
+ characteristics of each column are known when the query expression is
+ compiled and before its execution. This metadata information remains
+ constant regardless of changes to the contents of the tables used in the
+ query expression. The metadata for the JDBC
+ <classname>ResultSet</classname> is in the form of a
+ <classname>ResultSetMetaData</classname> object. Various methods of the
+ <classname>ResultSetMetaData</classname> interface return different
+ properties of each column of the
+ <classname>ResultSet</classname>.</para>
+
+ <para>A result set may contain 0 or more rows. The rows are determined
+ by the execution of the query expression.</para>
+
+ <para>The <methodname>setMaxRows(int)</methodname> method of JDBC
+ <classname>Statement</classname> allows limiting the number of rows
+ returned by the statement. This limit is conceptually applied after the
+ result has been built, and the excess rows are discarded.</para>
+ </section>
+
+ <section>
+ <title>Navigation</title>
+
+ <para>A cursor is either scrollable or not. Scrollable cursors allow
+ accessing rows by absolute or relative positioning. No-scroll cursors
+ only allow moving to the next row. The cursor can be optionally declared
+ with the SQL qualifiers SCROLL, or NO SCROLL. The JDBC statement
+ parameter can be specified as: TYPE_FORWARD_ONLY and
+ TYPE_SCROLL_INSENSITIVE. The JDBC type TYPE_SCROLL_SENSITIVE is not
+ supported by HSQLDB.</para>
+
+ <para>The default is NO SCROLL or TYPE_FORWARD_ONLY.</para>
+
+ <para>When a JDBC <classname>ResultSet</classname> is opened, it is
+ positioned before the first row. Using the
+ <methodname>next()</methodname> method the position is moved to the
+ first row. While the <classname>ResultSet</classname> is positioned on a
+ row, various getter methods can be used to access the columns of the
+ row.</para>
+ </section>
+
+ <section>
+ <title>Updatability</title>
+
+ <para>The result returned by some query expressions is updatable. HSQLDB
+ supports core SQL updatability features, plus some enhancements from the
+ SQL optional features.</para>
+
+ <para>A query expression is updatable if it is a SELECT from a single
+ underlying base table (or updatable view) either directly or indirectly.
+ A SELECT statement featuring DISTINCT or GROUP BY or FETCH, LIMIT,
+ OFFSET is not updatable. In an updatable query expression, one or more
+ columns are updatable. An updatable column is a column that can be
+ traced directly to the underlying table. Therefore, columns that contain
+ expressions are not updatable. Examples of updatable query expressions
+ are given below. The view V is updatable when its query expression is
+ updatable. The SELECT statement from this view is also updatable:</para>
+
+ <programlisting>SELECT A, B FROM T WHERE C > 5
+SELECT A, B FROM (SELECT * FROM T WHERE C > 10) AS TT WHERE TT.B <10
+CREATE VIEW V(X,Y) AS SELECT A, B FROM T WHERE C > 0 AND B < 10
+SELECT X FROM V WHERE Y = 5
+</programlisting>
+
+ <para>If a cursor is declared with the SQL qualifier, <literal>FOR
+ UPDATE OF <column name list></literal>, then only the stated
+ columns in the result set become updatable. If any of the stated columns
+ is not actually updatable, then the cursor declaration will not
+ succeed.</para>
+
+ <para>If the SQL qualifier, FOR UPDATE is used, then all the updatable
+ columns of the result set become updatable.</para>
+
+ <para>If a cursor is declared with FOR READ ONLY, then it is not
+ updatable.</para>
+
+ <para>In HSQLDB, if FOR READ ONLY or FOR UPDATE is not used then all the
+ updatable columns of the result set become updatable. This relaxes the
+ SQL standard rule that in this case limits updatability to only simply
+ updatable SELECT statements (where all columns are updatable).</para>
+
+ <para>In JDBC, CONCUR_READ_ONLY or CONCUR_UPDATABLE can be specified for
+ the <classname>Statement</classname> parameter. CONCUR_UPDATABLE is
+ required if the returning ResultSet is to be updatable. If
+ CONCUR_READ_ONLY, which is the default, is used, then even an updatable
+ ResultSet becomes read-only.</para>
+
+ <para>When a <classname>ResultSet</classname> is updatable, various
+ setter methods can be used to modify the column values. The names of the
+ setter methods begin with "update". After all the updates on a row are
+ done, the <methodname>updateRow()</methodname> method must be called to
+ finalise the row update.</para>
+
+ <para>An updatable <classname>ResultSet</classname> may or may not be
+ insertable-into. In an insertable <classname>ResultSet</classname>, all
+ columns of the result are updatable and any column of the base table
+ that is not in the result must be a generated column or have a default
+ value.</para>
+
+ <para>In the <classname>ResultSet</classname> object, a special
+ pseudo-row, called the insert row, is used to populate values for
+ insertion into the <classname>ResultSet</classname> (and consequently,
+ into the base table). The setter methods must be used on all the
+ columns, followed by a call to
+ <methodname>insertRow()</methodname>.</para>
+
+ <para>Individual rows from all updatable result sets can be deleted one
+ at a time. The <methodname>deleteRow()</methodname> is called when the
+ <classname>ResultSet</classname> is positioned on a row.</para>
+
+ <para>While using an updatable ResultSet to modify data, it is
+ recommended not to change the same data using another ResultSet and not
+ to execute SQL data change statements that modify the same data.</para>
+ </section>
+
+ <section>
+ <title>Sensitivity</title>
+
+ <para>The sensitivity of the cursor relates to visibility of changes
+ made to the data by the same transaction but without using the given
+ cursor. While the result set is open, the same transaction may use
+ statements such as INSERT or UPDATE, and change the data of the tables
+ from which the result set data is derived. A cursor is SENSITIVE if it
+ reflects those changes. It is INSENSITIVE if it ignores such changes. It
+ is ASENSITIVE if behaviour is implementation dependent.</para>
+
+ <para>The SQL default is ASENSITIVE, i.e., implantation
+ dependent.</para>
+
+ <para>In HSQLDB all cursors are INSENSITIVE. They do not reflect changes
+ to the data made by other statements.</para>
+ </section>
+
+ <section>
+ <title>Holdability</title>
+
+ <para>A cursor is holdable if the result set is not automatically closed
+ when the current transaction is committed. Holdability can be specified
+ in the cursor declaration using the SQL qualifiers WITH HOLD or WITHOUT
+ HOLD.</para>
+
+ <para>In JDBC, hodability is specified using either of the following
+ values for the Statement parameter: HOLD_CURSORS_OVER_COMMIT, or
+ CLOSE_CURSORS_AT_COMMIT.</para>
+
+ <para>The SQL default is WITHOUT HOLD.</para>
+
+ <para>The JDBC default for HSQLDB result sets is WITH HOLD for read-only
+ result sets and WITHOUT HOLD for updatable result sets.</para>
+
+ <para>If the holdability of a <classname>ResultSet</classname> is
+ specified in a conflicting manner in the SQL statement and the JDBC
+ <classname>Statement</classname> object, the JDBC setting takes
+ precedence.</para>
+ </section>
+
+ <section>
+ <title>Autocommit</title>
+
+ <para>The autocommit property of a connection is a feature of JDBC and
+ ODBC and is not part of the SQL Standard. In autocommit mode, all
+ transactional statements are followed by an implicit commit. In
+ autocommit mode, all <classname>ResultSet</classname> objects are
+ read-only and holdable.</para>
+ </section>
+
+ <section>
+ <title>JDBC Overview</title>
+
+ <para>The JDBC settings, ResultSet.CONCUR_READONLY and
+ ResultSet.CONCUR_UPDATABLE are the alternatives for read-only or
+ updatability. The default is ResultSet.CONCUR_READONLY.</para>
+
+ <para>The JDBC settings, ResultSet.TYPE_FORWARD_ONLY,
+ ResultSet.TYPE_SCROLL_INSENSITIVE, ResultSet.TYPE_SCROLL_SENSITIVE are
+ the alternatives for both scrollability (navigation) and sensitivity.
+ HyperSQL does not support ResultSet.TYPE_SCROLL_SENSITIVE. The two other
+ alternatives can be used for both updatable and read-only result
+ sets.</para>
+
+ <para>The JDBC settings ResultSet.CLOSE_CURSORS_AT_COMMIT and
+ ResultSet.HOLD_CURSORS_OVER_COMMIT are the alternatives for the lifetime
+ of the result set. The default is ResultSet.CLOSE_CURSORS_AT_COMMIT. The
+ other setting can only be used for read-only result sets.</para>
+
+ <para>Examples of creating statements for updatable result sets are
+ given below:</para>
+
+ <programlisting>Connection c = newConnection();
+Statement st;
+c.setAutoCommit(false);
+st = c.createStatement(ResultSet.TYPE_FORWARD_ONLY, ResultSet.CONCUR_UPDATABLE);
+st = c.createStatement(ResultSet.TYPE_SCROLL_INSENSITIVE, ResultSet.CONCUR_UPDATABLE);</programlisting>
+ </section>
+
+ <section>
+ <title>JDBC Parameters</title>
+
+ <para>When a JDBC PreparedStatement or CallableStatement is used with an
+ SQL statement that contains dynamic parameters, the data types of the
+ parameters are resolved and determined by the engine when the statement
+ is prepared. The SQL Standard has detailed rules to determine the data
+ types and imposes limits on the maximum length or precision of the
+ parameter. HyperSQL applies the standard rules with two exceptions for
+ parameters with String and BigDecimal Java types. HyperSQL ignores the
+ limits when the parameter value is set, and only enforces the necessary
+ limits when the PreparedStatement is executed. In all other cases,
+ parameter type limits are checked and enforce when the parameter is
+ set.</para>
+
+ <para>In the example below the setString() calls do not raise an
+ exception, but one of the execute() statements does.</para>
+
+ <programlisting>// table definition: CREATE TABLE T (NAME VARCHAR(12), ...)
+Connection c = newConnection();
+PreparedStatement st = c.prepareStatement("SELECT * FROM T WHERE NAME = ?");
+// type of the parameter is VARCHAR(12), which limits length to 12 characters
+st.setString(1, "Eyjafjallajokull"); // string is longer than type, but no exception is raised here
+set.execute(); // executes with no exception and does not find any rows
+// but if an UPDATE is attempted, an exception is raised
+st = c.prepareStatement("UPDATE T SET NAME = ? WHERE ID = 10");
+st.setString(1, "Eyjafjallajokull"); // string is longer than type, but no exception is raised here
+st.execute(); // exception is thrown when HyperSQL checks the value for update
+
+</programlisting>
+
+ <para>All of the above also applies to setting the values in new and
+ updated rows in updatable ResultSet objects.</para>
+
+ <para>JDBC parameters can be set with any compatible type, as supported
+ by the JDBC specification. For CLOB and BLOB types, you can use streams,
+ or create instances of BLOB or CLOB before assigning them to the
+ parameters. You can even use CLOB or BLOB objects returned from
+ connections to other RDBMS servers. The Connection.createBlob() and
+ createClob() methods can be used to create the new LOBs. For very large
+ LOB's the stream methods are preferable as they use less memory.</para>
+
+ <para>For array parameters, you must use a java.sql.Array object that
+ contains the array elements before assigning to JDBC parameters. The
+ Connection.createArrayOf(...) method can be used to create a new object,
+ or you can use an Array returned from connections to other RDBMS
+ servers.</para>
+ </section>
+
+ <section>
+ <title>JDBC Returned Values</title>
+
+ <para>The methods of the JDBC ResultSet interface can be used to return
+ values and to convert value to different types as supported by the JDBC
+ specification.</para>
+
+ <para>When a CLOB and BLOB object is returned from a ResultSet, no data
+ is transferred until the data is read by various methods of
+ java.sql.CLOB and java.sql.BLOB. Data is streamed in large blocks to
+ avoid excessive memory use.</para>
+
+ <para>Array objects are returned as instances of java.sql.Array.</para>
+ </section>
+ </section>
+
+ <section>
+ <title>Syntax Elements</title>
+
+ <para>The syntax elements that can be used in data access and data change
+ statements are described in this section. The SQL Standard has a very
+ extensive set of definitions for these elements. The BNF definitions given
+ here are sometimes simplified.</para>
+
+ <section>
+ <title>Literals</title>
+
+ <para>Literals are used to express constant values. The general type of
+ a literal is known by its format. The specific type is based on
+ conventions.</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>unicode escape elements</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">unicode escape
+ elements</emphasis></simpara>
+
+ <simpara><emphasis>unicode escape elements</emphasis></simpara>
+
+ <simpara><literal><Unicode escape specifier> ::= [ UESCAPE
+ <quote><Unicode escape character><quote> ]
+ </literal></simpara>
+
+ <simpara><literal><Unicode escape value> ::= <Unicode 4 digit
+ escape value> | <Unicode 6 digit escape value> | <Unicode
+ character escape value></literal></simpara>
+
+ <simpara><literal><Unicode 4 digit escape value> ::= <Unicode
+ escape
+ character><hexit><hexit><hexit><hexit></literal></simpara>
+
+ <simpara><literal><Unicode 6 digit escape value> ::= <Unicode
+ escape character><plus sign>
+ <hexit><hexit><hexit><hexit><hexit><hexit></literal></simpara>
+
+ <simpara><literal><Unicode character escape value> ::= <Unicode
+ escape character><Unicode escape character></literal></simpara>
+
+ <simpara><literal><Unicode escape character> ::= a single
+ character than a <hexit> (a-f, A-F, 0-9), <plus sign>,
+ <quote>, <double quote>, or <white
+ space></literal></simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>character literal</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">character literal</emphasis></simpara>
+
+ <simpara><emphasis>character literal</emphasis></simpara>
+
+ <simpara><literal><character string literal> ::= [
+ <introducer><character set specification> ] <quote> [
+ <character representation>... ] <quote> [ {
+ <separator> <quote> [ <character representation>... ]
+ <quote> }... ]</literal></simpara>
+
+ <simpara><literal><introducer> ::=
+ <underscore></literal></simpara>
+
+ <simpara><literal><character representation> ::= <nonquote
+ character> | <quote symbol></literal></simpara>
+
+ <simpara><literal><nonquote character> ::= any character apart
+ from the quote symbol.</literal></simpara>
+
+ <simpara><literal><quote symbol> ::=
+ <quote><quote></literal></simpara>
+
+ <simpara><literal><national character string literal> ::= N
+ <quote> [ <character representation>... ] <quote> [ {
+ <separator> <quote> [ <character representation>... ]
+ <quote> }... ]</literal></simpara>
+
+ <simpara><literal><Unicode character string literal> ::= [
+ <introducer><character set specification> ]
+ U<ampersand><quote> [ <Unicode representation>... ]
+ <quote> [ { <separator> <quote> [ <Unicode
+ representation>... ] <quote> }... ] <Unicode escape
+ specifier></literal></simpara>
+
+ <simpara><literal><Unicode representation> ::= <character
+ representation> | <Unicode escape value></literal></simpara>
+
+ <simpara>The type of a character literal is CHARACTER. The length of the
+ string literal is the character length of the type. If the quote
+ character is used in a string, it is represented with two quote
+ characters. Long literals can be divided into multiple quoted strings,
+ separated with a space or end-of-line character.</simpara>
+
+ <simpara>Unicode literals start with U& and can contain ordinary
+ characters and unicode escapes. A unicode escape begins with the
+ backslash ( \ ) character and is followed by four hexadecimal characters
+ which specify the character code.</simpara>
+
+ <simpara>Example of character literals are given below:</simpara>
+
+ <programlisting>'a literal' ' string seperated' ' into parts'
+'a string''s literal form with quote character'
+U&'Unicode string with Greek delta \0394 and phi \03a6 letters'
+</programlisting>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>binary literal</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">binary literal</emphasis></simpara>
+
+ <simpara><emphasis>binary literal</emphasis></simpara>
+
+ <simpara><literal><binary string literal> ::= X <quote> [
+ <space>... ] [ { <hexit> [ <space>... ] <hexit>
+ [ <space>... ] }... ] <quote> [ { <separator>
+ <quote> [ <space>... ] [ { <hexit> [ <space>...
+ ] <hexit> [ <space>... ] }... ] <quote> }...
+ ]</literal></simpara>
+
+ <simpara><literal><hexit> ::= <digit> | A | B | C | D | E |
+ F | a | b | c | d | e | f</literal></simpara>
+
+ <simpara>The type of a binary literal is BINARY. The octect length of
+ the binary literal is the length of the type. Case-insensitive
+ hexadecimal characters are used in the binary string. Each pair of
+ characters in the literal represents a byte in the binary string. Long
+ literals can be divided into multiple quoted strings, separated with a
+ space or end-of-line character.</simpara>
+
+ <programlisting>X'1abACD34' 'Af'</programlisting>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>bit literal</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">bit literal</emphasis></simpara>
+
+ <simpara><emphasis>bit literal</emphasis></simpara>
+
+ <simpara><literal><bit string literal> ::= B <quote> [
+ <bit> ... ] <quote> [ { <separator> <quote> [
+ <bit>... ] <quote> }... ]</literal></simpara>
+
+ <simpara><literal><bit> ::= 0 | 1</literal></simpara>
+
+ <simpara>The type of a binary literal is BIT. The bit length of the bit
+ literal is the length of the type. Digits 0 and 1 are used to represent
+ the bits. Long literals can be divided into multiple quoted strings,
+ separated with a space or end-of-line character.</simpara>
+
+ <programlisting>B'10001001' '00010'</programlisting>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>numeric literal</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">numeric literal</emphasis></simpara>
+
+ <simpara><emphasis>numeric literal</emphasis></simpara>
+
+ <simpara><literal><signed numeric literal> ::= [ <sign> ]
+ <unsigned numeric literal></literal></simpara>
+
+ <simpara><literal><unsigned numeric literal> ::= <exact numeric
+ literal> | <approximate numeric literal></literal></simpara>
+
+ <simpara><literal><exact numeric literal> ::= <unsigned
+ integer> [ <period> [ <unsigned integer> ] ] |
+ <period> <unsigned integer></literal></simpara>
+
+ <simpara><literal><sign> ::= <plus sign> | <minus
+ sign></literal></simpara>
+
+ <simpara><literal><approximate numeric literal> ::=
+ <mantissa> E <exponent></literal></simpara>
+
+ <simpara><literal><mantissa> ::= <exact numeric
+ literal></literal></simpara>
+
+ <simpara><literal><exponent> ::= <signed
+ integer></literal></simpara>
+
+ <simpara><literal><signed integer> ::= [ <sign> ]
+ <unsigned integer></literal></simpara>
+
+ <simpara><literal><unsigned integer> ::=
+ <digit>...</literal></simpara>
+
+ <simpara>The type of an exact numeric literal without a decimal point is
+ INTEGER, BIGINT, or DECIMAL, depending on the value of the literal (the
+ smallest type that can represent the value is the type).</simpara>
+
+ <simpara>The type of an exact numeric literal with a decimal point is
+ DECIMAL. The precision of a decimal literal is the total number of
+ digits of the literal. The scale of the literal is the total number of
+ digits to the right of the decimal point.</simpara>
+
+ <simpara>The type of an approximate numeric literal is DOUBLE. An
+ approximate numeric literal always includes the mantissa and exponent,
+ separated by E.</simpara>
+
+ <programlisting>12
+34.35
++12E-2
+</programlisting>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>boolean literal</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">boolean literal</emphasis></simpara>
+
+ <simpara><emphasis>boolean literal</emphasis></simpara>
+
+ <simpara><literal><boolean literal> ::= TRUE | FALSE |
+ UNKNOWN</literal></simpara>
+
+ <simpara>The boolean literal is one of the specified keywords.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>datetime and interval literal</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">datetime and interval
+ literal</emphasis></simpara>
+
+ <simpara><emphasis>datetime and interval literal</emphasis></simpara>
+
+ <simpara><literal><datetime literal> ::= <date literal> |
+ <time literal> | <timestamp literal></literal></simpara>
+
+ <simpara><literal><date literal> ::= DATE <date
+ string></literal></simpara>
+
+ <simpara><literal><time literal> ::= TIME <time
+ string></literal></simpara>
+
+ <simpara><literal><timestamp literal> ::= TIMESTAMP <timestamp
+ string></literal></simpara>
+
+ <simpara><literal><date string> ::= <quote> <unquoted
+ date string> <quote></literal></simpara>
+
+ <simpara><literal><time string> ::= <quote> <unquoted
+ time string> <quote></literal></simpara>
+
+ <simpara><literal><timestamp string> ::= <quote>
+ <unquoted timestamp string> <quote></literal></simpara>
+
+ <simpara><literal><time zone interval> ::= <sign> <hours
+ value> <colon> <minutes value></literal></simpara>
+
+ <simpara><literal><date value> ::= <years value> <minus
+ sign> <months value> <minus sign> <days
+ value></literal></simpara>
+
+ <simpara><literal><time value> ::= <hours value>
+ <colon> <minutes value> <colon> <seconds
+ value></literal></simpara>
+
+ <simpara><literal><interval literal> ::= INTERVAL [ <sign> ]
+ <interval string> <interval qualifier></literal></simpara>
+
+ <simpara><literal><interval string> ::= <quote> <unquoted
+ interval string> <quote></literal></simpara>
+
+ <simpara><literal><unquoted date string> ::= <date
+ value></literal></simpara>
+
+ <simpara><literal><unquoted time string> ::= <time value> [
+ <time zone interval> ]</literal></simpara>
+
+ <simpara><literal><unquoted timestamp string> ::= <unquoted
+ date string> <space> <unquoted time
+ string></literal></simpara>
+
+ <simpara><literal><unquoted interval string> ::= [ <sign> ]
+ { <year-month literal> | <day-time literal>
+ }</literal></simpara>
+
+ <simpara><literal><year-month literal> ::= <years value> [
+ <minus sign> <months value> ] | <months
+ value></literal></simpara>
+
+ <simpara><literal><day-time literal> ::= <day-time interval>
+ | <time interval></literal></simpara>
+
+ <simpara><literal><day-time interval> ::= <days value> [
+ <space> <hours value> [ <colon> <minutes value>
+ [ <colon> <seconds value> ] ] ]</literal></simpara>
+
+ <simpara><literal><time interval> ::= <hours value> [
+ <colon> <minutes value> [ <colon> <seconds
+ value> ] ] | <minutes value> [ <colon> <seconds
+ value> ] | <seconds value></literal></simpara>
+
+ <simpara><literal><years value> ::= <datetime
+ value></literal></simpara>
+
+ <simpara><literal><months value> ::= <datetime
+ value></literal></simpara>
+
+ <simpara><literal><days value> ::= <datetime
+ value></literal></simpara>
+
+ <simpara><literal><hours value> ::= <datetime
+ value></literal></simpara>
+
+ <simpara><literal><minutes value> ::= <datetime
+ value></literal></simpara>
+
+ <simpara><literal><seconds value> ::= <seconds integer
+ value> [ <period> [ <seconds fraction> ]
+ ]</literal></simpara>
+
+ <simpara><literal><seconds integer value> ::= <unsigned
+ integer></literal></simpara>
+
+ <simpara><literal><seconds fraction> ::= <unsigned
+ integer></literal></simpara>
+
+ <simpara><literal><datetime value> ::= <unsigned
+ integer></literal></simpara>
+
+ <simpara>The type of a datetime or interval type is specified in the
+ literal. The fractional second precision is the number of digits in the
+ fractional part of the literal. Details are described in the <link
+ endterm="sqlgeneral-title" xlink:href="#sqlgeneral-chapt"></link>
+ chapter</simpara>
+
+ <programlisting>DATE '2008-08-08'
+TIME '20:08:08'
+TIMESTAMP '2008-08-08 20:08:08.235'
+
+INTERVAL '10' DAY
+INTERVAL -'08:08' MINUTE TO SECOND
+</programlisting>
+ </section>
+
+ <section>
+ <title>References, etc.</title>
+
+ <para>References are identifier chains, which can be a single
+ identifiers or identifiers chains composed of single identifiers chained
+ together with the period symbol.</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>identifier chain</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">identifier chain</emphasis></simpara>
+
+ <simpara><emphasis>identifier chain</emphasis></simpara>
+
+ <simpara><literal><identifier chain> ::= <identifier> [ {
+ <period> <identifier> }... ]</literal></simpara>
+
+ <simpara><literal><basic identifier chain> ::= <identifier
+ chain></literal></simpara>
+
+ <simpara>A period-separated chain of identifiers. The identifiers in an
+ identifier chain can refer to database objects in a hierarchy. The
+ possible hierarchies are as follows. In each hierarchy, elements from
+ the start or the end can be missing, but the order of elements cannot be
+ changed.</simpara>
+
+ <simpara>catalog, schema, database object</simpara>
+
+ <simpara>catalog, schema, table, column</simpara>
+
+ <simpara>correlation name, column</simpara>
+
+ <simpara>Examples of identifier chain are given below:</simpara>
+
+ <programlisting>SELECT MYCAT.MYSCHEMA.MYTABLE.MYCOL FROM MYCAT.MYSCHEMA.MYTABLE
+DROP TABLE MYCAT.MYSCHEMA.MYTABLE CASCADE
+ALTER SEQUENCE MYCAT.MYSCHEMA.MYSEQUENCE RESTART WITH 100
+</programlisting>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>column reference</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">column reference</emphasis></simpara>
+
+ <simpara><emphasis>column reference</emphasis></simpara>
+
+ <simpara><literal><column reference> ::= <basic identifier
+ chain> | MODULE <period> <qualified identifier>
+ <period> <column name></literal></simpara>
+
+ <simpara>Reference a column or a routine variable.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>SQL parameter reference</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">SQL parameter
+ reference</emphasis></simpara>
+
+ <simpara><emphasis>SQL parameter reference</emphasis></simpara>
+
+ <simpara><literal><SQL parameter reference> ::= <basic
+ identifier chain></literal></simpara>
+
+ <simpara>Reference an SQL routine parameter.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>contextually typed value specification</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">contextually typed value
+ specification</emphasis></simpara>
+
+ <simpara><emphasis>contextually typed value
+ specification</emphasis></simpara>
+
+ <simpara><literal><contextually typed value specification> ::=
+ <null specification> | <default
+ specification></literal></simpara>
+
+ <simpara><literal><null specification> ::=
+ NULL</literal></simpara>
+
+ <simpara><literal><default specification> ::=
+ DEFAULT</literal></simpara>
+
+ <simpara>Specify a value whose data type or value is inferred from its
+ context. DEFAULT is used for assignments to table columns that have a
+ default value, or to table columns that are generated either as an
+ IDENTITY value or as an expression. NULL can be used only in a context
+ where the type of the value is known. For example, a NULL can be
+ assigned to a column of the table in an INSERT or UPDATE statement,
+ because the type of the column is known. But if NULL is used in a SELECT
+ list, it must be used in a CAST statement.</simpara>
+ </section>
+
+ <section>
+ <title>Value Expression</title>
+
+ <para>Value expression is a general name for all expressions that return
+ a value. Different types of expressions are allowed in different
+ contexts.</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>value expression primary</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">value expression
+ primary</emphasis></simpara>
+
+ <simpara><emphasis>value expression primary</emphasis></simpara>
+
+ <simpara><literal><value expression primary> ::= <parenthesized
+ value expression> | <nonparenthesized value expression
+ primary></literal></simpara>
+
+ <simpara><literal><parenthesized value expression> ::= <left
+ paren> <value expression> <right
+ paren></literal></simpara>
+
+ <simpara><literal><nonparenthesized value expression primary> ::=
+ <unsigned value specification> | <column reference> |
+ <set function specification> | <scalar subquery> | <case
+ expression> | <cast specification> | <next value
+ expression> | <routine invocation></literal></simpara>
+
+ <simpara>Specify a value that is syntactically self-delimited.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>value specification</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">value specification</emphasis></simpara>
+
+ <simpara><emphasis>value specification</emphasis></simpara>
+
+ <simpara><literal><value specification> ::= <literal> |
+ <general value specification></literal></simpara>
+
+ <simpara><literal><unsigned value specification> ::= <unsigned
+ literal> | <general value specification></literal></simpara>
+
+ <simpara><literal><target specification> ::= <host parameter
+ specification> | <SQL parameter reference> | <column
+ reference> | <dynamic parameter
+ specification></literal></simpara>
+
+ <simpara><literal><simple target specification> ::= <host
+ parameter specification> | <SQL parameter reference> |
+ <column reference> | <embedded variable
+ name></literal></simpara>
+
+ <simpara><literal><host parameter specification> ::= <host
+ parameter name> [ <indicator parameter> ]</literal></simpara>
+
+ <simpara><literal><dynamic parameter specification> ::=
+ <question mark></literal></simpara>
+
+ <simpara>Specify one or more values, host parameters, SQL parameters,
+ dynamic parameters, or host variables.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>row value expression</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">row value expression</emphasis></simpara>
+
+ <simpara><emphasis>row value expression</emphasis></simpara>
+
+ <simpara><literal><row value expression> ::= <row value special
+ case> | <explicit row value constructor> </literal></simpara>
+
+ <simpara><literal><row value predicand> ::= <row value special
+ case> | <row value constructor predicand></literal></simpara>
+
+ <simpara><literal><row value special case> ::=
+ <nonparenthesized value expression primary></literal></simpara>
+
+ <simpara><literal><explicit row value constructor> ::= <left
+ paren> <row value constructor element> <comma> <row
+ value constructor element list> <right paren>
+ |</literal></simpara>
+
+ <simpara><literal> ROW <left paren> <row value constructor
+ element list> <right paren> | <row
+ subquery></literal></simpara>
+
+ <simpara>Specify a row consisting of one or more elements. A comma
+ separated list of expressions, enclosed in brackets, with the optional
+ keyword ROW. In SQL, a row containing a single element can often be used
+ where a single value is expected.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>set function specification</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">set function
+ specification</emphasis></simpara>
+
+ <simpara><emphasis>set function specification</emphasis></simpara>
+
+ <simpara><literal><set function specification> ::= <aggregate
+ function> | <grouping operation></literal></simpara>
+
+ <simpara><literal><grouping operation> ::= GROUPING <left
+ paren> <column reference> [ { <comma> <column
+ reference> }... ] <right paren></literal></simpara>
+
+ <simpara>Specify a value derived by the application of a function to an
+ argument. Early releases of HyperSQL 2.0 do not support
+ <literal><grouping operation></literal> .</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>COALESCE expression</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">COALESCE</emphasis></simpara>
+
+ <simpara><emphasis>coalesce expression</emphasis></simpara>
+
+ <simpara><literal><coalesce expression> := COALESCE <left
+ paren> <value expression> { <comma> <value
+ expression> }... <right paren></literal></simpara>
+
+ <simpara>Replace null values with another value. The coalesce expression
+ has two or more instances of <value expression>. If the first
+ <value expression> evaluates to a non-null value, it is returned
+ as the result of the coalesce expression. If it is null, the next
+ <literal><value expression></literal> is evaluated and if it
+ evaluates to a non-non value, it is returned, and so on.</simpara>
+
+ <simpara>The type of the return value of a COALESCE expression is the
+ aggregate type of the types of all the <literal><value
+ expression></literal> instances. Therefore, any value returned is
+ implicitly cast to this type. HyperSQL also features built-in functions
+ with similar functionality.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>NULLIF expression</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">NULLIF</emphasis></simpara>
+
+ <simpara><emphasis>nullif expression</emphasis></simpara>
+
+ <simpara><literal><nullif expression> := NULLIF <left paren>
+ <value expression> <comma> <value expression>
+ <right paren></literal></simpara>
+
+ <simpara>Return NULL if two values are equal. If the result of the first
+ <literal><value expression></literal> is not equal to the result
+ of the second, then it is returned, otherwise NULL is returned. The type
+ of the return value is the type of the first <literal><value
+ expression></literal>.</simpara>
+
+ <programlisting>SELECT i, NULLIF(n, 'not defined') FROM t</programlisting>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>case expression</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">CASE</emphasis></simpara>
+
+ <simpara><emphasis>case specification</emphasis></simpara>
+
+ <simpara><literal><case specification> ::= <simple case> |
+ <searched case></literal></simpara>
+
+ <simpara><literal><simple case> ::= CASE <case operand>
+ <simple when clause>... [ <else clause> ]
+ END</literal></simpara>
+
+ <simpara><literal><searched case> ::= CASE <searched when
+ clause>... [ <else clause> ] END</literal></simpara>
+
+ <simpara><literal><simple when clause> ::= WHEN <when operand
+ list> THEN <result></literal></simpara>
+
+ <simpara><literal><searched when clause> ::= WHEN <search
+ condition> THEN <result></literal></simpara>
+
+ <simpara><literal><else clause> ::= ELSE
+ <result></literal></simpara>
+
+ <simpara><literal><case operand> ::= <row value predicand> |
+ <overlaps predicate part 1></literal></simpara>
+
+ <simpara><literal><when operand list> ::= <when operand> [ {
+ <comma> <when operand> }... ]</literal></simpara>
+
+ <simpara><literal><when operand> ::= <row value predicand> |
+ <comparison predicate part 2> | <between predicate part 2> |
+ <in predicate part 2> | <character like predicate part 2> |
+ <octet like predicate part 2> | <similar predicate part 2> |
+ <regex like predicate part 2> | <null predicate part 2> |
+ <quantified comparison predicate part 2> | <match predicate
+ part 2> | <overlaps predicate part 2> | <distinct predicate
+ part 2></literal></simpara>
+
+ <simpara><literal><result> ::= <result expression> |
+ NULL</literal></simpara>
+
+ <simpara><literal><result expression> ::= <value
+ expression></literal></simpara>
+
+ <simpara>Specify a conditional value. The result of a case expression is
+ always a value. All the values introduced with THEN must be of the same
+ type.</simpara>
+
+ <simpara>An (simple) example of the CASE statement is given below. It
+ returns 'Britain', 'Germany', or 'Other country' depending on the value
+ of dialcode'</simpara>
+
+ <programlisting>CASE dialcode WHEN 44 THEN 'Britain' WHEN 49 THEN 'Germany' ELSE 'Other country' END</programlisting>
+
+ <simpara>The case statement can be far more complex and involve several
+ conditions.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>CAST</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">CAST</emphasis></simpara>
+
+ <simpara><emphasis>cast specification</emphasis></simpara>
+
+ <simpara><literal><cast specification> ::= CAST <left paren>
+ <cast operand> AS <cast target> <right
+ paren></literal></simpara>
+
+ <simpara><literal><cast operand> ::= <value expression> |
+ <implicitly typed value specification></literal></simpara>
+
+ <simpara><literal><cast target> ::= <domain name> | <data
+ type></literal></simpara>
+
+ <simpara>Specify a data conversion. Data conversion takes place
+ automatically among variants of a general type. For example numeric
+ values are freely converted from one type to another in
+ expressions.</simpara>
+
+ <simpara>Explicit type conversion is necessary in two cases. One case is
+ to determine the type of a NULL value. The other case is to force
+ conversion for special purposes. Values of data types can be cast to a
+ character type. The exception is BINARY and OTHER types. The result of
+ the cast is the literal expression of the value. Conversely, a value of
+ a character type can be converted to another type if the character value
+ is a literal representation of the value in the target type. Special
+ conversions are possible between numeric and interval types, which are
+ described in the section covering interval types.</simpara>
+
+ <simpara>The examples below show examples of cast with their
+ result:</simpara>
+
+ <programlisting>CAST (NULL AS TIMESTAMP)
+CAST (' 199 ' AS INTEGER) = 199
+CAST ('tRue ' AS BOOLEAN) = TRUE
+CAST (INTERVAL '2' DAY AS INTEGER) = 2
+CAST ('1992-04-21' AS DATE) = DATE '1992-04-21'
+</programlisting>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>NEXT VALUE FOR</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">NEXT VALUE FOR</emphasis></simpara>
+
+ <simpara><emphasis>next value expression</emphasis></simpara>
+
+ <simpara><literal><next value expression> ::= NEXT VALUE FOR
+ <sequence generator name></literal></simpara>
+
+ <simpara>Return the next value of a sequence generator. This expression
+ can be used as a select list element in queries, or in assignments to
+ table columns in data change statements. If the expression is used more
+ than once in a single row that is being evaluated, the same value is
+ returned for each invocation. After evaluation of the particular row is
+ complete, the sequence generator will return a different value from the
+ old value. The new value is generated by the sequence generator by
+ adding the increment to the last value it generated. In the example
+ below:</simpara>
+
+ <programlisting>INSERT INTO MYTABLE(COL1, COL2) VALUES 2, NEXT VALUE FOR MYSEQUENCE
+</programlisting>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>value expression</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">value expression</emphasis></simpara>
+
+ <simpara><emphasis>value expression</emphasis></simpara>
+
+ <simpara><literal><value expression> ::= <numeric value
+ expression> | <string value expression> | <datetime value
+ expression> | <interval value expression> | <boolean value
+ expression> | <row value expression></literal></simpara>
+
+ <simpara>An expression that returns a value. The value can be a single
+ value, or a row consisting more than one value.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>numeric value expression</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">numeric value
+ expression</emphasis></simpara>
+
+ <simpara><emphasis>numeric value expression</emphasis></simpara>
+
+ <simpara><literal><numeric value expression> ::= <term> |
+ <numeric value expression> <plus sign> <term> |
+ <numeric value expression> <minus sign>
+ <term></literal></simpara>
+
+ <simpara><literal><term> ::= <factor> | <term>
+ <asterisk> <factor> | <term> <solidus>
+ <factor></literal></simpara>
+
+ <simpara><literal><factor> ::= [ <sign> ] <numeric
+ primary></literal></simpara>
+
+ <simpara><literal><numeric primary> ::= <value expression
+ primary> | <numeric value function></literal></simpara>
+
+ <simpara>Specify a numeric value. The BNF indicates that
+ <literal><asterisk></literal> and
+ <literal><solidus></literal> (the operators for multiplication and
+ division) have precedence over <literal><minus sign></literal> and
+ <literal><plus sign></literal>.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>numeric value function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">numeric value
+ function</emphasis></simpara>
+
+ <simpara><emphasis>numeric value function</emphasis></simpara>
+
+ <simpara><literal><numeric value function> ::= <position
+ expression> | <extract expression> | <length expression>
+ ...</literal></simpara>
+
+ <simpara>Specify a function yielding a value of type numeric. The
+ supported numeric value functions are listed and described in the <link
+ endterm="builtinfunctions-title"
+ xlink:href="#builtinfunctions-chapt"></link> chapter.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>string value expression</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">string value
+ expression</emphasis></simpara>
+
+ <simpara><emphasis>string value expression</emphasis></simpara>
+
+ <simpara><literal><string value expression> ::= <string
+ concatenation> | <string factor></literal></simpara>
+
+ <simpara><literal><string factor> ::= <value expression
+ primary> | <string value function></literal></simpara>
+
+ <simpara><literal><string concatenation> ::= <string value
+ expression> <concatenation operator> <string
+ factor></literal></simpara>
+
+ <simpara><literal><concatenation operator> ::=
+ ||</literal></simpara>
+
+ <simpara>Specify a character string value, a binary string value, or a
+ bit string value. The BNF indicates that a string value expression can
+ be formed by concatenation of two or more <literal><value expression
+ primary></literal>. The types of the <literal><value expression
+ primary></literal> elements must be compatible, that is, all must be
+ string, or binary or bit string values.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>character value function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">character value
+ function</emphasis></simpara>
+
+ <simpara><emphasis>string value function</emphasis></simpara>
+
+ <simpara><literal><string value function> ::=
+ ...</literal></simpara>
+
+ <simpara>Specify a function that returns a character string or binary
+ string. The supported character value functions are listed and described
+ in the <link endterm="builtinfunctions-title"
+ xlink:href="#builtinfunctions-chapt"></link> chapter.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>datetime value expression</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">datetime value
+ expression</emphasis></simpara>
+
+ <simpara><emphasis>datetime value expression</emphasis></simpara>
+
+ <simpara><literal><datetime value expression> ::= <datetime
+ term> | <interval value expression> <plus sign>
+ <datetime term> | <datetime value expression> <plus
+ sign> <interval term> | <datetime value expression>
+ <minus sign> <interval term></literal></simpara>
+
+ <simpara><literal><datetime term> ::= <datetime
+ factor></literal></simpara>
+
+ <simpara><literal><datetime factor> ::= <datetime primary> [
+ <time zone> ]</literal></simpara>
+
+ <simpara><literal><datetime primary> ::= <value expression
+ primary> | <datetime value function></literal></simpara>
+
+ <simpara><literal><time zone> ::= AT <time zone
+ specifier></literal></simpara>
+
+ <simpara><literal><time zone specifier> ::= LOCAL | TIME ZONE
+ <interval primary></literal></simpara>
+
+ <simpara>Specify a datetime value. Details are described in the <link
+ endterm="sqlgeneral-title" xlink:href="#sqlgeneral-chapt"></link>
+ chapter.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>datetime value function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">datetime value
+ function</emphasis></simpara>
+
+ <simpara><emphasis>datetime value function</emphasis></simpara>
+
+ <simpara><literal><datetime value function> ::=
+ ...</literal></simpara>
+
+ <simpara>Specify a function that returns a datetime value. The supported
+ datetime value functions are listed and described in the <link
+ endterm="builtinfunctions-title" xlink:arcrole=""
+ xlink:href="#builtinfunctions-chapt"></link> chapter.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>interval term</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">interval term</emphasis></simpara>
+
+ <simpara><emphasis>interval value expression</emphasis></simpara>
+
+ <simpara><literal><interval value expression> ::= <interval
+ term> | <interval value expression 1> <plus sign>
+ <interval term 1> | <interval value expression 1> <minus
+ sign> <interval term 1> | <left paren> <datetime value
+ expression> <minus sign> <datetime term> <right
+ paren> <interval qualifier></literal></simpara>
+
+ <simpara><literal><interval term> ::= <interval factor> |
+ <interval term 2> <asterisk> <factor> | <interval
+ term 2> <solidus> <factor> | <term>
+ <asterisk> <interval factor></literal></simpara>
+
+ <simpara><literal><interval factor> ::= [ <sign> ]
+ <interval primary></literal></simpara>
+
+ <simpara><literal><interval primary> ::= <value expression
+ primary> [ <interval qualifier> ] | <interval value
+ function></literal></simpara>
+
+ <simpara><literal><interval value expression 1> ::= <interval
+ value expression></literal></simpara>
+
+ <simpara><literal><interval term 1> ::= <interval
+ term></literal></simpara>
+
+ <simpara><literal><interval term 2> ::= <interval
+ term></literal></simpara>
+
+ <simpara>Specify an interval value. Details are described in the <link
+ endterm="sqlgeneral-title" xlink:href="#sqlgeneral-chapt"></link>
+ chapter.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>interval absolute value function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">interval absolute value
+ function</emphasis></simpara>
+
+ <simpara><emphasis>interval value function</emphasis></simpara>
+
+ <simpara><literal><interval value function> ::= <interval
+ absolute value function></literal></simpara>
+
+ <simpara><literal><interval absolute value function> ::= ABS
+ <left paren> <interval value expression> <right
+ paren></literal></simpara>
+
+ <simpara>Specify a function that returns the absolute value of an
+ interval. If the interval is negative, it is negated, otherwise the
+ original value is returned.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>boolean value expression</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">boolean value
+ expression</emphasis></simpara>
+
+ <simpara><emphasis>boolean value expression</emphasis></simpara>
+
+ <simpara><literal><boolean value expression> ::= <boolean
+ term> | <boolean value expression> OR <boolean
+ term></literal></simpara>
+
+ <simpara><literal><boolean term> ::= <boolean factor> |
+ <boolean term> AND <boolean factor></literal></simpara>
+
+ <simpara><literal><boolean factor> ::= [ NOT ] <boolean
+ test></literal></simpara>
+
+ <simpara><literal><boolean test> ::= <boolean primary> [ IS
+ [ NOT ] <truth value> ]</literal></simpara>
+
+ <simpara><literal><truth value> ::= TRUE | FALSE |
+ UNKNOWN</literal></simpara>
+
+ <simpara><literal><boolean primary> ::= <predicate> |
+ <boolean predicand></literal></simpara>
+
+ <simpara><literal><boolean predicand> ::= <parenthesized
+ boolean value expression> | <nonparenthesized value expression
+ primary></literal></simpara>
+
+ <simpara><literal><parenthesized boolean value expression> ::=
+ <left paren> <boolean value expression> <right
+ paren></literal></simpara>
+
+ <simpara>Specify a boolean value.</simpara>
+ </section>
+
+ <section>
+ <title>Predicates</title>
+
+ <simpara>Predicates are conditions with two sides and evaluate to a
+ boolean value. The left side of the predicate, the <literal><row
+ value predicand></literal>, is the common element of all predicates.
+ This element is a generalisation of both <literal><value
+ expression></literal>, which is a scalar, and of
+ <literal><explicit row value constructor></literal>, which is a
+ row. The two sides of a predicate can be split in CASE statements where
+ the <literal><row value predicand></literal> is part of multiple
+ predicates.</simpara>
+
+ <simpara>The number of fields in all <literal><row value
+ predicand></literal> used in predicates must be the same and the
+ types of the fields in the same position must be compatible for
+ comparison. If either of these conditions does not hold, an exception is
+ raised. The number of fields in a row is called the
+ <glossterm>degree</glossterm>.</simpara>
+
+ <simpara>In many types of predicates (but not all of them), if the
+ <literal><row value predicand></literal> evaluates to NULL, the
+ result of the predicate is UNKNOWN. If the <literal><row value
+ predicand></literal> has more than one element, and one or more of
+ the fields evaluate to NULL, the result depends on the particular
+ predicate.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>comparison predicate</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">comparison predicand</emphasis></simpara>
+
+ <simpara><emphasis>comparison predicate</emphasis></simpara>
+
+ <simpara><literal><comparison predicate> ::= <row value
+ predicand> <comp op> <row value
+ predicand></literal></simpara>
+
+ <simpara><literal><comp op> ::= <equals operator> | <not
+ equals operator> | <less than operator> | <greater than
+ operator> | <less than or equals operator> | <greater than
+ or equals operator></literal></simpara>
+
+ <simpara>Specify a comparison of two row values. If either
+ <literal><row value predicand></literal> evaluates to NULL, the
+ result of <literal><comparison predicate></literal> is UNKNOWN.
+ Otherwise, the result is TRUE, FALSE or UNKNOWN.</simpara>
+
+ <simpara>If the <glossterm>degree</glossterm> of <literal><row value
+ predicand></literal> is larger than one, comparison is performed
+ between each field and the corresponding field in the other
+ <literal><row value predicand></literal> from left to right, one
+ by one.</simpara>
+
+ <simpara>When comparing two elements, if either field is NULL then the
+ result is UNKNOWN.</simpara>
+
+ <simpara>For <literal><equals operator></literal>, if the result
+ of comparison is TRUE for all field, the result of the predicate is
+ TRUE. If the result of comparison is FALSE for one field, the result of
+ predicate is FALSE. Otherwise the result is UNKNOWN.</simpara>
+
+ <simpara>The <literal><not equals operator></literal> is
+ translated to <literal>NOT (<row value predicand> = <row value
+ predicand>)</literal>.</simpara>
+
+ <simpara>The <literal><less than or equals operator></literal> is
+ translated to <literal>(<row value predicand> = <row value
+ predicand>) OR (<row value predicand> < <row value
+ predicand>)</literal>. The <literal><greater than or equals
+ operator></literal> is translated similarly.</simpara>
+
+ <simpara>For the <literal><less than operator></literal> and
+ <literal><greater than operator></literal>, if two fields at a
+ given position are equal, then comparison continues to the next field.
+ Otherwise, the result of the last performed comparison is returned as
+ the result of the predicate. This means that if the first field is NULL,
+ the result is always UNKNOWN.</simpara>
+
+ <simpara>The logic that governs NULL values and UNKNOWN result is as
+ follows: Suppose the NULL values were substituted by arbitrary real
+ values. If substitution cannot change the result of the predicate, then
+ the result is TRUE or FALSE, based on the existing non-NULL values,
+ otherwise the result of the predicate is UNKNOWN.</simpara>
+
+ <simpara>The examples of comparison given below use literals, but the
+ literals actually represent the result of evaluation of some
+ expression.</simpara>
+
+ <programlisting>((1, 2, 3, 4) = (1, 2, 3, 4)) IS TRUE
+((1, 2, 3, 4) = (1, 2, 3, 5)) IS FALSE
+((1, 2, 3, 4) < (1, 2, 3, 4)) IS FALSE
+((1, 2, 3, 4) < (1, 2, 3, 5)) IS TRUE
+((NULL, 1, NULL) = (NULL, 1, NULL)) IS UNKNOWN
+((NULL, 1, NULL) = (NULL, 2, NULL)) IS FALSE
+((NULL, 1, NULL) <> (NULL, 2, NULL)) IS TRUE
+((NULL, 1, 2) <all operators> (NULL, 1, 2)) IS UNKNOWN
+((1, NULL, ...) < (1, 2, ...)) IS UNKNOWN
+((1, NULL, ...) < (2, NULL, ...)) IS TRUE
+((2, NULL, ...) < (1, NULL, ...)) IS FALSE
+</programlisting>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>BETWEEN predicate</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">BETWEEN</emphasis></simpara>
+
+ <simpara><emphasis>between predicate</emphasis></simpara>
+
+ <simpara><literal><between predicate> ::= <row value
+ predicand> <between predicate part 2></literal></simpara>
+
+ <simpara><literal><between predicate part 2> ::= [ NOT ] BETWEEN [
+ ASYMMETRIC | SYMMETRIC ] <row value predicand> AND <row value
+ predicand></literal></simpara>
+
+ <simpara>Specify a range comparison. The default is ASYMMETRIC. The
+ expression <literal>X BETWEEN Y AND Z</literal> is equivalent to
+ <literal>(X >= Y AND X <= Z)</literal>. Therefore if Y > Z, the
+ BETWEEN expression is never true. The expression <literal>X BETWEEN
+ SYMMETRIC Y AND Z</literal> is equivalent to <literal>(X >= Y AND X
+ <= Z) OR (X >= Z AND X <= Y)</literal>. The expression
+ <literal>Z NOT BETWEEN ...</literal> is equivalent to <literal>NOT (Z
+ BETWEEN ...)</literal>. If any of the three <literal><row value
+ predicand></literal> evaluates to NULL, the result is
+ UNKNOWN.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>IN predicate</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">IN</emphasis></simpara>
+
+ <simpara><emphasis>in predicate</emphasis></simpara>
+
+ <simpara><literal><in predicate> ::= <row value predicand> [
+ NOT ] IN <in predicate value></literal></simpara>
+
+ <simpara><literal><in predicate value> ::= <table subquery>
+ | <left paren> <in value list> <right paren>
+ </literal></simpara>
+
+ <simpara><literal>| <left paren> UNNEST <left paren>
+ <array value expression> <right paren> <right
+ paren></literal></simpara>
+
+ <simpara><literal><in value list> ::= <row value expression>
+ [ { <comma> <row value expression> }...
+ ]</literal></simpara>
+
+ <simpara>Specify a quantified comparison. The expression <literal>X NOT
+ IN Y is</literal> equivalent to <literal>NOT (X IN Y)</literal>. The
+ <literal>( <in value list> )</literal> is converted into a table
+ with one or more rows. The expression <literal>X IN Y</literal> is
+ equivalent to <literal>X = ANY Y</literal>, which is a
+ <literal><quantified comparison predicate></literal>.</simpara>
+
+ <simpara>If the <literal><table subquery></literal> returns no
+ rows, the result is FALSE. Otherwise the <literal><row value
+ predicand></literal> is compared one by one with each row of the
+ <literal><table subquery></literal>.</simpara>
+
+ <simpara>If the comparison is TRUE for at least one row, the result is
+ TRUE. If the comparison is FALSE for all rows, the result is FALSE.
+ Otherwise the result is UNKNOWN.</simpara>
+
+ <simpara>HyperSQL supports an extension to the SQL Standard to allow an
+ array to be used in the <in predicate value>. This is intended to
+ be used with prepared statements where a variable length array of values
+ can be used as the parameter value for each call. The example below
+ shows how this is used.</simpara>
+
+ <programlisting>SELECT * from customer where firstname in ( UNNEST(?) )
+</programlisting>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>LIKE predicate</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">LIKE</emphasis></simpara>
+
+ <simpara><emphasis>like predicate</emphasis></simpara>
+
+ <simpara><literal><like predicate> ::= <character like
+ predicate> | <octet like predicate></literal></simpara>
+
+ <simpara><literal><character like predicate> ::= <row value
+ predicand> [ NOT ] LIKE <character pattern> [ ESCAPE <escape
+ character> ]</literal></simpara>
+
+ <simpara><literal><character pattern> ::= <character value
+ expression></literal></simpara>
+
+ <simpara><literal><escape character> ::= <character value
+ expression></literal></simpara>
+
+ <simpara><literal><octet like predicate> ::= <row value
+ predicand> [ NOT ] LIKE <octet pattern> [ ESCAPE <escape
+ octet> ]</literal></simpara>
+
+ <simpara><literal><octet pattern> ::= <binary value
+ expression></literal></simpara>
+
+ <simpara><literal><escape octet> ::= <binary value
+ expression></literal></simpara>
+
+ <simpara>Specify a pattern-match comparison for character or binary
+ strings. The <literal><row value predicand></literal> is always a
+ <literal><string value expression></literal> of character or
+ binary type. The <literal><character pattern></literal> or
+ <literal><octet pattern></literal> is a <literal><string value
+ expression></literal> in which the underscore and percent characters
+ have special meanings. The underscore means match any one character,
+ while the percent means match a sequence of zero or more characters. The
+ <literal><escape character></literal> or <literal><escape
+ octet></literal> is also a <literal><string value
+ expression></literal> that evaluates to a string of exactly one
+ character length. If the underscore or the percent is required as normal
+ characters in the pattern, the specified <literal><escape
+ character></literal> or <literal><escape octet></literal> can
+ be used in the pattern before the underscore or the percent. The
+ <literal><row value predicand></literal> is compared with the
+ <literal><character pattern></literal> and the result of
+ comparison is returned. If any of the expressions in the predicate
+ evaluates to NULL, the result of the predicate is UNKNOWN. The
+ expression <literal>A NOT LIKE B</literal> is equivalent to <literal>NOT
+ (A LIKE B)</literal>. If the length of the escape is not 1 or it is used
+ in the pattern not immediately before an underscore or a percent
+ character, an exception is raised.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>IS NULL predicate</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">IS NULL</emphasis></simpara>
+
+ <simpara><emphasis>null predicate</emphasis></simpara>
+
+ <simpara><literal><null predicate> ::= <row value predicand>
+ IS [ NOT ] NULL</literal></simpara>
+
+ <simpara>Specify a test for a null value. The expression <literal>X IS
+ NOT NULL</literal> is NOT equivalent to <literal>NOT (X IS
+ NULL)</literal>if the degree of the <literal><row value
+ predicand></literal> is larger than 1. The rules are: If all fields
+ are null, <literal>X IS NULL</literal> is TRUE and <literal>X IS NOT
+ NULL</literal> is FALSE. If only some fields are null, both <literal>X
+ IS NULL</literal> and <literal>X IS NOT NULL</literal> are FALSE. If all
+ fields are not null, <literal>X IS NULL</literal> is FALSE and
+ <literal>X IS NOT NULL</literal> is TRUE.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>ALL and ANY predicates</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">ALL and ANY</emphasis></simpara>
+
+ <simpara><emphasis>quantified comparison predicate</emphasis></simpara>
+
+ <simpara><literal><quantified comparison predicate> ::= <row
+ value predicand> <comp op> <quantifier> <table
+ subquery></literal></simpara>
+
+ <simpara><literal><quantifier> ::= <all> |
+ <some></literal></simpara>
+
+ <simpara><literal><all> ::= ALL</literal></simpara>
+
+ <simpara><literal><some> ::= SOME | ANY</literal></simpara>
+
+ <simpara>Specify a quantified comparison. For a quantified comparison,
+ the <literal><row value predicand></literal> is compared one by
+ one with each row of the <literal><table sub
+ query></literal>.</simpara>
+
+ <simpara>If the <literal><table subquery></literal> returns no
+ rows, then if <literal>ALL</literal> is specified the result is TRUE,
+ but if <literal>SOME</literal> or <literal>ANY</literal> is specified
+ the result is FALSE.</simpara>
+
+ <simpara>If <literal>ALL</literal> is specified, if the comparison is
+ TRUE for all rows, the result of the predicate is TRUE. If the
+ comparison is FALSE for at least one row, the result is FALSE. Otherwise
+ the result is UNKNOWN.</simpara>
+
+ <simpara>If <literal>SOME</literal> or <literal>ANY</literal> is
+ specified, if the comparison is TRUE for at least one row, the result is
+ TRUE. If the comparison is FALSE for all rows, the result is FALSE.
+ Otherwise the result is UNKNOWN. Note that the IN predicate is
+ equivalent to the SOME or ANY predicate using the <literal><equals
+ operator></literal>.</simpara>
+
+ <simpara>In the examples below, the date of an invoice is compared to
+ holidays in a given year. In the first example the invoice date must
+ equal one of the holidays, in the second example it must be later than
+ all holidays (later than the last holiday), in the third example it must
+ be on or after some holiday (on or after the first holiday), and in the
+ fourth example, it must be before all holidays (before the first
+ holiday).</simpara>
+
+ <programlisting>invoice_date = SOME (SELECT holiday_date FROM holidays)
+invoice_date > ALL (SELECT holiday_date FROM holidays)
+invoice_date >= ANY (SELECT holiday_date FROM holidays)
+invoice_date < ALL (SELECT holiday_date FROM holidays)
+</programlisting>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>EXISTS predicate</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">EXISTS</emphasis></simpara>
+
+ <simpara><emphasis>exists predicate</emphasis></simpara>
+
+ <simpara><literal><exists predicate> ::= EXISTS <table
+ subquery></literal></simpara>
+
+ <simpara>Specify a test for a non-empty set. If the evaluation of
+ <literal><table subquery></literal> results in one or more rows,
+ then the expression is TRUE, otherwise FALSE.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>UNIQUE predicate</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">UNIQUE</emphasis></simpara>
+
+ <simpara><emphasis>unique predicate</emphasis></simpara>
+
+ <simpara><literal><unique predicate> ::= UNIQUE <table
+ subquery></literal></simpara>
+
+ <simpara>Specify a test for the absence of duplicate rows. The result of
+ the test is either TRUE or FALSE (never UNKNOWN). The rows of the
+ <literal><table subquery></literal> that contain one or more NULL
+ values are not considered for this test. If the rest of the rows are
+ distinct from each other, the result of the test is TRUE, otherwise it
+ is FALSE. The distinctness of rows X and Y is tested with the predicate
+ <literal>X IS DISTINCT FROM Y</literal>.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>MATCH predicate</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">MATCH</emphasis></simpara>
+
+ <simpara><emphasis>match predicate</emphasis></simpara>
+
+ <simpara><literal><match predicate> ::= <row value
+ predicand> MATCH [ UNIQUE ] [ SIMPLE | PARTIAL | FULL ] <table
+ subquery></literal></simpara>
+
+ <simpara>Specify a test for matching rows. The default is MATCH SIMPLE
+ without UNIQUE. The result of the test is either TRUE or FALSE (never
+ UNKNOWN).</simpara>
+
+ <simpara>The interpretation of NULL values is different from other
+ predicates and quite counter-intuitive. If the <literal><row value
+ predicand></literal> is NULL, or all of its fields are NULL, the
+ result is TRUE.</simpara>
+
+ <simpara>Otherwise, the <literal><row value predicand></literal>
+ is compared with each row of the <literal><table
+ subquery></literal>.</simpara>
+
+ <simpara>If SIMPLE is specified, if some field of <literal><row value
+ predicate></literal> is NULL, the result is TRUE. Otherwise if
+ <literal><row value predicate> </literal>is equal to one or more
+ rows of <literal><table subquery></literal> the result is TRUE if
+ UNIQUE is not specified, or if UNIQUE is specified and only one row
+ matches. Otherwise the result is FALSE.</simpara>
+
+ <simpara>If PARTIAL is specified, if the non-null values
+ <literal><row value predicate> </literal>are equal to those in one
+ or more rows of <literal><table subquery></literal> the result is
+ TRUE if UNIQUE is not specified, or if UNIQUE is specified and only one
+ row matches. Otherwise the result is FALSE.</simpara>
+
+ <simpara>If FULL is specified, if some field of <literal><row value
+ predicate></literal> is NULL, the result is FALSE. Otherwise if
+ <literal><row value predicate></literal> is equal to one or more
+ rows of <literal><table subquery></literal> the result is TRUE if
+ UNIQUE is not specified, or if UNIQUE is specified and only one row
+ matches.</simpara>
+
+ <simpara>Note that MATCH can also used be used in FOREIGN KEY constraint
+ definitions. The exact meaning is described in the <link
+ endterm="databaseobjects-title"
+ xlink:href="#databaseobjects-chapt"></link> chapter.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>OVERLAPS predicate</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">OVERLAPS</emphasis></simpara>
+
+ <simpara><emphasis>overlaps predicate</emphasis></simpara>
+
+ <simpara><literal><overlaps predicate> ::= <row value
+ predicand> OVERLAPS <row value predicand></literal></simpara>
+
+ <simpara>Specify a test for an overlap between two datetime periods.
+ Each <literal><row value predicand></literal> must have two fields
+ and the fields together represent a datetime period. So the predicates
+ is always in the form <literal>(X1, X2) OVERLAPS (Y1, Y2)</literal>. The
+ first field is always a datetime value, while the second field is either
+ a datetime value or an interval value.</simpara>
+
+ <simpara>If the second value is an interval value, it is replaced with
+ the sum of the datetime value and itself, for example <literal>(X1, X1 +
+ X2) OVERLAPS (Y1, Y1 + Y 2)</literal>.</simpara>
+
+ <simpara>If any of the values is NULL, the result is UNKNOWN.</simpara>
+
+ <simpara>The expression is true if there is there is any overlap between
+ the two datetime periods. In the example below, the period is compared
+ with a week long period ending yesterday.</simpara>
+
+ <programlisting>(startdate, enddate) OVERLAPS (CURRENT_DATE - 7 DAY, CURRENT_DATE - 1 DAY)</programlisting>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>IS DISTINCT predicate</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">IS DISTINCT</emphasis></simpara>
+
+ <simpara><emphasis>is distinct predicate</emphasis></simpara>
+
+ <simpara><literal><distinct predicate> ::= <row value
+ predicand> IS [ NOT ] DISTINCT FROM <row value
+ predicand></literal></simpara>
+
+ <simpara>Specify a test of whether two row values are distinct. The
+ result of the test is either TRUE or FALSE (never UNKNOWN). The
+ <glossterm>degree</glossterm> the two <literal><row value
+ predicand></literal> must be the same. Each field of the first
+ <literal><row value predicand></literal> is compared to the field
+ of the second <literal><row value predicand></literal> at the same
+ position. If one field is NULL and the other is not NULL, or if the
+ elements are NOT equal, then the result of the expression is TRUE. If no
+ comparison result is TRUE, then the result of the predicate is FALSE.
+ The expression <literal>X IS NOT DISTINCT FROM Y</literal> is equivalent
+ to <literal>NOT (X IS DISTINCT FORM Y)</literal>. The following check
+ returns true if startdate is not equal to enddate. It also returns true
+ if either startdate or enddate is NULL. It returns false in other
+ cases.</simpara>
+
+ <programlisting>startdate IS DISTINCT FROM enddate</programlisting>
+ </section>
+
+ <section>
+ <title>Other Syntax Elements</title>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>search condition</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">search condition</emphasis></simpara>
+
+ <simpara><emphasis>search condition</emphasis></simpara>
+
+ <simpara><literal><search condition> ::= <boolean value
+ expression></literal></simpara>
+
+ <simpara>Specify a condition that is TRUE, FALSE, or UNKNOWN. A search
+ condition is often a predicate.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>PATH</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">PATH</emphasis></simpara>
+
+ <simpara><emphasis>path specification</emphasis></simpara>
+
+ <simpara><literal><path specification> ::= PATH <schema name
+ list></literal></simpara>
+
+ <simpara><literal><schema name list> ::= <schema name> [ {
+ <comma> <schema name> }... ]</literal></simpara>
+
+ <simpara>Specify an order for searching for a user-defined SQL-invoked
+ routine. This is not currently supported by HyperSQL.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>routine invocation</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">routine invocation</emphasis></simpara>
+
+ <simpara><emphasis>routine invocation</emphasis></simpara>
+
+ <simpara><literal><routine invocation> ::= <routine name>
+ <SQL argument list></literal></simpara>
+
+ <simpara><literal><routine name> ::= [ <schema name>
+ <period> ] <qualified identifier></literal></simpara>
+
+ <simpara><literal><SQL argument list> ::= <left paren> [
+ <SQL argument> [ { <comma> <SQL argument> }... ] ]
+ <right paren></literal></simpara>
+
+ <simpara><literal><SQL argument> ::= <value expression> |
+ <target specification></literal></simpara>
+
+ <simpara>Invoke an SQL-invoked routine. Examples are given in the <link
+ endterm="sqlroutines-title" xlink:href="#sqlroutines-chapt"></link>
+ chapter.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>COLLATE</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">COLLATE</emphasis></simpara>
+
+ <simpara><emphasis>collate clause</emphasis></simpara>
+
+ <simpara><literal><collate clause> ::= COLLATE <collation
+ name></literal></simpara>
+
+ <simpara>Specify a default collation. This is not currently supported by
+ HyperSQL</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>CONSTRAINT</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">CONSTRAINT</emphasis></simpara>
+
+ <simpara><emphasis>constraint name definition</emphasis></simpara>
+
+ <simpara><literal><constraint name definition> ::= CONSTRAINT
+ <constraint name></literal></simpara>
+
+ <simpara><literal><constraint characteristics> ::= <constraint
+ check time> [ [ NOT ] DEFERRABLE ] | [ NOT ] DEFERRABLE [
+ <constraint check time> ]</literal></simpara>
+
+ <simpara><literal><constraint check time> ::= INITIALLY DEFERRED |
+ INITIALLY IMMEDIATE</literal></simpara>
+
+ <simpara>Specify the name of a constraint and its characteristics. This
+ is an optional element of CONSTRAINT definition, not yet supported by
+ HyperSQL.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>aggregate function</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">aggregate function</emphasis></simpara>
+
+ <simpara><emphasis>aggregate function</emphasis></simpara>
+
+ <simpara><literal><aggregate function> ::= COUNT <left
+ paren> <asterisk> <right paren> [ <filter clause> ]
+ | <general set function> [ <filter clause> ]
+ </literal></simpara>
+
+ <simpara><literal><general set function> ::= <set function
+ type> <left paren> [ <set quantifier> ] <value
+ expression> <right paren></literal></simpara>
+
+ <simpara><literal><set function type> ::= <computational
+ operation></literal></simpara>
+
+ <simpara><literal><computational operation> ::= AVG | MAX | MIN |
+ SUM | EVERY | ANY | SOME | COUNT | STDDEV_POP | STDDEV_SAMP | VAR_SAMP |
+ VAR_POP</literal></simpara>
+
+ <simpara><literal><set quantifier> ::= DISTINCT |
+ ALL</literal></simpara>
+
+ <simpara><literal><filter clause> ::= FILTER <left paren>
+ WHERE <search condition> <right paren></literal></simpara>
+
+ <simpara>Specify a value computed from a collection of rows. An
+ aggregate function is used exclusively in a <literal><query
+ specification></literal> and its use transforms a normal query into
+ an aggregate query returning a single row instead of the group of
+ multiple rows that the original query returns. For example,
+ <literal>SELECT acolumn <table expression></literal> is a query
+ that returns the value of acolumn for all the rows the satisfy the given
+ condition. But <literal>SELECT MAX(acolumn) <table
+ expression></literal> returns only one row, containing the largest
+ value in that column. The query <literal>SELECT COUNT(*) <table
+ expression></literal> returns the count of rows, while
+ <literal>SELECT COUNT(acolumn) <table expression></literal>
+ returns the count of rows where <literal>acolumn IS NOT
+ NULL</literal>.</simpara>
+
+ <simpara>If the <literal><table expression></literal> is a grouped
+ table, the aggregate function returns the result of the
+ <literal>COUNT</literal> or <literal><computational
+ operation></literal> for each group. In this case the result has the
+ same number of rows as the original query. For example <literal>SELECT
+ SUM(acolumn) <table expression></literal> when <literal><table
+ expression></literal> has a <literal>GROUP BY</literal> clause,
+ returns the sum of values for <literal>acolumn</literal> in each
+ group.</simpara>
+
+ <simpara>The AVG and SUM operations can be performed on numeric
+ expressions only. AVG returns the average value, while SUM returns the
+ sum of all non-null values. MAX and MIN return the minimum or the
+ maximum value. If all values are NULL, the operations return NULL. The
+ <literal>COUNT(*)</literal> operation returns the count of all values,
+ while <literal>COUNT(<value expression>)</literal> returns the
+ count of non-NULL values.</simpara>
+
+ <simpara>The EVERY, ANY and SOME operations can be performed on boolean
+ expressions only. EVERY returns TRUE if all the values are TRUE,
+ otherwise FALSE. ANY and SOME are the same operation and return TRUE if
+ one of the values is TRUE, otherwise it returns FALSE.</simpara>
+
+ <simpara>The other operations perform the statistical functions
+ STDDEV_POP, STDDEV_SAMP, VAR_SAMP, VAR_POP on numeric values. NULL
+ values are ignored in calculations.</simpara>
+
+ <simpara>User defined aggregate functions can be defined and used
+ instead of the built-in aggregate functions. Syntax and examples are
+ given in the <link endterm="sqlroutines-title"
+ xlink:href="#sqlroutines-chapt"></link> chapter.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>sort specification list</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">sort specification
+ list</emphasis></simpara>
+
+ <simpara><emphasis>sort specification list</emphasis></simpara>
+
+ <simpara><literal><sort specification list> ::= <value
+ expression> [ASC | DESC] [NULLS FIRST | NULLS
+ LAST]</literal></simpara>
+
+ <simpara>Specify a sort order. A sort operation is performed on the
+ result of a <literal><query expression></literal> or
+ <literal><query specification></literal> and sorts the result
+ according to one or more <literal><value expression></literal>.
+ The <literal><value expression></literal> is usually a single
+ column of the result, but in some cases it can be a column of the
+ <literal><table expression></literal> that is not used in the
+ select list.</simpara>
+ </section>
+ </section>
+
+ <section>
+ <title>Data Access Statements</title>
+
+ <para>HyperSQL fully supports all of SQL-92 data access statements, plus
+ some additions from SQL:2008. Due to time constraints, the current version
+ of this Guide does not cover the subject fully. You are advised to consult
+ an SQL book such as the recent O'Reilly title "SQL and Relational Theory"
+ by C. J. Date.</para>
+
+ <para>Database queries are data access statements. The most commonly used
+ data access statement is the SELECT statement, but there are other
+ statements that perform a similar role. Data access statements access
+ tables and return result tables. The returned result tables are falsely
+ called result sets, as they are not necessarily sets of rows, but
+ multisets of rows.</para>
+
+ <para>Result tables are formed by performing the following operations on
+ base tables and views. These operations are loosely based on Relational
+ Algebra.</para>
+
+ <para><glossterm>JOIN</glossterm> operations</para>
+
+ <para><glossterm>SET</glossterm> and <glossterm>MULTISET</glossterm>
+ operations</para>
+
+ <para><glossterm>SELECTION</glossterm></para>
+
+ <para><glossterm>PROJECTION</glossterm></para>
+
+ <para><glossterm>COMPUTING</glossterm></para>
+
+ <para><glossterm>COLUMN NAMING</glossterm></para>
+
+ <para><glossterm>GROUPING</glossterm> and
+ <glossterm>AGGREGATION</glossterm></para>
+
+ <para><glossterm>SELECTION AFTER GROUPING OR
+ AGGREGATION</glossterm></para>
+
+ <para><glossterm>SET and MULTISET (COLLECTION)
+ OPERATIONS</glossterm></para>
+
+ <para><glossterm>ORDERING</glossterm></para>
+
+ <para><glossterm>SLICING</glossterm></para>
+
+ <para>Conceptually, the operations are performed one by one in the above
+ order if they apply to the given data access statement. In the example
+ below a simple select statement is made more complex by adding various
+ operations.</para>
+
+ <para><programlisting>CREATE TABLE atable (a INT, b INT, c INT, d INT, e INT, f INT);
+/* in the next SELECT, no join is performed and no further operation takes place */
+SELECT * FROM atable
+/* in the next SELECT, selection is performed by the WHERE clause, with no further action */
+SELECT * FROM atable WHERE a + b = c
+/* in the next SELECT, projection is performed after the other operations */
+SELECT d, e, f FROM atable WHERE a + b = c
+/* in the next SELECT, computation is performed after projection */
+SELECT (d + e) / f FROM atable WHERE a + b = c
+/* in the next two SELECT statements, column naming is performed in different ways*/
+SELECT (a + e) / f AS calc, f AS div FROM atable WHERE a + b = c
+SELECT dcol, ecol, fcol FROM atable(acol, bcol, ccol, dcol, ecol, fcol) WHERE acol + bcol = ccol
+/* in the next SELECT, both grouping and aggregation is performed */
+SELECT d, e, SUM(f) FROM atable GROUP BY d, e
+/* in the next SELECT, selection is performed after grouping and aggregation is performed */
+SELECT d, e, SUM(f) FROM atable GROUP BY d, e HAVING SUM(f) > 10
+/* in the next SELECT, a UNION is performed on two selects from the same table */
+SELECT d, e, f FROM atable WHERE d = 3 UNION SELECT a, b, c FROM atable WHERE a = 30
+/* in the next SELECT, ordering is performed */
+SELECT (a + e) / f AS calc, f AS div FROM atable WHERE a + b = c ORDER BY calc DESC, div NULLS LAST
+/* in the next SELECT, slicing is performed after ordering */
+SELECT * FROM atable WHERE a + b = c ORDER BY a FETCH 5 ROWS ONLY
+
+</programlisting>The next sections discuss various types of tables and
+ operations involved in data access statements.</para>
+
+ <section>
+ <title>Table</title>
+
+ <para>In data access statements, a table can be a database table (or
+ view) or an ephemeral table formed for the duration of the query. Some
+ types of table are <table primary> and can participate in joins
+ without the use of extra parentheses. The BNF in the Table Primary
+ section below lists different types of <table primary>:</para>
+
+ <para>Tables can also be formed by specifying the values that are
+ contained in them:</para>
+
+ <simpara><literal><table value constructor> ::= VALUES <row
+ value expression list></literal></simpara>
+
+ <simpara><literal><row value expression list> ::= <table row
+ value expression> [ { <comma> <table row value
+ expression> }... ]</literal></simpara>
+
+ <simpara>In the example below a table with two rows and 3 columns is
+ constructed out of some values:</simpara>
+
+ <programlisting>VALUES (12, 14, null), (10, 11, CURRENT_DATE)</programlisting>
+
+ <simpara>When a table is used directly in a UNION or similar operation,
+ the keyword TABLE is used with the name:</simpara>
+
+ <simpara><literal><explicit table> ::= TABLE <table or query
+ name></literal></simpara>
+
+ <simpara>In the examples below, all rows of the two tables are included
+ in the union. The keyword TABLE is used in the first example. The two
+ examples below are equivalent.</simpara>
+
+ <programlisting>TABLE atable UNION TABLE anothertable
+SELECT * FROM atable UNION SELECT * FROM anothertable
+</programlisting>
+ </section>
+
+ <section>
+ <title>Query Specification</title>
+
+ <para>A query specification is a SELECT statement. It is the most common
+ form of <literal><derived table></literal> . A <literal><table
+ expression></literal> is a base table, a view or any form of allowed
+ derived table. The SELECT statement performs projection, naming,
+ computing or aggregation on the rows of the <literal><table
+ expression></literal> .</para>
+
+ <simpara><literal><query specification> ::= SELECT [ DISTINCT |
+ ALL ] <select list> <table expression></literal></simpara>
+
+ <simpara><literal><select list> ::= <asterisk> | <select
+ sublist> [ { <comma> <select sublist> }... ]
+ </literal></simpara>
+
+ <simpara><literal><select sublist> ::= <derived column> |
+ <qualified asterisk> </literal></simpara>
+
+ <simpara><literal><qualified asterisk> ::= <asterisked
+ identifier chain> <period> <asterisk></literal></simpara>
+
+ <simpara><literal><asterisked identifier chain> ::= <asterisked
+ identifier> [ { <period> <asterisked identifier> }... ]
+ </literal></simpara>
+
+ <simpara><literal><asterisked identifier> ::=
+ <identifier></literal></simpara>
+
+ <simpara><literal><derived column> ::= <value expression> [
+ <as clause> ] </literal></simpara>
+
+ <simpara><literal><as clause> ::= [ AS ] <column name>
+ </literal></simpara>
+
+ <para>The qualifier DISTINCT or ALL apply to the results of the SELECT
+ statement after all other operations have been performed. ALL simply
+ returns the rows, while DISTINCT compares the rows and removes the
+ duplicate ones.</para>
+
+ <para>Projection is performed by the <literal><select
+ list></literal>.</para>
+
+ <para>A single <literal><asterisk></literal> means all columns of
+ the <literal><table expression></literal> are included, in the
+ same order as they appear in the <literal><table
+ expression></literal>. An asterisk qualified by a table name means
+ all the columns of the qualifier table name are included.</para>
+
+ <para>A derived column is a <literal><value expression></literal>,
+ optionally named with the <literal><as clause></literal>. A
+ <literal><value expression></literal> can be many things. Common
+ types include: the name of a column in the <literal><table
+ expression></literal>; an expression based on different columns or
+ constant values; a function call; an aggregate function; a CASE WHEN
+ expression.</para>
+ </section>
+
+ <section>
+ <title>Table Expression</title>
+
+ <para>A table expression is part of the SELECT statement and consists of
+ the FROM clause with optional other clauses that performs selection (of
+ rows) and grouping from the table(s) in the FROM clause.</para>
+
+ <simpara><literal><table expression> ::= <from clause> [
+ <where clause> ] [ <group by clause> ] [ <having
+ clause> ]</literal></simpara>
+
+ <para><literal><from clause> ::= FROM <table reference> [ {
+ <comma> <table reference> }... ]</literal></para>
+
+ <simpara><literal><table reference> ::= <table primary> |
+ <joined table> </literal></simpara>
+
+ <simpara><literal><table primary> ::= <table or query name>
+ [ [ AS ] <correlation name> [ <left paren> <derived
+ column list> <right paren> ] ] </literal></simpara>
+
+ <simpara><literal>| <derived table> [ AS ] <correlation
+ name> [ <left paren> <derived column list> <right
+ paren> ] </literal></simpara>
+
+ <simpara><literal>| <lateral derived table> [ AS ] <correlation
+ name> [ <left paren> <derived column list> <right
+ paren> ] </literal></simpara>
+
+ <simpara><literal>| <collection derived table> [ AS ]
+ <correlation name> [ <left paren> <derived column
+ list> <right paren> ] </literal></simpara>
+
+ <simpara><literal>| <table function derived table> [ AS ]
+ <correlation name> [ <left paren> <derived column
+ list> <right paren> ] </literal></simpara>
+
+ <simpara><literal>| <parenthesized joined
+ table></literal></simpara>
+
+ <simpara><literal><where clause> ::= WHERE <boolean value
+ expression></literal></simpara>
+
+ <simpara><literal><group by clause> ::= GROUP BY [ <set
+ quantifier> ] <grouping element> [ { <comma> <grouping
+ element> }... ]</literal></simpara>
+
+ <simpara><literal><having clause> ::= HAVING <boolean value
+ expression></literal></simpara>
+
+ <para>The <literal><from clause></literal> contains one or more
+ <literal><table reference></literal> separated by commas. A table
+ reference is often a table or view name or a joined table.</para>
+
+ <para>The <literal><where clause></literal> filters the rows of
+ the table in the <from clause> and removes the rows for which the
+ search condition is not TRUE.</para>
+
+ <para>The <literal><group by clause></literal> is a comma
+ separated list of columns of the table in the <literal><from
+ clause></literal> or expressions based on the columns.</para>
+
+ <para>When a <literal><group by clause></literal> is used, only
+ the columns used in the <literal><group by clause></literal> or
+ expressions used there, can be used in the <literal><select
+ list></literal>, together with any <literal><aggregate
+ function></literal> on other columns. A <literal><group by
+ clause></literal> compares the rows and groups together the rows that
+ have the same values in the columns of the <literal><group by
+ clause></literal>. Then any <literal><aggregate
+ function></literal> in the <literal><select list></literal> is
+ performed on each group, and for each group, a row is formed that
+ contains the values of the columns of the <literal><group by
+ clause></literal> and the values returned from each
+ <literal><aggregate function>. In the first example below, a
+ simple column reference is used in GROUP BY, while in the second
+ example, an expression is used.</literal><programlisting>CREATE TABLE atable (a INT, b INT, c INT, d INT, e INT, f INT);
+SELECT d, e, f FROM atable WHERE a + b = c GROUP BY d, e, f
+SELECT d + e, SUM(f) FROM atable WHERE a + b = c GROUP BY d + e HAVING SUM(f) > 2 AND d + e > 4
+</programlisting></para>
+
+ <para>A <literal><having clause></literal> filters the rows of the
+ table that is formed after applying the <literal><group by
+ clause></literal> using its search condition. The search condition
+ must be an expression based on the expressions in the GROUP BY list or
+ the aggregate functions used.</para>
+ </section>
+
+ <section>
+ <title>Table Primary</title>
+
+ <para>Table primary refers to different forms of table reference in the
+ FROM clause.</para>
+
+ <para>The simplest form of reference is simply a name. This is the name
+ of a table, a view, a transition table in a trigger definition, or a
+ query name specified in the WITH clause of a query expression.</para>
+
+ <para><literal><table or query name> ::= <table name> |
+ <transition table name> | <query name></literal></para>
+
+ <para>A query expression that is enclosed in parentheses and returns
+ from zero to many rows is a <literal><table subquery></literal>.
+ In a <literal><derived table></literal> the query expression is
+ self contained and cannot reference the columns of other table
+ references.</para>
+
+ <para><literal><derived table> ::= <table
+ subquery></literal></para>
+
+ <para><literal>When the word LITERAL is used before a <table
+ subquery>, it means the query expression can reference the columns of
+ other table references that precede it. </literal></para>
+
+ <para><literal><lateral derived table> ::= LATERAL <table
+ subquery></literal></para>
+
+ <para>UNNEST is similar to LATERAL, but instead of a query expression,
+ and expression that returns an array is used. This expression is
+ converted into a table which has one column that contains the elements
+ of the array, and, if WITH ORDINALITY is used, a second column that
+ contains the index of each element. The array expression usually
+ contains a reference to a column of the table reference preceding the
+ current table reference.</para>
+
+ <para><literal><collection derived table> ::= UNNEST <left
+ paren> <array value expression> <right paren> [ WITH
+ ORDINALITY ]</literal></para>
+
+ <para>When TABLE is used in this context, it also converts an array
+ value expression to a table, but this array must be the result of a
+ function call. A function that returns a MULTISET can also be used in
+ this context and each row of the multiset is expanded into a row of the
+ table.</para>
+
+ <para><literal><table function derived table> ::= TABLE <left
+ paren> <collection value expression> <right
+ paren></literal></para>
+
+ <para>The column list that is specified for the table reference must
+ contain names that are unique within the list</para>
+
+ <para><literal><derived column list> ::= <column name
+ list></literal></para>
+
+ <para><literal><column name list> ::= <column name> [ {
+ <comma> <column name> }... ] </literal></para>
+
+ <para>A parenthesized joined table is simply a joined table contained in
+ parentheses. Joined tables are discussed below.</para>
+
+ <para><literal><parenthesized joined table> ::= <left paren>
+ <parenthesized joined table> <right paren> | <left
+ paren> <joined table> <right paren></literal></para>
+ </section>
+
+ <section>
+ <title>Joined Table</title>
+
+ <para>Joins are operators with two table as the operands, resulting in a
+ third table, called joined table. All join operators are evaluated left
+ to right, therefore, with multiple joins, the table resulting from the
+ first join operator becomes an operand of the next join operator.
+ Parentheses can be used to group sequences of joined tables and change
+ the evaluation order. So if more than two tables are joined together
+ with join operators, the end result is also a joined table. There are
+ different types of join, each producing the result table in a different
+ way.</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>CROSS JOIN</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">CROSS JOIN</emphasis></simpara>
+
+ <para>The simplest form of join is CROSS JOIN. The CROSS JOIN of two
+ tables is a table that has all the columns of the first table, followed
+ by all the columns of the second table, in the original order. Each row
+ of the first table is combined with each row of the second table to fill
+ the rows of the new table. If the rows of each table form a set, then
+ the rows of the CROSS JOIN table form the Cartesian product of the rows
+ of the two table operands.</para>
+
+ <para>The CROSS JOIN can be expressed in two forms. The first form is
+ <literal>A CROSS JOIN B</literal>. The second form is <literal>A,
+ B</literal>. This type of join is not generally very useful, as it
+ returns large result tables.</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>UNION JOIN</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">UNION JOIN</emphasis></simpara>
+
+ <para>The UNION JOIN has limited use in queries. The result table has
+ the same columns as that of CROSS JOIN. Each row of the first table is
+ extended to the right with nulls and added to the new table. Each row of
+ the second table is extended to the left with nulls and added to the new
+ table. The UNION JOIN is expressed as <literal>A UNION JOIN B</literal>.
+ This should not be confused with <literal>A UNION B</literal>, which is
+ a set operation. Union join is for special applications and is not
+ commonly used.</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>JOIN with condition</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">JOIN ... ON</emphasis></simpara>
+
+ <para>The condition join is similar to CROSS JOIN, but a condition is
+ tested for each row of the new table and the row is created only if the
+ condition is true. This form of join is expressed as <literal>A JOIN B
+ ON (<search condition>)</literal>.</para>
+
+ <para>Equijoin is a condition join in which the search condition is an
+ equality condition between on or more pairs of columns from the two
+ table. Equijoin is the most commonly used type of join.</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>JOIN USING</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">JOIN ... USING</emphasis></simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>NATURAL JOIN</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">NATURAL JOIN</emphasis></simpara>
+
+ <para>Joins with USING or NATURAL keywords joins are similar to an
+ equijoin but they cannot be replaced simply with an equijoin. The new
+ table is formed with the specified or implied shared columns of the two
+ tables, followed by the rest of the columns from each table. In NATURAL
+ JOIN, the shared columns are all the column pairs that have the same
+ name in the first and second table. In JOIN USING, only columns names
+ that are specified by the USING clause are shared. The joins are
+ expressed as <literal>A NATURAL JOIN B</literal>, and <literal>A JOIN B
+ USING (<comma separated column name list>)</literal>.</para>
+
+ <para>The columns of the joined table are formed by the following
+ procedures: In JOIN ... USING the shared columns are added to the joined
+ table in the same order as they appear in the column name list. In
+ NATURAL JOIN the shared columns are added to the joined table in the
+ same order as they appear in the first table. In bother forms of join,
+ the non-shared columns of the first table are added in the order they
+ appear in the first table, finally the non-shared columns of the second
+ table are added in the order they appear in the second table.</para>
+
+ <para>The type of each shared column of the joined table is based on the
+ type of the columns in the original tables. If the original types are
+ not exactly the same, the type of the shared column is formed by type
+ aggregation. Type aggregations selects a type that can represent values
+ of both aggregated types. Simple type aggregation picks one of the
+ types. For example SMALLINT and INTEGER, results in INTEGER, or
+ VARCHAR(10) and VARCHAR(20) results in VARCHAR(20). More complex type
+ aggregation inherits properties from both types. For example DECIMAL(8)
+ and DECIMAL (6,2) results in DECIMAL (8,2).</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>OUTER JOIN</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">OUTER JOIN</emphasis></simpara>
+
+ <para>LEFT, RIGHT and FULL OUTER JOIN</para>
+
+ <para>The three qualifiers can be added to all types of JOIN apart from
+ CROSS JOIN and UNION JOIN. First the new table is populated with the
+ rows from the original join. If LEFT is specified, all the rows from the
+ first table that did not make it into the new table are extended to the
+ right with nulls and added to the table. If RIGHT is specified, all the
+ rows from the second table that did not make it into the new table are
+ extended to the left with nulls and added to the table. If FULL is
+ specified, the addition of leftover rows is performed from both the
+ first and the second table. These forms are expressed by prefixing the
+ join specification with the given keyword. For example <literal>A LEFT
+ OUTER JOIN B ON (<search condition>)</literal> or <literal>A
+ NATURAL FULL OUTER JOIN B</literal> or <literal>A FULL OUTER JOIN B
+ USING (<comma separated column name list>)</literal>.</para>
+ </section>
+
+ <section>
+ <title>Selection</title>
+
+ <para>Despite the name, selection has nothing to do with the list of
+ columns in a SELECT statement. In fact, it refers to the search
+ condition used to limit the rows that from a result table (selection of
+ rows, not columns). In SQL, simple selection is expressed with a WHERE
+ condition appended to a single table or a joined table. In some cases,
+ this method of selection is the only method available. But when it is
+ possible to perform the selection with join conditions, this is the
+ better method, as it results in a clearer expression of the
+ query.</para>
+ </section>
+
+ <section>
+ <title>Projection</title>
+
+ <para>Projection is selection of the columns from a simple or joined
+ table to form a result table. Explicit projection is performed in the
+ SELECT statement by specifying the select column list. Some form of
+ projection is also performed in JOIN ... USING and NATURAL JOIN.</para>
+
+ <para>The joined table has columns that are formed according to the
+ rules mentioned above. But in many cases, not all the columns are
+ necessary for the intended operation. If the statement is in the form,
+ SELECT * FROM <joined table>, then all the columns of <joined
+ table> are returned. But normally, the columns to be returned are
+ specified after the SELECT keyword, separated from each other with
+ commas.</para>
+ </section>
+
+ <section>
+ <title>Computed Columns</title>
+
+ <para>In the select list, it is possible to use expressions that
+ reference any columns of <joined table>. Each of these expressions
+ forms a computed column. It is computed for each row of the result
+ table, using the values of the columns of the <joined table> for
+ that row.</para>
+ </section>
+
+ <section>
+ <title>Naming</title>
+
+ <para>Naming is used to hide the original names of tables or table
+ columns and to replace them with new names in the scope of the query.
+ Naming is also used for defining names for computed columns.</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>naming in joined table</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">Naming in Joined
+ Table</emphasis></simpara>
+
+ <para>Naming is performed by adding a new name after a table's real name
+ and by adding a list of column names after the new table name. Both
+ table naming and column naming are optional, but table naming is
+ required for column naming. The expression <literal>A [AS] X (<comma
+ separated column name list>)</literal> means table A is used in the
+ query expression as table X and its columns are named as in the given
+ list. The original name A, or its original column names, are not visible
+ in the scope of the query. The BNF is given below. The
+ <literal><correlation name></literal> can be the same or different
+ from the name of the table. The <literal><derived column
+ list></literal> is a comma separated list of column names. The degree
+ of this list must be equal to the degree of the table. The column names
+ in the list must be distinct. They can be the same or different from the
+ names of the table's columns.</para>
+
+ <para><literal><table or query name> [ [ AS ] <correlation
+ name> [ <left paren> <derived column list> <right
+ paren> ] ]</literal></para>
+
+ <simpara>In the examples below, the columns of the original tables are
+ named (a, b, c, d, e, f). The two queries are equivalent. In the second
+ query, the table and its columns are renamed and the new names are used
+ in the WHERE clauses:</simpara>
+
+ <programlisting>CREATE TABLE atable (a INT, b INT, c INT, d INT, e INT, f INT);
+SELECT d, e, f FROM atable WHERE a + b = c
+SELECT x, y, z FROM atable AS t (u, v, w, x, y, z) WHERE u + v = w</programlisting>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>naming in select list</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">Naming in Select
+ List</emphasis></simpara>
+
+ <para>Naming in the SELECT list logically takes place after naming in
+ the joined table. The new names for columns are not visible in the
+ immediate query expression or query expression. They become visible in
+ the ORDER BY clause and in the result table that is returned to the
+ user. Or if the query expression is used as a derived table in an
+ enclosing query expression.</para>
+
+ <para>In the example below, the query is on the same table but with
+ column renaming in the Select list. The new names are used in the ORDER
+ BY clause:</para>
+
+ <programlisting>SELECT x + y AS xysum, y + z AS yzsum FROM atable AS t (u, v, w, x, y, z) WHERE u + v = w ORDER BY xysum, yzsum</programlisting>
+
+ <para>If the names <literal>xysum</literal> or <literal>yzsum</literal>
+ are not used, the computed columns cannot be referenced in the ORDER BY
+ list.</para>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>name resolution</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">Name Resolution</emphasis></simpara>
+
+ <simpara>In a joined table, if a column name appears in tables on both
+ sides then any reference to the name must use the table name in order to
+ specify which table is being referred to.</simpara>
+ </section>
+
+ <section>
+ <title>Grouping Operations</title>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>GROUPING OPERATIONS</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">Grouping Operations</emphasis></simpara>
+
+ <para>Grouping results in the elimination of duplicate rows. A grouping
+ operation is performed after the operations discussed above. A simple
+ form of grouping is performed by the use of DISTINCT after SELECT. This
+ eliminates all the duplicate rows (rows that have the same value in each
+ of their columns when compared to another row). The other form of
+ grouping is performed with the GROUP BY clause. This form is usually
+ used together with aggregation.</para>
+ </section>
+
+ <section>
+ <title>Aggregation</title>
+
+ <para>Aggregation is an operation that computes a single value from the
+ values of a column over several rows. The operation is performed with an
+ aggregate function. The simplest form of aggregation is counting,
+ performed by the COUNT function.</para>
+
+ <para>Other common aggregate functions return the maximum, minimum and
+ average value among the values in different rows.</para>
+ </section>
+
+ <section>
+ <title>Set Operations</title>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>SET OPERATIONS</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">Set and Multiset
+ Operations</emphasis></simpara>
+
+ <para>While join operations generally result in laterally expanded
+ tables, SET and COLLECTION operations are performed on two tables that
+ have the same degree and result in a table of the same degree. The SET
+ operations are UNION, INTERSECT and EXCEPT (difference). When each of
+ these operations is performed on two tables, the collection of rows in
+ each table and in the result is reduced to a set of rows, by eliminating
+ duplicates. The set operations are then performed on the two tables,
+ resulting in the new table which itself is a set of rows. Collection
+ operations are similar but the tables are not reduced to sets before or
+ after the operation and the result is not necessarily a set, but a
+ collection of rows.</para>
+
+ <para>The set operations on two tables A and B are: <literal>A UNION
+ [DISTINCT] B</literal>, <literal>A INTERSECT [DISTINCT] B</literal> and
+ <literal>A EXCEPT [DISTINCT] B</literal>. The result table is formed in
+ the following way: The UNION operation adds all the rows from A and B
+ into the new table, but avoids copying duplicate rows. The INTERSECT
+ operation copies only those rows from each table that also exist in the
+ other table, but avoids copying duplicate rows. The EXCEPT operation
+ copies those rows from the first table which do not exist in the second
+ table, but avoids copying duplicate rows.</para>
+
+ <para>The collection operations are similar to the set operations, but
+ can return duplicate rows. They are <literal>A UNION ALL B</literal>,
+ <literal>A INTERSECT ALL B</literal> and <literal>A EXCEPT ALL
+ B</literal>. The UNION ALL operation adds all the rows from A and B into
+ the new table. The INTERSECT operation copies only those rows from each
+ table that also exist in the other table. If n copies of a rows exists
+ in one table, and m copies in the other table, the number of copies in
+ the result table is the smaller of n and m. The EXCEPT operation copies
+ those rows from the first table which do not exist in the second table.
+ If n copies of a row exist in the first table and m copies in the second
+ table the number of copies in the result table is n-m, or if n < m,
+ then zero.</para>
+ </section>
+
+ <section>
+ <title>Query Expression</title>
+
+ <para>A query expression consists of an optional WITH clause and a query
+ expression body. The WITH clause lists one or more named ephemeral
+ tables that can be referenced in the query expression body.</para>
+
+ <para><literal><query expression> ::= [ <with clause> ]
+ <query expression body></literal></para>
+
+ <para><literal><with clause> ::= WITH <with
+ list></literal></para>
+
+ <para><literal><with list> ::= <with list element> [ {
+ <comma> <with list element> }... ] </literal></para>
+
+ <para><literal><with list element> ::= <query name> [
+ <left paren> <with column list> <right paren> ] AS
+ <left paren> <query expression> <right paren>
+ </literal></para>
+
+ <para><literal><with column list> ::= <column name
+ list></literal></para>
+
+ <para>A query expression body refers to a table formed by using UNION
+ and other set operations. The query expression body is evaluated from
+ left to right and the INTERSECT operator has precedence over the UNION
+ and EXCEPT operators. A simplified BNF is given below:</para>
+
+ <simpara><literal><query expression body> ::= <query term> |
+ <query expression body> UNION | EXCEPT [ ALL | DISTINCT ] [
+ <corresponding spec> ] <query term></literal></simpara>
+
+ <simpara><literal><query term> ::= <query primary> |
+ <query term> INTERSECT [ ALL | DISTINCT ] [ <corresponding
+ spec> ] <query term></literal></simpara>
+
+ <simpara><literal><query primary> ::= <simple table> |
+ <left paren> <query expression body> [ <order by
+ clause> ] [ <result offset clause> ] [ <fetch first
+ clause> ] <right paren></literal></simpara>
+
+ <simpara><literal><simple table> ::= <query specification> |
+ <table value constructor> | <explicit table> <explicit
+ table> ::= TABLE <table or query name></literal></simpara>
+
+ <para><literal><corresponding spec> ::= CORRESPONDING [ BY
+ <left paren> <column name list> <right paren>
+ ]</literal></para>
+
+ <para>A <literal><query term></literal> and a <literal><query
+ primary></literal> can be a SELECT statement, an
+ <literal><explicit table></literal>, or a <literal><table value
+ constructor></literal>.</para>
+
+ <para>The CORRESPONDING clause is optional. If it is not specified, then
+ the <literal><query term></literal> and the <literal><query
+ primary></literal> must have the same number of columns. If
+ CORRESPONDING is specified, the two sides need not have the same number
+ of columns. If no column list is used with CORRESPONDING, then all the
+ column names that are common in the tables on two sides are used in the
+ order in which they appear in the first table. If a columns list is
+ used, it allows you to select only some columns of the tables on the
+ left and right side to create the new table. In the example below the
+ columns named u and v from the two SELECT statements are used to create
+ the UNION table.</para>
+
+ <para><programlisting>SELECT * FROM atable UNION CORRESPONDING BY (u, v) SELECT * FROM anothertable
+</programlisting>The type of each column of the query expression is determined
+ by combining the types of the corresponding columns from the two
+ participating tables.</para>
+ </section>
+
+ <section>
+ <title>Ordering</title>
+
+ <para>When the rows of the result table have been formed, it is possible
+ to specify the order in which they are returned to the user. The ORDER
+ BY clause is used to specify the columns used for ordering, and whether
+ ascending or descending ordering is used. It can also specify whether
+ NULL values are returned first or last.</para>
+
+ <programlisting>SELECT x + y AS xysum, y + z AS yzsum FROM atable AS t (u, v, w, x, y, z) WHERE u + v = w ORDER BY xysum NULLS LAST, yzsum NULLS FIRST</programlisting>
+
+ <para>The ORDER BY clause specifies one or more <literal><value
+ expressions></literal>. The list of rows is sorted according to the
+ first <literal><value expression></literal>. When some rows are
+ sorted equal then they are sorted according to the next
+ <literal><value expression></literal> and so on.</para>
+
+ <para><literal><order by clause> ::= ORDER BY <sort
+ specification> [ { <comma> <sort specification> }...
+ ]</literal></para>
+
+ <para><literal><sort specification> ::= <value expression> [
+ ASC | DESC ] [ NULLS FIRST | NULLS LAST ]</literal></para>
+ </section>
+
+ <section>
+ <title>Slicing</title>
+
+ <para>A different form of limiting the rows can be performed on the
+ result table after it has been formed according to all the other
+ operations (selection, grouping, ordering etc.). This is specified by
+ the FETCH ... ROWS and OFFSET clauses of a SELECT statement. In this
+ form, the specified OFFSET rows are removed from start of the table,
+ then up to the specified FETCH rows are kept and the rest of the rows
+ are discarded.</para>
+
+ <para><literal><result offset clause> ::= OFFSET <offset row
+ count> { ROW | ROWS } </literal></para>
+
+ <para><literal><fetch first clause> ::= FETCH { FIRST | NEXT } [
+ <fetch first row count> ] { ROW | ROWS } ONLY</literal></para>
+
+ <para><literal><limit clause> ::= LIMIT [ <fetch first row
+ count> ]</literal></para>
+
+ <para>A slicing operation takes the result set that has been already
+ processed and ordered. It then discards the specified number of rows
+ from the start of the result set and returns the specified number of
+ rows after the discarded rows.</para>
+
+ <programlisting>SELECT a, b FROM atable WHERE d < 5 ORDER BY absum OFFSET 3 FETCH 2 ROWS ONLY
+SELECT a, b FROM atable WHERE d < 5 ORDER BY absum OFFSET 3 LIMIT 2 /* alternative keyword */ </programlisting>
+ </section>
+ </section>
+
+ <section>
+ <title>Data Change Statements</title>
+
+ <section>
+ <title>Delete Statement</title>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>DELETE FROM</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">DELETE FROM</emphasis></simpara>
+
+ <simpara><emphasis>delete statement: searched</emphasis></simpara>
+
+ <simpara><literal><delete statement: searched> ::= DELETE FROM
+ <target table> [ [ AS ] <correlation name> ] [ WHERE
+ <search condition> ]</literal></simpara>
+
+ <simpara>Delete rows of a table. The search condition is a
+ <literal><boolean value expression></literal> that is evaluated
+ for each row of the table. If the condition is true, the row is deleted.
+ If the condition is not specified, all the rows of the table are
+ deleted. In fact, an implicit SELECT is performed in the form of
+ <literal>SELECT * FROM <target table> [ WHERE <search
+ condition>]</literal> and the selected rows are deleted. When used in
+ JDBC, the number of rows returned by the implicit SELECT is returned as
+ the update count.</simpara>
+
+ <simpara>If there are FOREIGN KEY constraints on other tables that
+ reference the subject table, and the FOREIGN KEY constraints have
+ referential actions, then rows from those other tables that reference
+ the deleted rows are either deleted, or updated, according to the
+ specified referential actions.</simpara>
+
+ <simpara>In the second example below the rows that have the maximum
+ value for column A are deleted;</simpara>
+
+ <programlisting>DELETE FROM T WHERE C > 5
+DELETE FROM T AS TT WHERE TT.A = (SELECT MAX(A) FROM T)
+</programlisting>
+ </section>
+
+ <section>
+ <title>Truncate Statement</title>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>TRUNCATE TABLE</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">TRUNCATE TABLE</emphasis></simpara>
+
+ <simpara><emphasis>truncate table statement</emphasis></simpara>
+
+ <simpara><literal><truncate table statement> ::= TRUNCATE TABLE
+ <target table> [ <identity column restart option>
+ ]</literal></simpara>
+
+ <simpara><literal><identity column restart option> ::= CONTINUE
+ IDENTITY | RESTART IDENTITY</literal></simpara>
+
+ <simpara>Delete all rows of a table without firing its triggers. This
+ statement can only be used on base tables (not views). If the table is
+ referenced in a FOREIGN KEY constraint, the statement causes an
+ exception. Triggers defined on the table are not executed with this
+ statement. The default for <literal><identity column restart
+ option></literal> is <literal>CONTINUE IDENTITY</literal>. This means
+ no change to the IDENTITY sequence of the table. If <literal>RESTART
+ IDENTITY</literal> is specified, then the sequence is reset to its start
+ value.</simpara>
+
+ <simpara>TRUNCATE is faster than ordinary DELETE. The TRUNCATE statement
+ is an SQL Standard data change statement, therefore it is performed
+ under transaction control and can be rolled back if the connection is
+ not in the auto-commit mode.</simpara>
+ </section>
+
+ <section>
+ <title>Insert Statement</title>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>INSERT INTO</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">INSERT INTO</emphasis></simpara>
+
+ <simpara><emphasis>insert statement</emphasis></simpara>
+
+ <simpara><literal><insert statement> ::= INSERT INTO <target
+ table> <insert columns and source></literal></simpara>
+
+ <simpara><literal><insert columns and source> ::= <from
+ subquery> | <from constructor> | <from
+ default></literal></simpara>
+
+ <simpara><literal><from subquery> ::= [ <left paren>
+ <insert column list> <right paren> ] [ <override
+ clause> ] <query expression></literal></simpara>
+
+ <simpara><literal><from constructor> ::= [ <left paren>
+ <insert column list> <right paren> ] [ <override
+ clause> ] <contextually typed table value
+ constructor></literal></simpara>
+
+ <simpara><literal><override clause> ::= OVERRIDING USER VALUE |
+ OVERRIDING SYSTEM VALUE</literal></simpara>
+
+ <simpara><literal><from default> ::= DEFAULT
+ VALUES</literal></simpara>
+
+ <simpara><literal><insert column list> ::= <column name
+ list></literal></simpara>
+
+ <simpara>Insert new rows in a table. An INSERT statement inserts one or
+ more rows into the table.</simpara>
+
+ <simpara>The special form, <literal>INSERT INTO <target table>
+ DEFAULT VALUES</literal> can be used with tables which have a default
+ value for each column.</simpara>
+
+ <simpara>With the other forms of INSERT, the optional
+ <literal>(<insert column list>)</literal> specifies to which
+ columns of the table the new values are assigned.</simpara>
+
+ <simpara>In one form, the inserted values are from a <literal><query
+ expression></literal> and all the rows that are returned by the
+ <literal><query expression></literal> are inserted into the table.
+ If the <literal><query expression></literal> returns no rows,
+ nothing is inserted.</simpara>
+
+ <simpara>In the other form, a comma separated list of values called
+ <literal><contextually typed table value constructor></literal> is
+ used to insert one or more rows into the table. This list is
+ contextually typed, because the keywords NULL and DEFAULT can be used
+ for the values that are assigned to each column of the table. The
+ keyword DEFAULT means the default value of the column and can be used
+ only if the target column has a default value or is an IDENTITY or
+ GENERATED column of the table.</simpara>
+
+ <simpara>The <literal><override clause></literal> must be used
+ when a value is explicitly assigned to a column that has been defined as
+ GENERATED ALWAYS AS IDENTITY. The clause, OVERRIDE SYSTEM VALUE means
+ the provided values are used for the insert, while OVERRIDING USER VALUE
+ means the provided values are simply ignored and the values generated by
+ the system are used instead.</simpara>
+
+ <simpara>An array can be inserted into a column of the array type by
+ using literals, by specifying a parameter in a prepared statement or an
+ existing array returned by query expression. The last example below
+ inserts an array.</simpara>
+
+ <simpara>The rows that are inserted into the table are checked against
+ all the constraints that have been declared on the table. The whole
+ INSERT operation fails if any row fails to inserted due to constraint
+ violation. Examples:</simpara>
+
+ <programlisting>INSERT INTO T DEFAULT VALUES /* all columns of T have DEFAULT clauses */
+INSERT INTO T (SELECT * FROM Z) /* table Z has the same columns as table T */
+INSERT INTO T (A,B) VALUES ((1,2),(3,NULL), (DEFAULT,6)) /* three rows are inserted into table T */
+INSERT INTO T VALUES 3, ARRAY['hot','cold']
+</programlisting>
+ </section>
+
+ <section>
+ <title>Update Statement</title>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>UPDATE</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">UPDATE</emphasis></simpara>
+
+ <simpara><emphasis>update statement: searched</emphasis></simpara>
+
+ <simpara><literal><update statement: searched> ::= UPDATE
+ <target table> [ [ AS ] <correlation name> ] SET <set
+ clause list> [ WHERE <search condition> ]</literal></simpara>
+
+ <simpara>Update rows of a table. An UPDATE statement selects rows from
+ the <literal><target table></literal> using an implicit SELECT
+ statement formed in the following manner:</simpara>
+
+ <simpara><literal>SELECT * FROM <target table> [ [ AS ]
+ <correlation name> ] [ WHERE <search condition>
+ ]</literal></simpara>
+
+ <simpara>Then it applies the <literal>SET <set clause
+ list></literal> expression to each selected row.</simpara>
+
+ <simpara>If the implicit SELECT returns no rows, no update takes place.
+ When used in JDBC, the number of rows returned by the implicit SELECT is
+ returned as the update count.</simpara>
+
+ <simpara>If there are FOREIGN KEY constraints on other tables that
+ reference the subject table, and the FOREIGN KEY constraints have
+ referential actions, then rows from those other tables that reference
+ the updated rows are updated, according to the specified referential
+ actions.</simpara>
+
+ <simpara>The rows that are updated are checked against all the
+ constraints that have been declared on the table. The whole UPDATE
+ operation fails if any row violates any constraint.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>set clause in UPDATE and MERGE statements</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">set clause list</emphasis></simpara>
+
+ <simpara><emphasis>set clause list</emphasis></simpara>
+
+ <simpara><literal><set clause list> ::= <set clause> [ {
+ <comma> <set clause> }... ]</literal></simpara>
+
+ <simpara><literal><set clause> ::= <multiple column
+ assignment> | <set target> <equals operator> <update
+ source></literal></simpara>
+
+ <simpara><literal><multiple column assignment> ::= <set target
+ list> <equals operator> <assigned
+ row></literal></simpara>
+
+ <simpara><literal><set target list> ::= <left paren> <set
+ target> [ { <comma> <set target> }... ] <right
+ paren></literal></simpara>
+
+ <simpara><literal><assigned row> ::= <contextually typed row
+ value expression></literal></simpara>
+
+ <simpara><literal><set target> ::= <column
+ name></literal></simpara>
+
+ <simpara><literal><update source> ::= <value expression> |
+ <contextually typed value specification></literal></simpara>
+
+ <simpara>Specify a list of assignments. This is used in UPDATE, MERGE
+ and SET statements to assign values to a scalar or row target.</simpara>
+
+ <simpara>Apart from setting a whole target to a value, a SET statement
+ can set individual elements of an array to new values. The last example
+ below shows this form of assignment to the array in the column named
+ B.</simpara>
+
+ <simpara>In the examples given below, UPDATE statements with single and
+ multiple assignments are shown. Note in the third example, a SELECT
+ statement is used to provide the update values for columns A and C,
+ while the update value for column B is given separately. The SELECT
+ statement must return exactly one row . In this example the SELECT
+ statement refers to the existing value for column C in its search
+ condition.</simpara>
+
+ <programlisting>UPDATE T SET A = 5 WHERE ...
+UPDATE T SET (A, B) = (1, NULL) WHERE ...
+UPDATE T SET (A, C) = (SELECT X, Y FROM U WHERE Z = C), B = 10 WHERE ...
+UPDATE T SET A = 3, B[3] = 'warm'
+</programlisting>
+ </section>
+
+ <section>
+ <title>Merge Statement</title>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>MERGE INTO</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">MERGE INTO</emphasis></simpara>
+
+ <simpara><emphasis>merge statement</emphasis></simpara>
+
+ <simpara><literal><merge statement> ::= MERGE INTO <target
+ table> [ [ AS ] <merge correlation name> ] USING <table
+ reference> ON <search condition> <merge operation
+ specification></literal></simpara>
+
+ <simpara><literal><merge correlation name> ::= <correlation
+ name></literal></simpara>
+
+ <simpara><literal><merge operation specification> ::= <merge
+ when clause>...</literal></simpara>
+
+ <simpara><literal><merge when clause> ::= <merge when matched
+ clause> | <merge when not matched clause></literal></simpara>
+
+ <simpara><literal><merge when matched clause> ::= WHEN MATCHED
+ THEN <merge update specification></literal></simpara>
+
+ <simpara><literal><merge when not matched clause> ::= WHEN NOT
+ MATCHED THEN <merge insert specification></literal></simpara>
+
+ <simpara><literal><merge update specification> ::= UPDATE SET
+ <set clause list></literal></simpara>
+
+ <simpara><literal><merge insert specification> ::= INSERT [
+ <left paren> <insert column list> <right paren> ] [
+ <override clause> ] VALUES <merge insert value
+ list></literal></simpara>
+
+ <simpara><literal><merge insert value list> ::= <left paren>
+ <merge insert value element> [ { <comma> <merge insert
+ value element> }... ] <right paren></literal></simpara>
+
+ <simpara><literal><merge insert value element> ::= <value
+ expression> | <contextually typed value
+ specification></literal></simpara>
+
+ <simpara>Update rows, or insert new rows into the <literal><target
+ table></literal>. The MERGE statement uses a second table, specified
+ by <literal><table reference></literal>, to determine the rows to
+ be updated or inserted. It is possible to use the statement only to
+ update rows or to insert rows, but usually both update and insert are
+ specified.</simpara>
+
+ <simpara>The <literal><search condition></literal> matches each
+ row of the <literal><table reference></literal> with each row of
+ the <literal><target table></literal>. If the two rows match then
+ the UPDATE clause is used to update the matching row of the target
+ table. Those rows of <literal><table reference></literal> that
+ have no matching rows are then used to insert new rows into the
+ <literal><target table></literal>. Therefore, a MERGE statement
+ can update between 0 and all the rows of the <literal><target
+ table></literal> and can insert between 0 and the number of the rows
+ in <literal><table reference></literal> into the
+ <literal><target table></literal>. If any row in the
+ <literal><target table></literal> matches more than one row in
+ <literal><table reference></literal> a cardinality error is
+ raised. On the other hand, several rows in the <literal><target
+ table></literal> can matches a single row in <literal><table
+ reference></literal> without any error. The constraints and
+ referential actions specified on the database tables are enforced the
+ same way as for an update and an insert statement.</simpara>
+
+ <simpara>The MERGE statement can be used with only the WHEN NOT MATCHED
+ clause as a conditional INSERT statement that inserts a row if no
+ existing rows match a condition.</simpara>
+
+ <simpara>In the first example below, the table originally contains two
+ rows for different furniture. The <literal><table
+ reference></literal> is the <literal>(VALUES(1, 'conference table'),
+ (14, 'sofa'), (5, 'coffee table'))</literal> expression, which evaluates
+ to a table with 3 rows. When the x value for a row matches an existing
+ row, then the existing row is updated. When the x value does not match,
+ the row is inserted. Therefore one row of table t is updated from
+ 'dining table' to 'conference table', and two rows are inserted into
+ table t. The second example uses a SELECT statement as the source of the
+ values for the MERGE.</simpara>
+
+ <simpara>In the third example, a new row in inserted into the table only
+ when the primary key for the new row does not exist. This example uses
+ parameters and should be executed as a JDBC PreparedStatement.</simpara>
+
+ <programlisting>CREATE TABLE t (id INT PRIMARY KEY, description VARCHAR(100))
+INSERT INTO t VALUES (1, 'dining table'), (2, 'deck chair')
+MERGE INTO t USING (VALUES(1, 'conference table'), (14, 'sofa'), (5, 'coffee table'))
+ AS vals(x,y) ON t.id = vals.x
+ WHEN MATCHED THEN UPDATE SET t.description = vals.y
+ WHEN NOT MATCHED THEN INSERT VALUES vals.x, vals.y
+
+MERGE INTO t USING (SELECT * FROM tt WHERE acol = 2) AS vals(x,y) ON t.id = vals.x
+ WHEN MATCHED THEN UPDATE SET t.description = vals.y
+ WHEN NOT MATCHED THEN INSERT VALUES vals.x, vals.y
+
+MERGE INTO t USING (VALUES(CAST(? AS INT))) AS vals(x) ON t.id = vals.x
+ WHEN NOT MATCHED THEN INSERT VALUES vals.x, ?
+</programlisting>
+ </section>
+ </section>
+</chapter>
diff --git a/doc-src/guide/databaseobjects.xml b/doc-src/guide/databaseobjects.xml
new file mode 100644
index 0000000..3c0a60f
--- /dev/null
+++ b/doc-src/guide/databaseobjects.xml
@@ -0,0 +1,2908 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter version="5.0" xml:id="databaseobjects-chapt"
+ xmlns="http://docbook.org/ns/docbook"
+ xmlns:xlink="http://www.w3.org/1999/xlink"
+ xmlns:xi="http://www.w3.org/2001/XInclude"
+ xmlns:ns5="http://www.w3.org/2000/svg"
+ xmlns:ns4="http://www.w3.org/1998/Math/MathML"
+ xmlns:ns3="http://www.w3.org/1999/xhtml"
+ xmlns:ns="http://docbook.org/ns/docbook">
+ <title xml:id="databaseobjects-title">Schemas and Database Objects</title>
+
+ <info>
+ <authorgroup>
+ <author>
+ <personname><firstname>Fred</firstname><surname>Toussi</surname></personname>
+
+ <affiliation>
+ <orgname>The HSQL Development Group</orgname>
+ </affiliation>
+ </author>
+ </authorgroup>
+
+ <releaseinfo>$Revision: 3622 $</releaseinfo>
+
+ <pubdate>$Date: 2010-06-04 11:33:51 -0400 (Fri, 04 Jun 2010) $</pubdate>
+
+ <keywordset>
+ <keyword>Hsqldb</keyword>
+
+ <keyword>HyperSQL</keyword>
+
+ <keyword>SQL</keyword>
+ </keywordset>
+
+ <legalnotice>
+ <para>Copyright 2009 Fred Toussi. Permission is granted to distribute
+ this document without any alteration under the terms of the HSQLDB
+ license. Additional permission is granted to the HSQL Development Group
+ to distribute this document with or without alterations under the terms
+ of the HSQLDB license.</para>
+ </legalnotice>
+ </info>
+
+ <section>
+ <title>Overview</title>
+
+ <para>The persistent elements of an SQL environment are database objects.
+ The database consists of catalogs plus authorizations.</para>
+
+ <para>A catalog contains schemas, while schemas contain the objects that
+ contain data or govern the data.</para>
+
+ <para>Each catalog contains a special schema called INFORMATION_SCHEMA.
+ This schema is read-only and contains some views and other schema objects.
+ The views contain lists of all the database objects that exist within the
+ catalog, plus all authorizations.</para>
+
+ <para>Each database object has a name. A name is an identifier and is
+ unique within its name-space.</para>
+ </section>
+
+ <section>
+ <title>Schemas and Schema Objects</title>
+
+ <para>In HyperSQL, there is only one catalog per database. The name of the
+ catalog is PUBLIC. You can rename the catalog with the <literal>ALTER
+ CATALOG RENAME TO</literal> statement. All schemas belong the this
+ catalog. The catalog name has no relation to the file name of the
+ database.</para>
+
+ <para>Each database has also an internal "unique" name which is
+ automatically generated when the database is created. This name is used
+ for event logging. You can also change this unique name.</para>
+
+ <para>Schema objects are database objects that contain data or govern or
+ perform operations on data. By definition, each schema object belongs to a
+ specific schema.</para>
+
+ <para>Schema objects can be divided into groups according to their
+ characteristics.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Some kinds of schema objects can exist independently from other
+ schema object. Other kinds can exist only as an element of another
+ schema object. These dependent objects are automatically destroyed
+ when the parent object is dropped.</para>
+ </listitem>
+
+ <listitem>
+ <para>Separate name-spaces exists for different kinds of schema
+ object. Some name-spaces are shared between two similar kinds of
+ schema objects.</para>
+ </listitem>
+
+ <listitem>
+ <para>There can be dependencies between various schema objects, as a
+ schema object can include references to other schema objects. These
+ references can cross schema boundaries. Interdependence and cross
+ referencing between schema objects is allowed in some circumstances
+ and disallowed in some others.</para>
+ </listitem>
+
+ <listitem>
+ <para>Schema objects can be destroyed with the DROP statement. If
+ dependent schema objects exist, a DROP statement will succeed only if
+ it has a CASCADE clause. In this case, dependent objects are also
+ destroyed in most cases. In some cases, such as dropping DOMAIN
+ objects, the dependent objects are not destroyed, but modified to
+ remove the dependency.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>A new HyperSQL catalog contains an empty schema called PUBLIC. By
+ default, this schema is the initial schema when a new session is started.
+ New schemas and schema objects can be defined and used in the PUBLIC
+ schema, as well as any new schema that is created by the user. You can
+ rename the PUBLIC schema.</para>
+
+ <para>HyperSQL allows all schemas to be dropped, except the schema that is
+ the default initial schema for new sessions (by default, the PUBLIC
+ schema). For this schema, a DROP SCHEMA ... CASCADE statement will succeed
+ but will result in an empty schema, rather than no schema.</para>
+
+ <para>The statements for setting the initial schema for users are
+ described in the <link endterm="accesscontrol-statements-title" os=""
+ xlink:href="#accesscontrol-chapt"></link> chapter.</para>
+
+ <section>
+ <title>Names and References</title>
+
+ <para>The name of a schema object is an
+ <literal><identifier></literal>. The name belongs to the
+ name-space for the particular kind of schema object. The name is unique
+ within its name-space. For example, each schema has a separate
+ name-space for TRIGGER objects.</para>
+
+ <para>In addition to the name-spaces in the schema. Each table has a
+ name-space for the names of its columns.</para>
+
+ <para>Because a schema object is always in a schema and a schema always
+ in a catalog, it is possible, and sometimes necessary, to qualify the
+ name of the schema object that is being referenced in an SQL statement.
+ This is done by forming an <<literal>identifier chain></literal>.
+ In some contexts, only a simple <literal><identifier></literal>
+ can be used and the <literal><identifier chain></literal> is
+ prohibited. While in some other contexts, the use of
+ <literal><identifier chain></literal> is optional. An identifier
+ chain is formed by qualifying each object with the name of the object
+ that owns its name-space. Therefore a column name is prefixed with a
+ table name, a table name is prefixed with a schema name, and a schema
+ name is prefixed with a catalog name. A fully qualified column name is
+ in the form <literal><catalog name>.<schema name>.<table
+ name>.<column name></literal>, likewise, a fully qualified
+ sequence name is in the form <literal><catalog name>.<schema
+ name>.<sequence name></literal>.</para>
+
+ <para>HyperSQL extends the SQL standard to allow renaming all database
+ objects. The ALTER ... RENAME TO command has slightly different forms
+ depending on the type of object. If an object is referenced in a VIEW or
+ ROUTINE definition, it is not always possible to rename it.</para>
+ </section>
+
+ <section>
+ <title>Character Sets</title>
+
+ <simpara>A CHARACTER SET is the whole or a subset of the UNICODE
+ character set.</simpara>
+
+ <simpara>A character set name can only be a <literal><regular
+ identifier></literal>. There is a separate name-space for character
+ sets.</simpara>
+
+ <simpara>There are several predefined character sets. These character
+ sets belong to INFORMATION_SCHEMA. However, when they are referenced in
+ a statement, no schema prefix can be used in the statement that
+ references them.</simpara>
+
+ <simpara>The following character sets have been specified by the SQL
+ Standard:</simpara>
+
+ <simpara>SQL_TEXT, SQL_IDENTIFIER, SQL_CHARACTER, ASCII_GRAPHIC,
+ GRAPHIC_IRV, ASCII_FULL, ISO8BIT, LATIN1, UTF32, UTF16, UTF8.</simpara>
+
+ <simpara>The ASCII_GRAPHIC is the same as GRAPHIC_IRV and ASCII_FULL is
+ the same as ISO8BIT.</simpara>
+
+ <simpara>Most of the character sets are defined by well-known standards
+ such as UNICODE.</simpara>
+
+ <simpara>The SQL_CHARACTER consists of ASCII letters, digits and the
+ symbols used in the SQL language. The SQL_TEXT, SQL_IDENTIFIER are
+ implementation defined. HyperSQL defines SQL_TEXT as the UNICODE
+ character set and SQL_IDENTIFIER as the UNICODE character set minus the
+ SQL language special characters.</simpara>
+
+ <simpara>The character repertoire of HyperSQL is the UTF16 character
+ set, which covers all possible character sets. If a predefined character
+ set is specified for a table column, then any string stored in the
+ column must contain only characters from the specified character
+ set.</simpara>
+
+ <simpara>Early releases of HyperSQL version 2.0 may not enforce the
+ CHARACTER SET that is specified for a column and may accept any
+ character string.</simpara>
+ </section>
+
+ <section>
+ <title>Collations</title>
+
+ <simpara>A COLLATION is the method used for ordering character strings
+ in ordered sets and to determine equivalence of two character
+ strings.</simpara>
+
+ <simpara>There are several predefined collations. These collations
+ belong to INFORMATION_SCHEMA. However, when they are referenced in a
+ statement, no schema prefix can be used in the statement that references
+ them.</simpara>
+
+ <simpara>There is a separate name-space for collations..</simpara>
+
+ <simpara>Collations for a large number of languages are supported by
+ HyperSQL.</simpara>
+
+ <simpara>Early releases of HyperSQL version 2.0 only support a single
+ collation for the whole database.</simpara>
+ </section>
+
+ <section>
+ <title>Distinct Types</title>
+
+ <simpara>A distinct, user-defined TYPE is simply based on a built-in
+ type. A distinct TYPE is used in table definitions and in CAST
+ statements.</simpara>
+
+ <simpara>Distinct types share a name-space with domains.</simpara>
+ </section>
+
+ <section>
+ <title>Domains</title>
+
+ <simpara>A DOMAIN is a user-defined type, simply based on a built-in
+ type. A DOMAIN can have constraints that limit the values that the
+ DOMAIN can represent. A DOMAIN can be used in table definitions and in
+ CAST statements.</simpara>
+
+ <simpara>Distinct types share a name-space with domains.</simpara>
+ </section>
+
+ <section>
+ <title>Number Sequences</title>
+
+ <simpara>A SEQUENCE object produces INTEGER values in sequence. The
+ SEQUENCE can be referenced in special contexts only within certain SQL
+ statements. For each row where the object is referenced, its value is
+ incremented.</simpara>
+
+ <simpara>There is a separate name-space for SEQUENCE objects.</simpara>
+
+ <simpara>IDENTITY columns are columns of tables which have an internal,
+ unnamed SEQUENCE object.</simpara>
+
+ <simpara>SEQUENCE objects and IDENTITY columns are supported fully
+ according to the latest SQL 2008 Standard syntax.</simpara>
+
+ <simpara><emphasis role="bold">Sequences</emphasis></simpara>
+
+ <para>The SQL:2008 syntax and usage is different from what is supported
+ by many existing database engines. Sequences are created with the
+ <literal>CREATE SEQUENCE</literal> command and their current value can
+ be modified at any time with <literal>ALTER SEQUENCE</literal>. The next
+ value for a sequence is retrieved with the <literal>NEXT VALUE FOR
+ <name></literal> expression. This expression can be used for
+ inserting and updating table rows.</para>
+
+ <example>
+ <title>inserting the next sequence value into a table row</title>
+
+ <programlisting>INSERT INTO mytable VALUES 2, 'John', NEXT VALUE FOR mysequence;</programlisting>
+ </example>
+
+ <para>You can also use it in select statements. For example, if you want
+ to number the returned rows of a SELECT in sequential order, you can
+ use:</para>
+
+ <example>
+ <title>numbering returned rows of a SELECT in sequential order</title>
+
+ <programlisting>SELECT NEXT VALUE FOR mysequence, col1, col2 FROM mytable WHERE ...</programlisting>
+ </example>
+
+ <para>In version 2.0, the semantics of sequences is exactly as defined
+ by SQL:2008. If you use the same sequence twice in the same row in an
+ INSERT statement, you will get the same value as required by the
+ Standard.</para>
+
+ <para>The correct way to use a sequence value is the NEXT VALUE FOR
+ expression. You can query the SEQUENCES table for the next value that
+ will be returned from any of the defined sequences. The SEQUENCE_NAME
+ column contains the name and the NEXT_VALUE column contains the next
+ value to be returned. Note that this is only for getting information and
+ you should not use the sequence value.</para>
+
+ <simpara><emphasis role="bold">Identity Auto-Increment
+ Columns</emphasis></simpara>
+
+ <para>Each table can contain a single auto-increment column, known as
+ the IDENTITY column. An IDENTITY column is a SMALLINT, INTEGER, BIGINT,
+ DECIMAL or NUMERIC column with its value generated by a sequence
+ generator.</para>
+
+ <para>In HyperSQL 2.0, an IDENTITY column is not by default treated as
+ the primary key for the table (as a result, multi-column primary keys
+ are possible with an IDENTITY column present).</para>
+
+ <para>The SQL standard syntax is used, which allows the initial value
+ and other options to be specified.<programlisting><colname> [ INTEGER | BIGINT | DECIMAL | NUMERIC ] GENERATED { BY DEFAULT | ALWAYS} AS IDENTITY [( <options> )] [PRIMARY KEY]</programlisting></para>
+
+ <para>When you add a new row to such a table using an <literal>INSERT
+ INTO <tablename> ... </literal>statement, you can use the DEFAULT
+ keyword for the IDENTITY column, which results in an auto-generated
+ value for the column. The <literal>IDENTITY() </literal>function returns
+ the last value inserted into any IDENTITY column by this session. Each
+ session manages this function call separately and is not affected by
+ inserts in other sessions. Use <literal>CALL IDENTITY() </literal>as an
+ SQL statement to retrieve this value. If you want to use the value for a
+ field in a child table, you can use <literal>INSERT INTO
+ <childtable> VALUES (...,IDENTITY(),...);</literal>. Both types of
+ call to<literal> IDENTITY()</literal> must be made before any additional
+ update or insert statements are issued by the session.</para>
+
+ <para>The last inserted IDENTITY value can also be retrieved via JDBC,
+ by specifying the Statement or PreparedStatement object to return the
+ generated value.</para>
+
+ <para>The next IDENTITY value to be used can be changed with following
+ statement. Note that this statement is not used in normal operation and
+ is only for special purposes: <programlisting>ALTER TABLE ALTER COLUMN <column name> RESTART WITH <new value>;</programlisting>For
+ backward compatibility, support has been retained for <literal>CREATE
+ TABLE <tablename>(<colname> IDENTITY, ...)</literal> as a
+ shortcut which defines the column both as an IDENTITY column and a
+ PRIMARY KEY column. Also, for backward compatibility, it is possible to
+ use NULL as the value of an IDENTITY column in an INSERT statement and
+ the value will be generated automatically. You should avoid these
+ compatibility features as they may be removed from future versions of
+ HyperSQL.</para>
+
+ <para>In the following example, the identity value for the first INSERT
+ statement is generated automatically using the DEFAULT keyword. The
+ second INSERT statement uses a call to the IDENTITY() function to
+ populate a row in the child table with the generated identity
+ value.</para>
+
+ <informalexample>
+ <programlisting>CREATE TABLE star (id INTEGER GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
+ firstname VARCHAR(20),
+ lastname VARCHAR(20))
+CREATE TABLE movies (starid INTEGER, movieid INTEGER PRIMARY KEY, title VARCHAR(40))
+INSERT INTO star (id, firstname, lastname) VALUES (DEFAULT, 'Felix', 'the Cat')
+INSERT INTO movies (starid, movieid, title) VALUES (IDENTITY(), 10, 'Felix in Hollywood')
+</programlisting>
+ </informalexample>
+ </section>
+
+ <section>
+ <title>Tables</title>
+
+ <simpara>In the SQL environment, tables are the most essential
+ components, as they hold all persistent data.</simpara>
+
+ <simpara>If TABLE is considered as metadata (i.e. without its actual
+ data) it is called a <emphasis>relation</emphasis> in relational theory.
+ It has one or more columns, with each column having a distinct name and
+ a data type. A table usually has one or more constraints which limit the
+ values that can potentially be stored in the TABLE. These constraints
+ are discussed in the next section.</simpara>
+
+ <simpara>A single column of the table can be defined as IDENTITY. The
+ values stored in this column are auto-generated and are based on an
+ (unnamed) identity sequence.</simpara>
+ </section>
+
+ <section>
+ <title>Views</title>
+
+ <simpara>A VIEW is similar to a TABLE but it does not permanently
+ contain rows of data. A view is defined as a QUERY EXPRESSION, which is
+ often a SELECT statement that references views and tables, but it can
+ also consist of a TABLE CONSTRUCTOR that does not reference any tables
+ or views.</simpara>
+
+ <simpara>A view has many uses:</simpara>
+
+ <itemizedlist>
+ <listitem>
+ <para>Hide the structure and column names of tables. The view can
+ represent one or more tables or views as a separate table. This can
+ include aggregate data, such as sums and averages, from other
+ tables.</para>
+ </listitem>
+
+ <listitem>
+ <para>Allow access to specific rows in a table. For example, allow
+ access to records that were added since a given date, while hiding
+ older records.</para>
+ </listitem>
+
+ <listitem>
+ <para>Allow access to specific columns. For example allow access to
+ columns that contain non-confidential information. Note that this
+ can also be achieved with the GRANT SELECT statement, using
+ column-level privileges</para>
+ </listitem>
+ </itemizedlist>
+
+ <simpara>A VIEW that returns the columns of a single ordinary TABLE may
+ be <glossterm>updatable</glossterm>. Some
+ <glossterm>updatable</glossterm> views are
+ <glossterm>insertable-into</glossterm>. When rows of an updatable view
+ are updated, or new rows are inserted, these changes are reflected in
+ the base table. A VIEW definition may specify that the inserted or
+ updated rows conform to the search condition of the view. This is done
+ with the CHECK OPTION clause.</simpara>
+
+ <simpara>Views share a name-space with tables.</simpara>
+ </section>
+
+ <section>
+ <title>Constraints</title>
+
+ <simpara>A CONSTRAINT is a child schema object and can belong to a
+ DOMAIN or a TABLE. CONSTRAINT objects can be defined without specifying
+ a name. In this case the system generates a name for the new object
+ beginning with "SYS_".</simpara>
+
+ <!-- For some reason, without the quotes, the _ and . do not appear in
+ the HTML output. Can remove the quotes if this issue is taken care of
+ or disappears. -blaine -->
+
+ <simpara>In a DOMAIN, CHECK constraints can be defined that limits the
+ value represented by the DOMAIN. These constraints work exactly like a
+ CHECK constraint on a single column of a table as described
+ below.</simpara>
+
+ <simpara>In a TABLE, a constraint takes three basic forms.</simpara>
+
+ <simpara><emphasis role="bold">CHECK</emphasis></simpara>
+
+ <simpara>A CHECK constraint consists of a <literal><search
+ condition></literal> that must not be false (can be unknown) for each
+ row of the table. The <literal><search condition></literal> can
+ reference all the columns of the current row, and if it contains a
+ <literal><subquery></literal>, other tables and views in the
+ database (excluding its own table).</simpara>
+
+ <simpara><emphasis role="bold">NOT NULL</emphasis></simpara>
+
+ <simpara>A simple form of check constraint is the NOT NULL constraint,
+ which applies to a single column.</simpara>
+
+ <simpara><emphasis role="bold">UNIQUE</emphasis></simpara>
+
+ <simpara>A UNIQUE constraint is based on an equality comparison of
+ values of specific columns (taken together) of one row with the same
+ values from each of the other rows. The result of the comparison must
+ never be true (can be false or unknown). If a row of the table has NULL
+ in any of the columns of the constraint, it conforms to the constraint.
+ A unique constraint on multiple columns (c1, c2, c3, ..) means that in
+ no two rows, the sets of values for the columns can be equal unless at
+ lease one of them is NULL. Each single column taken by itself can have
+ repeat values in different rows. The following example satisfies a
+ UNIQUE constraint on the two columns</simpara>
+
+ <example>
+ <title>Column values which satisfy a 2-column UNIQUE
+ constraint</title>
+
+ <simplelist columns="2" type="horiz">
+ <member>1,</member>
+
+ <member>2</member>
+
+ <member>2,</member>
+
+ <member>1</member>
+
+ <member>2,</member>
+
+ <member>2</member>
+
+ <member>NULL,</member>
+
+ <member>1</member>
+
+ <member>NULL,</member>
+
+ <member>1</member>
+
+ <member>1,</member>
+
+ <member>NULL</member>
+
+ <member>NULL,</member>
+
+ <member>NULL</member>
+
+ <member>NULL,</member>
+
+ <member>NULL</member>
+ </simplelist>
+ </example>
+
+ <simpara><emphasis role="bold">PRIMARY KEY</emphasis></simpara>
+
+ <simpara>A PRIMARY KEY constraint is equivalent to a UNIQUE constraint
+ on one or more NOT NULL columns. Only one PRIMARY KEY can be defined in
+ each table.</simpara>
+
+ <simpara><emphasis role="bold">FOREIGN KEY</emphasis></simpara>
+
+ <simpara>A FOREIGN key constraint is based on an equality comparison
+ between values of specific columns (taken together) of each row with the
+ values of the columns of a UNIQUE constraint on another table or the
+ same table. The result of the comparison must never be false (can be
+ unknown). A special form of FOREIGN KEY constraint, based on its CHECK
+ clause, allows the result to be unknown only if the values for all
+ columns are NULL. A FOREIGN key can be declared only if a UNIQUE
+ constraint exists on the referenced columns.</simpara>
+
+ <simpara>Constraints share a name space with assertions.</simpara>
+ </section>
+
+ <section>
+ <title>Assertions</title>
+
+ <para>An ASSERTION is a top-level schema objects. It consists of a
+ <literal><search condition></literal> that must not be false (can
+ be unknown).</para>
+
+ <para>Assertions share a name-space with constraints</para>
+ </section>
+
+ <section>
+ <title>Triggers</title>
+
+ <simpara>A TRIGGER is a child schema object that always belongs to a
+ TABLE or a VIEW.</simpara>
+
+ <simpara>Each time a DELETE, UPDATE or INSERT is performed on the table
+ or view, additional actions are taken by the triggers that have been
+ declared on the table or view.</simpara>
+
+ <simpara>Triggers are discussed in detail in chapter <link
+ endterm="triggers-title" os="" xlink:href="#triggers-chapt"></link>
+ .</simpara>
+ </section>
+
+ <section>
+ <title>Routines</title>
+
+ <simpara>Routines are user-defined functions or procedures. The names
+ and usage of functions and procedures are different. FUNCTION is a
+ routine that can be referenced in many types of statements. PROCEDURE is
+ a routine that can be referenced only in a CALL statement.</simpara>
+
+ <simpara>There is a separate name-space for routines.</simpara>
+
+ <simpara>Because of the possibility of overloading, each routine can
+ have more than one name. The name of the routine is the same for all
+ overloaded variants, but each variant has a <glossterm>specific
+ name</glossterm>, different from all other routine names and specific
+ names in the schema. The <glossterm>specific name</glossterm> can be
+ specified in the routine definition statement. Otherwise it is assigned
+ by the engine. The specific name is used only for schema manipulation
+ statements, which need to reference a specific variant of the routine.
+ For example, if a routine has two signatures, each signature has its own
+ <glossterm>specific name</glossterm>. This allows the user to drop one
+ of the signatures while keeping the other.</simpara>
+
+ <simpara>Routines are discussed in detail in chapter <link
+ endterm="sqlroutines-title" os=""
+ xlink:href="#sqlroutines-chapt"></link> .</simpara>
+ </section>
+
+ <section>
+ <title>Indexes</title>
+
+ <para>Indexes are an implementation-defined extension to the SQL
+ Standard. HyperSQL has a dedicated name-space for indexes in each
+ schema.</para>
+ </section>
+ </section>
+
+ <section>
+ <title>Statements for Schema Definition and Manipulation</title>
+
+ <simpara>Schemas and schema objects can be created, modified and dropped.
+ The SQL Standard defines a range of statements for this purpose. HyperSQL
+ supports many additional statements, especially for changing the
+ properties of existing schema objects.</simpara>
+
+ <section>
+ <title>Common Elements and Statements</title>
+
+ <simpara>These elements and statements are used for different types of
+ object. They are described here, before the statements that can use
+ them.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>identifier definition</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">identifier</emphasis></simpara>
+
+ <simpara><emphasis>definition of identifier</emphasis></simpara>
+
+ <simpara><literal><identifier> ::= <regular identifier> |
+ <delimited identifier> | <SQL language identifier>
+ </literal></simpara>
+
+ <simpara><literal><delimited identifier> ::= <double quote>
+ <character sequence> <double quote></literal></simpara>
+
+ <simpara><literal><regular identifier> ::= <special character
+ sequence></literal></simpara>
+
+ <simpara><literal><SQL language identifier> ::= <special
+ character sequence></literal></simpara>
+
+ <simpara>A <literal><delimited identifier></literal> is a sequence
+ of characters enclosed with double-quote symbols. All characters are
+ allowed in the character sequence.</simpara>
+
+ <simpara>A <literal><regular identifier></literal> is a special
+ sequence of characters. It consists of letters, digits and the
+ underscore characters. It must begin with a letter.</simpara>
+
+ <simpara>A <literal><SQL language identifier></literal> is similar
+ to <literal><regular identifier></literal> but the letters can
+ range only from A-Z in the ASCII character set. This type of identifier
+ is used for names of CHARACTER SET objects.</simpara>
+
+ <simpara>If the character sequence of a delimited identifier is the same
+ as an undelimited identifier, it represents the same identifier. For
+ example "JOHN" is the same identifier as JOHN. In a <literal><regular
+ identifier></literal> the case-normal form is considered for
+ comparison. This form consists of the upper-case of equivalent of all
+ the letters.</simpara>
+
+ <simpara>The character sequence length of all identifiers must be
+ between 1 and 128 characters.</simpara>
+
+ <simpara>A reserved word is one that is used by the SQL Standard for
+ special purposes. It is similar to a <literal><regular
+ identifier></literal> but it cannot be used as an identifier for user
+ objects. If a reserved word is enclosed in double quote characters, it
+ becomes a quoted identifier and can be used for database
+ objects.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>CASCADE or RESTRICT</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">CASCADE or RESTRICT</emphasis></simpara>
+
+ <simpara><emphasis>drop behavior</emphasis></simpara>
+
+ <simpara><literal><drop behavior> ::= CASCADE |
+ RESTRICT</literal></simpara>
+
+ <simpara>The <literal><drop behavior></literal> is a required
+ element of statements that drop a SCHEMA or a schema object. If
+ <literal><drop behavior></literal> is not specified then
+ <literal>RESTRICT</literal> is implicit. It determines the effect of the
+ statement if there are other objects in the catalog that reference the
+ SCHEMA or the schema object. If RESTRICT is specified, the statement
+ fails if there are referencing objects. If CASCADE is specified, all the
+ referencing objects are modified or dropped with cascading effect.
+ Whether a referencing object is modified or dropped, depends on the kind
+ of schema object that is dropped.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>IF EXISTS</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">IF EXISTS</emphasis></simpara>
+
+ <simpara><emphasis>drop condition (HyperSQL)</emphasis></simpara>
+
+ <simpara><literal><if exists clause> ::= IF
+ EXISTS</literal></simpara>
+
+ <simpara>This clause is not part of the SQL standard and is a HyperSQL
+ extension to some commands that drop objects (schemas, tables, views,
+ sequences and indexes). If it is specified, then the statement does not
+ return an error if the drop statement is issued on a non-existent
+ object.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>SPECIFIC</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">SPECIFIC</emphasis></simpara>
+
+ <simpara><emphasis>specific routine designator</emphasis></simpara>
+
+ <simpara><literal><specific routine designator> ::= SPECIFIC
+ <routine type> <specific name> </literal></simpara>
+
+ <simpara><literal><routine type> ::= ROUTINE | FUNCTION |
+ PROCEDURE</literal></simpara>
+
+ <simpara>This clause is used in statements that need to specify one of
+ the multiple versions of an overloaded routine. The
+ <literal><specific name></literal> is the one specified in the
+ <literal><routine definition></literal> statement.</simpara>
+ </section>
+
+ <section>
+ <title>Renaming Objects</title>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>RENAME</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">RENAME</emphasis></simpara>
+
+ <simpara><emphasis>rename statement (HyperSQL)</emphasis></simpara>
+
+ <simpara><literal><rename statement> ::= ALTER <object type>
+ <name> RENAME TO <new name></literal></simpara>
+
+ <simpara><literal><object type> ::= CATALOG | SCHEMA | DOMAIN |
+ TYPE | TABLE | CONSTRAINT | INDEX | ROUTINE | SPECIFIC
+ ROUTINE</literal></simpara>
+
+ <simpara><literal><column rename statement> ::= ALTER TABLE
+ <table name> ALTER COLUMN <name> RENAME TO <new
+ name></literal></simpara>
+
+ <simpara>This statement is used to rename an existing object. It is not
+ part of the SQL Standard. The specified <literal><name></literal>
+ is the existing name, which can be qualified with a schema name, while
+ the <literal><new name></literal> is the new name for the
+ object.</simpara>
+ </section>
+
+ <section>
+ <title>Commenting Objects</title>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>COMMENT</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">COMMENT</emphasis></simpara>
+
+ <simpara><emphasis>comment statement (HyperSQL)</emphasis></simpara>
+
+ <simpara><literal><comment statement> ::= COMMENT ON { TABLE |
+ COLUMN | ROUTINE } <name> IS <character string
+ literal></literal></simpara>
+
+ <simpara>Adds a comment to the object metadata, which can later be read
+ from an INFORMATION_SCHEMA view. This command is not part of the SQL
+ Standard. The strange syntax is due to compatibility with other database
+ engines that support the statement.<literal> The <name></literal>
+ is the name of a table, view, column or routine. The name of the column
+ consists of dot-separated<literal> <table name> . <column
+ name></literal>. The name of the table, view or routine can be a
+ simple name. All names can be qualified with a schema name. If there is
+ alread a comment on the object, the new comment will replace
+ it.</simpara>
+
+ <para>The comments appear in the results returned by JDBC
+ DatabaseMetaData methods, getTables() and getColumns(). The
+ INFORMATION_SCHEMA.SYSTEM_COMMENTS view contains the comments. You can
+ query this view using the schema, table, and column names to retreive
+ the comments.</para>
+ </section>
+
+ <section>
+ <title>Schema Creation</title>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>CREATE SCHEMA</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">CREATE SCHEMA</emphasis></simpara>
+
+ <simpara><emphasis>schema definition</emphasis></simpara>
+
+ <para>The CREATE_SCHEMA or DBA role is required in order to create a
+ schema. A schema can be created with or without schema objects. Schema
+ objects can always be added after creating the schema, or existing ones
+ can be dropped. Within the <literal><schema definition></literal>
+ statement, all schema object creation takes place inside the newly
+ created schema. Therefore, if a schema name is specified for the schema
+ objects, the name must match that of the new schema. In addition to
+ statements for creating schema objects, the statement can include
+ instances of <literal><grant statement></literal> and
+ <literal><role definition></literal>. This is a curious aspect of
+ the SQL standard, as these elements do not really belong to schema
+ creation.</para>
+
+ <simpara><literal><schema definition> ::= CREATE SCHEMA <schema
+ name clause> [ <schema character set specification> ] [
+ <schema element>... ]</literal></simpara>
+
+ <simpara><literal><schema name clause> ::= <schema name> |
+ AUTHORIZATION <authorization identifier> | <schema name>
+ AUTHORIZATION <authorization identifier></literal></simpara>
+
+ <para>If the name of the schema is specified simply as
+ <literal><schema name></literal>, then the AUTHORIZATION is the
+ current user. Otherwise, the specified <literal><authorization
+ identifier></literal> is used as the AUTHORIZATION for the schema. If
+ <literal><schema name></literal> is omitted, then the name of the
+ schema is the same as the specified <literal><authorization
+ identifier></literal>.</para>
+
+ <simpara><literal><schema element> ::= <table definition> |
+ <view definition> | <domain definition> | <character set
+ definition> | <collation definition> | <transliteration
+ definition> | <assertion definition> | <trigger
+ definition> | <user-defined type definition> | <user-defined
+ cast definition> | <user-defined ordering definition> |
+ <transform definition> | <schema routine> | <sequence
+ generator definition> | <grant statement> | <role
+ definition></literal></simpara>
+
+ <simpara>An example of the command is given below. Note that a single
+ semicolon appears at the end, there should be no semicolon between the
+ statements:</simpara>
+
+ <programlisting> CREATE SCHEMA ACCOUNTS AUTHORIZATION DBA
+ CREATE TABLE AB(A INTEGER, ...)
+ CREATE TABLE CD(C CHAR(10), ...)
+ CREATE VIEW VI AS SELECT ...
+ GRANT SELECT ON AB TO PUBLIC
+ GRANT SELECT ON CD TO JOE;
+</programlisting>
+
+ <simpara>It is not really necessary to create a schema and all its
+ objects as one command. The schema can be created first, and its objects
+ can be created one by one.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>DROP SCHEMA</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">DROP SCHEMA</emphasis></simpara>
+
+ <simpara><emphasis>drop schema statement</emphasis></simpara>
+
+ <simpara><literal><drop schema statement> ::= DROP SCHEMA [ IF
+ EXISTS ] <schema name> [ IF EXISTS ] <drop behavior>
+ </literal></simpara>
+
+ <simpara>This command destroys an existing schema. If <literal><drop
+ behavior></literal> is <literal>RESTRICT</literal>, the schema must
+ be empty, otherwise an error is raised. If <literal>CASCADE</literal> is
+ specified, then all the objects contained in the schema are destroyed
+ with a CASCADE option.</simpara>
+ </section>
+
+ <section>
+ <title>Table Creation and Manipulation</title>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>CREATE TABLE</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">CREATE TABLE</emphasis></simpara>
+
+ <simpara><emphasis>table definition</emphasis></simpara>
+
+ <simpara><literal><table definition> ::= CREATE [ { <table
+ scope> | <table type> } ] TABLE <table name> <table
+ contents source> [ ON COMMIT { PRESERVE | DELETE } ROWS
+ ]</literal></simpara>
+
+ <simpara><literal><table scope> ::= { GLOBAL | LOCAL }
+ TEMPORARY</literal></simpara>
+
+ <simpara><literal><table type> :: = MEMORY |
+ CACHED</literal></simpara>
+
+ <simpara><literal><table contents source> ::= <table element
+ list> | <as subquery clause></literal></simpara>
+
+ <simpara><literal><table element list> ::= <left paren>
+ <table element> [ { <comma> <table element> }... ]
+ <right paren></literal></simpara>
+
+ <simpara><literal><table element> ::= <column definition> |
+ <table constraint definition> | <like
+ clause></literal></simpara>
+
+ <simpara><emphasis>like clause</emphasis></simpara>
+
+ <simpara>A <literal><like clause></literal> copies all column
+ definitions from another table into the newly created table. Its three
+ options indicate if the <literal><default clause></literal>,
+ <literal><identity column specification></literal> and
+ <literal><generation clause></literal> associated with the column
+ definitions are copied or not. If an option is not specified, it
+ defaults to <literal>EXCLUDING</literal>. The <literal><generation
+ clause></literal> refers to columns that are generated by an
+ expression but not to identity columns. All NOT NULL constraints are
+ copied with the original columns, other constraints are not. The
+ <literal><like clause></literal> can be used multiple times,
+ allowing the new table to have copies of the column definitions of one
+ or more other tables.</simpara>
+
+ <informalexample>
+ <programlisting>CREATE TABLE t (id INTEGER PRIMARY KEY, LIKE atable INCLUDING DEFAULTS EXCLUDING IDENTITY)
+</programlisting>
+ </informalexample>
+
+ <simpara><literal><like clause> ::= LIKE <table name> [
+ <like options> ]</literal></simpara>
+
+ <simpara><literal><like options> ::= <like
+ option>...</literal></simpara>
+
+ <simpara><literal><like option> ::= <identity option> |
+ <column default option> | <generation
+ option></literal></simpara>
+
+ <simpara><literal><identity option> ::= INCLUDING IDENTITY |
+ EXCLUDING IDENTITY</literal></simpara>
+
+ <simpara><literal><column default option> ::= INCLUDING DEFAULTS |
+ EXCLUDING DEFAULTS</literal></simpara>
+
+ <simpara><literal><generation option> ::= INCLUDING GENERATED |
+ EXCLUDING GENERATED</literal></simpara>
+
+ <simpara><emphasis>as subquery clause</emphasis></simpara>
+
+ <simpara><literal><as subquery clause> ::= [ <left paren>
+ <column name list> <right paren> ] AS <table subquery>
+ { WITH NO DATA | WITH DATA }</literal></simpara>
+
+ <simpara>An <literal><as subquery clause></literal> used in table
+ definition creates a table based on a <literal><table
+ subquery></literal>. This kind of table definition is similar to a
+ view definition. If <literal>WITH DATA</literal> is specified, then the
+ new table will contain the rows of data returned by the
+ <literal><table subquery></literal>.</simpara>
+
+ <informalexample>
+ <programlisting>CREATE TABLE t (a, b, c) AS (SELECT * FROM atable) WITH DATA
+</programlisting>
+ </informalexample>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>column definition</primary>
+ </indexterm>
+
+ <simpara><emphasis>column definition</emphasis></simpara>
+
+ <simpara>A column definition consists of a <literal><column
+ name></literal> and in most cases a <literal><data
+ type></literal> or <literal><domain name></literal> as minimum.
+ The other elements of <literal><column definition></literal> are
+ optional. Each <literal><column name></literal> in a table is
+ unique.</simpara>
+
+ <simpara><literal><column definition> ::= <column name> [
+ <data type or domain name> ] [ <default clause> |
+ <identity column specification> | <generation clause> ] [
+ <column constraint definition>... ] [ <collate clause>
+ ]</literal></simpara>
+
+ <simpara><literal><data type or domain name> ::= <data type>
+ | <domain name></literal></simpara>
+
+ <simpara><literal><column constraint definition> ::= [
+ <constraint name definition> ] <column constraint> [
+ <constraint characteristics> ]</literal></simpara>
+
+ <simpara><literal><column constraint> ::= NOT NULL | <unique
+ specification> | <references specification> | <check
+ constraint definition></literal></simpara>
+
+ <simpara><literal><identity column specification> ::= GENERATED {
+ ALWAYS | BY DEFAULT } AS IDENTITY [ <left paren> <common
+ sequence generator options> <right paren> ]</literal></simpara>
+
+ <simpara><literal><generation clause> ::= GENERATED ALWAYS AS
+ <generation expression></literal></simpara>
+
+ <simpara><literal><generation expression> ::= <left paren>
+ <value expression> <right paren></literal></simpara>
+
+ <simpara>The <literal><identity column specification></literal>
+ can be specified for only a single column of the table.</simpara>
+
+ <simpara>A <literal><column constraint definition></literal> is a
+ shortcut for a <literal><table constraint definition></literal>. A
+ constraint that is defined in this way is automatically turned into a
+ table constraint. A name is automatically generated for the constraint
+ and assigned to it.</simpara>
+
+ <simpara>The <literal><identity column specification></literal> is
+ used for special columns which represent values based on unnamed
+ sequence generators. It is possible to insert a row into the able
+ without specifying a value for the column. The value is then generated
+ by the sequence generators according to its rules. An identity column
+ may or may not be the primary key. Example below:</simpara>
+
+ <informalexample>
+ <programlisting>CREATE TABLE t (id INTEGER GENERATED ALWAYS AS IDENTITY(START WITH 100), name VARCHAR(20) PRIMARY KEY, )
+</programlisting>
+ </informalexample>
+
+ <simpara>The <literal><generation clause></literal> is used for
+ special columns which represent values based on the values held in other
+ columns in the same row. The <literal><value expression></literal>
+ must reference only other, non-generated, columns of the table in the
+ same row. Therefore, any function used in the expression may not access
+ SQL-data, and no <literal><query expression></literal> is allowed.
+ When <literal><generation clause></literal> is used,
+ <literal><data type></literal> or <literal><domain
+ name></literal> may be omitted.</simpara>
+
+ <simpara>A generated column can be part of a foreign key or unique
+ constraints or a column of an index. This capability is the main reason
+ for using generated columns. A generated column may contain a formula
+ that computes a value based on the values of other columns. Fast
+ searches of the computed value can be performed when an index is
+ declared on the generated column. Or the computed values can be declared
+ to be unique, using a UNIQUE constraint on the table.</simpara>
+
+ <simpara>When a row is inserted into a table, or an existing row is
+ updated, no value except DEFAULT can be specified for a generated
+ column. In the example below, data is inserted into the non-generated
+ columns and the generated column will contain 'Felix the Cat' or 'Pink
+ Panther'.</simpara>
+
+ <informalexample>
+ <programlisting>CREATE TABLE t (id INTEGER PRIMARY KEY,
+ firstname VARCHAR(20),
+ lastname VARCHAR(20),
+ fullname VARCHAR(40) GENERATED ALWAYS AS (firstname || ' ' || lastname))
+INSERT INTO t (id, firstname, lastname) VALUES (1, 'Felix', 'the Cat')
+INSERT INTO t (id, firstname, lastname, fullname) VALUES (2, 'Pink', 'Panther', DEFAULT)
+</programlisting>
+ </informalexample>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>DEFAULT clause</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">DEFAULT</emphasis></simpara>
+
+ <simpara><emphasis>default clause</emphasis></simpara>
+
+ <simpara>A default clause can be used if GENERATED is not specified. If
+ a column has a <literal><default clause></literal> then it is
+ possible to insert a row into the table without specifying a value for
+ the column.</simpara>
+
+ <simpara><literal><default clause> ::= DEFAULT <default
+ option></literal></simpara>
+
+ <simpara><literal><default option> ::= <literal> |
+ <datetime value function> | USER | CURRENT_USER | CURRENT_ROLE |
+ SESSION_USER | SYSTEM_USER | CURRENT_CATALOG | CURRENT_SCHEMA |
+ CURRENT_PATH | NULL</literal></simpara>
+
+ <simpara>The type of the <literal><default option></literal> must
+ match the type of the column.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>CONSTRAINT name and characteristics</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">CONSTRAINT</emphasis></simpara>
+
+ <simpara><emphasis>constraint name and
+ characteristics</emphasis></simpara>
+
+ <simpara><literal><constraint name definition> ::= CONSTRAINT
+ <constraint name></literal></simpara>
+
+ <simpara><literal><constraint characteristics> ::= <constraint
+ check time> [ [ NOT ] DEFERRABLE [ <constraint check time> ]
+ ]</literal></simpara>
+
+ <simpara><literal><constraint check time> ::= INITIALLY DEFERRED |
+ INITIALLY IMMEDIATE</literal></simpara>
+
+ <simpara>Specify the name of a constraint and its characteristics. By
+ default the constraint is <literal>NOT DEFERRABLE</literal> and
+ <literal>INITIALLY IMMEDIATE</literal>. This means the constraint is
+ enforced as soon as a data change statement is executed. If
+ <literal>INITIALLY DEFERRED</literal> is specified, then the constraint
+ is enforced when the session commits. The characteristics must be
+ compatible. The constraint check time can be changed temporarily for an
+ SQL session. HyperSQL does not support deferring constraint enforcement.
+ This feature of the SQL Standard has been criticised because it allows a
+ session to read uncommitted data that violates database integrity
+ constraints but has not yet been checked.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>CONSTRAINT (table constraint)</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">CONSTRAINT</emphasis></simpara>
+
+ <simpara><emphasis>table constraint definition</emphasis></simpara>
+
+ <simpara><literal><table constraint definition> ::= [
+ <constraint name definition> ] <table constraint> [
+ <constraint characteristics> ]</literal></simpara>
+
+ <simpara><literal><table constraint> ::= <unique constraint
+ definition> | <referential constraint definition> | <check
+ constraint definition></literal></simpara>
+
+ <simpara>Three kinds of constraint can be defined on a table: UNIQUE
+ (including PRIMARY KEY), FOREIGN KEY and CHECK. Each kind has its own
+ rules to limit the values that can be specified for different columns in
+ each row of the table.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>UNIQUE constraint</primary>
+ </indexterm>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>PRIMARY KEY constraint</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">UNIQUE</emphasis></simpara>
+
+ <simpara><emphasis>unique constraint definition</emphasis></simpara>
+
+ <simpara><literal><unique constraint definition> ::= <unique
+ specification> <left paren> <unique column list>
+ <right paren> | UNIQUE ( VALUE )</literal></simpara>
+
+ <simpara><literal><unique specification> ::= UNIQUE | PRIMARY
+ KEY</literal></simpara>
+
+ <simpara><literal><unique column list> ::= <column name
+ list></literal></simpara>
+
+ <simpara>A unique constraint is specified on a single column or on
+ multiple columns. On each set of columns taken together, only one UNIQUE
+ constraint can be specified. Each column of a PRIMARY KEY constraint has
+ an implicit NOT NULL constraint.</simpara>
+
+ <simpara>If <literal>UNIQUE( VALUE )</literal> is specified, the
+ constraint created on all columns of the table.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>FOREIGN KEY constraint</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">FOREIGN KEY</emphasis></simpara>
+
+ <simpara><emphasis>referential constraint
+ definition</emphasis></simpara>
+
+ <simpara><literal><referential constraint definition> ::= FOREIGN
+ KEY <left paren> <referencing columns> <right paren>
+ <references specification></literal></simpara>
+
+ <simpara><literal><references specification> ::= REFERENCES
+ <referenced table and columns> [ MATCH <match type> ] [
+ <referential triggered action> ]</literal></simpara>
+
+ <simpara><literal><match type> ::= FULL | PARTIAL |
+ SIMPLE</literal></simpara>
+
+ <simpara><literal><referencing columns> ::= <reference column
+ list></literal></simpara>
+
+ <simpara><literal><referenced table and columns> ::= <table
+ name> [ <left paren> <reference column list> <right
+ paren> ]</literal></simpara>
+
+ <simpara><literal><reference column list> ::= <column name
+ list></literal></simpara>
+
+ <simpara><literal><referential triggered action> ::= <update
+ rule> [ <delete rule> ] | <delete rule> [ <update
+ rule> ]</literal></simpara>
+
+ <simpara><literal><update rule> ::= ON UPDATE <referential
+ action></literal></simpara>
+
+ <simpara><literal><delete rule> ::= ON DELETE <referential
+ action></literal></simpara>
+
+ <simpara><literal><referential action> ::= CASCADE | SET NULL |
+ SET DEFAULT | RESTRICT | NO ACTION</literal></simpara>
+
+ <simpara>A referential constraint allows links to be established between
+ the rows of two tables. The specified list of <literal><referencing
+ columns></literal> corresponds one by one to the columns of the
+ specified list of <literal><referenced columns></literal> in
+ another table (or sometimes in the same table). For each row in the
+ table, a row must exist in the referenced table with equivalent values
+ in the two column lists. There must exist a single unique constraint in
+ the referenced table on all the <literal><referenced
+ columns></literal>.</simpara>
+
+ <simpara>The <literal>[ MATCH match type ]</literal> clause is optional
+ and has an effect only on multi-column foreign keys and only on rows
+ containing at least a NULL in one of the <literal><referencing
+ columns></literal>. If the clause is not specified, MATCH SIMPLE is
+ the default. If <literal>MATCH SIMPLE</literal> is specified, then any
+ NULL means the row can exist (without a corresponding row in the
+ referenced table). If <literal>MATCH FULL</literal> is specified then
+ either all the column values must be NULL or none of them.
+ <literal>MATCH PARTIAL</literal> allows any NULL but the non NULL values
+ must match those of a row in the referenced table. HyperSQL does not
+ support <literal>MATCH PARTIAL</literal>.</simpara>
+
+ <simpara>Referential actions are specified with ON UPDATE and ON DELETE
+ clauses. These actions take place when a row in the referenced table
+ (the parent table) has referencing rows in the referencing table and it
+ is deleted or modified with any SQL statement. The default is NO ACTION.
+ This means the SQL statement that causes the DELETE or UPDATE is
+ terminated with an exception. The RESTRICT option is similar and works
+ exactly the same without deferrable constraints (which are not allowed
+ by HyperSQL). The other three options, CASCADE, SET NULL and SET DEFAULT
+ all allow the DELETE or UPDATE statement to complete. With DELETE
+ statements the CASCADE option results in the referencing rows to be
+ deleted. With UPDATE statements, the changes to the values of the
+ referenced columns are copied to the referencing rows. With both DELETE
+ or UPDATE statement, the SET NULL option results in the columns of the
+ referencing rows to be set to NULL. Similarly, the SET DEFAULT option
+ results in the columns of the referencing rows to be set to their
+ default values.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>CHECK constraint</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">CHECK</emphasis></simpara>
+
+ <simpara><emphasis>check constraint definition</emphasis></simpara>
+
+ <simpara><literal><check constraint definition> ::= CHECK <left
+ paren> <search condition> <right
+ paren></literal></simpara>
+
+ <simpara>A CHECK constraint can exist for a TABLE or for a DOMAIN. The
+ <literal><search condition></literal> evaluates to an SQL BOOLEAN
+ value for each row of the table. Within the <literal><search
+ condition></literal> all columns of the table row can be referenced.
+ For all rows of the table, the <literal><search
+ condition></literal> evaluates to TRUE or UNKNOWN. When a new row is
+ inserted, or an existing row is updated, the <literal><search
+ condition></literal> is evaluated and if it is FALSE, the insert or
+ update fails.</simpara>
+
+ <simpara>A CHECK constraint for a DOMAIN is similar. In its
+ <literal><search condition></literal>, the term VALUE is used to
+ represents the value to which the DOMAIN applies.</simpara>
+
+ <informalexample>
+ <programlisting>CREATE TABLE t (a VARCHAR(20) CHECK (a IS NOT NULL AND CHARACTER_LENGTH(a) > 2))
+</programlisting>
+ </informalexample>
+
+ <simpara>The search condition of a CHECK constraint cannot contain any
+ function that is not deterministic. A check constraint is a data
+ integrity constraint, therefore it must hold with respect to the rest of
+ the data in the database. It cannot use values that are temporal or
+ ephemeral. For example CURRENT_USER is a function that returns different
+ values depending on who is using the database, or CURRENT_DATE changes
+ day-to-day. Some temporal expressions are retrospectively deterministic
+ and are allowed in check constraints. For example, (CHECK VALUE <
+ CURRENT_DATE) is valid, because CURRENT_DATE will not move backwards in
+ time, but (CHECK VALUE > CURRENT_DATE) is not acceptable.</simpara>
+
+ <simpara>If you want to enforce the condition that a date value that is
+ inserted into the database belongs to the future (at the time of
+ insertion), or any similar constraint, then use a TRIGGER with the
+ desired condition.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>SET TABLE read-write property</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">SET TABLE
+ writeability</emphasis></simpara>
+
+ <simpara><emphasis>set table write property
+ (HyperSQL)</emphasis></simpara>
+
+ <simpara><literal><set table read only statement> ::= SET TABLE
+ <table name> { READ ONLY | READ WRITE }</literal></simpara>
+
+ <simpara>Set the writeability property of a table. Tables are writable
+ by default. This statement can be used to change the property between
+ <literal>READ ONLY</literal> and <literal>READ WRITE</literal>. This is
+ a feature of HyperSQL.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>SET TABLE SOURCE</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">SET TABLE SOURCE</emphasis></simpara>
+
+ <simpara><emphasis>set table source statement</emphasis></simpara>
+
+ <simpara><literal><set table source statement> ::= SET TABLE
+ <table name> SOURCE <file and options>
+ [DESC]</literal></simpara>
+
+ <simpara><literal><file and options>::= <doublequote>
+ <file path> [<semicolon> <property>...]
+ <doublequote> </literal></simpara>
+
+ <simpara>Set the text source for a text table. This statement cannot be
+ used for tables that are not defined as TEXT TABLE.</simpara>
+
+ <variablelist>
+ <title>Supported Properties</title>
+
+ <varlistentry>
+ <term>quoted = { true | false }</term>
+
+ <listitem>
+ <para>default is true. If false, treats double quotes as normal
+ characters</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>all_quoted = { true | false }</term>
+
+ <listitem>
+ <para>default is false. If true, adds double quotes around all
+ fields.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>encoding = <encoding name></term>
+
+ <listitem>
+ <para>character encoding for text and character fields, for
+ example, encoding=UTF-8</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ignore_first = { true | false }</term>
+
+ <listitem>
+ <para>default is false. If true ignores the first line of the
+ file</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>cache_scale= <numeric value></term>
+
+ <listitem>
+ <para>exponent to calculate rows of the text file in cache.
+ Default is 8, equivalent to nearly 800 rows</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>cache_size_scale = <numeric value>r</term>
+
+ <listitem>
+ <para>exponent to calculate average size of each row in cache.
+ Default is 8, equivalent to 256 bytes per row.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>fs = <unquoted character></term>
+
+ <listitem>
+ <para>field separator</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>vs = <unquoted character></term>
+
+ <listitem>
+ <para>varchar separator</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <variablelist>
+ <title>Special indicators for HyperSQL Text Table separators</title>
+
+ <varlistentry>
+ <term>\semi</term>
+
+ <listitem>
+ <para>semicolon</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>\quote</term>
+
+ <listitem>
+ <para>quote</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>\space</term>
+
+ <listitem>
+ <para>space character</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>\apos</term>
+
+ <listitem>
+ <para>apostrophe</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>\n</term>
+
+ <listitem>
+ <para>newline - Used as an end anchor (like $ in regular
+ expressions)</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>\r</term>
+
+ <listitem>
+ <para>carriage return</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>\t</term>
+
+ <listitem>
+ <para>tab</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>\\</term>
+
+ <listitem>
+ <para>backslash</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>\u####</term>
+
+ <listitem>
+ <para>a Unicode character specified in hexadecimal</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <simpara>In the example below, the text source of the table is set to
+ "myfile", the field separator to the pipe symbol, and the long varchar
+ separator to the tilde symbol.</simpara>
+
+ <programlisting> SET TABLE mytable SOURCE 'myfile;fs=|;vs=.;lvs=~'</programlisting>
+
+ <simpara>Only a user with the DBA role can execute this
+ statement.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>SET TABLE SOURCE HEADER</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">SET TABLE SOURCE
+ HEADER</emphasis></simpara>
+
+ <simpara><emphasis>set table source header
+ statement</emphasis></simpara>
+
+ <simpara><literal><set table source header statement> ::= SET
+ TABLE <table name> SOURCE HEADER <header
+ string></literal></simpara>
+
+ <simpara>Set the header for the text source for a text table. If this
+ command is used, the <literal><header string></literal> is used as
+ the first line of the source file of the text table. This line is not
+ part of the table data. Only a user with the DBA role can execute this
+ statement.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>SET TABLE SOURCE on-off</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">SET TABLE SOURCE
+ on-off</emphasis></simpara>
+
+ <simpara><emphasis>set table source on-off
+ statement</emphasis></simpara>
+
+ <simpara><literal><set table source on-off statement> ::= SET
+ TABLE <table name> SOURCE { ON | OFF } </literal></simpara>
+
+ <simpara>Attach or detach a text table from its text source. This
+ command does not change the properties or the name of the file that is
+ the source of a text table. When OFF is specified, the command detaches
+ the table from its source and closes the file for the source. In this
+ state, it is not possible to read or write to the table. This allows the
+ user to replace the file with a different file, or delete it. When ON is
+ specified, the source file is read. Only a user with the DBA role can
+ execute this statement</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>ALTER TABLE</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">ALTER TABLE</emphasis></simpara>
+
+ <simpara><emphasis>alter table statement</emphasis></simpara>
+
+ <simpara><literal><alter table statement> ::= ALTER TABLE
+ <table name> <alter table action></literal></simpara>
+
+ <simpara><literal><alter table action> ::= <add column
+ definition> | <alter column definition> | <drop column
+ definition> | <add table constraint definition> | <drop
+ table constraint definition></literal></simpara>
+
+ <simpara>Change the definition of a table. Specific types of this
+ statement are covered below.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>ADD COLUMN</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">ADD COLUMN</emphasis></simpara>
+
+ <simpara><emphasis>add column definition</emphasis></simpara>
+
+ <simpara><literal><add column definition> ::= ADD [ COLUMN ]
+ <column definition> [ BEFORE <other column name>
+ ]</literal></simpara>
+
+ <simpara>Add a column to an existing table. The <literal><column
+ definition></literal> is specified the same way as it is used in
+ <literal><table definition></literal>. HyperSQL allows the use of
+ <literal>[ BEFORE <other column name> ]</literal> to specify at
+ which position the new column is added to the table.</simpara>
+
+ <simpara>If the table contains rows, the new column must have a
+ <literal><default clause></literal> or use one of the forms of
+ GENERATED. The column values for each row is then filled with the result
+ of the <literal><default clause></literal> or the generated
+ value.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>ALTER COLUMN</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">ALTER COLUMN</emphasis></simpara>
+
+ <simpara><emphasis>alter column definition</emphasis></simpara>
+
+ <simpara><literal><alter column definition> ::= ALTER [ COLUMN ]
+ <column name> <alter column action></literal></simpara>
+
+ <simpara><literal><alter column action> ::= <set column default
+ clause> | <drop column default clause> | <alter column data
+ type clause> | <alter identity column specification> |
+ <alter column nullability> | <alter column
+ name></literal></simpara>
+
+ <simpara>Change a column and its definition. Specific types of this
+ statement are covered below. See also the RENAME statement
+ above.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>SET DEFAULT</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">SET DEFAULT</emphasis></simpara>
+
+ <simpara><emphasis>set column default clause</emphasis></simpara>
+
+ <simpara><literal><set column default clause> ::= SET <default
+ clause></literal></simpara>
+
+ <simpara>Set the default clause for a column. This can be used if the
+ column is not defined as GENERATED.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>DROP DEFAULT (table)</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">DROP DEFAULT</emphasis></simpara>
+
+ <simpara><emphasis>drop column default clause</emphasis></simpara>
+
+ <simpara><literal><drop column default clause> ::= DROP
+ DEFAULT</literal></simpara>
+
+ <simpara>Drop the default clause from a column.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>SET DATA TYPE</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">SET DATA TYPE</emphasis></simpara>
+
+ <simpara><emphasis>alter column data type clause</emphasis></simpara>
+
+ <simpara><literal><alter column data type clause> ::= SET DATA
+ TYPE <data type></literal></simpara>
+
+ <simpara>Change the declared type of a column. The (proposed) SQL
+ Standard allows only changes to type properties such as maximum length,
+ precision, or scale, and only changes that cause the property to
+ enlarge. HyperSQL allows changing the type if all the existing values
+ can be cast into the new type without string truncation or loss of
+ significant digits.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>alter identity column</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">alter identity
+ column</emphasis></simpara>
+
+ <simpara><emphasis>alter identity column
+ specification</emphasis></simpara>
+
+ <simpara><literal><alter identity column specification> ::=
+ <alter identity column option>...</literal></simpara>
+
+ <simpara><literal><alter identity column option> ::= <alter
+ sequence generator restart option> | SET <basic sequence generator
+ option></literal></simpara>
+
+ <simpara>Change the properties of an identity column. This command is
+ similar to the commands used for changing the properties of named
+ SEQUENCE objects discussed in this section.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>alter column nullability</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">SET NULL</emphasis></simpara>
+
+ <simpara><emphasis>alter column nullability</emphasis></simpara>
+
+ <simpara><literal><alter column nullability> ::= SET
+ NULL</literal></simpara>
+
+ <simpara>Removes a NOT NULL constraint from a column. This option is
+ specific to HyperSQL</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>DROP COLUMN</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">DROP COLUMN</emphasis></simpara>
+
+ <simpara><emphasis>drop column definition</emphasis></simpara>
+
+ <simpara><literal><drop column definition> ::= DROP [ COLUMN ]
+ <column name> <drop behavior></literal></simpara>
+
+ <simpara>Destroy a column of a base table. The <literal><drop
+ behavior></literal> is either <literal>RESTRICT</literal> or
+ <literal>CASCADE</literal>. If the column is referenced in a table
+ constraint that references other columns as well as this column, or if
+ the column is referenced in a VIEW, or the column is referenced in a
+ TRIGGER, then the statement will fail if <literal>RESTRICT</literal> is
+ specified. If <literal>CASCADE</literal> is specified, then any
+ CONSTRAINT, VIEW or TRIGGER object that references the column is dropped
+ with a cascading effect.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>ADD CONSTRAINT</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">ADD CONSTRAINT</emphasis></simpara>
+
+ <simpara><emphasis>add table constraint definition</emphasis></simpara>
+
+ <simpara><literal><add table constraint definition> ::= ADD
+ <table constraint definition></literal></simpara>
+
+ <simpara>Add a constraint to a table. The existing rows of the table
+ must conform to the added constraint, otherwise the statement will not
+ succeed.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>DROP CONSTRAINT</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">DROP CONSTRAINT</emphasis></simpara>
+
+ <simpara><emphasis>drop table constraint definition</emphasis></simpara>
+
+ <simpara><literal><drop table constraint definition> ::= DROP
+ CONSTRAINT <constraint name> <drop
+ behavior></literal></simpara>
+
+ <simpara>Destroy a constraint on a table. The <literal><drop
+ behavior></literal> has an effect only on UNIQUE and PRIMARY KEY
+ constraints. If such a constraint is referenced by a FOREIGN KEY
+ constraint, the FOREIGN KEY constraint will be dropped if
+ <literal>CASCADE</literal> is specified. If the columns of such a
+ constraint are used in a GROUP BY clause in the query expression of a
+ VIEW or another kind of schema object, and a functional dependency
+ relationship exists between these columns and the other columns in that
+ query expression, then the VIEW or other schema object will be dropped
+ when <literal>CASCADE</literal> is specified.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>DROP TABLE</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">DROP TABLE</emphasis></simpara>
+
+ <simpara><emphasis>drop table statement</emphasis></simpara>
+
+ <simpara><literal><drop table statement> ::= DROP TABLE [ IF
+ EXISTS ] <table name> [ IF EXISTS ] <drop
+ behavior></literal></simpara>
+
+ <simpara>Destroy a table. The default drop behaviour is RESTRICT and
+ will cause the statement to fail if there is any view or foreign key
+ constraint that references the table. If <literal><drop
+ behavior></literal> is <literal>CASCADE</literal>, it causes all
+ schema objects that reference the table to drop. Referencing views are
+ dropped. In the case of foreign key constraints that reference the
+ table, the constraint is dropped, rather than the TABLE or DOMAIN that
+ contains it.</simpara>
+ </section>
+
+ <section>
+ <title>View Creation and Manipulation</title>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>CREATE VIEW</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">CREATE VIEW</emphasis></simpara>
+
+ <simpara><emphasis>view definition</emphasis></simpara>
+
+ <simpara><literal><view definition> ::= CREATE [ RECURSIVE ] VIEW
+ <table name> <view specification> AS <query
+ expression> [ WITH [ CASCADED | LOCAL ] CHECK OPTION
+ ]</literal></simpara>
+
+ <simpara><literal><view specification> ::= [ <left paren>
+ <view column list> <right paren> ]</literal></simpara>
+
+ <simpara><literal><view column list> ::= <column name
+ list></literal></simpara>
+
+ <simpara>Define a view. The <literal><query expression></literal>
+ is a SELECT or similar statement. The <literal><view column
+ list></literal> is the list of unique names for the columns of the
+ view. The number of columns in the <literal><view column
+ list></literal> must match the number of columns returned by the
+ <literal><query expression></literal>. If <literal><view column
+ list></literal> is not specified, then the columns of the
+ <literal><query expression></literal> should have unique names and
+ are used as the names of the view column.</simpara>
+
+ <simpara>Some views are updatable. As covered elsewhere, an updatable
+ view is based on a single table or updatable view. For updatable views,
+ the optional <literal>CHECK OPTION</literal> clause can be specified. If
+ this option is specified, then if a row of the view is updated or a new
+ row is inserted into the view, then it should contain such values that
+ the row would be included in the view after the change. If <literal>WITH
+ CASCADED CHECK OPTION</literal> is specified, then if the
+ <literal><query expression></literal> of the view references
+ another view, then the search condition of the underlying view should
+ also be satisfied by the update or insert operation.</simpara>
+
+ <simpara>More on recursive...</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>DROP VIEW</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">DROP VIEW</emphasis></simpara>
+
+ <simpara><emphasis>drop view statement</emphasis></simpara>
+
+ <simpara><literal><drop view statement> ::= DROP VIEW [ IF EXISTS
+ ] <table name> [ IF EXISTS ] <drop
+ behavior></literal></simpara>
+
+ <simpara>Destroy a view. The <literal><drop behavior></literal> is
+ similar to dropping a table.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>ALTER view</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">ALTER VIEW</emphasis></simpara>
+
+ <simpara><emphasis>alter view statement</emphasis></simpara>
+
+ <simpara><literal><alter view statement> ::= ALTER VIEW <table
+ name> <view specification> AS <query expression> [ WITH [
+ CASCADED | LOCAL ] CHECK OPTION ]</literal></simpara>
+
+ <simpara>Alter a view. The statement is otherwise identical to CREATE
+ VIEW. The new definition replaces the old. If there are database objects
+ such as routines or views that reference the view, then these objects
+ are recompiled with the new view definition. If the new definition is
+ not compatible, the statement fails.</simpara>
+ </section>
+
+ <section>
+ <title>Domain Creation and Manipulation</title>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>CREATE DOMAIN</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">CREATE DOMAIN</emphasis></simpara>
+
+ <simpara><emphasis>domain definition</emphasis></simpara>
+
+ <simpara><literal><domain definition> ::= CREATE DOMAIN <domain
+ name> [ AS ] <predefined type> [ <default clause> ] [
+ <domain constraint>... ] [ <collate clause>
+ ]</literal></simpara>
+
+ <simpara><literal><domain constraint> ::= [ <constraint name
+ definition> ] <check constraint definition> [ <constraint
+ characteristics> ]</literal></simpara>
+
+ <simpara>Define a domain. Although a DOMAIN is not strictly a type in
+ the SQL Standard, it can be informally considered as a type. A DOMAIN is
+ based on a <literal><predefined type></literal>, which is a base
+ type defined by the Standard. It can have a <literal><default
+ clause></literal>, similar to a column default clause. It can also
+ have one or more CHECK constraints which limit the values that can be
+ assigned to a column or variable that has the DOMAIN as its
+ type.</simpara>
+
+ <informalexample>
+ <programlisting>CREATE DOMAIN valid_string AS VARCHAR(20) DEFAULT 'NO VALUE' CHECK (value IS NOT NULL AND CHARACTER_LENGTH(value) > 2)
+</programlisting>
+ </informalexample>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>ALTER DOMAIN</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">ALTER DOMAIN</emphasis></simpara>
+
+ <simpara><emphasis>alter domain statement</emphasis></simpara>
+
+ <simpara><literal><alter domain statement> ::= ALTER DOMAIN
+ <domain name> <alter domain action></literal></simpara>
+
+ <simpara><literal><alter domain action> ::= <set domain default
+ clause> | <drop domain default clause> | <add domain
+ constraint definition> | <drop domain constraint
+ definition></literal></simpara>
+
+ <simpara>Change a domain and its definition.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>SET DOMAIN DEFAULT</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">SET DEFAULT</emphasis></simpara>
+
+ <simpara><emphasis>set domain default clause</emphasis></simpara>
+
+ <simpara><literal><set domain default clause> ::= SET <default
+ clause></literal></simpara>
+
+ <simpara>Set the default value in a domain.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>DROP DOMAIN DEFAULT</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">DROP DEFAULT</emphasis></simpara>
+
+ <simpara><emphasis>drop domain default clause</emphasis></simpara>
+
+ <simpara><literal><drop domain default clause> ::= DROP
+ DEFAULT</literal></simpara>
+
+ <simpara>Remove the default clause of a domain.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>ADD DOMAIN CONSTRAINT</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">ADD CONSTRAINT</emphasis></simpara>
+
+ <simpara><emphasis>add domain constraint definition</emphasis></simpara>
+
+ <simpara><literal><add domain constraint definition> ::= ADD
+ <domain constraint></literal></simpara>
+
+ <simpara>Add a constraint to a domain.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>DROP DOMAIN CONSTRAINT</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">DROP CONSTRAINT</emphasis></simpara>
+
+ <simpara><emphasis>drop domain constraint
+ definition</emphasis></simpara>
+
+ <simpara><literal><drop domain constraint definition> ::= DROP
+ CONSTRAINT <constraint name></literal></simpara>
+
+ <simpara>Destroy a constraint on a domain. If the <literal><drop
+ behavior></literal> is <literal>CASCADE</literal>, and the constraint
+ is a UNIQUE constraint which is referenced by a FOREIGN KEY constraint
+ on another table, then the FOREIGN KEY constraint is also
+ dropped.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>DROP DOMAIN</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">DROP DOMAIN</emphasis></simpara>
+
+ <simpara><emphasis>drop domain statement</emphasis></simpara>
+
+ <simpara><literal><drop domain statement> ::= DROP DOMAIN
+ <domain name> <drop behavior></literal></simpara>
+
+ <simpara>Destroy a domain. If <literal><drop behavior></literal>
+ is <literal>CASCADE</literal>, it works differently from most other
+ objects. If a table features a column of the specified DOMAIN, the
+ column survives and inherits the DEFAULT CLAUSE, and the CHECK
+ CONSTRAINT of the DOMAIN.</simpara>
+ </section>
+
+ <section>
+ <title>Trigger Creation</title>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>CREATE TRIGGER</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">CREATE TRIGGER</emphasis></simpara>
+
+ <simpara><emphasis>trigger definition</emphasis></simpara>
+
+ <simpara><literal><trigger definition> ::= CREATE TRIGGER
+ <trigger name> <trigger action time> <trigger event>
+ ON <table name> [ REFERENCING <transition table or variable
+ list> ] <triggered action></literal></simpara>
+
+ <simpara><literal><trigger action time> ::= BEFORE | AFTER |
+ INSTEAD OF</literal></simpara>
+
+ <simpara><literal><trigger event> ::= INSERT | DELETE | UPDATE [
+ OF <trigger column list> ]</literal></simpara>
+
+ <simpara><literal><trigger column list> ::= <column name
+ list></literal></simpara>
+
+ <simpara><literal><triggered action> ::= [ FOR EACH { ROW |
+ STATEMENT } ] [ <triggered when clause> ] <triggered SQL
+ statement></literal></simpara>
+
+ <simpara><literal><triggered when clause> ::= WHEN <left
+ paren> <search condition> <right
+ paren></literal></simpara>
+
+ <simpara><literal><triggered SQL statement> ::= <SQL procedure
+ statement> | BEGIN ATOMIC { <SQL procedure statement>
+ <semicolon> }... END | [QUEUE <integer literal>] [NOWAIT]
+ CALL <HSQLDB trigger class FQN></literal></simpara>
+
+ <simpara><literal><transition table or variable list> ::=
+ <transition table or variable>...</literal></simpara>
+
+ <simpara><literal><transition table or variable> ::= OLD [ ROW ] [
+ AS ] <old transition variable name> | NEW [ ROW ] [ AS ] <new
+ transition variable name> | OLD TABLE [ AS ] <old transition table
+ name> | NEW TABLE [ AS ] <new transition table
+ name></literal></simpara>
+
+ <simpara><literal><old transition table name> ::= <transition
+ table name></literal></simpara>
+
+ <simpara><literal><new transition table name> ::= <transition
+ table name></literal></simpara>
+
+ <simpara><literal><transition table name> ::=
+ <identifier></literal></simpara>
+
+ <simpara><literal><old transition variable name> ::=
+ <correlation name></literal></simpara>
+
+ <simpara><literal><new transition variable name> ::=
+ <correlation name></literal></simpara>
+
+ <simpara>Trigger definition is a relatively complex statement. The
+ combination of <literal><trigger action time></literal> and
+ <literal><trigger event></literal> determines the type of the
+ trigger. Examples include BEFORE DELETE, AFTER UPDATE, INSTEAD OF
+ INSERT. If the optional <literal>[ OF <trigger column list>
+ ]</literal> is specified for an UPDATE trigger, then the trigger is
+ activated only if one of the columns that is in the <literal><trigger
+ column list></literal> is specified in the UPDATE statement that
+ activates the trigger.</simpara>
+
+ <simpara>If a trigger is <literal>FOR EACH ROW</literal>, which is the
+ default option, then the trigger is activated for each row of the table
+ that is affected by the execution of an SQL statement. Otherwise, it is
+ activated once only per statement execution. In the first case, there is
+ a before and after state for each row. For UPDATE triggers, both before
+ and after states exist, representing the row before the update, and
+ after the update. For DELETE, triggers, there is only a before state.
+ For INSERT triggers, there is only an after state. If a trigger is
+ <literal>FOR EACH STATEMENT</literal>, then a transient table is created
+ containing all the rows for the before state and another transient table
+ is created for the after state.</simpara>
+
+ <simpara>The <literal>[ REFERENCING <transition table or variable>
+ ]</literal> is used to give a name to the before and after data row or
+ table. This name can be referenced in the <literal><SQL procedure
+ statement></literal> to access the data.</simpara>
+
+ <simpara>The optional <literal><triggered when clause></literal>
+ is a search condition, similar to the search condition of a DELETE or
+ UPDATE statement. If the search condition is not TRUE for a row, then
+ the trigger is not activated for that row.</simpara>
+
+ <simpara>The <literal><SQL procedure statement></literal> is
+ limited to INSERT, DELETE, UPDATE and MERGE statements.</simpara>
+
+ <simpara>The <literal><HSQLDB trigger class FQN></literal> is a
+ delimited identifier that contains the fully qualified name of a Java
+ class that implements the <classname>org.hsqldb.Trigger</classname>
+ interface.</simpara>
+
+ <simpara>Early releases of HyperSQL version 2.0 do not allow the use of
+ OLD TABLE or NEW TABLE in statement level trigger definitions.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>DROP TRIGGER</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">DROP TRIGGER</emphasis></simpara>
+
+ <simpara><emphasis>drop trigger statement</emphasis></simpara>
+
+ <simpara><literal><drop trigger statement> ::= DROP TRIGGER
+ <trigger name></literal></simpara>
+
+ <simpara>Destroy a trigger.</simpara>
+ </section>
+
+ <section>
+ <title>Routine Creation</title>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>schema routine</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">schema routine</emphasis></simpara>
+
+ <simpara><emphasis>SQL-invoked routine</emphasis></simpara>
+
+ <simpara><literal><SQL-invoked routine> ::= <schema
+ routine></literal></simpara>
+
+ <simpara><literal><schema routine> ::= <schema procedure> |
+ <schema function></literal></simpara>
+
+ <simpara><literal><schema procedure> ::= CREATE <SQL-invoked
+ procedure></literal></simpara>
+
+ <simpara><literal><schema function> ::= CREATE <SQL-invoked
+ function></literal></simpara>
+
+ <simpara><literal><SQL-invoked procedure> ::= PROCEDURE <schema
+ qualified routine name> <SQL parameter declaration list>
+ <routine characteristics> <routine body></literal></simpara>
+
+ <simpara><literal><SQL-invoked function> ::= { <function
+ specification> | <method specification designator> }
+ <routine body></literal></simpara>
+
+ <simpara><literal><SQL parameter declaration list> ::= <left
+ paren> [ <SQL parameter declaration> [ { <comma> <SQL
+ parameter declaration> }... ] ] <right
+ paren></literal></simpara>
+
+ <simpara><literal><SQL parameter declaration> ::= [ <parameter
+ mode> ] [ <SQL parameter name> ] <parameter type> [
+ RESULT ]</literal></simpara>
+
+ <simpara><literal><parameter mode> ::= IN | OUT |
+ INOUT</literal></simpara>
+
+ <simpara><literal><parameter type> ::= <data
+ type></literal></simpara>
+
+ <simpara><literal><function specification> ::= FUNCTION <schema
+ qualified routine name> <SQL parameter declaration list>
+ <returns clause> <routine characteristics> [ <dispatch
+ clause> ]</literal></simpara>
+
+ <simpara><literal><method specification designator> ::= SPECIFIC
+ METHOD <specific method name> | [ INSTANCE | STATIC | CONSTRUCTOR
+ ] METHOD <method name> <SQL parameter declaration list> [
+ <returns clause> ] FOR <schema-resolved user-defined type
+ name></literal></simpara>
+
+ <simpara><literal><routine characteristics> ::= [ <routine
+ characteristic>... ]</literal></simpara>
+
+ <simpara><literal><routine characteristic> ::= <language
+ clause> | <parameter style clause> | SPECIFIC <specific
+ name> | <deterministic characteristic> | <SQL-data access
+ indication> | <null-call clause> | <returned result sets
+ characteristic> | <savepoint level
+ indication></literal></simpara>
+
+ <simpara><literal><savepoint level indication> ::= NEW SAVEPOINT
+ LEVEL | OLD SAVEPOINT LEVEL</literal></simpara>
+
+ <simpara><literal><returned result sets characteristic> ::=
+ DYNAMIC RESULT SETS <maximum returned result
+ sets></literal></simpara>
+
+ <simpara><literal><parameter style clause> ::= PARAMETER STYLE
+ <parameter style></literal></simpara>
+
+ <simpara><literal><dispatch clause> ::= STATIC
+ DISPATCH</literal></simpara>
+
+ <simpara><literal><returns clause> ::= RETURNS <returns
+ type></literal></simpara>
+
+ <simpara><literal><returns type> ::= <returns data type> [
+ <result cast> ] | <returns table type></literal></simpara>
+
+ <simpara><literal><returns table type> ::= TABLE <table
+ function column list></literal></simpara>
+
+ <simpara><literal><table function column list> ::= <left
+ paren> <table function column list element> [ { <comma>
+ <table function column list element> }... ] <right
+ paren></literal></simpara>
+
+ <simpara><literal><table function column list element> ::=
+ <column name> <data type></literal></simpara>
+
+ <simpara><literal><result cast> ::= CAST FROM <result cast from
+ type></literal></simpara>
+
+ <simpara><literal><result cast from type> ::= <data type> [
+ <locator indication> ]</literal></simpara>
+
+ <simpara><literal><returns data type> ::= <data type> [
+ <locator indication> ]</literal></simpara>
+
+ <simpara><literal><routine body> ::= <SQL routine spec> |
+ <external body reference></literal></simpara>
+
+ <simpara><literal><SQL routine spec> ::= [ <rights clause> ]
+ <SQL routine body></literal></simpara>
+
+ <simpara><literal><rights clause> ::= SQL SECURITY INVOKER | SQL
+ SECURITY DEFINER</literal></simpara>
+
+ <simpara><literal><SQL routine body> ::= <SQL procedure
+ statement></literal></simpara>
+
+ <simpara><literal><external body reference> ::= EXTERNAL [ NAME
+ <external routine name> ] [ <parameter style clause>
+ ]</literal></simpara>
+
+ <simpara><literal><parameter style> ::= SQL |
+ GENERAL</literal></simpara>
+
+ <simpara><literal><deterministic characteristic> ::= DETERMINISTIC
+ | NOT DETERMINISTIC</literal></simpara>
+
+ <simpara><literal><SQL-data access indication> ::= NO SQL |
+ CONTAINS SQL | READS SQL DATA | MODIFIES SQL DATA</literal></simpara>
+
+ <simpara><literal><null-call clause> ::= RETURNS NULL ON NULL
+ INPUT | CALLED ON NULL INPUT</literal></simpara>
+
+ <simpara><literal><maximum returned result sets> ::= <unsigned
+ integer></literal></simpara>
+
+ <simpara>Define an SQL-invoked routine.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>ALTER routine</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">ALTER routine</emphasis></simpara>
+
+ <simpara><emphasis>alter routine statement</emphasis></simpara>
+
+ <simpara><literal><alter routine statement> ::= ALTER <specific
+ routine designator> <alter routine characteristics> <alter
+ routine behavior></literal></simpara>
+
+ <simpara><literal><alter routine characteristics> ::= <alter
+ routine characteristic>...</literal></simpara>
+
+ <simpara><literal><alter routine characteristic> ::= <language
+ clause> | <parameter style clause> | <SQL-data access
+ indication> | <null-call clause> | <returned result sets
+ characteristic> | NAME <external routine
+ name></literal></simpara>
+
+ <simpara><literal><alter routine behavior> ::=
+ RESTRICT</literal></simpara>
+
+ <simpara>Alter a characteristic of an SQL-invoked routine. Early
+ releases of HyperSQL 2.0 may not support this statement.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>DROP routine</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">DROP</emphasis></simpara>
+
+ <simpara><emphasis>drop routine statement</emphasis></simpara>
+
+ <simpara><literal><drop routine statement> ::= DROP <specific
+ routine designator> <drop behavior></literal></simpara>
+
+ <simpara>Destroy an SQL-invoked routine.</simpara>
+ </section>
+
+ <section>
+ <title>Sequence Creation</title>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>CREATE SEQUENCE</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">CREATE SEQUENCE</emphasis></simpara>
+
+ <simpara><emphasis>sequence generator definition</emphasis></simpara>
+
+ <simpara><literal><sequence generator definition> ::= CREATE
+ SEQUENCE <sequence generator name> [ <sequence generator
+ options> ]</literal></simpara>
+
+ <simpara><literal><sequence generator options> ::= <sequence
+ generator option> ...</literal></simpara>
+
+ <simpara><literal><sequence generator option> ::= <sequence
+ generator data type option> | <common sequence generator
+ options></literal></simpara>
+
+ <simpara><literal><common sequence generator options> ::=
+ <common sequence generator option> ...</literal></simpara>
+
+ <simpara><literal><common sequence generator option> ::=
+ <sequence generator start with option> | <basic sequence
+ generator option></literal></simpara>
+
+ <simpara><literal><basic sequence generator option> ::=
+ <sequence generator increment by option> | <sequence generator
+ maxvalue option> | <sequence generator minvalue option> |
+ <sequence generator cycle option></literal></simpara>
+
+ <simpara><literal><sequence generator data type option> ::= AS
+ <data type></literal></simpara>
+
+ <simpara><literal><sequence generator start with option> ::= START
+ WITH <sequence generator start value></literal></simpara>
+
+ <simpara><literal><sequence generator start value> ::= <signed
+ numeric literal></literal></simpara>
+
+ <simpara><literal><sequence generator increment by option> ::=
+ INCREMENT BY <sequence generator increment></literal></simpara>
+
+ <simpara><literal><sequence generator increment> ::= <signed
+ numeric literal></literal></simpara>
+
+ <simpara><literal><sequence generator maxvalue option> ::=
+ MAXVALUE <sequence generator max value> | NO
+ MAXVALUE</literal></simpara>
+
+ <simpara><literal><sequence generator max value> ::= <signed
+ numeric literal></literal></simpara>
+
+ <simpara><literal><sequence generator minvalue option> ::=
+ MINVALUE <sequence generator min value> | NO
+ MINVALUE</literal></simpara>
+
+ <simpara><literal><sequence generator min value> ::= <signed
+ numeric literal></literal></simpara>
+
+ <simpara><literal><sequence generator cycle option> ::= CYCLE | NO
+ CYCLE</literal></simpara>
+
+ <simpara>Define a named sequence generator. A SEQUENCE object generates
+ a sequence of integers according to the specified rules. The simple
+ definition without the options defines a sequence of numbers in INTEGER
+ type starting at 1 and incrementing by 1. By default the
+ <literal>CYCLE</literal> property is set and the minimum and maximum
+ limits are the minimum and maximum limits of the type of returned
+ values. There are self-explanatory options for changing various
+ properties of the sequence. The <literal>MAXVALUE</literal> and
+ <literal>MINVALUE</literal> specify the upper and lower limits. If
+ <literal>CYCLE</literal> is specified, after the sequence returns the
+ highest or lowest value in range, the next value will respectively be
+ the lowest or highest value in range. If <literal>NO CYCLE</literal> is
+ specified, the use of the sequence generator results in an error once
+ the limit has been reached.</simpara>
+
+ <simpara>The integer types: SMALLINT, INTEGER, BIGINT, DECIMAL and
+ NUMERIC can be used as the type of the sequence. DECIMAL and NUMERIC
+ types must have a scale of 0 and a precision not exceeding 18.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>ALTER SEQUENCE</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">ALTER SEQUENCE</emphasis></simpara>
+
+ <simpara><emphasis>alter sequence generator
+ statement</emphasis></simpara>
+
+ <simpara><literal><alter sequence generator statement> ::= ALTER
+ SEQUENCE <sequence generator name> <alter sequence generator
+ options></literal></simpara>
+
+ <simpara><literal><alter sequence generator options> ::= <alter
+ sequence generator option>...</literal></simpara>
+
+ <simpara><literal><alter sequence generator option> ::= <alter
+ sequence generator restart option> | <basic sequence generator
+ option></literal></simpara>
+
+ <simpara><literal><alter sequence generator restart option> ::=
+ RESTART [ WITH <sequence generator restart value>
+ ]</literal></simpara>
+
+ <simpara><literal><sequence generator restart value> ::=
+ <signed numeric literal></literal></simpara>
+
+ <simpara>Change the definition of a named sequence generator. The same
+ options that are used in the definition of the SEQUENCE can be used to
+ alter it. The exception is the option for the start value which is
+ <literal>RESTART WITH</literal> for the ALTER SEQUENCE
+ statement..</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>DROP SEQUENCE</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">DROP SEQUENCE</emphasis></simpara>
+
+ <simpara><emphasis>drop sequence generator
+ statement</emphasis></simpara>
+
+ <simpara><literal><drop sequence generator statement> ::= DROP
+ SEQUENCE [ IF EXISTS ] <sequence generator name> [ IF EXISTS ]
+ <drop behavior></literal></simpara>
+
+ <simpara>Destroy an external sequence generator. If the
+ <literal><drop behavior></literal> is <literal>CASCADE</literal>,
+ then all objects that reference the sequence are dropped. These objects
+ can be VIEW, ROUTINE or TRIGGER objects.</simpara>
+
+ <!-- From Foundation chapt. 13 -->
+ </section>
+
+ <section>
+ <title>SQL Procedure Statement</title>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>SQL procedure statement</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">SQL procedure
+ statement</emphasis></simpara>
+
+ <simpara><emphasis>SQL procedure statement</emphasis></simpara>
+
+ <simpara>The definition of CREATE TRIGGER and CREATE PROCEDURE
+ statements refers to <SQL procedure statement>. The definition of
+ this element is given below. However, only a subset of these statements
+ are allowed in trigger or routine definition.</simpara>
+
+ <simpara><literal><SQL procedure statement> ::= <SQL executable
+ statement></literal></simpara>
+
+ <simpara><literal><SQL executable statement> ::= <SQL schema
+ statement> | <SQL data statement> | <SQL control
+ statement> | <SQL transaction statement> | <SQL connection
+ statement> | <SQL session statement> | <SQL diagnostics
+ statement> | <SQL dynamic statement></literal></simpara>
+
+ <simpara><literal><SQL schema statement> ::= <SQL schema
+ definition statement> | <SQL schema manipulation
+ statement></literal></simpara>
+
+ <simpara><literal><SQL schema definition statement> ::= <schema
+ definition> | <table definition> | <view definition> |
+ <SQL-invoked routine> | <grant statement> | <role
+ definition> | <domain definition> | <character set
+ definition> | <collation definition> | <transliteration
+ definition> | <assertion definition> | <trigger
+ definition> | <user-defined type definition> | <user-defined
+ cast definition> | <user-defined ordering definition> |
+ <transform definition> | <sequence generator
+ definition></literal></simpara>
+
+ <simpara><literal><SQL schema manipulation statement> ::= <drop
+ schema statement> | <alter table statement> | <drop table
+ statement> | <drop view statement> | <alter routine
+ statement> | <drop routine statement> | <drop user-defined
+ cast statement> | <revoke statement> | <drop role
+ statement> | <alter domain statement> | <drop domain
+ statement> | <drop character set statement> | <drop
+ collation statement> | <drop transliteration statement> |
+ <drop assertion statement> | <drop trigger statement> |
+ <alter type statement> | <drop data type statement> |
+ <alter sequence generator statement> | <drop sequence generator
+ statement></literal></simpara>
+ </section>
+
+ <section>
+ <title>Other Schema Object Creation</title>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>CREATE INDEX</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">CREATE INDEX</emphasis></simpara>
+
+ <simpara><emphasis>create index statement</emphasis></simpara>
+
+ <simpara><literal><create index statement> ::= CREATE INDEX
+ <index name> ON <table name> <left paren> {<column
+ name> [ASC | DESC]}, ... <left paren></literal></simpara>
+
+ <simpara>Creates an index on a group of columns of a table. The optional
+ [ASC | DESC] specifies if the column is indexed in the ascending or
+ descending order, but has no effect on how the index is created (it is
+ allowed for compatibility with other database engines). HyperSQL can use
+ all indexes in ascending or descending order as needed.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>DROP INDEX</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">DROP INDEX</emphasis></simpara>
+
+ <simpara><emphasis>drop index statement</emphasis></simpara>
+
+ <simpara><literal><drop index statement> ::= DROP INDEX [ IF
+ EXISTS ] <index name> [ IF EXISTS ]</literal></simpara>
+
+ <simpara>Destroy an index.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>CREATE TYPE</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">CREATE TYPE</emphasis></simpara>
+
+ <simpara><emphasis>user-defined type definition</emphasis></simpara>
+
+ <simpara><literal><user-defined type definition> ::= CREATE TYPE
+ <user-defined type body></literal></simpara>
+
+ <simpara><literal><user-defined type body> ::= <schema-resolved
+ user-defined type name> [ AS <representation>
+ ]</literal></simpara>
+
+ <simpara><literal><representation> ::= <predefined
+ type></literal></simpara>
+
+ <simpara>Define a user-defined type. Currently only simple distinct
+ types can be defined without further attributes.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>CREATE CAST</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">CREATE CAST</emphasis></simpara>
+
+ <simpara><emphasis>user-defined cast definition</emphasis></simpara>
+
+ <simpara><literal><user-defined cast definition> ::= CREATE CAST
+ <left paren> <source data type> AS <target data type>
+ <right paren> WITH <cast function> [ AS ASSIGNMENT
+ ]</literal></simpara>
+
+ <simpara><literal><cast function> ::= <specific routine
+ designator></literal></simpara>
+
+ <simpara><literal><source data type> ::= <data
+ type></literal></simpara>
+
+ <simpara><literal><target data type> ::= <data
+ type></literal></simpara>
+
+ <simpara>Define a user-defined cast. This feature may be supported in a
+ future versions of HyperSQL.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>DROP CAST</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">DROP CAST</emphasis></simpara>
+
+ <simpara><emphasis>drop user-defined cast statement</emphasis></simpara>
+
+ <simpara><literal><drop user-defined cast statement> ::= DROP CAST
+ <left paren> <source data type> AS <target data type>
+ <right paren> <drop behavior></literal></simpara>
+
+ <simpara>Destroy a user-defined cast. This feature may be supported in a
+ future versions of HyperSQL.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>CREATE CHARACTER SET</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">CREATE CHARACTER SET</emphasis></simpara>
+
+ <simpara><emphasis>character set definition</emphasis></simpara>
+
+ <simpara><literal><character set definition> ::= CREATE CHARACTER
+ SET <character set name> [ AS ] <character set source> [
+ <collate clause> ]</literal></simpara>
+
+ <simpara><literal><character set source> ::= GET <character set
+ specification></literal></simpara>
+
+ <simpara>Define a character set. A new CHARACTER SET is based on an
+ existing CHARACTER SET. The optional <literal><collate
+ clause></literal> specifies the collation to be used, otherwise the
+ collation is inherited from the default collation for the source
+ CHARACTER SET.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>DROP CHARACTER SET</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">DROP CHARACTER SET</emphasis></simpara>
+
+ <simpara><emphasis>drop character set statement</emphasis></simpara>
+
+ <simpara><literal><drop character set statement> ::= DROP
+ CHARACTER SET <character set name></literal></simpara>
+
+ <simpara>Destroy a character set. If the character set name is
+ referenced in any database object, the command fails. Note that
+ <literal>CASCADE</literal> or <literal>RESTRICT</literal> cannot be
+ specified for this command.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>CREATE COLLATION</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">CREATE COLLATION</emphasis></simpara>
+
+ <simpara><emphasis>collation definition</emphasis></simpara>
+
+ <simpara><literal><collation definition> ::= CREATE COLLATION
+ <collation name> FOR <character set specification> FROM
+ <existing collation name> [ <pad characteristic>
+ ]</literal></simpara>
+
+ <simpara><literal><existing collation name> ::= <collation
+ name></literal></simpara>
+
+ <simpara><literal><pad characteristic> ::= NO PAD | PAD
+ SPACE</literal></simpara>
+
+ <simpara>Define a collation. A new collation is based on an existing
+ COLLATION and applies to an existing CHARACTER SET. The <literal><pad
+ characteristic></literal> specifies whether strings are padded with
+ spaces for comparison. This feature may be supported in a future
+ versions of HyperSQL.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>DROP COLLATION</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">DROP COLLATION</emphasis></simpara>
+
+ <simpara><emphasis>drop collation statement</emphasis></simpara>
+
+ <simpara><literal><drop collation statement> ::= DROP COLLATION
+ <collation name> <drop behavior></literal></simpara>
+
+ <simpara>Destroy a collation. If the <literal><drop
+ behavior></literal> is <literal>CASCADE</literal>, then all
+ references to the collation revert to the default collation that would
+ be in force if the dropped collation was not specified. This feature may
+ be supported in a future versions of HyperSQL.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>CREATE TRANSLATION</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">CREATE TRANSLATION</emphasis></simpara>
+
+ <simpara><emphasis>transliteration definition</emphasis></simpara>
+
+ <simpara><literal><transliteration definition> ::= CREATE
+ TRANSLATION <transliteration name> FOR <source character set
+ specification> TO <target character set specification> FROM
+ <transliteration source></literal></simpara>
+
+ <simpara><literal><source character set specification> ::=
+ <character set specification></literal></simpara>
+
+ <simpara><literal><target character set specification> ::=
+ <character set specification></literal></simpara>
+
+ <simpara><literal><transliteration source> ::= <existing
+ transliteration name> | <transliteration
+ routine></literal></simpara>
+
+ <simpara><literal><existing transliteration name> ::=
+ <transliteration name> </literal></simpara>
+
+ <simpara><literal><transliteration routine> ::= <specific
+ routine designator></literal></simpara>
+
+ <simpara>Define a character transliteration. This feature may be
+ supported in a future versions of HyperSQL.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>DROP TRANSLATION</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">DROP TRANSLATION</emphasis></simpara>
+
+ <simpara><emphasis>drop transliteration statement</emphasis></simpara>
+
+ <simpara><literal><drop transliteration statement> ::= DROP
+ TRANSLATION <transliteration name></literal></simpara>
+
+ <simpara>Destroy a character transliteration. This feature may be
+ supported in a future versions of HyperSQL.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>CREATE ASSERTION</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">CREATE ASSERTION</emphasis></simpara>
+
+ <simpara><emphasis>assertion definition</emphasis></simpara>
+
+ <simpara><literal><assertion definition> ::= CREATE ASSERTION
+ <constraint name> CHECK <left paren> <search
+ condition> <right paren> [ <constraint characteristics>
+ ]</literal></simpara>
+
+ <simpara>Specify an integrity constraint. This feature may be supported
+ in a future versions of HyperSQL.</simpara>
+
+ <indexterm significance="preferred" type="sql">
+ <primary>DROP ASSERTION</primary>
+ </indexterm>
+
+ <simpara><emphasis role="bold">DROP ASSERTION</emphasis></simpara>
+
+ <simpara><emphasis>drop assertion statement</emphasis></simpara>
+
+ <simpara><literal><drop assertion statement> ::= DROP ASSERTION
+ <constraint name> [ <drop behavior> ]</literal></simpara>
+
+ <simpara>Destroy an assertion. This feature may be supported in a future
+ versions of HyperSQL.</simpara>
+ </section>
+ </section>
+
+ <section>
+ <title>The Information Schema</title>
+
+ <para>The Information Schema is a special schema in each catalog. The SQL
+ Standard defines a number of character sets and domains in this schema. In
+ addition, all the implementation-defined collations belong to the
+ Information Schema.</para>
+
+ <para>The SQL Standard defines many views in the Information Schema. These
+ views show the properties of the database objects that currently exist in
+ the database. When a user accesses one these views, only the properties of
+ database objects that the user can access are included.</para>
+
+ <para>HyperSQL supports all the views defined by the Standard, apart from
+ a few views that report on extended user-defined types and other optional
+ features of the Standard that are not supported by HyperSQL.</para>
+
+ <para>HyperSQL also adds some views to the Information Schema. These views
+ are for features that are not reported in any of the views defined by the
+ Standard, or for use by JDBC DatabaseMetaData.</para>
+
+ <section>
+ <title>Predefined Character Sets, Collations and Domains</title>
+
+ <para>The SQL Standard defines a number of character sets and domains in
+ the INFORMATION SCHEMA.</para>
+
+ <para>These domains are used in the INFORMATION SCHEMA views:</para>
+
+ <simpara>CARDINAL_NUMBER, YES_OR_NO, CHARACTER_DATA, SQL_IDENTIFIER,
+ TIME_STAMP</simpara>
+
+ <simpara>All available collations are in the INFORMATION
+ SCHEMA.</simpara>
+ </section>
+
+ <section>
+ <title>Views in INFORMATION SCHEMA</title>
+
+ <para>The following views are defined by the SQL Standard:</para>
+
+ <para>ADMINISTRABLE_ROLE_AUTHORIZATIONS</para>
+
+ <para>APPLICABLE_ROLES</para>
+
+ <para>ASSERTIONS</para>
+
+ <para>AUTHORIZATIONS</para>
+
+ <para>CHARACTER_SETS</para>
+
+ <para>CHECK_CONSTRAINTS</para>
+
+ <para>CHECK_CONSTRAINT_ROUTINE_USAGE</para>
+
+ <para>COLLATIONS</para>
+
+ <para>COLUMNS</para>
+
+ <para>COLUMN_COLUMN_USAGE</para>
+
+ <para>COLUMN_DOMAIN_USAGE</para>
+
+ <para>COLUMN_PRIVILEGES</para>
+
+ <para>COLUMN_UDT_USAGE</para>
+
+ <para>CONSTRAINT_COLUMN_USAGE</para>
+
+ <para>CONSTRAINT_TABLE_USAGE</para>
+
+ <para>DATA_TYPE_PRIVILEGES</para>
+
+ <para>DOMAINS</para>
+
+ <para>DOMAIN_CONSTRAINTS</para>
+
+ <para>ENABLED_ROLES</para>
+
+ <para>INFORMATION_SCHEMA_CATALOG_NAME</para>
+
+ <para>KEY_COLUMN_USAGE</para>
+
+ <para>PARAMETERS</para>
+
+ <para>REFERENTIAL_CONSTRAINTS</para>
+
+ <para>ROLE_AUTHORIZATION_DESCRIPTORS</para>
+
+ <para>ROLE_COLUMN_GRANTS</para>
+
+ <para>ROLE_ROUTINE_GRANTS</para>
+
+ <para>ROLE_TABLE_GRANTS</para>
+
+ <para>ROLE_UDT_GRANTS</para>
+
+ <para>ROLE_USAGE_GRANTS</para>
+
+ <para>ROUTINE_COLUMN_USAGE</para>
+
+ <para>ROUTINE_JAR_USAGE</para>
+
+ <para>ROUTINE_PRIVILEGES</para>
+
+ <para>ROUTINE_ROUTINE_USAGE</para>
+
+ <para>ROUTINE_SEQUENCE_USAGE</para>
+
+ <para>ROUTINE_TABLE_USAGE</para>
+
+ <para>ROUTINES</para>
+
+ <para>SCHEMATA</para>
+
+ <para>SEQUENCES</para>
+
+ <para>SQL_FEATURES</para>
+
+ <para>SQL_IMPLEMENTATION_INFO</para>
+
+ <para>SQL_PACKAGES</para>
+
+ <para>SQL_PARTS</para>
+
+ <para>SQL_SIZING</para>
+
+ <para>SQL_SIZING_PROFILES</para>
+
+ <para>TABLES</para>
+
+ <para>TABLE_CONSTRAINTS</para>
+
+ <para>TABLE_PRIVILEGES</para>
+
+ <para>TRANSLATIONS</para>
+
+ <para>TRIGGERED_UPDATE_COLUMNS</para>
+
+ <para>TRIGGERS</para>
+
+ <para>TRIGGER_COLUMN_USAGE</para>
+
+ <para>TRIGGER_ROUTINE_USAGE</para>
+
+ <para>TRIGGER_SEQUENCE_USAGE</para>
+
+ <para>TRIGGER_TABLE_USAGE</para>
+
+ <para>USAGE_PRIVILEGES</para>
+
+ <para>USER_DEFINED_TYPES</para>
+
+ <para>VIEWS</para>
+
+ <para>VIEW_COLUMN_USAGE</para>
+
+ <para>VIEW_ROUTINE_USAGE</para>
+
+ <para>VIEW_TABLE_USAGE</para>
+
+ <para>The following views are specific to HyperSQL:</para>
+
+ <para>SYSTEM_BESTROWIDENTIFIER</para>
+
+ <para>SYSTEM_CACHEINFO</para>
+
+ <para>SYSTEM_COLUMNS</para>
+
+ <para>SYSTEM_COMMENTS</para>
+
+ <para>SYSTEM_CROSSREFERENCE</para>
+
+ <para>SYSTEM_INDEXINFO</para>
+
+ <para>SYSTEM_PRIMARYKEYS</para>
+
+ <para>SYSTEM_PROCEDURECOLUMNS</para>
+
+ <para>SYSTEM_PROCEDURES</para>
+
+ <para>SYSTEM_PROPERTIES</para>
+
+ <para>SYSTEM_SCHEMAS</para>
+
+ <para>SYSTEM_SEQUENCES</para>
+
+ <para>SYSTEM_SESSIONINFO</para>
+
+ <para>SYSTEM_SESSIONS</para>
+
+ <para>SYSTEM_TABLES</para>
+
+ <para>SYSTEM_TABLETYPES</para>
+
+ <para>SYSTEM_TEXTTABLES</para>
+
+ <para>SYSTEM_TYPEINFO</para>
+
+ <para>SYSTEM_UDTS</para>
+
+ <para>SYSTEM_USERS</para>
+
+ <para>SYSTEM_VERSIONCOLUMNS</para>
+ </section>
+ </section>
+</chapter>
diff --git a/doc-src/guide/dbfiles-app.xml b/doc-src/guide/dbfiles-app.xml
new file mode 100644
index 0000000..9520559
--- /dev/null
+++ b/doc-src/guide/dbfiles-app.xml
@@ -0,0 +1,239 @@
+<!-- $Id: dbfiles-app.xml 847 2009-01-19 22:24:49Z unsaved $ -->
+
+<appendix>
+
+<title>Hsqldb Database Files and Recovery</title>
+<appendixinfo>
+ <releaseinfo>$Revision: 847 $</releaseinfo>
+ <pubdate>$Date: 2009-01-19 17:24:49 -0500 (Mon, 19 Jan 2009) $</pubdate>
+ <keywordset>
+ <keyword>HSQLDB</keyword>
+ <keyword>Data</keyword>
+ <keyword>Files</keyword>
+ </keywordset>
+ <legalnotice><para>
+ This text is based on HypersonicSQL documentation, updated to reflect
+ the latest version 1.8.0 of HSQLDB.
+ </para></legalnotice>
+</appendixinfo>
+
+<section>
+ <para>
+ The Standalone and Client/Server modes will in most cases use files to
+ store all data to disk in a persistent and safe way.
+ This document describes the meaning of the files, the states and the
+ procedures followed by the engine to recover the data.
+ </para> <para>
+ A database named 'test' is used in this description.
+ The database files will be as follows.
+ </para>
+</section>
+
+<variablelist>
+ <title>Database Files</title>
+ <varlistentry><term>test.properties</term><listitem><para>
+ Contains the entry 'modified'.
+ If the entry 'modified' is set to 'yes' then the database is either
+ running or was not closed correctly (because the close algorithm sets
+ 'modified' to 'no' at the end).
+ </para></listitem>
+ </varlistentry>
+ <varlistentry><term>test.script</term><listitem><para>
+ This file contains the SQL statements that makes up the database up to
+ the last checkpoint - it is in synch with
+ <filename>test.backup</filename>.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry><term>test.data</term><listitem><para>
+ This file contains the (binary) data records for CACHED tables only.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry><term>test.backup</term><listitem><para>
+ This is compressed file that contains the complete backup of the old
+ <filename>test.data</filename> file at the time of last checkpoint.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry><term>test.log</term><listitem><para>
+ This file contains the extra SQL statements that have modified the
+ database since the last checkpoint (something like the 'Redo-log' or
+ 'Transaction-log', but just text).
+ </para><para>
+ In the above list, a checkpoint results from both a CHECKPOINT command
+ and a SHUTDOWN command.
+ </para></listitem>
+ </varlistentry>
+</variablelist>
+
