$Id: README.uesql 10467 2004-11-17 00:06:15Z rafa $

UESQL
=====
UESQL is based on Structured Query Language (SQL) but it is slightly different.
The only differences rely in the way SQL-92 defines the embedded variables, and
the character representations.


Extensions to SQL-92
====================
The  format  of  the <connect statement> is slightly different from the  SQL-92
standard  (look for subsections 11.A and 11.B  in the  compiler parser source):

  <connect statement> ::= CONNECT TO <connection target>
  <connection target> ::=   <catalog location>
                            [AS <connection name>]
                            [USER <user login>]
                          | DEFAULT
  <catalog location>  ::= <quote> <dbms server name> [<solidus> <catalog name>] <quote>
  <user login>        ::= <quote> <user name>        [<solidus> <password>]     <quote>
  <quote>             ::= '
  <solidus>           ::= /

It has been  added statements  for creating / droping catalogs  (implementation
dependent in SQL-92 standard).

  <catalog definition> ::= CREATE CATALOG <catalog name clause>

  <catalog name clause> ::=
      <catalog name> AUTHORIZATION <catalog authorization identifier>
    | <catalog name>
    |                AUTHORIZATION <catalog authorization identifier>

  <catalog name> ::= <identifier> | <embedded variable name>

  <catalog authorization identifier> ::= <authorization identifier>

  <drop catalog statement> ::= DROP CATALOG <catalog name> <drop behavior>


The  format of the non-terminal  <embedded variable name>  has been extended to
support embedded n-adic function calls  (although arguments to functions can be
only  atomic variables and C strings).  It  has been also extended  to  support
embedded arrays.  These  extensions  are supported only,  if the compiler is in
relaxed  syntax mode (--relaxed-syntax).  Modifications to the standard SQL-92:

  <embedded variable name> ::=
      <embedded extended variable name>
    | <embedded array>
    | <embedded n-adic function call>

  <embedded extended variable name> ::=
      <colon><host identifier>[<period><host identifier>]...
    | <colon><host identifier>
      [<colon><colon><host identifier>[<period><host identifier>]...]...

  <embedded array> ::=
    <embedded extended variable name> <C array index>...

  <embedded n-adic function call> ::=
    <embedded extended variable name>
    <left paren>
    [ <function parameter> [ <comma> <function parameter> ]... ]
    <right paren>

  <C array index> ::=
      <left bracket> <C host identifier> <right bracket>
    | <left bracket> <unsigned integer>  <right bracket>

  <function parameter> ::=
      <C variable>
    | <C string literal>
    | <C numeric literal>

  <C variable> ::=
    { <ampersand> | <asterisk> }... <C host identifier>

  <C string literal> ::= !! C string without escaped double quotes

  <C numeric literal> ::=
    { <real exact numeric literal> | <signed integer> | <unsigned integer> }


Also it has been added a  new statement for declaring embedded search condition
variables (see subsections 17.A, 8.12 and 6.2).  These extensions are supported
only, if the compiler is in relaxed  syntax mode (--relaxed-syntax). The search
condition variables declared with this statement, can be used in every place
where a <search condition> is used (INSERT, SELECT, UPDATE...).

  <declare search condition> ::=
    DECLARE <search condition name> CONDITION WHERE <search condition>

  <search condition name> ::= <target specification>

  <search condition value specification> ::= <embedded variable name>


Using UESQL in C++
==================

  Debugging
  ---------
  If  you define _UESQL_DEBUG__  when  compiling  generated  files,  then  when
  running,  the  translated  SQL  statements  will be printed using the  macros
  defined in 'mpcl/test.h' header from MPCL.

  Exceptions
  ----------
  Every UESQL code block can throw two exceptions:

    uesql::TExceptionUESQL_Sqlerror
    uesql::TExceptionUESQL_NotFound

  So,  if you  want to make your code safe and robust,  you should catch  these
  exceptions, at least, in the 'main()' function.

  Embedded variables
  ------------------
  In UESQL,  the embedded  variables  are  instances  of  derived  classes from
  uesql::TBaseType.

    uesql::TBaseType
    ----------------
     |  This is the base class for SQL data types.
     |
     +--uesql::TDate (-> mpcl::TLocalDate)
     |  ----------------------------------
     |    This class represents SQL dates.
     |
     +--uesql::TIdentifier (-> mpcl::TString -> std::string)
     |  ----------------------------------------------------
     |    This class represents SQL identifiers like schema names, field names,
     |    cursor names, etc.
     |
     +--uesql::TInteger
     |  ---------------
     |    This class represents SQL integers.
     |
     +--uesql::TReal
     |  ------------
     |    This class represents SQL real numbers.
     |
     +--uesql::TString (-> mpcl::TString -> std::string)
        ------------------------------------------------
          This  class  supports  string SQL literals.  If you  want to  use the
          percentage signs in  the string,  you must escape them as in function
          std::printf() format strings.


Using UESQL in JAVA
===================

  Debugging
  ---------
  You can activate the debugging logger for this subsystem (named 'org.uesqlc')
  by doing this:

    import java.util.logging.Level;
    import java.util.logging.Logger;

    Logger.getLogger ("org.uesqlc").setLevel (Level.ALL);

  Exceptions
  ----------
  Every UESQL code block can throw two exceptions:

    org.uesqlc.TSqlerrorException
    org.uesqlc.TNotFoundException

  So,  if you  want to make your code safe and robust,  you should catch  these
  exceptions, at least, in the main entry point.

  Embedded variables
  ------------------
  In UESQL,  the embedded variables are instances of classes that implement the
  interface org.uesqlc.IType.

    org.uesqlc.IType
    ----------------
     |  This is the interface that must be implemented by SQL data types.
     |
     +--org.uesqlc.TDate
     |  ----------------
     |    This class represents SQL dates.
     |
     +--org.uesqlc.TIdentifier
     |  ----------------------
     |    This class represents SQL identifiers like schema names, field names,
     |    cursor names, etc.
     |
     +--org.uesqlc.TInteger
     |  -------------------
     |    This class represents SQL integers.
     |
     +--org.uesqlc.TReal
     |  ----------------
     |    This class represents SQL real numbers.
     |
     +--org.uesqlc.TString
     |  ------------------
     |    This class supports string SQL literals.
     |
     +--org.uesqlc.TTime
     |  -------------------
     |    This class represents SQL times.
     |
     +--org.uesqlc.TTimestamp
        -------------------
          This class represents SQL timestamps.


Developing new target translations (CDMLs) in C++
=================================================
In every CDML that you create,  you should include the  declaration of SQLCODE,
SQLMESSAGE  and  SQLSTATUS (there is a  header and an implementation for  these
variables  in the  files  'include/uesqlc/defs.hh').  Besides that,  after each
statement you must update the values of these variables,  so the user can check
the state of the executed statements.

When  defining a CDML for a new target translation,  you should use always  the
name-space 'uesql' to avoid collisions with standard or other name-spaces.

When  creating  a  new  target  (following the format 'dbms-api-version'),  you
should create the next files:
 
  dbms-api-version.cc
  dbms-api-version.hh

If  you create these files, you will make life easier for the programmers  that
use  the new target  translation.  The final user always has to add the library
'libuesqlc' in the linkage.


Available target translations
=============================
This  is  the inheritance tree  for CDML documents. See the source of the  CDML
documents for more information about target translations.

  uesql-1.0.cdml
  --------------
   |  This is the base CDML document for UESQL 1.0.
   |
   +--base-identity.cdml
      ------------------
       |  This  is  a document  for  translating  from  UESQL  to  plain SQL-92
       |  statements.
       |
       +--c++/debug.cdml
       |  --------------
       |  Document  for  translating UESQL to plain SQL-92 statements, embedded
       |  in C++ comments.
       |
       +--c++/identity.cdml
       |  -----------------
       |  This  is a document for  translating from UESQL to UESQL  embedded in
       |  C++ comments.
       |
       +--c++/connection_management.cdml
       |  ------------------------------
       |   |  This  is a  document  for  managing  conditions  and input/output
       |   |  embedded variables.
       |   |
       |   +--c++/odbc-3.x.cdml (ODBC >= 3.0)
       |   |  -------------------------------
       |   |  Document for translating UESQL to ODBC 3.x.
       |   |
       |   +--c++/oracle-oci-7.x.cdml (Oracle Server OCI Version >= 7.0)
       |   |  ----------------------------------------------------------
       |   |  Document for translating UESQL to Oracle OCI.
       |   |
       |   +--c++/postgresql-libpq-7.3.x.cdml (PostgreSQL LIBPQ >= 7.3.x)
       |      -----------------------------------------------------------
       |      Document for translating UESQL to PostgreSQL Libpq.
       |
       +--java/connection_management.cdml
          -------------------------------
           |  This  is a  document  for  managing  conditions  and input/output
           |  embedded variables.
           |
           +--java/postgresql-jdbc-3.0.cdml
              -----------------------------
              Document for translating UESQL to JDBC 3.0 over PostgreSQL >= 7.3.x.