


Sybtcl(TCL)       Misc. Reference Manual Pages        Sybtcl(TCL)



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

IIIINNNNTTTTRRRROOOODDDDUUUUCCCCTTTTIIIIOOOONNN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 program-
     ming.


SSSSYYYYBBBBTTTTCCCCLLLL CCCCOOOOMMMMMMMMAAAANNNNDDDDSSSS
     ssssyyyybbbbccccoooonnnnnnnneeeeccccttt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?
          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, syb-
          connect  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.

          A handle is returned and should be used for  all  other
          Sybtcl  commands  using this connection.  Multiple con-
          nections to the same or different servers are  allowed,
          up  to  a  maximum of 25 total connections.  Sybconnect
          raises a Tcl error if the connection is  not  made  for
          any  reason  (login  or  password incorrect, server not
          found in the Sybase interfaces file,  network  unavail-
          able, etc.).


     ssssyyyybbbbuuuusssseee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 successfully, 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.


     ssssyyyybbbbssssqqqqllll _h_a_n_d_l_e _s_q_l-_c_o_m_m_a_n_d ?-async?
          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 previously
          opened  with  sybconnect.   If  the  optional  argument
          ----aaaassssyyyynnnncccc is specified, then the SQL is sent to the server
          without waiting for a response and sybsql  will  return



Tcl                       Last change:                          1






Sybtcl(TCL)       Misc. Reference Manual Pages        Sybtcl(TCL)



          immediately with the value "PENDING".  The sybpoll com-
          mand can be used to check  the  status  of  the  server
          results;  sybnext must be called to determine if result
          rows were generated.  If ----aaaassssyyyynnnnccc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sssyyyybbbbmmmmssssgggg array index _r_e_t_s_t_a_t_u_s is set with
          the return code of a stored procedure, 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 gen-
          erated; _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 conversion
          rules in the Sybase Commands Reference manual (image or
          binary data is hexadecimal string preceded  with  "0x";
          datetime  should  be a recognizable date, etc.  The SQL
          Server CONVERT function may be used  to  force  conver-
          sions.


     ssssyyyybbbbppppoooollllllll _h_a_n_d_l_e ?_t_i_m_e_o_u_t? ?-all?
          Return a list of Sybtcl handles that have results wait-
          ing.   _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 specified,  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  handles
          that  have been executed with -async are checked, and a
          Tcl list of all handles that have results  waiting  are
          returned.   When -_a_l_l is combined 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 sybsql,



Tcl                       Last change:                          2






Sybtcl(TCL)       Misc. Reference Manual Pages        Sybtcl(TCL)



          sybpoll returns a null string.


     ssssyyyybbbbnnnneeeexxxxttt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?
          ?tclvar colnum ...?
          Return the next row from the last SQL  statements  exe-
          cuted  with  sybsql  as  a  Tcl list.  _H_a_n_d_l_e must be a
          valid handle previously opened with  sybconnect.   Syb-
          next  raises a Tcl error if the handle specified is not
          open.  All returned columns are converted to  character
          strings.   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 until results
          are available.   Sybpoll  may  be  used  to  check  for
          results.   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 fourth
          argument consisting of a single character can be speci-
          fied  for  a  column number substitution character.  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nn)  in _c_o_m_m_a_n_d_s as a result column specifica-
          tion.  For example, @@@@1111,,,, @@@@2222,,,,  @@@@3333  refer  to  the  first,
          second,  and third columns in the result.  @@@@00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  substitu-
          tion   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                       Last change:                          3






Sybtcl(TCL)       Misc. Reference Manual Pages        Sybtcl(TCL)



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

          A Tcl error is raised if a column  substitution  number
          is  greater  than the number of columns in the results.
          Note that Transact-SQL "compute"  statements  are  con-
          sidered  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bbbrrrreeeeaaaakkkk,  sybnext  execution  is interrupted and
          returns with TCL_OK.  Remaining  rows  may  be  fetched
          with  a  subsequent  sybnext  command.  If the commands
          execute rrrreeeettttuuuurrrrnnnn or ccccoooonnnnttttiiiinnnnuuuueee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sssyyyybbbbmmmmssssggg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 executed 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 syb-
          next.  Refer to the section "SERVER MESSAGE  AND  ERROR
          INFORMATION"  for  information  about  how  the _n_e_x_t_r_o_w
          value is set.

          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sssyyyybbbbmmmmssssggg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sssyyyybbbbmmmmssssggg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sssyyyybbbbccccoooollllssss _h_a_n_d_l_e
          Return the names of the columns from the  last  sybnext
          or  sybretval  command  as a Tcl list.  Sybcols returns
          the column name used in the SQL select command; a  null
          string  for  any  column  that is an aggregate function
          (count, sum, avg, min, max) in a regular row.   A  com-
          pute  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).




Tcl                       Last change:                          4






Sybtcl(TCL)       Misc. Reference Manual Pages        Sybtcl(TCL)



          The ssssyyyybbbbmmmmssssggg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 han-
          dle specified is not open.


     ssssyyyybbbbccccaaaannnncccceeeellll _h_a_n_d_l_e
          Cancel any pending results from the  last  sybsql  com-
          mand.  _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sssyyyybbbbrrrreeeettttvvvvaaaalll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 previously been called
          until NO_MORE_ROWS was encountered before sybretval can
          access  the  return  values.  The  ssssyyyybbbbmmmmssssgggg  array  index
          _r_e_t_s_t_a_t_u_s contains the return code from the stored pro-
          cedure.   Sybretval  raises  a  Tcl error if the handle
          specified is not open.  See notes regarding stored pro-
          cedure output variables.


     ssssyyyybbbbwwwwrrrriiiitttteeeetttteeeexxxxtttt _h_a_n_d_l_e _o_b_j_e_c_t _c_o_l_n_u_m _f_i_l_e_n_a_m_e ?-nolog?
          Write the contents of a 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tttaaaabbbblllleeee....ccccoooolllluuuummmmnnnn.   _C_o_l_n_u_m is the relative position
          of the column from the last sssseeeelllleeeecccctttt.   _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nnnoooolllloooogggg may be specified to disable
          logging (the database must  have  previously  been  set
          with a no log option.)

          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sssyyyybbbbssssqqqqllll $$$$hhhhaaaannnndddd """"iiiinnnnsssseeeerrrrtttt iiiinnnnttttoooo  aaaauuuu____ppppiiiixxxx  ((((aaaauuuu____iiiidddd))))  vvvvaaaalllluuuueeeessss
          ((((''''111111111111----22222222----3333333333333333''''))))""""
               ssssyyyybbbbssssqqqqllll $$$$hhhhaaaannnndddd """"uuuuppppddddaaaatttteeee aaaauuuu____ppppiiiixxxx sssseeeetttt ppppiiiicccc ====  nnnnuuuullllllll  wwwwhhhheeeerrrreeee



Tcl                       Last change:                          5






Sybtcl(TCL)       Misc. Reference Manual Pages        Sybtcl(TCL)



          aaaauuuu____iiiidddd ==== ''''111111111111----22222222----3333333333333333''''""""
               ssssyyyybbbbssssqqqqllll $$$$hhhhaaaannnndddd """"sssseeeelllleeeecccctttt ppppiiiicccc ffffrrrroooommmm aaaauuuu____ppppiiiixxxx wwwwhhhheeeerrrreeee aaaauuuu____iiiidddd ====
          ''''111111111111----22222222----3333333333333333''''""""
               ssssyyyybbbbwwwwrrrriiiitttteeeetttteeeexxxxtttt $$$$hhhhaaaannnndddd aaaauuuu____ppppiiiixxxx....ppppiiiicccc 1111 iiiimmmmaaaaggggeeee....ffffiiiilllleeee ----nnnnoooolllloooogggg

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

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


     ssssyyyybbbbrrrreeeeaaaaddddtttteeeexxxxtttt _h_a_n_d_l_e _f_i_l_e_n_a_m_e
          Read the contents of a TEXT or IMAGE column  and  write
          results  into  a  file.   _H_a_n_d_l_e must be a valid handle
          previously opened with  sybconnect.   _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  success-
          ful  sssseeeelllleeeecccctttt of a single text or image column. For exam-
          ple (assume $hand is an open handle, using  the  "pubs"
          database):

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

          Sybreadtext returns a decimal  number  upon  successful
          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sssyyyybbbbmmmmssssggg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  rea-
          sons:   filename  could not be opened, sybreadtext used
          out of sequence, etc.


     ssssyyyybbbbcccclllloooosssseeee _h_a_n_d_l_e
          Closes the server connection  associated  with  _h_a_n_d_l_e.



Tcl                       Last change:                          6






Sybtcl(TCL)       Misc. Reference Manual Pages        Sybtcl(TCL)



          _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SSSEEEERRRRVVVVEEEERRRR MMMMEEEESSSSSSSSAAAAGGGGEEEE AAAANNNNDDDD EEEERRRRRRRROOOORRRR IIIINNNNFFFFOOOORRRRMMMMAAAATTTTIIIIOOOONNNN
     Sybtcl creates and maintains a Tcl global array  to  provide
     feedback of Sybase server messages, named ssssyyyybbbbmmmmssssgggg.  Sybmsg is
     also used to communicate with the sybtcl interface  routines
     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
     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  com-
     mand  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vvveeeerrrrssssiiiioooonnnn
          is set to the version of Sybtcl.


     nnnnuuuullllllllvvvvaaaalllluuuueee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.   Nullvalue  is
          initially set to "default".


     ffffiiiixxxxeeeeddddcccchhhhaaaarrrr
          can be set by the programmer to indicate that character
          datatypes  returned by sybnext should not have trailing
          spaces    trimmed    from    the    value.      Setting
          sybmsg(fixedchar)  to "yes" will ensure that all trail-
          ing spaces are returned.  The default value  ("")  will
          cause trailing spaces to be trimmed.


     ffffllllooooaaaattttpppprrrreeeecccc
          can be set by the programmer to indicate the  precision
          of  decimal  places  to  print  for floating point data
          values.  The default ("") will return 17 digits of pre-
          cision.   Setting sybmsg(floatprec) must be done before
          issuing a  sybsql  statement,  and  effects  all  float
          values returned by sybnext.  Valid values for floatprec
          are 1 to 17.





Tcl                       Last change:                          7






Sybtcl(TCL)       Misc. Reference Manual Pages        Sybtcl(TCL)



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

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

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

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

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

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

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

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

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

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

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

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

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


     mmmmaaaaxxxxtttteeeexxxxtttt
          can be set by the programmer to  limit  the  amount  of
          text or image data returned by sybnext and sybreadtext.
          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



Tcl                       Last change:                          8






Sybtcl(TCL)       Misc. Reference Manual Pages        Sybtcl(TCL)



          with sybnext.


     hhhhaaaannnnddddlllleeee
          indicates the handle of the last sybtcl command.   Han-
          dle  is  set  on  every sybtcl command (execpt where an
          invalid handle is used.)


     nnnneeeexxxxttttrrrroooowwww
          indicates the results of the last SQL command and  sub-
          sequent  next row processing.  Nextrow is set by sybsql
          and sybnext.  Possible values are:

          RRRREEEEGGGG____RRRROOOOWWWW
               at least one row is available after  execution  of
               sybsql,  or  the results of sybnext returned a row
               as a Tcl list.

          nn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 com-
               pute  statement  in  the last SQL command executed
               with sybsql.

          NNNNOOOO____MMMMOOOORRRREEEE____RRRROOOOWWWWSSS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PPPEEEENNNNDDDDIIIINNNNGGGG
               indicates the last execution of  sybsql  was  made
               with  the  "-async"  flag.  Sybpoll may be used to
               check the status of results.  Sybnext  will  block
               until  results are available.  When sybsql is exe-
               cuted with -async, any errors will not  be  avail-
               able until the first execution of sybnext.

          FFFFAAAAIIIILLL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.



Tcl                       Last change:                          9






Sybtcl(TCL)       Misc. Reference Manual Pages        Sybtcl(TCL)



          NNNNOOOO____MMMMOOOORRRREEEE____RRRREEEESSSSUUUULLLLTTTTSSSS
               indicates that the final set of results  from  the
               last  execution  of  sybsql have been processed by
               sybnext.

     rrrreeeettttssssttttaaaattttuuuussss
          indicates the return code after a stored procedure  has
          executed.  Retstatus is set by sybsql or sybnext, when-
          ever a the results of a stored procedure are available.

     ccccoooolllllllleeeennnnggggtttthhhhsss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 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
          sybcols.

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

     mmmmssssggggnnnnoooo
          indicates the message number from a Sybase Server  mes-
          sage.   Can  be  set  by  any sybtcl command.  Refer to
          Sybase documentation for  interpretation.   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 message numbers received during one sybtcl  com-
          mand, separating individual numbers by newlines.

     mmmmssssggggtttteeeexxxxttt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  command,
          separating  individual  messages  by  newlines.  Output
          from Transact-SQL  PRINT  statments  are  collected  in
          msgtext.

     sssseeeevvvveeeerrrriiiittttyyyy
          indicates the severity level from a Sybase Server  mes-
          sage  or  DB-Library routine.  Can be set by any sybtcl
          command.  Refer to Sybase documentation for interpreta-
          tion.



Tcl                       Last change:                         10






Sybtcl(TCL)       Misc. Reference Manual Pages        Sybtcl(TCL)



     ssssvvvvrrrrnnnnaaaammmmeeee
          indicates the name of the Sybase Server that  generated
          a message.  Can be set by any sybtcl command.

     pppprrrrooooccccnnnnaaaammmmeeee
          indicates the name of the stored  procedure  that  gen-
          erated a message.  Only set when a stored procedure was
          executed.  Set by sybsql.

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

     ddddbbbbeeeerrrrrrr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dddbbbbeeeerrrrrrrrssssttttrrrr
          the error text associated with dberr.

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

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


NNNNOOOOTTTTEEEESSS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  "OUTPUT"  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  pro-
     cedure   uses   Transact-SQL   "PRINT"   statements,   check
     $sybmsg(msgtext) before executing any other Sybtcl commands.
     Otherwise,  the  PRINT  output  will  be  lost  on  the next



Tcl                       Last change:                         11






Sybtcl(TCL)       Misc. Reference Manual Pages        Sybtcl(TCL)



     command.  Multiple PRINT statements are  separated  by  new-
     lines in $sybmsg(msgtext).

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

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

          sssspppp____ddddbbbbooooppppttttiiiioooonnnn   ''''yyyyoooouuuurrrrddddbbbbnnnnaaaammmmeeee'''',,,,   ''''sssseeeelllleeeecccctttt   iiiinnnnttttoooo////bbbbuuuullllkkkkccccooooppppyyyy'''',,,,
     ''''ttttrrrruuuueee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 sybnext
     is ultimately dependent on sybtcl's ability to malloc() _m_a_x_-
     _t_e_x_t  bytes  of  memory  for  each  TEXT  or  IMAGE   column
     retrieved.   Setting sybmsg(maxtext) to too high a value may
     cause core dumps or memory shortages.  Sybreadtext 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 shortages as  sybnext
     might.


EEEENNNNVVVVIIIIRRRROOOONNNNMMMMEEEENNNNTTTT VVVVAAAARRRRIIIIAAAABBBBLLLLEEEESSSS
     DSQUERY
          The default Sybase server.

     SYBASE
          The home directory for Sybase files.


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


BBBBUUUUGGGGSSSS
     More items seem  to  be  creeping  into  the  sybmsg  array.
     Perhaps  it's  time  for  a syboption command for passing in
     nullvalue, maxtext, and whatever else comes along, on a  per
     dbproc basis.

AAAAUUUUTTTTHHHHOOOORRRR
     Tom Poindexter, Denver Colorado.  Version 2.5  released  May
     1997.  The ?commands? option to sybnext was borrowed from my
     work with Oratcl, a Tcl interface  to  the  Oracle  database



Tcl                       Last change:                         12






Sybtcl(TCL)       Misc. Reference Manual Pages        Sybtcl(TCL)



     product.
     tpoindex@nyx.net





















































Tcl                       Last change:                         13



