


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



NNNNAAAAMMMMEEEE
     Oratcl - Oracle Database 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
     Oratcl is a collection of Tcl  commands  and  a  Tcl  global
     array  that  provides  access  to an Oracle Database Server.
     Each Oratcl command generally invokes  several  Oracle  Call
     Interface (OCI) library functions.  Programmers using Oratcl
     should be familar with basic concepts of OCI programming.


OOOORRRRAAAAT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
     oooorrrraaaallllooooggggoooonnnn _c_o_n_n_e_c_t-_s_t_r
          Connect to an Oracle  server  using  _c_o_n_n_e_c_t-_s_t_r.   The
          connect string should be a valid Oracle connect string,
          in the form:

               _n_a_m_e
               _n_a_m_e/_p_a_s_s_w_o_r_d
               _n_a_m_e@_n:_d_b_n_a_m_e
               _n_a_m_e/_p_a_s_s_w_o_r_d@_n:_d_b_n_a_m_e

          A logon handle is returned and should be used  for  all
          other   Oratcl  commands  using  this  connection  that
          require a logon handle.  Multiple  connections  to  the
          same  or different servers are allowed, up to a maximum
          of 25 total connections.  Oralogon raises a  Tcl  error
          if  the connection is not made for any reason (login or
          password incorrect, network unavailable, etc.).  If the
          connect  string  does not include a database specifica-
          tion, the value of the environment variable  ORACLE_SID
          is used as the server.


     oooorrrraaaallllooooggggooooffffffff _l_o_g_o_n-_h_a_n_d_l_e
          Logoff from the  Oracle  server  connection  associated
          with  _l_o_g_o_n-_h_a_n_d_l_e. _L_o_g_o_n-_h_a_n_d_l_e must be a valid handle
          previously opened with oralogon.  Oralogoff  returns  a
          null string.  Oralogoff raises a Tcl error if the logon
          handle specified is not open.


     oooorrrraaaaooooppppeeeennnn _l_o_g_o_n-_h_a_n_d_l_e
          Open an SQL cursor to the server.   Oraopen  returns  a
          cursor  to  be  used on subsequent Oratcl commands that
          require a cursor handle.  _L_o_g_o_n-_h_a_n_d_l_e must be a  valid
          handle  previously opened with oralogon.  Multiple cur-
          sors can be opened through the same or different  logon
          handles,  up to a maximum of 25 total cursors.  Oraopen
          raises a Tcl error if the logon handle specified is not
          open.



Tcl                       Last change:                          1






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



     oooorrrraaaacccclllloooosssseeee _c_u_r_s_o_r-_h_a_n_d_l_e
          Closes the cursor associated with cursor-handle.   Ora-
          close raises a Tcl error if the cursor handle specified
          is not open.


     oooorrrraaaassssqqqqllll _c_u_r_s_o_r-_h_a_n_d_l_e _s_q_l-_s_t_a_t_e_m_e_n_t ?-_p_a_r_s_e_o_n_l_y? ?-_a_s_y_n_c?
          Send the Oracle  SQL  statement  _s_q_l-_s_t_a_t_e_m_e_n_t  to  the
          server.   _C_u_r_s_o_r-_h_a_n_d_l_e  must  be a valid handle previ-
          ously opened with  oraopen.   Orasql  will  return  the
          numeric  return code "0" on successful execution of the
          sql statement.  The oooorrrraaaammmmssssgggg array index _r_c is  set  with
          the return code; the _r_o_w_s index is set to the number of
          rows affected by the  SQL  statement  in  the  case  of
          _i_n_s_e_r_t, _u_p_d_a_t_e, or _d_e_l_e_t_e.

          The oooorrrraaaammmmssssgggg array index _r_o_w_i_d is  set  with  the  Oracle
          ROWID  of  the last row processed in an _i_n_s_e_r_t, _u_p_d_a_t_e,
          or _d_e_l_e_t_e statement.

          Only a single SQL statement may be  specified  in  _s_q_l-
          _s_t_a_t_e_m_e_n_t.  _O_r_a_f_e_t_c_h  allows  retrieval  of return rows
          generated.

          The optional -_p_a_r_s_e_o_n_l_y argument parses  but  does  not
          execute  the SQL statement.  The SQL statement may con-
          tain bind variables that begin with a colon (':').  The
          statement  may  then  be  executed with the _o_r_a_b_i_n_d_e_x_e_c
          command, allowing bind variables to be substituted with
          values.   Bind  variables  should  only be used for SQL
          statements _s_e_l_e_c_t, _i_n_s_e_r_t, _u_p_d_a_t_e, _o_r _d_e_l_e_t_e.

          The optional -_a_s_y_n_c argument  specifies  the  that  SQL
          should  be executed asynchronously.  Orasql will return
          the numeric code "3123" when using -async.   Note  that
          -_a_s_y_n_c is only available for orasql when Oratcl is com-
          piled with Oracle 7.2 or  higher  libraries,  and  when
          connected to an Oracle server of version 7.2 or higher.
          See _o_r_a_p_o_l_l below.

          Only -_p_a_r_s_e_o_n_l_y or -_a_s_y_n_c may be specified.

          Orasql performs an implicit _o_r_a_c_a_n_c_e_l  if  any  results
          are  still  pending  from the last execution of orasql.
          Orasql raises a Tcl error if the cursor  handle  speci-
          fied  is not open, or if the SQL statement is syntacti-
          cally incorrect.

          Table inserts made with orasql should follow conversion
          rules in the Oracle SQL Reference manual.





Tcl                       Last change:                          2






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



     oooorrrraaaabbbbiiiinnnnddddeeeexxxxeeeecccc _c_u_r_s_o_r-_h_a_n_d_l_e ?-_a_s_y_n_c? ?:_v_a_r_n_a_m_e _v_a_l_u_e ...?
          Execute a previously parsed SQL  statement,  optionally
          binding  values to SQL variables. _C_u_r_s_o_r-_h_a_n_d_l_e must be
          a valid handle previously opened with oraopen.  An  SQL
          statement must have previously been parsed by executing
          orasql with the -_p_a_r_s_e_o_n_l_y option.  Orabindexec may  be
          repeatedly  executed  after  a statement is parsed with
          bind variables substituted on each execution.   Orabin-
          dexec  does  not  re-parse SQL statements before execu-
          tion.

          The optional -_a_s_y_n_c argument  specifies  the  that  SQL
          should  be executed asynchronously.  Orasql will return
          the numeric code 3123 when using -async.  If -async  is
          specified, it must preceed any remaining :varname value
          pairs for the command.  Note that -async is only avail-
          able for orasql when Oratcl is compiled with Oracle 7.2
          or higher libraries, and when connected  to  an  Oracle
          server of version 7.2 or higher.  See _o_r_a_p_o_l_l below.

          Optional :_v_a_r_n_a_m_e _v_a_l_u_e pairs  allow  substitutions  on
          SQL  bind variables before execution.  As many :varname
          value pairs should be specified as there are defined in
          the  previously parsed SQL statement.  Varnames must be
          prefixed by a colon ":".

          Orabindexec will return "0" when the  SQL  is  executed
          successfully;  "3123"  when  executed  with  the -_a_s_y_n_c
          argument; "1003" if a previous SQL has not been  parsed
          with  orasql; "1008" if not all SQL bind variables have
          been specified.  Refer to Oracle error numbers and mes-
          sages for other possible values.

          The oooorrrraaaammmmssssgggg array index _r_o_w_i_d is  set  with  the  Oracle
          ROWID  of  the last row processed in an _i_n_s_e_r_t, _u_p_d_a_t_e,
          or _d_e_l_e_t_e statement.


?_t_c_l_v_a_r_n_a_m_e _c_o_l_n_u_m
     oooorrrraaaaffffeeeettttcccchhhh   _c_u_r_s_o_r-
          _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?
          Return the next row from the last  SQL  statement  exe-
          cuted with orasql as a Tcl list.  _C_u_r_s_o_r-_h_a_n_d_l_e must be
          a  valid  handle  previously   opened   with   oraopen.
          Orafetch raises a Tcl error if the cursor handle speci-
          fied 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 orafetch contains the
          values of the selected columns in the  order  specified
          by _s_e_l_e_c_t.




Tcl                       Last change:                          3






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



          The  optional  _c_o_m_m_a_n_d_s  argument  allows  orafetch  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 argu-
          ment consisting of a single character can be  specified
          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  per-
          formed on the _c_o_m_m_a_n_d_s string.  Orafetch interprets the
          substitution character followed by  a  number  (@@@@nnnn)  in
          commands  as  a result column specification.  For exam-
          ple, @@@@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.  Sub-
          stituted columns are inserted into the commands  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.

          A Tcl error is raised if a column  substitution  number
          is  greater  than the number of columns in the results.
          If the commands execute bbbbrrrreeeeaaaakkkk,  orafetch  execution  is
          interrupted  and  returns  with TCL_OK.  Remaining rows
          may be fetched with a subsequent orafetch  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 orafetch  execution  continues
          with  the next row.  Orafetch will raise a Tcl error if
          the _c_o_m_m_a_n_d_s  return  an  error.   Commands  should  be
          enclosed in "" or {}.

          Oratcl performs conversions for all  data  types.   Raw
          data  is  returned  as  a hexadecimal string, without a
          leading  "0x".   Use  the  SQL  functions  to  force  a
          specific conversion.

          If an SQL statement has been executed in  asynchrounous
          mode  (-_a_s_y_n_c  argument on _o_r_a_s_q_l or _o_r_a_b_i_n_d_e_x_e_c), exe-
          cuting orafetch will block until SQL execution is  com-
          plete.  See _o_r_a_p_o_l_l below.

          The oooorrrraaaammmmssssgggg array index _r_c is set with the  return  code



Tcl                       Last change:                          4






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



          of the fetch.  0 indicates the row was fetched success-
          fully; 1403 indicates the end of data was reached.

          The index _r_o_w_s is set to the cumulative number of  rows
          fetched  so  far.   The oooorrrraaaammmmssssgggg array index _r_o_w_i_d is set
          with the Oracle ROWID of  the  last  row  fetched  when
          retrieved with a _s_e_l_e_c_t _f_o_r _u_p_d_a_t_e statement.

          The oooorrrraaaammmmssssgggg array index _m_a_x_l_o_n_g  limits  the  amount  of
          long   or  long  raw  data  returned  for  each  column
          returned.  The default is 32768 bytes.

          The oooorrrraaaam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.


     oooorrrraaaappppoooollllllll _c_u_r_s_o_r-_h_a_n_d_l_e ?-_a_l_l?
          Return a list of cursor handles that have results wait-
          ing  to be fetched.  _C_u_r_s_o_r-_h_a_n_d_l_e must be a valid han-
          dle previously opened with oraopen.   If  the  previous
          SQL  execution  has not finished, orapoll will return a
          null string.  If execution has finished for the  cursor
          handle  and/or results are available, the cursor handle
          is returned.

          The optional argument -_a_l_l may be specified to return a
          list of all cursor handles that have results waiting.

          Note that orapoll is only available when Oratcl is com-
          piled  with  Oracle  7.2  or higher libraries, and when
          connected to an Oracle server of version 7.2 or higher.

          Asynchronous processing (-_a_s_y_n_c argument on  _o_r_a_s_q_l  or
          _o_r_a_b_i_n_d_e_x_e_c)  is  actually  done  on a logon-connection
          basis.  Executing orasql  or  orabindexec  with  -_a_s_y_n_c
          causes  all open cursors through the same logon connec-
          tion handle to be changed to asycnchronous mode.  Like-
          wise,  if  orafetch  is  executed on a cursor, all open
          cursors through the same logon connection  handle  will
          be  changed  to  blocking mode.  It is recommended that
          asynchronous processing be limited to  one  cursor  per
          logon  connection to avoid unexpected changes of block-
          ing to/from asynchronous mode for other cursors.


     oooorrrraaaabbbbrrrreeeeaaaakkkk _c_u_r_s_o_r-_h_a_n_d_l_e
          Cause a currently executing SQL statement to be  inter-
          rupted.   _C_u_r_s_o_r-_h_a_n_d_l_e  must  be a valid handle previ-
          ously opened with oraopen.  Use the  _o_r_a_c_a_n_c_e_l  command
          to cancel SQL results, see below.




Tcl                       Last change:                          5






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



          Note that orabreak is only  available  when  Oratcl  is
          compiled  with Oracle 7.2 or higher libraries, and when
          connected to an Oracle server of version 7.2 or higher.


     oooorrrraaaapppplllleeeexxxxeeeecccc _c_u_r_s_o_r-_h_a_n_d_l_e _p_l-_b_l_o_c_k ?:_v_a_r_n_a_m_e _v_a_l_u_e ...?
          Execute  an  anonymous  PL  block,  optionally  binding
          values  to  PL/SQL  variables.  _C_u_r_s_o_r-_h_a_n_d_l_e must be a
          valid handle previously opened with oraopen.   Pl-block
          may  either be a complete PL/SQL procedure or a call to
          a stored procedure coded as an anonymous PL/SQL  block.
          Optional  :_v_a_r_n_a_m_e _v_a_l_u_e pairs may follow the pl-block.
          Varnames must be prefixed by a colon ":", and match the
          subsitution  bind  names  used  in  the procedure.  Any
          :varname that is not matched with a value  is  ignored.
          If  a  :varname is used for output, the value should be
          coded as a null string, "".

          Cursor variables may be returned from a PL/SQL block by
          specifing  an open cursor as the bind value for a :var-
          name bind variable. The  cursor  must  have  previously
          been  opened  by oraopen using the same logon handle as
          the cursor used to execute the oraplexec command.   The
          cursor  is  closed  and re-opened with the results of a
          PL/SQL "OPEN :cursor FOR select" statement.  After ora-
          plexec  completes,  the  cursor returned may then fetch
          result rows by using orafetch;  column  information  is
          available by using oracols.

          Note that cursor variables are only available for  ora-
          plexec  when  Oratcl  is  compiled  with  Oracle 7.2 or
          higher libraries,  and  when  connected  to  an  Oracle
          server of version 7.2 or higher.

          Oraplexec returns the contents of each  :varname  as  a
          Tcl  list  upon  the  termination of PL/SQL block. Ora-
          plexec raises a Tcl error if the cursor  handle  speci-
          fied  is  not open, or if the PL/SQL block is in error.
          The oooorrrraaaammmmssssgggg array index _r_c contains the return code from
          the stored procedure.


     oooorrrraaaaccccoooollllssss _c_u_r_s_o_r-_h_a_n_d_l_e
          Return the names of the columns from the  last  orasql,
          orafetch,  or oraplexec command as a Tcl list.  Oracols
          may be used after _o_r_a_p_l_e_x_e_c, in which  case  the  bound
          variable names are returned.

          The oooorrrraaaam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;  index  _c_o_l_p_r_e_c_s is set to a Tcl list



Tcl                       Last change:                          6






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



          corresponding to the precision of the numeric  columns,
          other  corresponding  non-numeric  columns  are  a null
          string (Version 7 only); index _c_o_l_s_c_a_l_e_s is  set  to  a
          Tcl  list  corresponding  to  the  scale of the numeric
          columns, other corresponding non-numeric columns are  a
          null  string  (Version  7  only).  Oracols raises a Tcl
          error if the cursor handle specified is not open.


     oooorrrraaaaccccaaaannnncccceeeellll _c_u_r_s_o_r-_h_a_n_d_l_e
          Cancels any pending results from a prior orasql command
          that  use a cursor opened through the connection speci-
          fied by cursor-handle. _C_u_r_s_o_r-_h_a_n_d_l_e must  be  a  valid
          handle   previously  opened  with  oraopen.   Oracancel
          raises a Tcl error if the cursor  handle  specified  is
          not open.


     oooorrrraaaaccccoooommmmmmmmiiiitttt _l_o_g_o_n-_h_a_n_d_l_e
          Commit any pending transactions from prior orasql  com-
          mands  that  use a cursor opened through the connection
          specified by logon-handle. _L_o_g_o_n-_h_a_n_d_l_e must be a valid
          handle  previously  opened  with  oralogon.   Oracommit
          raises a Tcl error if the logon handle specified is not
          open.


     oooorrrraaaarrrroooollllllll _l_o_g_o_n-_h_a_n_d_l_e
          Rollback any pending  transactions  from  prior  orasql
          commands  that  use a cursor opened through the connec-
          tion specified by logon-handle. _L_o_g_o_n-_h_a_n_d_l_e must be  a
          valid  handle previously opened with oralogon.  Oraroll
          raises a Tcl error if the logon handle specified is not
          open.


     oooorrrraaaaaaaauuuuttttooooccccoooommmm _l_o_g_o_n-_h_a_n_d_l_e {_o_n | _o_f_f}
          Enables or disables automatic commit of SQL data  mani-
          pulation  statements  using a cursor opened through the
          connection specified by logon handle. _L_o_g_o_n-_h_a_n_d_l_e must
          be a valid handle previously opened with oralogon.  One
          of the literal values "on" or "off" must be  specified.
          The automatic commit feature defaults to "off".  Oraau-
          tocom raises a Tcl error if the logon handle  specified
          is not open.


     oooorrrraaaawwwwrrrriiiitttteeeelllloooonnnngggg _c_u_r_s_o_r-_h_a_n_d_l_e _r_o_w_i_d _t_a_b_l_e _c_o_l_u_m_n _f_i_l_e_n_a_m_e
          Write the contents of a file to  a  LONG  or  LONG  RAW
          column.   _C_u_r_s_o_r-_h_a_n_d_l_e  must  be a valid handle previ-
          ously opened with oraopen.  _R_o_w_i_d is the  Oracle  rowid
          of an existing row.  The rowid must be in the format of



Tcl                       Last change:                          7






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



          an Oracle rowid datatype.  _T_a_b_l_e is the table name that
          contains the row and column.  _C_o_l_u_m_n is the column name
          that is the LONG or LONG RAW column.  _F_i_l_e_n_a_m_e  is  the
          name  of  the  file  that contains the LONG or LONG RAW
          data to write into the  column.  Orawritelong  composes
          and  executes  an  SQL  _u_p_d_a_t_e  statement  based on the
          table, column, and rowid.

          Orawritelong returns a decimal number  upon  successful
          completion  of  the number of bytes written to the LONG
          column.  A properly formatted  Rowid  may  be  obtained
          through a prior execution of orasql, "_s_e_l_e_c_t _r_o_w_i_d _f_r_o_m
          _t_a_b_l_e _w_h_e_r_e ...".

          Orawritelong raises a Tcl error if  the  cursor  handle
          specified  is  not  open, or if rowid, table, or column
          are invalid, or if the row does not exist.


     oooorrrraaaarrrreeeeaaaaddddlllloooonnnngggg _c_u_r_s_o_r-_h_a_n_d_l_e _r_o_w_i_d _t_a_b_l_e _c_o_l_u_m_n _f_i_l_e_n_a_m_e
          Read the contents of a LONG  or  LONG  RAW  column  and
          write  results  into  a  file.  _C_u_r_s_o_r-_h_a_n_d_l_e must be a
          valid handle previously opened with oraopen.  _R_o_w_i_d  is
          the Oracle rowid of an existing row.  The rowid must be
          in the format of an Oracle rowid  datatype.   _T_a_b_l_e  is
          the  table  name  that  contains  the  row  and column.
          _C_o_l_u_m_n is the column name that is the LONG or LONG  RAW
          column.   _F_i_l_e_n_a_m_e  is  the  name of a file in which to
          write the LONG or LONG RAW data.  Orareadlong  composes
          and  executes  an  SQL  _s_e_l_e_c_t  statement  based on the
          table, column, and rowid. A  properly  formatted  Rowid
          may  be  obtained  through a prior execution of orasql,
          "_s_e_l_e_c_t _r_o_w_i_d _f_r_o_m _t_a_b_l_e _w_h_e_r_e ...".

          Orareadlong returns a decimal  number  upon  successful
          completion  of  the  number of bytes read from the LONG
          column.

          Orareadlong raises a Tcl error  if  the  cursor  handle
          specified  is  not  open, or if rowid, table, or column
          are invalid, or if the row does not exist.


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
     Oratcl creates and maintains a Tcl global array  to  provide
     feedback of Oracle server messages, named oooorrrraaaammmmssssgggg.  Oramsg is
     also used to communicate with the Oratcl interface  routines
     to specify null return values and LONG limits.  In all cases
     except for _n_u_l_l_v_a_l_u_e and _m_a_x_l_o_n_g, each element is  reset  to
     null  upon invocation of any Oratcl command, and any element
     affected by the command is set.  The oramsg array is  shared
     among  all  open  Oratcl  handles.  Oramsg should be defined



Tcl                       Last change:                          8






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



     with the global  statement  in  any  Tcl  procedure  needing
     access to oramsg.

     Oramsg elements:


     vvvveeeerrrrssssiiiioooonnnn
          indicates the version of Oratcl.


     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".


     mmmmaaaaxxxxlllloooonnnngggg
          can be set by the programmer to  limit  the  amount  of
          LONG  or  LONG  RAW  data  returned  by  orafetch.  The
          default is 32768 bytes. The maximum is  65536  (Version
          6)  or  2147483647  (Version  7) bytes.  Any value less
          than or equal to zero is ignored.  Any change  to  max-
          long becomes effective on the next call to orasql.  See
          notes on maxlong usage with orafetch.


     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 Oratcl command.   Han-
          dle  is  set  on  every Oratcl command (execpt where an
          invalid handle is used.)


     rrrrcccc
          indicates the results of the last SQL command and  sub-
          sequent  orafetch  processing.   Rc  is  set by orasql,
          orafetch, oraplexec,  and is the  numeric  return  code
          from  the last OCI library function called by an Oratcl
          command.  Refer to  Oracle  Error  Messages  and  Codes
          manual for detailed information.  Typical values are:

          0000
               Function completed normally, without error.

          999900000000----999999999999
               invalid SQL  statement,  invalid  sql  statements,
               missing keywords, invalid column names, etc.

          1111000000000000----1111000099999999
               program interface error, e.g.,  no  sql  statement



Tcl                       Last change:                          9






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



               parsed,   SQL  bind  variables  not  bound,  logon
               denied, insufficient privileges, etc.

          1111444400000000----1111444499999999
               execution errors or feedback.

          1111444400003333
               end of data was reached on an orafetch command.

          1111444400006666
               a column fetched by orafetch was  truncated.   Can
               occur  when  fetching  a LONG or LONG RAW, and the
               _m_a_x_l_o_n_g value is  smaller  than  the  acutal  data
               size.  3333111122223333
               asynchronous execution is pending completion.

     eeeerrrrrrrroooorrrrttttxxxxtttt
          the message text associated with rc.   Since  the  ora-
          plexec command may invoke several SQL statements, there
          is a possiblity that several messages may  be  received
          from the server.

     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
          oracols. Collengths is only set by oracols.

     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
          oracols.  Coltypes  is  only  set by oracols.  Possible
          types  returned  are:   char,  varchar2  (Version   7),
          number,  long,  rowid,  date,  raw,  long_raw, mlslabel
          (Version 7), raw_mlslabel (Version 7), unknown.

     ccccoooollllpppprrrreeeeccccssss
          is a Tcl list of the precision of the  numeric  columns
          returned  by  oracols. Colprecs is only set by oracols.
          For non-numeric columns,  the  list  entry  is  a  null
          string.   The  colprecs element only returns meaningful
          information when Oratcl is compiled for Version 7.  Due
          to  an  OCI limitation in Version 6, zeros are returned
          as precision.

     ccccoooollllssssccccaaaalllleeeessss
          is a Tcl list of  the  scale  of  the  numeric  columns
          returned  by  oracols. Colprecs is only set by oracols.
          For non-numeric columns,  the  list  entry  is  a  null
          string.   The colscales element only returns meaningful
          information when Oratcl is compiled for Version 7.  Due
          to  an  OCI limitation in Version 6, zeros are returned
          as scale.

     ssssqqqqllllffffuuuunnnncccc



Tcl                       Last change:                         10






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



          the numeric OCI code of  the  last  sql  function  per-
          formed.  See the OCI manual for descriptions.

     ppppeeeeoooo
          parse error offset, an index into an  sql  string  that
          failed due to error.

     oooocccciiiiffffuuuunnnncccc
          the number OCI code of the last OCI function called  by
          Oratcl.  See the OCI manual for descriptions.

     rrrroooowwwwssss
          the number of rows affected by an  _i_n_s_e_r_t,  _u_p_d_a_t_e,  or
          _d_e_l_e_t_e  in  an orasql command, or the cumulative number
          of rows fetched by orafetch.

     rrrroooowwwwiiiidddd
          the Oracle ROWID  of  the  row  affected  by  a  _s_e_l_e_c_t
          _i_n_s_e_r_t, _u_p_d_a_t_e, or _d_e_l_e_t_e in an orasql, orabindexec, or
          orafetch command.  The rowid element is formatted as  a
          hexadecimal  character  string that is suitable for use
          in subsequent SQL.

     oooocccciiiiiiiinnnnffffoooo
          a list of features present in the Oracle  library  when
          Oratcl was compiled.  Possible values are: either

          "version_6" or "version_7" - reflects the  Oracle  ver-
          sion

          "non_blocking" and "cursor_variables" - Oracle  version
          7.2+ non-blocking SQL execution and PL/SQL cursor vari-
          ables.


NNNNOOOOTTTTEEEESSSS
     Tcl errors can also be raised by any  Oratcl  command  if  a
     command's internal calls to OCI library routines fail.

     Oracle is very particular about using date literals in  SQL.
     The proper date format is 'dd-mmm-yy', where dd is a numeric
     day, mmm is a three character month name, yy  is  two  digit
     year.   Some versions of Oracle give very strange results or
     failures if date values are not in this format.

     The limit of the number of simultaneous connections and cur-
     sors  is  artificial,  based  on  a fixed table in oratcl.c.
     Change the source #_d_e_f_i_n_e _O_R_A_T_C_L_L_D_A_S or  #_d_e_f_i_n_e  _O_R_A_T_C_L_C_U_R_S
     if more are needed.

     Oratcl does not mix well with Tcl  slave  interpreters.   If
     Oratcl  functions  are  needed  in  a  slave,  set  up alias



Tcl                       Last change:                         11






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



     commands in the slave to execute Oratcl commands in the mas-
     ter interpreter.  See the 'interp' man page.

     The maximum amount of LONG or  LONG  RAW  data  returned  by
     orafetch is ultimately dependent on Oratcl's ability to mal-
     loc() _m_a_x_l_o_n_g bytes of memory for each LONG/LONG RAW  column
     retrieved.   Setting oramsg(maxlong) to too high a value may
     cause core dumps or memory shortages.

     Orareadlong compiled for Version 7 will utilize the  oflng()
     OCI  function;  otherwise,  a single data allocation will be
     made to hold the entire data.  If  memory  cannot  be  allo-
     cated, the command will fail.

     Unfortunately, OCI  does  not  provide  a  way  to  write  a
     LONG/LONG  RAW  column in chunks.  The entire amount of data
     required to perform orawritelong is allocated  in  a  single
     request.   Again, if memory cannot be allocated, the command
     will fail.

     Orafetch normally caches 10 rows at a time from  the  Oracle
     server.   When  a  query contains a LONG or LONG RAW column,
     single rows are  retrieved  from  the  server  in  order  to
     prevent memory shortages.

     Cursor variables returned by oraplexec must be specified  as
     a currently open cursor from the same logon connection:

          set lda [oralogon scott/tiger]
          set exec_cur [oraopen $lda]
          set fetch_cur [oraopen $lda]
          set plsql { begin
                  open :fetchcur for select empno, ename
                  from emp where job = :job ;
                  end;
               }
          oraplexec  $exec_cur  $plsql  :job  ANALYST   :fetchcur
          $fetch_cur
          orafetch  $fetch_cur  {puts "$empno $ename"}  ""  empno
          1  ename  2

     Using SQL bind variables are  more  efficient  than  letting
     Oracle  reparse SQL statements.  Use a combination of orasql
     ... -parseonly / orabindexec:

          set    sql    "insert     into     name_tab(first_name)
          values(:firstname)"
          orasql $cur $sql -parseonly
          foreach name [list Ted Alice John Sue] {
            orabindexec $cur :firstname $name
          }




Tcl                       Last change:                         12






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



     rather than:

          foreach name [list Ted Alice John Sue] {
            set    sql    "insert    into    name_tab(first_name)
          values('$name')"
            orasql $cur $sql
          }



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
     ORACLE_SID - The default Oracle server system ID.


FFFFIIIILLLLEEEESSSS
     /etc/oratab

     /etc/sqlnet

     $HOME/.sqlnet - definitions for Oracle servers.


BBBBUUUUGGGGSSSS
     Orawritelong compiled for Version 7 will may be  problematic
     until a specific OCI function is available from Oracle.

     Oracle OCI (Oracle  Call  Interface)  libraries  for  Oracle
     release  7.1.4 may cause problems due to changes that Oracle
     introduced in that version.   Use  OCI  libraries  7.0.x  or
     7.1.6+  if  you experience symptoms of excessively long con-
     nect times (2+ minutes) or "fetch out of sequence" errors.


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.  Concepts borrowed from my earlier work with Sybtcl, a
     TCL interface to the Sybase RDBMS product.


     tpoindex@nyx.net















Tcl                       Last change:                         13



