


Sybtcl(n)              Tcl Sybase Extension             Sybtcl(n)


NNAAMMEE
       Sybtcl - Sybase SQL Server access commands for Tcl

IINNTTRROODDUUCCTTIIOONN
       Sybtcl  is  a  collection of Tcl commands and a Tcl global
       array that provides  access  to  a  Sybase  Server.   Each
       Sybtcl  command  generally  invokes  several  Sybase  Open
       Client (a.k.a. DB-Library) library functions.  Programmers
       using  Sybtcl should be familar with basic concepts of DB-
       Library programming.


SSYYBBTTCCLL CCOOMMMMAANNDDSS
       ssyybbccoonnnneecctt  _l_o_g_i_n_-_n_a_m_e  _p_a_s_s_w_o_r_d   _?_s_e_r_v_e_r_?   _?_a_p_p_n_a_m_e_?
              _?_i_f_i_l_e_? _?_c_h_a_r_s_e_t_?
              Connect to a Sybase  server  using  _l_o_g_i_n_-_n_a_m_e  and
              _p_a_s_s_w_o_r_d.   If _s_e_r_v_e_r is specified, then an attempt
              will be made to login to the named  Sybase  server.
              If  _s_e_r_v_e_r  is  not specified, then the environment
              variable _D_S_Q_U_E_R_Y is used to determine a server;  if
              _D_S_Q_U_E_R_Y  is not set, sybconnect will try to connect
              to the Sybase server named _S_Y_B_A_S_E.  If  an  _a_p_p_n_a_m_e
              is  specified,  then  that  value  is passed to the
              server to display during a process list.  If  _i_f_i_l_e
              is  specified,  that file is used to resovle server
              addresses;   if   not   specified,    the    normal
              $SYBASE/interfaces  file  is  used.   If _c_h_a_r_s_e_t is
              specified, the charset  should  reference  a  vaild
              character  set  available  on your Sybase installa-
              tion.   See  the  $SYBASE/charsets  directory   for
              charsets supported on your installation.

              _L_o_g_i_n_-_n_a_m_e  and  _p_a_s_s_w_o_r_d  are required parameters.
              All  other  parameters  are  optional   postitional
              parameters.   For  example,  to  specify  the _i_f_i_l_e
              paramater, _s_e_r_v_e_r and _a_p_p_n_a_m_e must also  be  speci-
              fied.  Optional parameters may be a null string, in
              which case the default value is used.

              A handle is returned and should  be  used  for  all
              other  Sybtcl commands using this connection.  Mul-
              tiple connections to the same or different  servers
              are  allowed,  up  to a maximum of 50 total connec-
              tions.  Sybconnect raises a Tcl error if  the  con-
              nection  is not made for any reason (login or pass-
              word incorrect, server  not  found  in  the  Sybase
              interfaces file, network unavailable, etc.).


       ssyybbeerrrrhhaannddlleerr _?_t_c_l_p_r_o_c_?
              Set  a  Tcl  procedure to be called upon any DB-Lib
              error.  The Tcl procedure should  exist,  and  take
              the following arguments to the procedure:




Sybtcl                         3.0                              1





Sybtcl(n)              Tcl Sybase Extension             Sybtcl(n)


              _h_a_n_d_l_e
                     The  Sybtcl handle associated with the error
                     condition.  Handle may  be  a  null  string,
                     such  as  in  the case of an error occurring
                     during sybconnect.

              _s_e_v_e_r_i_t_y
                     The Sybase severity level of the error.

              _d_b_e_r_r  The Sybase DB-Lib error code.

              _o_s_e_r_r  The operating system error code.

              _d_b_e_r_r_s_t_r
                     The DB-Lib error string associated with  the
                     error code.

              _o_s_e_r_r_s_t_r
                     The operating system error string associated
                     with the error.
       Example:

            proc  err_handler  {handle   severity   dberr   oserr
       dberrstr oserrstr} {
                 puts  "error:  $handle  $severity  $dberr $oserr
       $dberrstr $oserrstr"
                return 1
            }
            syberrhandler err_handler

       The procedure may also return an integer value to indicate
       an action to perform:

              "0"    print  an  error message and abort the  pro-
                     gram immediately.

              "1"    continue by returning a "FAIL" condition  to
                     the currently executing DB-Lib function.

              "2"    cancel  the  operation that caused the error
                     if a result of a timeout condition.  For any
                     other case, this value is considered as "0",
                     immediate program termination.

              "3"    continue to wait for one additional time out
                     period  if  a result of a timeout condition.
                     For any other case, this value is considered
                     as "0", immediate program termination.
       If  no  value  is  returned, or any other value is return,
       Sybtcl treats the return value as "1" (continue).

       Syberrhandler called without an argument returns the  cur-
       rent  error  handler.   If  called with a null string, the
       error handler is disabled.



Sybtcl                         3.0                              2





Sybtcl(n)              Tcl Sybase Extension             Sybtcl(n)


       ssyybbmmssgghhaannddlleerr _?_t_c_l_p_r_o_c_?
              Set a Tcl procedure to be called  upon  any  server
              message.   The Tcl procedure should exist, and take
              the following arguments to the procedure:

              _h_a_n_d_l_e
                     The Sybtcl handle associated with the  error
                     condition.

              _m_s_g_n_o  The Sybase server message number.

              _m_s_g_s_t_a_t_e
                     The Sybase server message state.

              _s_e_v_e_r_i_t_y
                     The Sybase severity level of the error.

              _m_s_g_t_e_x_t
                     The server message text.

              _s_v_r_n_a_m_e
                     The  name  of the server generating the mes-
                     sage.

              _p_r_o_c_n_a_m_e
                     The name of  the  procedure  generating  the
                     message, if any.

              _l_i_n_e   The  line  numer of the procedure generating
                     the message, if any.
       Example:

            proc msg_handler {handle msgno msgstate severity msg-
       text svrname procname line} {
                 puts  "msg:  $handle  $msgno $msgstate $severity
       $msgtext $svrname $procname $line"
            }
            syberrhandler msg_handler

       Sybghandler called without an argument returns the current
       message  handler.   If called with a null string, the mes-
       sage handler is disabled.


       ssyybbuussee _h_a_n_d_l_e _?_d_b_n_a_m_e_?
              Return the database  name  currently  in  use.   If
              _d_b_n_a_m_e  is specified, then attempt to use the named
              database.  _H_a_n_d_l_e must be a valid handle previously
              opened with sybconnect.  If _d_b_n_a_m_e is used success-
              fully, the dbname is returned.  Sybuse raises a Tcl
              error  if  the  handle specified is not open or the
              database name specified could not be used.





Sybtcl                         3.0                              3





Sybtcl(n)              Tcl Sybase Extension             Sybtcl(n)


       ssyybbssqqll _h_a_n_d_l_e _s_q_l_-_c_o_m_m_a_n_d _?_-_a_s_y_n_c_?
              Send the Sybase Transact SQL statements _s_q_l_-_c_o_m_m_a_n_d
              to  the server.  _H_a_n_d_l_e must be a valid handle pre-
              viously opened with sybconnect.   If  the  optional
              argument  --aassyynncc is specified, then the SQL is sent
              to the server without waiting for  a  response  and
              sybsql  will  return  immediately  with  the  value
              "PENDING".  The sybpoll  command  can  be  used  to
              check  the  status  of  the server results; sybnext
              must be called to determine  if  result  rows  were
              generated.   If --aassyynncc is omitted, then sybsql will
              wait until the server has  responed.   Sybsql  will
              return  "REG_ROW"  if  the SQL statements generated
              return rows, "NO_MORE_ROWS"  if  the  SQL  commands
              executed, but no rows were returned in the first or
              only set of results.  The ssyybbmmssgg array  index  _r_e_t_-
              _s_t_a_t_u_s is set with the return code of a stored pro-
              cedure, if any; the _n_e_x_t_o_w index is also set to the
              value returned by sybsql.

              Multiple  SQL  statements  may be specified in _s_q_l_-
              _c_o_m_m_a_n_d.  _S_y_b_n_e_x_t allows retrieval of  return  rows
              generated; _S_y_b_r_e_t_v_a_l allows retrieval of any return
              values from stored procedures.  See notes regarding
              stored procedure output variables.

              Sybsql   performs  an  implicit  _s_y_b_c_a_n_c_e_l  if  any
              results are still pending from the  last  execution
              of sybsql.  Sybsql raises a Tcl error if the handle
              specified is not open, or if the SQL  commands  are
              syntactically incorrect.

              Table  inserts  made with sybsql should follow con-
              version rules in the Sybase Commands Reference man-
              ual  (image  or  binary  data is hexadecimal string
              preceded with "0x"; datetime should be a  recogniz-
              able  date,  etc.   The SQL Server CONVERT function
              may be used to force conversions.


       ssyybbppoollll _h_a_n_d_l_e _?_t_i_m_e_o_u_t_? _?_-_a_l_l_?
              Return a list of Sybtcl handles that  have  results
              waiting.   _H_a_n_d_l_e must be a valid handle previously
              opened with sybconnect.  If the  last  SQL  results
              are  not  ready,  a  null  string  is returned.  An
              optional _t_i_m_e_o_u_t value in milliseconds may be spec-
              ified, which is the amount of time the sybpoll will
              wait before returning a  result.   If  the  timeout
              value  is  -1,  sybpoll will wait until results are
              available before returning.   The  default  timeout
              value is 0, which polls and immediately returns.

              The option _-_a_l_l may be specified, in which all han-
              dles  that  have  been  executed  with  -async  are



Sybtcl                         3.0                              4





Sybtcl(n)              Tcl Sybase Extension             Sybtcl(n)


              checked,  and  a  Tcl list of all handles that have
              results waiting are returned.  When  _-_a_l_l  is  com-
              bined  with  a  timeout  of  -1, then sybpoll waits
              until any async handle  has  results  waiting,  and
              then  returns  a  list  of  all  handles  that have
              results waiting.  If the last SQL  statements  exe-
              cuted with _h_a_n_d_l_e were not sent as -async with syb-
              sql, sybpoll returns a null string.


       ssyybbeevveenntt _h_a_n_d_l_e _?_s_c_r_i_p_t_?
              Arrange to run a script when server data is  avail-
              able.   _H_a_n_d_l_e  must  be  a valid handle previously
              opened with sybconnect.  _S_y_b_s_q_l  must  have  previ-
              ously  been  executed,  without  or  without _-_a_s_y_n_c
              mode.  The event handler script should execute _s_y_b_-
              _n_e_x_t in order to process available data.  The event
              handler may be executed during any phase of  result
              processing   including   REG_ROW,   compute   rows,
              NO_MORE_ROWS, and NO_MORE_RESULTS.

              If _?_s_c_r_i_p_t_? is not specified,  the  existing  event
              handler  script is returned.  If _?_s_c_r_i_p_t_? is a null
              string, the event handler is  removed.   The  event
              handler  is  also removed at end of all results for
              the current SQL statement.

              For the event handler  to  actually  run,  the  Tcl
              interpreter  must be processing events.  Events can
              be processed on demand by executing the Tcl  uuppddaattee
              command,  or until a variable is set with the vvwwaaiitt
              command.  Events are  also  processed  while  a  Tk
              (wish) program is waiting on user input.

              Sybtcl's  callback  handler is greedy; it continues
              to invoke the sybevent script while data  rows  are
              available.   To  allow  other Tcl events to be pro-
              cessed, set _s_y_b_m_s_g_(_b_g_e_v_e_n_t_s_) to iiddlleettaasskkss or aallll.


       ssyybbnneexxtt _h_a_n_d_l_e _?_c_o_m_m_a_n_d_s_? _?_s_u_b_s_t_i_t_u_t_i_o_n___c_h_a_r_a_c_t_e_r_? _?_t_c_l_v_a_r
              _c_o_l_n_u_m _._._._?
              Return the next row from the  last  SQL  statements
              executed with sybsql as a Tcl list.  _H_a_n_d_l_e must be
              a valid handle previously opened  with  sybconnect.
              Sybnext  raises a Tcl error if the handle specified
              is not open.  A null string is  returned  if  there
              are  no  more  rows  in the current set of results.
              The Tcl list that is returned by  sybnext  contains
              the  values  of  the  selected columns in the order
              specified by _s_e_l_e_c_t.

              If the  SQL  statements  where  executed  with  the
              -async  option  of  sybsql,  then sybnext will wait



Sybtcl                         3.0                              5





Sybtcl(n)              Tcl Sybase Extension             Sybtcl(n)


              until results are available.  Sybpoll may  be  used
              to check for results in a non-blocking manner.  Any
              errors in the SQL statements will cause sybnext  to
              fail.

              The  optional  _c_o_m_m_a_n_d_s  argument allows sybnext to
              repeatedly fetch rows and execute _c_o_m_m_a_n_d_s for each
              row.   Substitutions  are  made  on _c_o_m_m_a_n_d_s before
              passing it to Tcl_Eval() for each row.  An optional
              argument  consisting  of  a single character can be
              specified for a column number substitution  charac-
              ter.   If none is specified, the character '@' will
              be used to denote the substitution  character.   If
              the  substitution  character  is  a null string, no
              column substitutions will be performed on the  _c_o_m_-
              _m_a_n_d_s  string.  Sybnext interprets the substitution
              character followed by a number (@@nn) in _c_o_m_m_a_n_d_s  as
              a  result  column  specification.  For example, @@11,,
              @@22,, @@33  refer  to  the  first,  second,  and  third
              columns  in  the  result.   @@00 refers to the entire
              result row, as a Tcl  list.   Substitution  columns
              may  appear  in any order, or more than once in the
              same command.   Substituted  columns  are  inserted
              into  the  _c_o_m_m_a_n_d_s string as proper list elements,
              i.e., one space will be added before and after  the
              substitution and column values with embedded spaces
              are enclosed by {} if needed.

              Tcl variables may also be set for _c_o_m_m_a_n_d_s on  each
              row that is processed.  Tcl variables are specified
              after  the  _s_u_b_s_t_i_t_u_t_i_o_n___c_h_a_r_a_c_t_e_r,  consisting  of
              matching  pairs  of Tcl variable names and a column
              numbers.  Column number may be "0",  in  which  the
              Tcl  variable  is set to the entire result row as a
              Tcl list.  Column numbers  must  be  less  than  or
              equal  to  the  number of columns in the SQL result
              set.

              Tcl variable column pairs may also be specified  as
              a list argument.

              Sybnext  will  execute _c_o_m_m_a_n_d_s until NO_MORE_ROWS.
              If additional results are pending, subsequent  syb-
              next   commands  will  retrieve  the  next  set  of
              results.

              A Tcl error is raised if a column substitution num-
              ber  is  greater  than the number of columns in the
              results.  Note that Transact-SQL  "compute"  state-
              ments  are  considered  to  be  part of the current
              select's result set, and thus, a  different  number
              of  columns  may  be  returned, causing the sybnext
              column substitution to fail when the compute row is
              returned.   If  the commands execute bbrreeaakk, sybnext



Sybtcl                         3.0                              6





Sybtcl(n)              Tcl Sybase Extension             Sybtcl(n)


              execution is interrupted and returns  with  TCL_OK.
              Remaining  rows  may  be  fetched with a subsequent
              sybnext command.  If the commands execute rreettuurrnn or
              ccoonnttiinnuuee,  the  remaining  commands are skipped and
              sybnext execution  continues  with  the  next  row.
              Sybnext  will  raise  a  Tcl  error if the _c_o_m_m_a_n_d_s
              return an error.  Commands should be enclosed in ""
              or {}.

              The  ssyybbmmssgg  array  index _r_e_t_s_t_a_t_u_s is set with the
              return code of a stored procedure, if one was  exe-
              cuted  in the last SQL command to sybsql; the index
              _n_e_x_t_r_o_w is set to one of several values,  depending
              on  the  results  of sybnext.  Refer to the section
              "SERVER MESSAGE AND ERROR INFORMATION" for informa-
              tion about how the _n_e_x_t_r_o_w value is set.

              When  _s_y_b_m_s_g  array  element  _b_i_n_a_r_y_a_s_h_e_x is set to
              '1', 'yes', or 'true', sybnext performs conversions
              for  image  and binary data.  Data is returned as a
              hexadecimal string, without a  leading  "0x".   Use
              the SQL Server function CONVERT to force a specific
              conversion.

              The ssyybbmmssgg array index _m_a_x_t_e_x_t limits the amount of
              text   or  image  data  returned  for  each  column
              returned.  The default is 32768 bytes.

              The ssyybbmmssgg array index  _n_u_l_l_v_a_l_u_e  can  be  set  to
              specify  the  value returned when a column is null.
              The default is "0" for numeric  data,  and  ""  for
              other datatypes.


       ssyybbccoollss _h_a_n_d_l_e
              Return  the names of the columns from the last syb-
              next or sybretval command as a Tcl  list.   Sybcols
              returns the column name used in the SQL select com-
              mand; a null string  for  any  column  that  is  an
              aggregate function (count, sum, avg, min, max) in a
              regular row.  A compute row column name is returned
              as  _f_u_n_c_t_i_o_n_(_c_o_l_u_m_n_-_n_a_m_e_).   Sybcols  may  be  used
              after _s_y_b_r_e_t_v_a_l, in which the output variable names
              are returned (see notes).

              The  ssyybbmmssgg  array index _c_o_l_l_e_n_g_t_h_s is set to a Tcl
              list corresponding to the lengths of  the  columns;
              index  _c_o_l_t_y_p_e_s  is set to a Tcl list corresponding
              to the types of the columns.  Sybcols raises a  Tcl
              error if the handle specified is not open.


       ssyybbccaanncceell _h_a_n_d_l_e
              Cancel  any  pending  results  from the last sybsql



Sybtcl                         3.0                              7





Sybtcl(n)              Tcl Sybase Extension             Sybtcl(n)


              command.  _H_a_n_d_l_e must be a valid handle  previously
              opened  with  sybconnect.   Sybcancel  may  be used
              before sybnext  exhausts  all  results.   Sybcancel
              raises  a  Tcl error if the handle specified is not
              open.


       ssyybbrreettvvaall _h_a_n_d_l_e
              Return a Tcl list  of  the  return  values  from  a
              stored  procedure.   _H_a_n_d_l_e  must be a valid handle
              previously opened with  sybconnect.   If  a  stored
              procedure also returns rows, sybnext must have pre-
              viously been called until NO_MORE_ROWS was  encoun-
              tered  before  sybretval can access the return val-
              ues.  The ssyybbmmssgg array index _r_e_t_s_t_a_t_u_s contains the
              return  code  from the stored procedure.  Sybretval
              raises a Tcl error if the handle specified  is  not
              open.   See notes regarding stored procedure output
              variables.


       ssyybbwwrriitteetteexxtt _h_a_n_d_l_e _o_b_j_e_c_t _c_o_l_n_u_m _[  _-_v_a_r_i_a_b_l_e  _v_a_r_n_a_m_e  _|
              _-_f_i_l_e _f_i_l_e_n_a_m_e _| _f_i_l_e_n_a_m_e _] _?_-_n_o_l_o_g_?
              Write the contents of a variable or file to a  TEXT
              or  IMAGE  column.   _H_a_n_d_l_e  must be a valid handle
              previously opened with sybconnect.  _O_b_j_e_c_t  is  the
              table  and  column name in the format ttaabbllee..ccoolluummnn.
              _C_o_l_n_u_m is the relative position of the column  from
              the  last  sseelleecctt.   _v_a_r_n_a_m_e  is  the name of a Tcl
              variable containing data, or _f_i_l_e_n_a_m_e is  the  name
              of the file that contains the text or image data to
              write into the column.  Text and image  writes  are
              logged  by default, --nnoolloogg may be specified to dis-
              able logging (the  database  must  have  previously
              been  set with a no log option.)  If neither --vvaarrii--
              aabbllee or --ffiillee is specified, the argument is  inter-
              preted as a filename.

              Sybwritetext   can  only  be  used  in  a  specific
              sequence with other sybsql commands.  Refer to  the
              Sybase  DB-Library  documentation for dbwritetext()
              and the DB-Library Reference Supplement  discussion
              on text/image handling.

              For  example (assume $hand is an open handle, using
              the "pubs" database):

                   ssyybbssqqll $$hhaanndd ""iinnsseerrtt iinnttoo aauu__ppiixx ((aauu__iidd))  vvaall--
              uueess ((''111111--2222--33333333''))""
                   ssyybbssqqll  $$hhaanndd  ""uuppddaattee  aauu__ppiixx  sseett ppiicc == nnuullll
              wwhheerree aauu__iidd == ''111111--2222--33333333''""
                   ssyybbssqqll $$hhaanndd ""sseelleecctt  ppiicc  ffrroomm  aauu__ppiixx  wwhheerree
              aauu__iidd == ''111111--2222--33333333''""
                   ssyybbwwrriitteetteexxtt  $$hhaanndd  aauu__ppiixx..ppiicc  11  iimmaaggee..ffiillee



Sybtcl                         3.0                              8





Sybtcl(n)              Tcl Sybase Extension             Sybtcl(n)


              --nnoolloogg

              An update to an existing text or image  column  can
              be  made using the last two commands from the above
              example.  Sybwritetext  returns  a  integer  number
              upon  successful  completion of the number of bytes
              written to the text/image column.

              Sybwritetext raises a Tcl error for  a  variety  of
              reasons:  filename could not be opened or a failure
              in internal DB-Library routines.   Common  failures
              are  specifing  --nnoolloogg  when  the database does not
              support  nolog;  unable  to  access  a  valid  text
              pointer  due to invalid oobbjjeecctt or ccoollnnuumm; sybwrite-
              text used out of sequence.  Consult ssyybbmmssgg((mmssggtteexxtt))
              or  ssyybbmmssgg((ddbbeerrrrssttrr))  for information after a fail-
              ure.


       ssyybbrreeaaddtteexxtt _h_a_n_d_l_e _[ _-_v_a_r_i_a_b_l_e _v_a_r_n_a_m_e _| _-_f_i_l_e _f_i_l_e_n_a_m_e  _|
              _f_i_l_e_- _n_a_m_e _]
              Read the contents of a TEXT  or  IMAGE  column  and
              write  results  into  a variable or a file.  _H_a_n_d_l_e
              must be a valid handle previously opened with  syb-
              connect.  _v_a_r_n_a_m_e is the name of a Tcl variable, or
              _F_i_l_e_n_a_m_e is the name of a file in  which  to  write
              the  text  or  image data.  Sybreadtext can only be
              used after the successful sseelleecctt of a  single  text
              or  image column.  If neither --vvaarriiaabbllee or --ffiillee is
              specified, the argument is interpreted as  a  file-
              name.  For example (assume $hand is an open handle,
              using the "pubs" database):

                   ssyybbssqqll $$hhaanndd ""sseelleecctt ccooppyy  ffrroomm  bblluurrbbss  wwhheerree
              aauu__iidd == ''448866--2299--11778866''""
                   ssyybbrreeaaddtteexxtt $$hhaanndd bblluurrbb..ttxxtt

              Sybreadtext  returns a decimal number upon success-
              ful completion of the number of bytes read from the
              text/image  column.  Sybreadtext returns "0" if the
              last select returned more than one column or no row
              was returned.

              The ssyybbmmssgg array index _m_a_x_t_e_x_t limits the amount of
              text or image data that can be written to a file by
              sybreadtext.  The default is 32768 bytes.

              Sybreadtext  raises  a  Tcl  error for a variety of
              reasons:  filename could not be opened, sybreadtext
              used out of sequence, etc.


       ssyybbcclloossee _h_a_n_d_l_e
              Closes   the   server  connection  associated  with



Sybtcl                         3.0                              9





Sybtcl(n)              Tcl Sybase Extension             Sybtcl(n)


              _h_a_n_d_l_e.  _H_a_n_d_l_e must be a valid  handle  previously
              opened  with  sybconnect.   Sybclose returns a null
              string.  Sybclose raises a Tcl error if the  handle
              specified is not open.


SSEERRVVEERR MMEESSSSAAGGEE AANNDD EERRRROORR IINNFFOORRMMAATTIIOONN
       Sybtcl creates and maintains a Tcl global array to provide
       feedback of Sybase server messages, named ssyybbmmssgg.   Sybmsg
       is also used to communicate with the sybtcl interface rou-
       tines to specify null return values and text/image limits.
       In  all  cases except for _n_u_l_l_v_a_l_u_e, _f_i_x_e_d_c_h_a_r, _f_l_o_a_t_p_r_e_c,
       _d_a_t_e_f_o_r_m_a_t, _b_g_e_v_e_n_t_s,  _b_g_p_o_l_l_i_n_t_e_r_v_a_l  and  _m_a_x_t_e_x_t,  each
       element  is  reset  to  null upon invocation of any sybtcl
       command, and any element affected by the command  is  set.
       The  sybmsg array is shared among all open sybtcl handles.
       Sybmsg should be defined with the global statement in  any
       Tcl procedure needing access to sybmsg.

       Sybmsg elements:


       vveerrssiioonn
              is set to the version of Sybtcl.


       nnuullllvvaalluuee
              can be set by the programmer to indicate the string
              value  returned  for  any  null  result.    Setting
              sybmsg(nullvalue)  to "default" will return "0" for
              numeric null data types (integer, float, and money)
              and  a null string for all other data types.  Null-
              value is initially set to "default".


       ffiixxeeddcchhaarr
              can be set by the programmer to indicate that char-
              acter datatypes returned by sybnext should not have
              trailing spaces trimmed from  the  value.   Setting
              sybmsg(fixedchar)  to  "1",  "true", or  "yes" will
              ensure that all trailing spaces are returned.   The
              default value ("") will cause trailing spaces to be
              trimmed.


       bbiinnaarryyaasshheexx
              can be set  by  the  programmer  to  indicate  that
              binary  data  types  (binary, image) should be con-
              verted to hexstrings.  Setting  sybmsg(binaryashex)
              to "1", "true", or  "yes" will convert binary types
              to hex strings.  The default value ("") will  cause
              binary data to be stored bit-for-bit.





Sybtcl                         3.0                             10





Sybtcl(n)              Tcl Sybase Extension             Sybtcl(n)


       ddaatteeffoorrmmaatt
              can be set by the programmer to indicate formatting
              for date data types.   The  dateformat  string  can
              contain  substitution  values or literals.  Substi-
              tions are made from the list below; other  literals
              are  copied  verbatim.   The default value is null,
              which will format dates a default format.

              YYYYYYYY
                     four digit year, 1900-

              YYYY
                     two digit year, 00-99

              MMMM
                     two digit month, 1-12

              MMOONNTTHH
                     name of month, January-December

              MMOONN
                     month abbreviation, Jan-Dec

              DDDD
                     two digit day, 1-31

              hhhh
                     two digit hour, 0-23

              mmmm
                     two digit minute, 0-59

              ssss
                     two digit second, 0-59

              mmss
                     three digit millisecond, 0-999

              ddyy
                     three digit day of year, 0-365

              ddww
                     one digit day of week, 1-7 (Mon-Sun)


       bbggeevveennttss
              can be set by the programmer to allow  or  disallow
              the  processing of Tcl events while Sybtcl is wait-
              ing for server response.  Events are processed dur-
              ing   Sybtcl  commands  that  may  wait  on  server
              responses:  sybsql (without -async option), sybnext
              (with  commands option), sybwritetest, and sybread-
              text.  The default value is "idletasks".   Possible
              values are:



Sybtcl                         3.0                             11





Sybtcl(n)              Tcl Sybase Extension             Sybtcl(n)


              iiddlleettaasskkss
                     Process only events that have been deferred,
                     such as display updates.  Similar to the Tcl
                     uuppddaattee iiddlleettaasskkss command.

              aallll
                     Process  all  events.   Similar  to  the Tcl
                     uuppddaattee command.

              nnoonnee
                     Do not process  events  during  Sybtcl  com-
                     mands.


       bbggppoolllliinntteerrvvaall
              can be set by the programmer to specify the polling
              interval in  milliseconds  while  processing  back-
              ground  events.   The  value  specified  must be an
              integer  between   1   and   1000.    The   default
              bgpollinterval value is 200.  Smaller values causes
              the polling loop to execute more frequently,  which
              may cause higer CPU usage.


       mmaaxxtteexxtt
              can be set by the programmer to limit the amount of
              text or image data returned by sybnext and sybread-
              text.   The default is 32768 bytes.  The maximum is
              2147483647 bytes.  Any value less than or equal  to
              zero  is  ignored.   Any  change to maxtext becomes
              effective on the next call to sybsql.  See notes on
              maxtext usage with sybnext.


       hhaannddllee
              indicates  the  handle  of the last sybtcl command.
              Handle is set on every sybtcl command (execpt where
              an invalid handle is used.)


       iissnnuullll
              is  a list of binary elements corresponding to each
              column element returned by sybnext.   Each  element
              is  set  to  "1"  if  the value is null, "0" if the
              value is not null.


       nneexxttrrooww
              indicates the results of the last SQL  command  and
              subsequent  next row processing.  Nextrow is set by
              sybsql and sybnext.  Possible values are:

              RREEGG__RROOWW
                     at  least  one  row   is   available   after



Sybtcl                         3.0                             12





Sybtcl(n)              Tcl Sybase Extension             Sybtcl(n)


                     execution  of sybsql, or the results of syb-
                     next returned a row as a Tcl list.

              nn
                     an integer number, which indicates that last
                     row  retrieved by sybnext returned a compute
                     row.  The value is the _c_o_m_p_u_t_e_i_d,  which  is
                     the  relative  compute statement in the last
                     SQL command executed with sybsql.

              NNOO__MMOORREE__RROOWWSS
                     indicates that sybsql executed  successfully
                     but no rows are available, or the results of
                     sybnext did not return a row.  Sybnext  will
                     return  a null string.  Return values from a
                     stored procedure, if any, are  available  at
                     this  time.  If more results are expected, a
                     subsequent execution of sybnext will  return
                     the  first row, if any, from the next set of
                     results.

              PPEENNDDIINNGG
                     indicates the last execution of  sybsql  was
                     made with the "-async" flag.  Sybpoll may be
                     used to check the status of  results.   Syb-
                     next will block until results are available.
                     When sybsql is  executed  with  -async,  any
                     errors will not be available until the first
                     execution of sybnext.

              FFAAIILL
                     indicates that a server error has  occurred.
                     Appropriate error codes and messages are set
                     in the sybmsg indices  _d_b_e_r_r  and  _d_b_e_r_r_s_t_r.
                     Sybnext  will return a null string.  If more
                     results are expected, a subsequent execution
                     of  sybnext  will  return  the first row, if
                     any, from the next set of results.

              NNOO__MMOORREE__RREESSUULLTTSS
                     indicates that the final set of results from
                     the  last execution of sybsql have been pro-
                     cessed by sybnext.

       rreettssttaattuuss
              indicates the return code after a stored  procedure
              has  executed.   Retstatus is set by sybsql or syb-
              next, whenever a the results of a stored  procedure
              are available.

       ccoolllleennggtthhss
              is  a  Tcl  list  of  the  lengths  of  the columns
              returned  by  sybcols.   Numeric  columns   (Sybase
              datatypes  int,  float,  etc.)  are  given  by  the



Sybtcl                         3.0                             13





Sybtcl(n)              Tcl Sybase Extension             Sybtcl(n)


              internal data lengths (e.g., int has  a  length  of
              4),   character  columns lengths are the maximum of
              any row returned.  Collengths is only set  by  syb-
              cols.

       ccoollttyyppeess
              is  a Tcl list of the types of the columns returned
              by sybcols.  Coltypes is only set by sybcols.  Pos-
              sible  types  returned  are:  char,  text,  binary,
              image,  tinyint,  smallint,   int,   float,   real,
              numeric, decimal, bit, money, smallmoney, datetime,
              smalldatetime.  Varchar and  varbinary  data  types
              are reported as char and binary.

       mmssggnnoo
              indicates  the  message number from a Sybase Server
              message.  Can be set by any sybtcl command.   Refer
              to  Sybase documentation for interpretation.  Since
              each sybtcl command may invoke several DB-Lib  rou-
              tines,  there is a possiblity that several messages
              may be received from the server.  Sybtcl will  con-
              catenate all server message numbers received during
              one sybtcl command, separating  individual  numbers
              by newlines.

       mmssggtteexxtt
              the message text associated with msgno.  Since each
              sybtcl command may invoke several DB-Lib  routines,
              there  is a possiblity that several messages may be
              received from the server.  Sybtcl will  concatenate
              all server messages received during one sybtcl com-
              mand, separating individual messages  by  newlines.
              Output  from  Transact-SQL PRINT statments are col-
              lected in msgtext.

       sseevveerriittyy
              indicates the severity level from a  Sybase  Server
              message  or  DB-Library routine.  Can be set by any
              sybtcl command.  Refer to Sybase documentation  for
              interpretation.

       ssvvrrnnaammee
              indicates the name of the Sybase Server that gener-
              ated a message.  Can be set by any sybtcl  command.

       pprrooccnnaammee
              indicates  the  name  of  the stored procedure that
              generated a message.  Only set when a stored proce-
              dure was executed.  Set by sybsql.

       lliinnee
              indicates  the  line  number  of the SQL command or
              stored procedure that generated a message.  Set  by
              sybsql.



Sybtcl                         3.0                             14





Sybtcl(n)              Tcl Sybase Extension             Sybtcl(n)


       ddbbeerrrr
              indicates  the  error  number  generated  by  a DB-
              Library routine.  Can be set by any sybtcl command.
              Refer to Sybase documentation for interpretation.

       ddbbeerrrrssttrr
              the error text associated with dberr.

       oosseerrrr
              indicates an operating system specific error number
              associated with a DB-Library error.  Can be set  by
              any sybtcl command.

       oosseerrrrssttrr
              the error text associated with oserr.


       ddbblliibbiinnffoo
              is  set  to options that were in effect with Sybtcl
              was compiled.  Possible values are:  "system10"  if
              linked  with  Sybase  System  10 DB-Libs or higher,
              "ctcompt" if compiled with the CT-Lib  compatiblity
              library.


NNOOTTEESS
       Tcl  errors  can also be raised by any sybtcl command if a
       command's internal  calls  to  DB-Library  routines  fail.
       Sybtcl  will  return  the  name of the DB-Lib routine that
       caused an error.

       When executing a stored procedure with sybsql, be sure  to
       include  in  the  SQL  commands  a "DECLARE" statement for
       local variables, and specify the local variables as  "OUT-
       PUT"  on  the "EXEC" statement.  Otherwise, sybretval will
       not be able to access the return values.   If  the  return
       variable  names  are  to  be  accessed by sybcols, use the
       assignment form of "EXEC", e.g.:

              declare @local-var datatype
              exec stored-proc @proc-var-name = @local-var output


       If  a  stored  procedure  is executed with sybsql, and the
       procedure  uses  Transact-SQL  "PRINT"  statements,  check
       $sybmsg(msgtext)  before  executing  any other Sybtcl com-
       mands.  Otherwise, the PRINT output will be  lost  on  the
       next  command.  Multiple PRINT statements are separated by
       newlines in $sybmsg(msgtext).

       Sybtcl error and message handlers simply  populate  values
       in  the  sybmsg  array.   The error handler always returns
       INT_CANCEL.




Sybtcl                         3.0                             15





Sybtcl(n)              Tcl Sybase Extension             Sybtcl(n)


       To use the --nnoolloogg feature of sybwritetext,  the  following
       option must have been set on the database:

            sspp__ddbbooppttiioonn   ''yyoouurrddbbnnaammee'',,  ''sseelleecctt  iinnttoo//bbuullkkccooppyy'',,
       ''ttrruuee''


       The limit of the number  of  simultaneous  connections  is
       artificial,  based on a fixed table in sybtcl.  Change the
       source _#_d_e_f_i_n_e _S_Y_B_T_C_L_P_R_O_C_S if more are needed.

       The maximum amount of TEXT or IMAGE data returned by  syb-
       next  is  ultimately dependent on sybtcl's ability to mal-
       loc() _m_a_x_t_e_x_t bytes of memory for each TEXT or IMAGE  col-
       umn  retrieved.   Setting  sybmsg(maxtext)  to  too high a
       value may cause core dumps or memory shortages.   Sybread-
       text  does  not malloc() an area to hold the entire value;
       instead it retrieves TEXT and IMAGE in chunks  and  writes
       to  a  file.   While  maxtext  limits  the  amount of data
       retrieved by sybreadtext, it shouldn't cause memory short-
       ages as sybnext might.

       When  using  sybnext  with the optional tcl-commands argu-
       ment, a substantial performance improvement can  be  real-
       ized  by  not using the substitution values (@1, @2, etc.)
       Instead, specify the  substitution  character  as  a  null
       string {}, and use the tclvar-columnum argument pairs.


EENNVVIIRROONNMMEENNTT VVAARRIIAABBLLEESS
       DSQUERY
              The default Sybase server.

       SYBASE
              The home directory for Sybase files.


FFIILLEESS
       $SYBASE/interfaces - definitions for Sybase Servers.


AAUUTTHHOORR
       Tom  Poindexter,  Denver  Colorado.   Version 3.0 released
       March 1999.  The ?commands? option to sybnext was borrowed
       from  my  work  with Oratcl, a Tcl interface to the Oracle
       database product.
       tpoindex@nyx.net
       http://www.nyx.net/~tpoindex









Sybtcl                         3.0                             16


