"Oratcl"(TCL) manual page

Table of Contents

## NAME

Oratcl - Oracle Database Server access commands for Tcl

## INTRODUCTION

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.

## ORATCL COMMANDS

oralogon connect-str
  Connect to an Oracle server using connect-str . The connect string should be a valid Oracle connect string, in the form:

  `` `` name
  `` `` name/password
  `` `` name@n:dbname
  `` `` name/password@n:dbname

  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 specification, the value of the environment variable ORACLE_SID is used as the server.

oralogoff logon-handle
  Logoff from the Oracle server connection associated with logon-handle . Logon-handle 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.

oraopen logon-handle
  Open an SQL cursor to the server. Oraopen returns a cursor to be used on subsequent Oratcl commands that require a cursor handle. Logon-handle must be a valid handle previously opened with oralogon. Multiple cursors 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.

oraclose cursor-handle
  Closes the cursor associated with cursor-handle. Oraclose raises a Tcl error if the cursor handle specified is not open.

orasql cursor-handle sql-statement ?-parseonly? ?-async?
  Send the Oracle SQL statement sql-statement to the server. Cursor-handle must be a valid handle previously opened with oraopen. Orasql will return the numeric return code "0" on successful execution of the sql statement. The oramsg array index rc is set with the return code; the rows index is set to the number of rows affected by the SQL statement in the case of insert, update, or delete .

  The oramsg array index rowid is set with the Oracle ROWID of the last row processed in an insert, update, or delete statement.

  Only a single SQL statement may be specified in sql-statement . Orafetch allows retrieval of return rows generated.

  The optional -parseonly argument parses but does not execute the SQL statement. The SQL statement may contain bind variables that begin with a colon (':'). The statement may then be executed with the orabindexec command, allowing bind variables to be substituted with values. Bind variables should only be used for SQL statements select, insert, update, or delete .

  The optional -async argument specifies the that SQL should be executed asynchronously. Orasql will return the numeric code "3123" when using -async. Note that -async is only available 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 orapoll below.

  Only -parseonly or -async may be specified.

  Orasql performs an implicit oracancel if any results are still pending from the last execution of orasql. Orasql raises a Tcl error if the cursor handle specified is not open, or if the SQL statement is syntactically incorrect.

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

orabindexec cursor-handle ?-async? ?:varname value ...?
  Execute a previously parsed SQL statement, optionally binding values to SQL variables. Cursor-handle must be a valid handle previously opened with oraopen. An SQL statement must have previously been parsed by executing orasql with the -parseonly option. Orabindexec may be repeatedly executed after a statement is parsed with bind variables substituted on each execution. Orabindexec does not re-parse SQL statements before execution.

  The optional -async 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 available 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 orapoll below.

  Optional :varname value 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 -async 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 messages for other possible values.

  The oramsg array index rowid is set with the Oracle ROWID of the last row processed in an insert, update, or delete statement.

orafetch cursor-handle ?commands? ?substitution_character? ?tclvarname colnum ...?
  Return the next row from the last SQL statement executed with orasql as a Tcl list. Cursor-handle must be a valid handle previously opened with oraopen. Orafetch raises a Tcl error if the cursor 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 orafetch contains the values of the selected columns in the order specified by select .

  The optional commands argument allows orafetch to repeatedly fetch rows and execute commands for each row. Substitutions are made on commands before passing it to Tcl_Eval() for each row. An optional fourth argument 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 performed on the commands string. Orafetch interprets the substitution character followed by a number (@n ) in commands as a result column specification. For example, @1, @2, @3 refer to the first, second, and third columns in the result. @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 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 commands on each row that is processed. Tcl variables are specified after the substitution_character , 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 break , orafetch execution is interrupted and returns with TCL_OK. Remaining rows may be fetched with a subsequent orafetch command. If the commands execute return or continue , the remaining commands are skipped and orafetch execution continues with the next row. Orafetch will raise a Tcl error if the commands 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 (-async argument on orasql or orabindexec ), executing orafetch will block until SQL execution is complete. See orapoll below.

  The oramsg array index rc is set with the return code of the fetch. 0 indicates the row was fetched successfully; 1403 indicates the end of data was reached.

  The index rows is set to the cumulative number of rows fetched so far. The oramsg array index rowid is set with the Oracle ROWID of the last row fetched when retrieved with a select for update statement.

  The oramsg array index maxlong limits the amount of long or long raw data returned for each column returned. The default is 32768 bytes.

  The oramsg array index nullvalue can be set to specify the value returned when a column is null. The default is "0" for numeric data, and "" for other datatypes.

orapoll cursor-handle ?-all?
  Return a list of cursor handles that have results waiting to be fetched. Cursor-handle must be a valid handle 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 -all may be specified to return a list of all cursor handles that have results waiting.

  Note that orapoll 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.

  Asynchronous processing (-async argument on orasql or orabindexec ) is actually done on a logon-connection basis. Executing orasql or orabindexec with -async causes all open cursors through the same logon connection handle to be changed to asycnchronous mode. Likewise, 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 blocking to/from asynchronous mode for other cursors.

orabreak cursor-handle
  Cause a currently executing SQL statement to be interrupted. Cursor-handle must be a valid handle previously opened with oraopen. Use the oracancel command to cancel SQL results, see below.

  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.

oraplexec cursor-handle pl-block ?:varname value ...?
  Execute an anonymous PL block, optionally binding values to PL/SQL variables. Cursor-handle 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 :varname value 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 :varname 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 oraplexec 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 oraplexec 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. Oraplexec raises a Tcl error if the cursor handle specified is not open, or if the PL/SQL block is in error. The oramsg array index rc contains the return code from the stored procedure.

oracols cursor-handle
  Return the names of the columns from the last orasql, orafetch, or oraplexec command as a Tcl list. Oracols may be used after oraplexec , in which case the bound variable names are returned.

  The oramsg array index collengths is set to a Tcl list corresponding to the lengths of the columns; index coltypes is set to a Tcl list corresponding to the types of the columns; index colprecs is set to a Tcl list corresponding to the precision of the numeric columns, other corresponding non-numeric columns are a null string (Version 7 only); index colscales 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.

oracancel cursor-handle
  Cancels any pending results from a prior orasql command that use a cursor opened through the connection specified by cursor-handle. Cursor-handle must be a valid handle previously opened with oraopen. Oracancel raises a Tcl error if the cursor handle specified is not open.

oracommit logon-handle
  Commit any pending transactions from prior orasql commands that use a cursor opened through the connection specified by logon-handle. Logon-handle must be a valid handle previously opened with oralogon. Oracommit raises a Tcl error if the logon handle specified is not open.

oraroll logon-handle
  Rollback any pending transactions from prior orasql commands that use a cursor opened through the connection specified by logon-handle. Logon-handle must be a valid handle previously opened with oralogon. Oraroll raises a Tcl error if the logon handle specified is not open.

oraautocom logon-handle {on | off}
  Enables or disables automatic commit of SQL data manipulation statements using a cursor opened through the connection specified by logon handle. Logon-handle 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". Oraautocom raises a Tcl error if the logon handle specified is not open.

orawritelong cursor-handle rowid table column filename
  Write the contents of a file to a LONG or LONG RAW column. Cursor-handle must be a valid handle previously opened with oraopen. Rowid is the Oracle rowid of an existing row. The rowid must be in the format of an Oracle rowid datatype. Table is the table name that contains the row and column. Column is the column name that is the LONG or LONG RAW column. Filename 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 update 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, "select rowid from table where ..." .

  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.

orareadlong cursor-handle rowid table column filename
  Read the contents of a LONG or LONG RAW column and write results into a file. Cursor-handle must be a valid handle previously opened with oraopen. Rowid is the Oracle rowid of an existing row. The rowid must be in the format of an Oracle rowid datatype. Table is the table name that contains the row and column. Column is the column name that is the LONG or LONG RAW column. Filename is the name of a file in which to write the LONG or LONG RAW data. Orareadlong composes and executes an SQL select statement based on the table, column, and rowid. A properly formatted Rowid may be obtained through a prior execution of orasql, "select rowid from table where ..." .

  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.

## SERVER MESSAGE AND ERROR INFORMATION

Oratcl creates and maintains a Tcl global array to provide feedback of Oracle server messages, named oramsg . Oramsg is also used to communicate with the Oratcl interface routines to specify null return values and LONG limits. In all cases except for nullvalue and maxlong , 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 with the global statement in any Tcl procedure needing access to oramsg.

Oramsg elements:

version
  indicates the version of Oratcl.

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

maxlong
  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 maxlong becomes effective on the next call to orasql. See notes on maxlong usage with orafetch.

handle
  indicates the handle of the last Oratcl command. Handle is set on every Oratcl command (execpt where an invalid handle is used.)

rc
  indicates the results of the last SQL command and subsequent 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:

  > - Function completed normally, without error.

900-999
  invalid SQL statement, invalid sql statements, missing keywords, invalid column names, etc.
1000-1099
  program interface error, e.g., no sql statement parsed, SQL bind variables not bound, logon denied, insufficient privileges, etc.
1400-1499
  execution errors or feedback.
  - end of data was reached on an orafetch command.
  - a column fetched by orafetch was truncated. Can occur when fetching a LONG or LONG RAW, and the maxlong value is smaller than the acutal data size. 3123
    asynchronous execution is pending completion.
  errortxt
    the message text associated with rc. Since the oraplexec command may invoke several SQL statements, there is a possiblity that several messages may be received from the server.
  collengths
    is a Tcl list of the lengths of the columns returned by oracols. Collengths is only set by oracols.
  coltypes
    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.
  colprecs
    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.
  colscales
    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.
  sqlfunc
    the numeric OCI code of the last sql function performed. See the OCI manual for descriptions.
  peo
    parse error offset, an index into an sql string that failed due to error.
  ocifunc
    the number OCI code of the last OCI function called by Oratcl. See the OCI manual for descriptions.
  rows
    the number of rows affected by an insert, update, or delete in an orasql command, or the cumulative number of rows fetched by orafetch.
  rowid
    the Oracle ROWID of the row affected by a select insert, update, or delete 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.
  ociinfo
    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 version

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

  ## NOTES

  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 cursors is artificial, based on a fixed table in oratcl.c. Change the source #define ORATCLLDAS or #define ORATCLCURS if more are needed.

  Oratcl does not mix well with Tcl slave interpreters. If Oratcl functions are needed in a slave, set up alias commands in the slave to execute Oratcl commands in the master 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 malloc() maxlong 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 allocated, 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
  > }

  rather than:

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

  ## ENVIRONMENT VARIABLES

  ORACLE_SID - The default Oracle server system ID.

  ## FILES

  /etc/oratab
  /etc/sqlnet
  $HOME/.sqlnet - definitions for Oracle servers.

  ## BUGS

  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 connect times (2+ minutes) or "fetch out of sequence" errors.

  ## AUTHOR

  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

  Table of Contents

  - NAME
  - INTRODUCTION
  - ORATCL COMMANDS
  - SERVER MESSAGE AND ERROR INFORMATION
  - NOTES
  - ENVIRONMENT VARIABLES
  - FILES
  - BUGS
  - AUTHOR