


sql(n)                         Tcl Extensions                          sql(n)



Name
  sql - SQL access routine for Tcl

Syntax
  ssqqll__ooppeennddbb _s_e_s_s_i_o_n-_h_a_n_d_l_e _d_b-_s_p_e_c ?_d_b-_s_p_e_c...?
  ssqqll__lliisstt
  ssqqll__wwhhiicchh

  _s_e_s_s_i_o_n ooppeenn ?--uuppddaattee?  _c_u_r_s_o_r-_h_a_n_d_l_e _s_e_l_e_c_t-_s_t_m_t
  _s_e_s_s_i_o_n eexxeecc _s_q_l-_c_o_m_m_a_n_d
  _s_e_s_s_i_o_n ccoommmmiitt
  _s_e_s_s_i_o_n rroollllbbaacckk
  _s_e_s_s_i_o_n vveerrssiioonn
  _s_e_s_s_i_o_n cclloosseeddbb

  _c_u_r_s_o_r
  _c_u_r_s_o_r uuppddaattee "_t_a_b_l_e SET _c_o_l=_e_x_p_r, _c_o_l=_e_x_p_r..."
  _c_u_r_s_o_r ddeelleettee _t_a_b_l_e
  _c_u_r_s_o_r cclloossee
  _c_u_r_s_o_r rreeooppeenn
  _c_u_r_s_o_r nnaammeess
  _c_u_r_s_o_r wwiiddtthhss
  _c_u_r_s_o_r ttyyppeess
  _c_u_r_s_o_r ccoouunntt

Description
  This Tcl extension provides a direct interface to SQL databases.
  Currently, this package supports Informix, Ingres, and Oracle's Rdb pro-
  duct.

  There are three top-level commands:

  ssqqll__ooppeennddbb _s_e_s_s_i_o_n-_h_a_n_d_l_e _d_b-_s_p_e_c ?_d_b-_s_p_e_c...?
       creates a new session, with the named databases accessible through it.
       If the creation is successful, a Tcl procedure named _s_e_s_s_i_o_n-_h_a_n_d_l_e is
       created, which is used to apply commands to the session.  The
       _s_e_s_s_i_o_n-_h_a_n_d_l_e string is returned.  The format of _d_b-_s_p_e_c is dependent
       upon the underlying database system.  It may just be a name, or it may
       include additional information such as user names and passwords.  If
       the underlying database system supports it, more than one database can
       be opened in the session, in which case SQL commands can access data
       in these databases simultaneously.

  ssqqll__wwhhiicchh
       Returns a two-element list, identifying the underlying database
       (Ingres, Rdb, _e_t_c.), and the version of the Tcl interface.

  ssqqll__lliisstt
       Lists all of the open sessions.

  Multiple sessions may be open at once, if the underlying database system
  supports it.  Sessions are completely independent of each other.  Each has
  its own transaction state, and SQL commands refer only to the data in the
  database(s) open in that session.  If two sessions have the same database
  open to access the same data, it is very easy to create deadlock.

  Within a session, all SQL operations are available.    Note that database
  systems vary considerably in the amount of system-level commands (database
  creation and deletion, for example) that are available through SQL.  The
  _s_e_s_s_i_o_n-_h_a_n_d_l_e is used to refer to a session.  It is a Tcl command, with
  subcommands that actually operate on the open database(s).  The next sec-
  tion describes these commands.

Session Commands

  _s_e_s_s_i_o_n cclloosseeddbb
       Close the session.  Deleting the Tcl session procedure has the same
       effect.  Any outstanding transactions are rolled back.  If an error
       occurs while closing the session, the error will be returned, but the
       session proc will already have been deleted.  The underlying database
       system may or may not still have the database open, depending upon the
       error.

  _s_e_s_s_i_o_n eexxeecc _s_q_l-_c_o_m_m_a_n_d
       Execute an SQL command.  The number of rows that were affected is
       returned.  If no rows were affected, zero is returned (no error is
       generated).  This command cannot be used to execute any command that
       returns data, such as select.  It must not be used to execute the ccoomm--
       mmiitt or rroollllbbaacckk SQL commands, which would lead to inconsistent state
       between the Tcl cursor commands and open SQL cursors.  (Use the ccoommmmiitt
       and rroollllbbaacckk session commands, instead.)

  _s_e_s_s_i_o_n ooppeenn ?--uuppddaattee? _c_u_r_s_o_r-_h_a_n_d_l_e _s_e_l_e_c_t-_s_t_m_t
       Open a cursor for the given SQL _s_e_l_e_c_t-_s_t_m_t. If the cursor creation is
       successful, a Tcl procedure named _c_u_r_s_o_r-_h_a_n_d_l_e is created, which is
       used to read rows from the result.  The cursor name is returned.  Up
       to 16 cursors may be open at once.  By default, cursors are opened
       read-only.  Specify the --uuppddaattee option to enable updating of the data.

  _s_e_s_s_i_o_n ccoommmmiitt
       Commit the transaction in progress.  All cursors are closed.

  _s_e_s_s_i_o_n rroollllbbaacckk
       Abort the transaction in progress.  All cursors are closed.

  _s_e_s_s_i_o_n vveerrssiioonn
       Determine the version of the database that this session is connected
       to.  The result is a two-element list, consisting of the name of the
       database system and the version (format specific to the database sys-
       tem.)

Cursor Subcommands
  Once a cursor has been opened, the cursor procedure may be invoked to
  retrieve data.  Cursor subcommands may be used to obtain information about
  the cursor and the data it returns.

  SQL has specialized data types for representing dates and money.  These are
  returned in Tcl as character strings and floating-point numbers.

  It is important to remember that the ccoommmmiitt and rroollllbbaacckk commands close all
  open cursors, deleting the cusor procedure(s).  If an SQL error occurs
  while processing the cursor procedure, the SQL error is returned and the
  cursor is closed.  It is up to the user, however, to call rroollllbbaacckk or ccoomm--
  mmiitt to terminate the transaction.

  _c_u_r_s_o_r
       Return the next row in the result as a properly formatted Tcl list.
       After the last row, an empty string is returned.  However, the cursor
       must still be closed.

  _c_u_r_s_o_r uuppddaattee "_t_a_b_l_e SET _c_o_l=_e_x_p_r, _c_o_l=_e_x_p_r..."
       Updates the current row (that the cursor just returned) in the speci-
       fied _t_a_b_l_e, setting the columns to the values given.  Note that the
       entire update statement (from _t_a_b_l_e on) must be a single argument.
       This is just shorthand for executing the SQL command:
       UPDATE _t_a_b_l_e SET _c_o_l=_e_x_p_r, _c_o_l=_e_x_p_r... WHERE CURRENT OF _c_u_r_s_o_r

  _c_u_r_s_o_r ddeelleettee _t_a_b_l_e
       Deletes the current row (that the cursor just returned) in the speci-
       fied _t_a_b_l_e.  This is just shorthand for executing the SQL command:
       DELETE FROM _t_a_b_l_e WHERE CURRENT OF _c_u_r_s_o_r

  _c_u_r_s_o_r cclloossee
       Close the cursor.  Deleting the Tcl cursor procedure has the same
       effect.

  _c_u_r_s_o_r rreeooppeenn
       Close and reopen the cursor.  The rows in the cursor will be read
       again, starting at the beginning.

  _c_u_r_s_o_r nnaammeess
       Returns a list of the SQL column names for the cursor.

  _c_u_r_s_o_r wwiiddtthhss
       Returns a list of column widths appropriate for formatting the cursor
       result.

  _c_u_r_s_o_r ttyyppeess
       Returns a list of column types.  The types that may be returned are:
       {{iinntteeggeerr _N_N}} (1, 2, 4, 8); {{iinntteeggeerr _N_N _S_S}} NN=(1, 2, 4, 8), SS=decimal
       scaling; {{ffllooaatt _N_N}} (4, 8); {{cchhaarr _N_N}} and {{vvaarrcchhaarr _N_N}} where _N_N is the
       number of characters in the field.  Each type is a two-element list
       consisting of the base type and the number of bytes used to represent
       it.  The data type returned is the converted type.  Because this pack-
       age automatically converts date and money types to char and float,
       those types will never be returned.

  _c_u_r_s_o_r ccoouunntt
       Returns the number of rows retrieved from the cursor, so far.


SQL Errors
  All SQL errors are returned to the user as Tcl errors, with the text of the
  SQL error message forming the Tcl error message.  The Tcl error code is set
  to a three-element list consisting of the string ssqqll, the SQL error number,
  and the sql error message.

  Some massaging is done to the error message, to strip off timestamps and
  extra newlines.

  When an SQL error occurs, the transaction is still pending.  It is up to
  the user to commit or roll back the transaction.  The usual action after an
  error is to roll back the transaction and return the error to higher
  layers.


Transactions (Commit and Rollback)
  In ANSI SQL, transactions are always enabled.  COMMIT must be used to con-
  firm the operations in a transaction and make them "real".  Alternatively,
  ROLLBACK can be used to cancel all outstanding operations.

  Some databases allow modes where transactions are only used when you ask
  for them.  The BEGIN WORK command marks the beginning of a transaction, and
  COMMIT/ROLLBACK applies only to the operations since the BEGIN WORK com-
  mand.  Operations performed outside of a transaction happen immediately.

  Some databases do not use transactions at all.  In those environments, the
  COMMIT and ROLLBACK commands do not work, and will produce an error.



Restrictions
  Binary Large Objects (BLOBs) are not supported.

  Null values in the database are rendered as the empty string for character
  data types, "0" for integer data types, and "0.0" for floating point data
  types.

  Up to 16 cursors may be open at once.  (Some SQL installations may have a
  lower limit.)

  A cursor is limited to 128 result columns.


Ingres Notes
  All ingres data types as of Release 6.4 are supported.

  Ingres does not support creation and deletion of databases through SQL.
  Use the shell programs ccrreeaatteeddbb and ddeessttrrooyyddbb.

  Ingres always uses transactions.  The BEGIN WORK command doesn't even
  exist.


Rdb Notes

  The syntax for ssqqll__ooppeennddbb can be quite complex.  The simple form associates
  a single database with the session:

  ssqqll__ooppeennddbb _h_a_n_d_l_e _d_b-_s_p_e_c
       _d_b-_s_p_e_c is an usually an "attach-expression", which is usually
       "ffiilleennaammee _a_t_t_a_c_h-_s_p_e_c".  In the simplest case, _a_t_t_a_c_h-_s_p_e_c is just the
       name of a local file containing a database.  For more details, see
       Rdb's syntax for the ATTACH command.

  ssqqll__ooppeennddbb _h_a_n_d_l_e DDEEFFAAUULLTT
       will open a connection to the database server with no database
       attached.  This allows you to create a database without having one to
       connect to:

            sql_opendb h default
            h exec "create database filename /usr/tmp/test.rdb"
            h closedb
            sql_opendb h "filename /usr/tmp/test.rdb"


  The more complex form allows multiple databases to be accessable within a
  single session.  Remember that you can still have multiple sessions.

  ssqqll__ooppeennddbb _h_a_n_d_l_e {_a_l_i_a_s _d_b-_s_p_e_c} {_a_l_i_a_s _d_b-_s_p_e_c}...
       _d_b-_s_p_e_c is as it was in the simple case -- each specifies a database
       to open.  The _a_l_i_a_s is used to identify the database when working with
       the session.  For example, a select statement might look like: "SELECT
       col1, col2 from _a_l_i_a_s.table1".

  Rdb always uses transactions.  The BEGIN WORK command doesn't even exist.

  Rdb's integer types support decimal scaling.  This is rendered with full
  precision (including trailing zeros) on output.


  Rdb's DECIMAL data type is not supported.

  Rdb's DATE type is rendered as a character string, which results in an 8-
  character all-numeric string of the form "YYYYMMDD".


  The SQL data types SEGMENTED STRING and VARBYTE are not supported.  Both of
  these are BLOBs.

  DATETIME and INTERVAL are not also not supported, due to lack of access to
  documentation.

  The vveerrssiioonn command doesn't return a useful version number, due to lack of
  access to documentation.


Informix Notes
  In order to use the SQL package, the INFORMIXDIR environment variable must
  be set.  Attempts to use ssqqll__ooppeennddbb will fail with an appropriate error
  message.  You can set INFORMIXDIR at the beginning of your script with the
  command "set env(INFORMIXDIR) /usr/local/informix".

  Informix's _d_b-_s_p_e_c is usually either _d_b-_n_a_m_e or _d_b-_n_a_m_e@_d_b-_s_e_r_v_e_r.  You can
  connect to a server, with no associated database, using the syntax @_d_b-
  _s_e_r_v_e_r.  This allows you to create a database without having one to connect
  to.  In fact, it appears that the CREATE DATABASE command can oonnllyy be used
  when connected to a server only, without a connection to an explicit data-
  base.

  With Informix, ssqqll__ooppeennddbb supports a user authentication option.

  ssqqll__ooppeennddbb ?--uusseerr _u_s_e_r _p_a_s_s_w_o_r_d? _s_e_s_s_i_o_n-_h_a_n_d_l_e _d_b-_s_p_e_c
       _u_s_e_r and _p_a_s_s_w_o_r_d specify the user name and password to use to connect
       to the database.

  Informix (as of 7.10) doesn't support multiple connections to a server when
  shared memory is used as the transport.  Informix will return an error if a
  second connection is attempted to the same server.

  Database connections are opened with the WITH CONCURRENT TRANSACTION
  option.  As mentioned above, this means that it is possible to create
  deadlocks when switching between connections to the same database.

  Informix's dynamic SQL syntax is not capable of declaring a cursor FOR
  UPDATE or FOR READONLY.  Non-ANSI databases' cursors are read-only by
  default and ANSI databases' cursors are updatable by default, if they meet
  certain criteria.  Because of this, the --uuppddaattee option to the ooppeenn command
  has no actual effect, and a cursor is updatable soley based upon whether
  the database is ANSI or not.  If --uuppddaattee is used on a non-ANSI database, an
  error will be returned.

  By default, Informix databases doesn't use transactions.  Databases created
  with default options do not support transactions.  Specifying WITH LOG or
  WITH LOG MODE ANSI in the CREATE DATABASE command will enable logging for
  that database.  When using the Informix SE server, the START DATABASE com-
  mand can be used change the logging mode on an existing database.

  To cope with these irregularities, two additional session commands, iiss__aannssii
  and hhaass__lloogg, are provided, which return 1 if the database has that charac-
  teristic and 0 if not.

  At initialization, $env(DBDATE) is set in Tcl's environment to force the
  formate for DATE data to be "YYYY-MM-DD" (numeric).

  DATETIME uses the same format:  "YYYY-MM-DD HH:MM:SS.FFFFF", except that
  only the parts appropriate to the specific data type are included, and any
  leading extended field is widened.  _e._g., DATETIME MONTH(3) TO MINUTE would
  be rendered as "MMM-DD HH:MM".

  INTERVAL uses the same format as DATETIME, except that Informix supresses
  leading zero fields with spaces.

  The SQL data types BYTES and TEXT are not supported.  (Both of these are
  BLOBs).


Installation
  This distribution consists of a primary source and header files,
  tcl_sql.sc.in and tcl_sql.h, and an additional source and header file for
  each supported database system.  The embedded SQL files must be run through
  an Embedded SQL preprocessor (specific to the DB system).  The Makefile is
  generated by the ccoonnffiigguurree script, and will contain the correct commands
  for database-specific processing.

  The extension must be initialized by calling Sql_Init(_i_n_t_e_r_p).  Typically,
  this call will be made within the Tcl_AppInit() routine.  Besides linking
  in the libtcl_sql__d_b_t_y_p_e.a library, all of the libraries required by the
  SQL database system must also be linked in.

  See the RREEAADDMMEE file for full details.


Author
  Glenn Trewitt, Digital Equipment Corporation, Network Systems Laboratory












































