SQL Server

开发平台：
Unix_Linux

gss-1：源码内容
							This is Info file gss, produced by Makeinfo-1.63 from the input file
/home/gsql/0.7b5/etc/gss.texi.

File: gss,  Node: Top,  Next: Distrib,  Prev: (dir),  Up: (dir)
The GNU SQL Server
******************
   GNU SQL Server is a relational database system. This Info file
describes how to use and program a database with the GNU SQL Server. It
corresponds to GNU SQL Server version 0.7
* Menu:
Common questions
* Distrib::	      How to get the latest GNU SQL Server distribution.
* Copying::	      The GNU General Public License gives you permission
			to redistribute GNU SQL Server on certain terms;
			it also explains that there is no warranty.
* Manifesto::	      What's GNU?  Gnu's Not Unix!
* Acknowledgments::   Major contributors to GNU SQL Server.
SQL server topics
* Intro::	      An introduction to current revision
* Architecture::      Overview of server architecture
* Dialect::           Dialect notes
* Server::            Running Server
* Client::            Compiling and running DB applications
* Bugs::	      How and when to report a bug.
* Key Index::
* Command Index::
* Variable Index::
* Concept Index::
Reporting Bugs
* Criteria:  Bug Criteria.	 Have you really found a bug?
* Understanding Bug Reporting::	 How to report a bug effectively.
* Checklist::			 Steps to follow for a good bug report.
* Sending Patches::		 How to send a patch for GNU SQL Server.

File: gss,  Node: Distrib,  Next: Copying,  Prev: Top,  Up: Top
Distribution
************
   GNU SQL Server is "free software"; this means that everyone is free
to use it and free to redistribute it on certain conditions.  GNU SQL
Server is not in the public domain; it is copyrighted and there are
restrictions on its distribution, but these restrictions are designed
to permit everything that a good cooperating citizen would want to do.
What is not allowed is to try to prevent others from further sharing
any version of GNU SQL Server that they might get from you.  The
precise conditions are found in the GNU General Public License that
comes with GNU SQL Server and also appears following this section.
   One way to get a copy of GNU SQL Server is from someone else who has
it.  You need not ask for our permission to do so, or tell any one
else; just copy it.  If you have access to the Internet, you can get
the latest distribution version of GNU SQL Server by anonymous FTP; see
the file `etc/FTP' in the GNU SQL Server distribution for more
information.
   You may also receive GNU SQL Server when you buy a computer.
Computer manufacturers are free to distribute copies on the same terms
that apply to everyone else.  These terms require them to give you the
full sources, including whatever changes they may have made, and to
permit you to redistribute the GNU SQL Server received from them under
the usual terms of the General Public License.  In other words, the
program must be free for you when you get it, not just free for the
manufacturer.
     Free Software Foundation
     59 Temple Place, Suite 330
     Boston, MA  02111-1307 USA
     USA
   The income from distribution fees goes to support the foundation's
purpose: the development of new free software, and improvements to our
existing programs including GNU SQL Server.
   If you find GNU SQL Server useful, please *send a donation* to the
Free Software Foundation to support our work.  Donations to the Free
Software Foundation are tax deductible.  If you use GNU SQL Server at
your workplace, suggest that the company make a donation.  If company
policy is unsympathetic to the idea of donating to charity, you might
instead suggest ordering a CD-ROM from the Foundation occasionally, or
subscribing to periodic updates.

File: gss,  Node: Copying,  Next: Manifesto,  Prev: Distrib,  Up: Top
GNU GENERAL PUBLIC LICENSE
**************************
                         Version 2, June 1991
     Copyright (C) 1989, 1991 Free Software Foundation, Inc.
     59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
     
     Everyone is permitted to copy and distribute verbatim copies
     of this license document, but changing it is not allowed.
Preamble
========
   The licenses for most software are designed to take away your
freedom to share and change it.  By contrast, the GNU General Public
License is intended to guarantee your freedom to share and change free
software--to make sure the software is free for all its users.  This
General Public License applies to most of the Free Software
Foundation's software and to any other program whose authors commit to
using it.  (Some other Free Software Foundation software is covered by
the GNU Library General Public License instead.)  You can apply it to
your programs, too.
   When we speak of free software, we are referring to freedom, not
price.  Our General Public Licenses are designed to make sure that you
have the freedom to distribute copies of free software (and charge for
this service if you wish), that you receive source code or can get it
if you want it, that you can change the software or use pieces of it in
new free programs; and that you know you can do these things.
   To protect your rights, we need to make restrictions that forbid
anyone to deny you these rights or to ask you to surrender the rights.
These restrictions translate to certain responsibilities for you if you
distribute copies of the software, or if you modify it.
   For example, if you distribute copies of such a program, whether
gratis or for a fee, you must give the recipients all the rights that
you have.  You must make sure that they, too, receive or can get the
source code.  And you must show them these terms so they know their
rights.
   We protect your rights with two steps: (1) copyright the software,
and (2) offer you this license which gives you legal permission to copy,
distribute and/or modify the software.
   Also, for each author's protection and ours, we want to make certain
that everyone understands that there is no warranty for this free
software.  If the software is modified by someone else and passed on, we
want its recipients to know that what they have is not the original, so
that any problems introduced by others will not reflect on the original
authors' reputations.
   Finally, any free program is threatened constantly by software
patents.  We wish to avoid the danger that redistributors of a free
program will individually obtain patent licenses, in effect making the
program proprietary.  To prevent this, we have made it clear that any
patent must be licensed for everyone's free use or not licensed at all.
   The precise terms and conditions for copying, distribution and
modification follow.
    TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
  0. This License applies to any program or other work which contains a
     notice placed by the copyright holder saying it may be distributed
     under the terms of this General Public License.  The "Program",
     below, refers to any such program or work, and a "work based on
     the Program" means either the Program or any derivative work under
     copyright law: that is to say, a work containing the Program or a
     portion of it, either verbatim or with modifications and/or
     translated into another language.  (Hereinafter, translation is
     included without limitation in the term "modification".)  Each
     licensee is addressed as "you".
     Activities other than copying, distribution and modification are
     not covered by this License; they are outside its scope.  The act
     of running the Program is not restricted, and the output from the
     Program is covered only if its contents constitute a work based on
     the Program (independent of having been made by running the
     Program).  Whether that is true depends on what the Program does.
  1. You may copy and distribute verbatim copies of the Program's
     source code as you receive it, in any medium, provided that you
     conspicuously and appropriately publish on each copy an appropriate
     copyright notice and disclaimer of warranty; keep intact all the
     notices that refer to this License and to the absence of any
     warranty; and give any other recipients of the Program a copy of
     this License along with the Program.
     You may charge a fee for the physical act of transferring a copy,
     and you may at your option offer warranty protection in exchange
     for a fee.
  2. You may modify your copy or copies of the Program or any portion
     of it, thus forming a work based on the Program, and copy and
     distribute such modifications or work under the terms of Section 1
     above, provided that you also meet all of these conditions:
       a. You must cause the modified files to carry prominent notices
          stating that you changed the files and the date of any change.
       b. You must cause any work that you distribute or publish, that
          in whole or in part contains or is derived from the Program
          or any part thereof, to be licensed as a whole at no charge
          to all third parties under the terms of this License.
       c. If the modified program normally reads commands interactively
          when run, you must cause it, when started running for such
          interactive use in the most ordinary way, to print or display
          an announcement including an appropriate copyright notice and
          a notice that there is no warranty (or else, saying that you
          provide a warranty) and that users may redistribute the
          program under these conditions, and telling the user how to
          view a copy of this License.  (Exception: if the Program
          itself is interactive but does not normally print such an
          announcement, your work based on the Program is not required
          to print an announcement.)
     These requirements apply to the modified work as a whole.  If
     identifiable sections of that work are not derived from the
     Program, and can be reasonably considered independent and separate
     works in themselves, then this License, and its terms, do not
     apply to those sections when you distribute them as separate
     works.  But when you distribute the same sections as part of a
     whole which is a work based on the Program, the distribution of
     the whole must be on the terms of this License, whose permissions
     for other licensees extend to the entire whole, and thus to each
     and every part regardless of who wrote it.
     Thus, it is not the intent of this section to claim rights or
     contest your rights to work written entirely by you; rather, the
     intent is to exercise the right to control the distribution of
     derivative or collective works based on the Program.
     In addition, mere aggregation of another work not based on the
     Program with the Program (or with a work based on the Program) on
     a volume of a storage or distribution medium does not bring the
     other work under the scope of this License.
  3. You may copy and distribute the Program (or a work based on it,
     under Section 2) in object code or executable form under the terms
     of Sections 1 and 2 above provided that you also do one of the
     following:
       a. Accompany it with the complete corresponding machine-readable
          source code, which must be distributed under the terms of
          Sections 1 and 2 above on a medium customarily used for
          software interchange; or,
       b. Accompany it with a written offer, valid for at least three
          years, to give any third party, for a charge no more than your
          cost of physically performing source distribution, a complete
          machine-readable copy of the corresponding source code, to be
          distributed under the terms of Sections 1 and 2 above on a
          medium customarily used for software interchange; or,
       c. Accompany it with the information you received as to the offer
          to distribute corresponding source code.  (This alternative is
          allowed only for noncommercial distribution and only if you
          received the program in object code or executable form with
          such an offer, in accord with Subsection b above.)
     The source code for a work means the preferred form of the work for
     making modifications to it.  For an executable work, complete
     source code means all the source code for all modules it contains,
     plus any associated interface definition files, plus the scripts
     used to control compilation and installation of the executable.
     However, as a special exception, the source code distributed need
     not include anything that is normally distributed (in either
     source or binary form) with the major components (compiler,
     kernel, and so on) of the operating system on which the executable
     runs, unless that component itself accompanies the executable.
     If distribution of executable or object code is made by offering
     access to copy from a designated place, then offering equivalent
     access to copy the source code from the same place counts as
     distribution of the source code, even though third parties are not
     compelled to copy the source along with the object code.
  4. You may not copy, modify, sublicense, or distribute the Program
     except as expressly provided under this License.  Any attempt
     otherwise to copy, modify, sublicense or distribute the Program is
     void, and will automatically terminate your rights under this
     License.  However, parties who have received copies, or rights,
     from you under this License will not have their licenses
     terminated so long as such parties remain in full compliance.
  5. You are not required to accept this License, since you have not
     signed it.  However, nothing else grants you permission to modify
     or distribute the Program or its derivative works.  These actions
     are prohibited by law if you do not accept this License.
     Therefore, by modifying or distributing the Program (or any work
     based on the Program), you indicate your acceptance of this
     License to do so, and all its terms and conditions for copying,
     distributing or modifying the Program or works based on it.
  6. Each time you redistribute the Program (or any work based on the
     Program), the recipient automatically receives a license from the
     original licensor to copy, distribute or modify the Program
     subject to these terms and conditions.  You may not impose any
     further restrictions on the recipients' exercise of the rights
     granted herein.  You are not responsible for enforcing compliance
     by third parties to this License.
  7. If, as a consequence of a court judgment or allegation of patent
     infringement or for any other reason (not limited to patent
     issues), conditions are imposed on you (whether by court order,
     agreement or otherwise) that contradict the conditions of this
     License, they do not excuse you from the conditions of this
     License.  If you cannot distribute so as to satisfy simultaneously
     your obligations under this License and any other pertinent
     obligations, then as a consequence you may not distribute the
     Program at all.  For example, if a patent license would not permit
     royalty-free redistribution of the Program by all those who
     receive copies directly or indirectly through you, then the only
     way you could satisfy both it and this License would be to refrain
     entirely from distribution of the Program.
     If any portion of this section is held invalid or unenforceable
     under any particular circumstance, the balance of the section is
     intended to apply and the section as a whole is intended to apply
     in other circumstances.
     It is not the purpose of this section to induce you to infringe any
     patents or other property right claims or to contest validity of
     any such claims; this section has the sole purpose of protecting
     the integrity of the free software distribution system, which is
     implemented by public license practices.  Many people have made
     generous contributions to the wide range of software distributed
     through that system in reliance on consistent application of that
     system; it is up to the author/donor to decide if he or she is
     willing to distribute software through any other system and a
     licensee cannot impose that choice.
     This section is intended to make thoroughly clear what is believed
     to be a consequence of the rest of this License.
  8. If the distribution and/or use of the Program is restricted in
     certain countries either by patents or by copyrighted interfaces,
     the original copyright holder who places the Program under this
     License may add an explicit geographical distribution limitation
     excluding those countries, so that distribution is permitted only
     in or among countries not thus excluded.  In such case, this
     License incorporates the limitation as if written in the body of
     this License.
  9. The Free Software Foundation may publish revised and/or new
     versions of the General Public License from time to time.  Such
     new versions will be similar in spirit to the present version, but
     may differ in detail to address new problems or concerns.
     Each version is given a distinguishing version number.  If the
     Program specifies a version number of this License which applies
     to it and "any later version", you have the option of following
     the terms and conditions either of that version or of any later
     version published by the Free Software Foundation.  If the Program
     does not specify a version number of this License, you may choose
     any version ever published by the Free Software Foundation.
 10. If you wish to incorporate parts of the Program into other free
     programs whose distribution conditions are different, write to the
     author to ask for permission.  For software which is copyrighted
     by the Free Software Foundation, write to the Free Software
     Foundation; we sometimes make exceptions for this.  Our decision
     will be guided by the two goals of preserving the free status of
     all derivatives of our free software and of promoting the sharing
     and reuse of software generally.
                                NO WARRANTY
 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO
     WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE
     LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
     HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT
     WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT
     NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
     FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS TO THE
     QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
     PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY
     SERVICING, REPAIR OR CORRECTION.
 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
     WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY
     MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE
     LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL,
     INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR
     INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
     DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU
     OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY
     OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN
     ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
                      END OF TERMS AND CONDITIONS
How to Apply These Terms to Your New Programs
=============================================
   If you develop a new program, and you want it to be of the greatest
possible use to the public, the best way to achieve this is to make it
free software which everyone can redistribute and change under these
terms.
   To do so, attach the following notices to the program.  It is safest
to attach them to the start of each source file to most effectively
convey the exclusion of warranty; and each file should have at least
the "copyright" line and a pointer to where the full notice is found.
     ONE LINE TO GIVE THE PROGRAM'S NAME AND AN IDEA OF WHAT IT DOES.
     Copyright (C) 19YY  NAME OF AUTHOR
     
     This program is free software; you can redistribute it and/or
     modify it under the terms of the GNU General Public License
     as published by the Free Software Foundation; either version 2
     of the License, or (at your option) any later version.
     
     This program is distributed in the hope that it will be useful,
     but WITHOUT ANY WARRANTY; without even the implied warranty of
     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
     GNU General Public License for more details.
     
     You should have received a copy of the GNU General Public License
     along with this program; if not, write to the Free Software
     Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
   Also add information on how to contact you by electronic and paper
mail.
   If the program is interactive, make it output a short notice like
this when it starts in an interactive mode:
     Gnomovision version 69, Copyright (C) 19YY NAME OF AUTHOR
     Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
     type `show w'.  This is free software, and you are welcome
     to redistribute it under certain conditions; type `show c'
     for details.
   The hypothetical commands `show w' and `show c' should show the
appropriate parts of the General Public License.  Of course, the
commands you use may be called something other than `show w' and `show
c'; they could even be mouse-clicks or menu items--whatever suits your
program.
   You should also get your employer (if you work as a programmer) or
your school, if any, to sign a "copyright disclaimer" for the program,
if necessary.  Here is a sample; alter the names:
     Yoyodyne, Inc., hereby disclaims all copyright
     interest in the program `Gnomovision'
     (which makes passes at compilers) written
     by James Hacker.
     
     SIGNATURE OF TY COON, 1 April 1989
     Ty Coon, President of Vice
   This General Public License does not permit incorporating your
program into proprietary programs.  If your program is a subroutine
library, you may consider it more useful to permit linking proprietary
applications with the library.  If this is what you want to do, use the
GNU Library General Public License instead of this License.

File: gss,  Node: Intro,  Next: Architecture,  Prev: Acknowledgments,  Up: Top
Introduction
************
   You are reading about GNU SQL Server, the GNU implementation of
relational database server.
   GNU SQL-Server (GSS) was implemented by small team of Russian
programmers working in the Institute for System Programming of Russian
Academy of Sciences with support of Free Software Foundation and
Russian Foundation for Basic Research.
   The project was started at 1992. To this time we already had some
version of an engine (we call it "The Subsystem for Data and
Transaction Management" - SDTM) which was developed for the
experimental object-based operating system CLASTOS. At the first step
SDTM was ported to UNIX environment. In parallel we started
implementation of the SQL compiler and SQL runtime library.  At the
first stage of the project we got the great help from Sergei Gaissarian
who is one of the best experts in compilers in our institute.
   Now we really have a working prototype of the system and would like
to give people a possibility to use it. Of course GSS is not so good as
current commercial implementations: sometimes it's too slow and we know
why; we don't have yet any advanced user interface (such as forms),
etc. But GNU SQL Server is under the GNU General  Public License and
now you can improve it.
   In this manual we briefly describe the general architecture of the
system, introduce our version of SQL and provide the information about
GSS installation. If you have some questions don't hesitate to contact
with us through e-mail: *gss@ispras.ru*.

File: gss,  Node: Architecture,  Next: Dialect,  Prev: Intro,  Up: Top
   GSS is based on client-server architecture for DBMS organizations.
The system is dedicated for use in distributed open systems in UNIX
environments. In fact, we support two kinds of "clients and servers".
   The whole set of processes working with a data base may be broken up
into several layers depending upon the distance from the data base. The
most internal layer which is the closest to a data base consists of a
set of processes of SDTM. These processes provide the services of
Synchronizer (two-phase predicate locks), Logical Log (the log of
updates at the logical level), Micro Log (the log for microoperations),
Buffer (main memory bufferization, exchanges with disks, locks of
pages), and Sorter (to make external sorts). SDTM also includes
utilities to restore the data base after failures and crashes of
modules for transactions. In fact, these modules represent some kind of
runtime library. They implement the external interface of SDTM.  All
processes of this layer communicate with message queues and shared
memory.
   The next layer consists of the server processes of the compiler and
interpreter of SQL-statements. These processes contain modules of
transactions and access the kernel and data through them. This layer
provides services which are available with the mechanism of remote
procedure calls.
   The server part of the system also contains the process of
Administrator that monitors a state of all other processes of the
server and creates by demand services of the compiler and interpreter.
This process communicates with other processes of the internal layer
with signals and messages and is accessible for external invocations
via   remote   procedure    calls.    The Administrator may  be
registered as an Internet daemon,  and it may unload all other parts of
server if they aren't used  for  a long time.
   Client parts of the system may reside on any computer of a local
network. The client part consists of the client part of the SQL
compiler and the client part of the interpreter which are linked
together with a user's program. The only requirement for an environment
where a client part functions is that it should support the mechanism
of remote procedure calls.
   The client part of the compiler (the precompiler) is responsible for
selection of pure SQL-text and its transmission to the main (server)
part of the compiler to convert into a procedural representation. After
such processing, the user gets a pure C-program where SQL-code is
replaced to calls of the runtime-library of the client part of the
query interpreter. A corresponded procedural code of SQL-statements is
stored within a data base.
   At runtime, the server part of the interpreter is provided with
reference to previously compiled and stored within data base code
together with parameters of a corresponded SQL-statement. Using this
reference, the server part of the interpreter retrieves the code from
data base and perform it with appropriate invocations of SDTM.
   We use machine-independent internal representation of procedural
SQL-code to provide more portability and reliability of the system. In
principle, we could generate machine codes. But the main problem was
that we often need to compile something dynamically (in runtime) and to
load additional parts of code from the data base by linking them
together with a running program. Standard loaders do not provide such
facilities. So we would need to write a sufficient part of special code
for each pair of processor  and  operating  system.  Moreover,  the
most overhead is paid not for interpretation but for data retrieval and
may be for the analysis of retrieval conditions.

File: gss,  Node: Dialect,  Next: Server,  Prev: Architecture,  Up: Top
                 The Dialect of SQL of GNU SQL Server
   Activities for standardization of SQL had started practically
simultaneously with its first commercial implementations. Original
System R's SQL was not developed with enough care. Commercial dialects
were so different that no one could be accepted as a standard.  The
first International Standard SQL-89 in many parts is not defined
precisely enough and allows different interpretations. Also, this
standard doesn't include such important things as schema manipulation
and dynamic SQL facilities. A much more complete and precise SQL
standard was adopted in 1992 but it still omit a lot of useful
functionality.
* Menu:
* Dialect Intro::        Requirements to the SQL Dialect
* Data description::     Definition of operating parameters
* Data types::           Data type correspondence
* Schema::               Schema manipulations and consistency constraints
* Access::               Data access control

File: gss,  Node: Dialect Intro,  Next: Data description,  Prev: Dialect,  Up: Dialect
Dialect Intro
=============
   The dialect of the SQL of GSS is oriented to embedded C and uses an
ASCII-compatible set of characters. The dialect supports data types
that are adequate to the base set of types of C, and also strings of
various length. Statements for data definitions allow us to create and
to drop relations and views, and also to grant privileges to other
users. Supported constraints allow us to prevent entrance of
NULL-values, and to define constraints of uniqueness on tables. The
language also allows us to declare check constraints on a table
(conditions that should be true on every tuple of the relation) and
referential constraints.
   The set of statements for data manipulations includes statements to
insert, update and delete tuples from relations. The select statement
may include unions (possibly, with elimination of duplicates), joins,
and nested subqueries. A result table may be sorted in ascendant or
descendant order. A result table may be processed tuple by tuple
through a sequential cursor.
   The SQL dialect is oriented for use in a UNIX-environment. This
environment provides the implementation with an authorization
identifier (user name) and a name of the module which is associated
with a given C-program with embedded SQL. The last name is formed as
the name of the corresponding source file qualified with the user name.
   The dialect does not support any explicit statement to connect a
data base. A connection is provided automatically to an SQL-server
specified at a phase of compilation. A name of the SQL-server is
defined as a network name of a computer where the server is installed.
   Below we consider some issues of the dialect with some details.

File: gss,  Node: Data description,  Next: Data types,  Prev: Dialect Intro,  Up: Dialect
Data description
================
   *Data description*
   SQL statements manipulate the following data elements: constants
(numbers and strings), parameters (variables of a host C-program),
columns, tables, and user defined schemes.  Identifiers which are used
to name these elements may be represented in traditional form
([A-Za-z][A-Za-z0-9]* e.g. A0z9) or as a double quoted string ("This is
an identifier too"). Names of host variables should also satisfy the
naming rules of the C programming language. The dialect of SQL does not
restrict the length of identifiers of host variables but any name of a
table, column, or user-defined schema should not be longer than 18
characters. Literal strings of characters are restricted by single
quotes ('this is an example of such literal') and may contain any
symbol of the character set used. Strings are sorted according to codes
of characters (thus if the KOI-8 - Russian extension of ASCII - is in
use than sorting will not always provide the desired ordering).
   Parameters and columns of any type and expressions constructed from
them may have a NULL-value in addition to all the usual values of a
given data type. In indexes, a NULL-value is considered as a value that
is less than every non-NULL value of the same type. To fetch into a
host variable a column or expression that may have NULL-value one
should use an additional indicator variable that gets a value of -1 if
a value of the main variable is NULL.

File: gss,  Node: Data types,  Next: Schema,  Prev: Data description,  Up: Dialect
Data types
==========
                              Data types
   In the current version we support only those data types that may be
directly mapped into data types of standard C programming language. The
correspondence between SQL data types and C data types is shown below:
         SQL data type        C data type
     
      CHAR(ACTOR)([length])  char [length]
      INT(EGER)              long
      SMALLINT               short
      REAL                   float
      DOUBLE PRECISION       double
   The system also partially supports the SQL FLOAT data type: depending
on required precision it is mapped onto either a float or a double data
type of C. But if too high precision is required (which may not be
emulated by double) then an error message is generated.  The same
method is used for the SQL DECIMAL data type if a scale is defined as
zero. Processing of such data types as DATETIME and CHARVAR have not
yet been implemented.

File: gss,  Node: Schema,  Next: Access,  Prev: Data types,  Up: Dialect
Schema
======
           Schema manipulations and consistency constraints
   By definition, user schema is a totality of all stored objects of a
given user: tables, views, modules (a set of compiled SQL-statements
that correspond to one user's program) and triggers. The user schema is
actually created when the first object of this user is created. SQL
CREATE SCHEMA statement does not create anything itself, it just
defines a context (default authority identifier) for all the nested
statements for table and view creation.
   SQL CREATE TABLE statement specifies table name, column description
and integrity constraints that should be applied to a given table. Each
column is specified by its name, data type and optionally by a default
value. Our dialect of SQL allows three kinds of integrity constraints:
primary and alternative key constraints (unique constraints),
referential constraints (for foreign keys), and check constraints. In
the case of referential constraints there should exist a unique
constraint for an appropriate set of the referred table. All unique and
check constraints are checked on each row update of a given table.
Foreign key constraints are checked on each row update both of
referring and referred tables.
   For each check or referential constraint an appropriate trigger is
created within a data base. The only function of this trigger is to
check a constraint and to undo SQL statements that violate the
constraint. Any explicit triggers are not allowed.
   The statement DROP TABLE is successively executed only if there are
not any references (foreign keys) belonging to it. Views, i.e.  stored
named queries, that are treated as tables are supported. Our version of
SQL does not support modules explicitly: there is not any special
language construction to create explicit modules. In fact, implicit
modules are created and maintained by the SQL compiler.

File: gss,  Node: Access,  Prev: Schema,  Up: Dialect
Access
======
                          Data access control
   Each (registered) user may create objects with any authorization
identifier that may differ from his/her own identifier. But only this
creator (owner) may modify or drop these objects.  Immediately after
creation only the owner has rights for any operation with this object,
and all other users cannot do anything. But later the owner can grant
all or part of his/her rights to other user(s) with the SQL GRANT
PRIVILEGES statement, including WITH GRANT OPTION.  According to SQL-89
standard our dialect supports SELECT, INSERT, DELETE, UPDATE, and
REFERENCE privileges.

File: gss,  Node: Server,  Next: Client,  Prev: Dialect,  Up: Top
   To start the server you need to run SQL server top routine 'gsqls'
from the `dbhome' directory (let's say
/usr/local/gnusql/0.7b3/i586-unknown-linux ) ( or `sqlser' subdirectory
of distribution). If you want to run it in background, you have to
redirect output streams to log. if you configured it to use debugger,
you need to give administrator answers: i.e. whether or not you start
debugger for each started subservice.
     Example:
     
     gsql{kml}/home/gsql/gss/sqlser(45): ls -l
     -rwxrwxr-x   1 vera     sql       266032 Oct  4 14:31 gsqls
     drwxrwxr-x   2 vera     sql          512 Oct  4 14:32 bin
     drwxrwxr-x   2 vera     sql          512 Oct  1 14:08 client
     drwxrwxr-x   2 vera     sql          512 Oct  4 12:43 db
     drwxrwxr-x   2 vera     sql          512 Oct  4 12:48 jarchive
     drwxrwxr-x   2 vera     sql          512 Sep 30 07:41 jrnls
     drwxrwxr-x   5 vera     sql          512 Sep 30 07:41 repository
     drwxrwxr-x   2 vera     sql          512 Sep 30 07:41 segs
     gsql{kml}/home/gsql/gss/sqlser(45): gsqls >&log &
   In the example above we are starting server in the directory where
we created it. It was not created to support debugging so we don't
worry about the input stream. Both output streams are redirected to
log. Server output now produces a lot of 'for any case' information
which we prefer not to turn off in the test release.
   TO BE FILLED LATER

File: gss,  Node: Client,  Next: Bugs,  Prev: Server,  Up: Top
                 Compiling and running DB applications
   To create any database application you need to write a C program
containing either embedded SQL operators or runtime system calls
supporting dynamic SQL.  Both cases require processing your program by
the SQL compiler. The Compiler connects the SQL server, sends SQL code
there and produces pure C code with runtime library calls substitution
as well as identification of SQL compiled code stored in the database.
(1)
   gsqlc [options] files...
   Option `-hHOSTNAME' gives the name of the host where the database
server resides. This option overrides the value of the environment
variable *GSSHOST*. If both of them are omitted the local host is
supposed to run the DB server.
   Option `-rMODE' gives the mode of file processing. The possible
values of `MODE' are: *C*,*SQL*,*MODULE*, *SCHEMA*.  If this option is
omitted the compiler interprets extension  *.ec* as a C program with
embedded SQL, and *.sql* as pure SQL code - either schema or module
definition.
   Options `-dPASSES_IDS' asks the compiler to produce compiler tree
dumps after given passes of compilation. PASSES_IDS is a set if
characters representing each pass. Pass identification can be found in
the file *src/include/options.def* in the distribution directory.
   To link your program you should tell the linker to use the runtime
library (either *sqlser/client/*.a* or *'-lgss'*).
   If you configured the package to use a debugger, the running
application program will ask you if you want to start the debugger for
the starting transaction process. You can override this request by
setting the *NEEDGDB* environment variable to "n".
   Too see examples of using SQL in a program see the examples in the
distribution *test* subdirectory.
   ---------- Footnotes ----------
   (1)  Currently the server doesn't check dependencies for compiled
code; this; this will be done in the future.

File: gss,  Node: Bugs,  Next: Key Index,  Prev: Client,  Up: Top
Reporting Bugs
==============
   At sometimes you may encounter a bug in the SQL Server.  Although we
cannot promise we can or will fix the bug, and we might not even agree
that it is a bug, we want to do hear about any problems you encounter.
Often we agree they are bugs and we want to fix them.
   To make it possible for us to fix a bug, you must report it.  In
order to do so effectively, you must know when and how to do it.
* Menu:
* Criteria:  Bug Criteria.	 Have you really found a bug?
* Understanding Bug Reporting::	 How to report a bug effectively.
* Checklist::			 Steps to follow for a good bug report.
* Sending Patches::		 How to send a patch for GNU SQL Server.

File: gss,  Node: Bug Criteria,  Next: Understanding Bug Reporting,  Up: Bugs
When Is There a Bug
-------------------
   If the SQL Server or client runtime library executes an illegal
instruction, or dies with an operating system error message that
indicates a problem in the program (as opposed to something like "disk
full"), then it is certainly a bug.
   If the client programs reports: "service crash" then it is certainly
a bug.
   If a database stores the wrong data or can't find yours, that is a
bug.  But be sure you know for certain what it ought to be. If you
aren't familiar with SQL or don't know for certain how the statement is
supposed to work, then it might actually be working right.  Rather than
jump to conclusions, show the problem to someone who knows for certain.
   If after a careful rereading of the manual you still do not
understand how to do some typical job, that indicates a bug in the
manual, which you should report.  The manual's job is to make
everything clear to people who are not SQL experts--including you.  It
is just as important to report documentation bugs as program bugs.  (
We aer in the very beginning of the manual and your notes will be very
helpfull - at least we will understand what should we describe and
what is obvious for everybody. /kml )

File: gss,  Node: Understanding Bug Reporting,  Next: Checklist,  Prev: Bug Criteria,  Up: Bugs
Understanding Bug Reporting
---------------------------
   When you decide that there is a bug, it is important to report it
and to report it in a way which is useful.  What is most useful is an
exact description of what SQL statements you executed and what kind and
amount of data your database had stored when you started a transaction.
Information about concurrent transactions can be extremely helpful.
   The most important principle in reporting a bug is to report *facts*,
not hypotheses or categorizations.  It is always easier to report the
facts, but people prefer to strain to speculate  explanations of their
own and report their speculations instead.  If the explanations are
based on guesses about how GSS is implemented, they will be useless; we
will have to try to figure out what the facts must have been to lead to
such speculations. Sometimes this is impossible.  But in any case, it is
unnecessary work for us to do when we could be doing something
constructive.

File: gss,  Node: Checklist,  Next: Sending Patches,  Prev: Understanding Bug Reporting,  Up: Bugs
Checklist for Bug Reports
-------------------------
   The best way to send a bug report is to mail it electronically to the
GNU SQL Server maintainers at `bug-gnu-sql@prep.ai.mit.edu'.  (If you
want to suggest a change as an improvement, use `gss@ispras.ru'.)
   If you'd like to read the bug reports, you can find them on the
newsgroup `it has not created yet' or subscribe for bug report mail
list.  ( see `http://www.ispras.ru/~gsql' for details; keep in mind,
however, that as a spectator you should not criticize anything about
what you see there.  The purpose of bug reports is to give information
to the SQL server maintainers.  Spectators are welcome only as long as
they do not interfere with this.  In particular, some bug reports
contain large amounts of data; spectators should not complain about
this.
   Please do not post bug reports using netnews; mail is more reliable
than netnews about reporting your correct address, which we may need in
order to ask you for more information.
   If you can't send electronic mail, then mail the bug report on paper
or machine-readable media to this address:
GNU SQL Server Bugs
Free Software Foundation
59 Temple Place, Suite 330
Boston, MA 02111-1307 USA
   We do not promise to fix the bug; but if the bug is serious, or
ugly, or easy to fix, chances are we will want to.
   To enable maintainers to investigate a bug, your report should
include all these things:
   * The version number of the SQL server.  Without this, we won't know
     whether there is any point in looking for the bug in the current
     version of the GNU SQL server.
     You can get the version number from the server log. At start time
     it reports that "GNU SQL server (version xxxxx) ".
   * The type of machine you are using, and the operating system name
     and version number.
   * The operands given to the `configure' command when the SQL Server
     was installed.
   * A complete list of any modifications you have made to the GSS
     source.  (We may not have time to investigate the bug unless it
     happens in an unmodified SQL Server.  But if you've made
     modifications and you don't tell us, you are sending us on a wild
     goose chase.)
     Be precise about these changes.  A description in English is not
     enough--send a context diff for them.
     Adding files of your own, or porting to another machine, is a
     modification of the source.
   * Details of any other deviations from the standard procedure for
     installing the GNU SQL Server.
   * The complete text of any files needed to reproduce the bug.
   * The precise log of client program and server output. If would be a
     good idea if you comment them by timestamp or syncronization marks.
   * A description of what behavior you observe that you believe is
     incorrect.
     Even if the problem you experience is a fatal signal, you should
     still say it explicitly.  Suppose something strange is going on,
     such as, your copy of the source is out of sync, or you have
     encountered a bug in the C library on your system.  (This has
     happened!)  Your copy might crash and the copy here might not.  If
     you *said* to expect a crash, then when GSS here fails to crash,
     we would know that the bug was not happening.  If you don't say to
     expect a crash, then we would not know whether the bug was
     happening--we would not be able to draw any conclusion from our
     observations.
   * If the manifestation of the bug is an SQL Server error message, it
     is important to report the precise text of the error message.
     This use of the debugger is possible only if you know how to make
     the bug happen again.  If you can't make it happen again, at least
     copy the whole error message.
   Here are some things that are not necessary in a bug report:
   * A system call trace of SQL server or client execution.
     System call traces are very useful for certain special kinds of
     debugging, but in most cases they give little useful information.
     It is therefore strange that many people seem to think that *the*
     way to report information about a crash is to send a system call
     trace.
     In most programs, a backtrace is normally far, far more
     informative than a system call trace.  Even in the SQL server, a
     simple backtrace is generally more informative.
   * A patch for the bug.
     A patch for the bug is useful if it is a good one.  But don't omit
     the other information that a bug report needs, such as the test
     case, on the assumption that a patch is sufficient.  We might see
     problems with your patch and decide to fix the problem another
     way, or we might not understand it at all.  And if we can't
     understand what bug you are trying to fix, or why your patch
     should be an improvement, we will not install it.
     *Note Sending Patches::, for guidelines on how to make it easy for
     us to understand and install your patches.
   * A guess about what the bug is or what it depends on.
     Such guesses are usually wrong.  Even experts can't guess right
     about such things without first using the debugger to find the
     facts.

						