ActiveTcl User Guide

Oratcl Frequently Asked Questions

Table of Contents

Section 1: General Information

• Q1.1 What is Oratcl?
• Q1.2 What platforms does Oratcl support?
• Q1.3 What versions of Oracle does Oratcl support?
• Q1.4 What version of Oratcl should I use?

Section 2: Obtaining Oratcl

• Q2.1 How is Oratcl distributed?
• Q2.2 Where can I get Oratcl?

Section 3: Building Oratcl

• Q3.1 How do I build Oratcl on UNIX systems?
• Q3.2 How do I build Oratcl on Win32 systems using Cygwin?
• Q3.3 How do I build Oratcl on Win32 systems using Microsoft development tools?
• Q3.4 When I try to compile Oratcl, I get an error like "unrecognized option `-rpath'." How can I fix this?

Section 4: Using Oratcl

• Q4.1 Is there documentation for Oratcl?
• Q4.2 How do I configure SQL*NET for Oratcl?
• Q4.3 What might a tnsnames.ora file look like?
• Q4.4 When I select DATE fields, the date is in the wrong format. How do I get what I want?

Section 5: Getting Help

• Q5.1 How can I get help for Oratcl?

Section 6: Contributing to Oratcl

• Q6.1 How can I contribute to Oratcl?

Section 1: General Information

Q1.1 What is Oratcl?

Oratcl is an extension to Tool Command Language (Tcl) that provides access to a Oracle Database server. Oratcl adds additional Tcl commands that login to an Oracle Server, pass SQL code, read results, etc. Oratcl was inspired by similar tools written for Perl (sybperl, oraperl) but was written from scratch instead of borrowing on the work of either Perl extension.

Q1.2 What platforms does Oratcl support?

The following is a list of platforms upon which Oratcl has been successfully deployed:

• Solaris 2.6, 7, 8, 9 and 10 *
• Windows 9x, NT4, 2000, XP, 2003 *
• AIX 4.3 *
• HP/UX
• RedHat Linux x86: ES3, AS3, ES4, AS4 *
• RedHat Linux x86-64: ES3, AS3, ES4, AS4 *
• Fedora core: 3, 4

The entries above with asterisks (*) have been tested by the developers. Other entries have been reported by users, but unverified by the developers.

It is intended that Oratcl work on any platform that supports both Tcl/Tk and Oracle. If you have difficulties building and/or running Oratcl, please post a message to the Oratcl/Sourceforge Help Forum.

Q1.3 What versions of Oracle does Oratcl support?

The current versions of Oratcl (version 4.4) supports Oracle 8i, 9i, 10g (32 bit and 64 bit versions) and the 10g release 2 instant client. Oratcl (version 3.3) supports older releases of Oracle that use the older OCI API. (I.E. Oracle 8.0.x). Previous versions supported the Oracle 7 OCI API and remain available for Oracle 7 users.

Q1.4 What version of Oratcl should I use?

Please refer to the table below when choosing a version of Oratcl:

		Oracle Version
		7.x	8.0.x	8.1+	8.1.7	9i	10g
Tcl Version	Tcl 7.x	Oratcl 2.6	Oratcl 2.6	Oratcl 2.6	Unknown	Unknown	Unknown
	Tcl 8.0x	Oratcl 2.6	Oratcl 2.6	Oratcl 2.6	Unknown	Unknown	Unknown
	Tcl 8.1-8.2	Oratcl 2.7	Oratcl 3.0.1	Oratcl 3.0.1	Unknown	Unknown	Unknown
	Tcl 8.3	Unknown	Oratcl 3.3	Oratcl 4.4	Oratcl 4.4	Oratcl 4.4	Oratcl 4.4
	Tcl 8.4	Unknown	Oratcl 3.3	Oratcl 4.4	Oratcl 4.4	Oratcl 4.4	Oratcl 4.4
	Tcl 8.5	Unknown	Oratcl 3.3	Oratcl 4.4	Oratcl 4.4	Oratcl 4.4	Oratcl 4.4

Section 2: Obtaining Oratcl

Q2.1 How is Oratcl distributed?

Current versions of Oratcl are distributed in source code form for all supported platforms (in tar/gzip format) .

Older versions of Oratcl will be available as long as there is demand.

Q2.2 Where can I get Oratcl?

Distributions will be made available on the SourceForge Oratcl site as soon as possible.

The most current version of Oratcl is also available through anonymous CVS . Please use oratcl as the modulename to check out.

Section 3: Building Oratcl

Q3.1 How do I build Oratcl on UNIX systems?

Oratcl uses the GNU autoconf automatic configuration system to create Makefiles appropriate for your Tcl and Oracle installations. Building Oratcl is often as simple as:

cd {oratcl source directory}
./configure --prefix=/path_to_installed_tcl
make && make install
     

More specific instructions can be found in the oratcl/INSTALL file included with the source distribution.

Q3.2 How do I build Oratcl on Win32 systems using Cygwin?

The GNU autoconf system is known to work for building and installing Oratcl for Cygwin environments. However, you must have installed Tcl/Tk by building it in the Cygwin environment for the Oratcl build to succeed.

The Oratcl objects built in the Cygwin environment will work with either a Cygwin Tcl/Tk or a standard Win32 Tcl/Tk installation.

Instructions for building Oratcl in a Cygwin environment are the same as for any other environment.

Q3.3 How do I build Oratcl on Win32 systems using Microsoft development tools?

Makefiles appropriate for building Oratcl with Microsoft Developer's Studio may be found in the oratcl/windows directory. Pre-built Win32 libraries may also be found in that directory.

Q3.4 When I try to compile Oratcl, I get an error like "unrecognized option `-rpath'." How can I fix this?

This error seems to occur on systems where the gcc compiler is installed as "cc", like Linux. The solution is to set the environment variable CC to "gcc" before running configure. For example, from the unix directory in the Oratcl source tree:

env CC="gcc" ../configure --prefix=/path/to/install
     

Section 4: Using Oratcl

Q4.1 Is there documentation for Oratcl?

The current Oratcl distribution includes a manual page in both HTML and nroff formats. You can find the manual pages in the oratcl/doc directory, or installed in prefix/man/mann on UNIX systems.

The manual pages are also available on-line. The most current version is available as the Oratcl Manual page at SourceForge.

Other versions of the manual pages are linked from the Oratcl Main Page also at SourceForge.

Q4.2 How do I configure SQL*NET for Oratcl?

Oratcl requires no special configuration to connect with a database other than a valid Oracle client install on the local server.

Recent versions of Oratcl are not linked with Oracle libraries at build time. Oratcl will dynamically load the oracle client libraries found at $ORACLE_HOME/lib or using the ORATCL environment variable ORACLE_LIBRARY to override the $ORACLE_HOME/lib. This ORACLE_LIBRARY variable is most useful with the 10g instant client.

Q4.3 What might a tnsnames.ora file look like?

The SQL*NET configuration for a database connection may be very complex, and is outside the scope of this document. However, at its simplest, a tnsnames.ora file may resemble this for TCP/IP connected databases:

mydb =
  (DESCRIPTION =
    (ADDRESS_LIST =
        (ADDRESS =
          (PROTOCOL = TCP)
          (HOST = mydbhost.domain.com)
          (PORT = 1521)
        )
    )
    (CONNECT_DATA =
      (SID = db)
    )
  )
     

In this case, the connect string given to oralogon should resemble "username/password@mydb".

Please note that the database alias ("mydb") need not be the same as the SID ("db"), but you must use the alias in the connect string. Also, Net8 introduced some new syntax and features and you may find that your configuration files look quite different than this stripped-down example.

Q4.4 When I select DATE fields, the date is in the wrong format. How do I get what I want?

Whenever a DATE field is selected, the database does an implicit TO_CHAR() conversion to change the data from the internal date format into something recognizable as a date. The actual format used in the TO_CHAR() operation is defined by the NLS_DATE_FORMAT session parameter, which may default to something like 'DD-MON-YYYY' rather than what you want.

To get the DATE information in the format you want, you can either set the NLS_DATE_FORMAT on a per-session basis, alter the NLS_DATE_FORMAT system-wide by editing the init.ora file, or request an explicit TO_CHAR() whenever you select a DATE. Usually, the first method is the easiest when you want all dates to appear in the same format to the Tcl program.

Below is an example of setting NLS_DATE_FORMAT on a per-session basis:

# oralogon, oraopen, etc. happen above
oraparse $cur {alter session set nls_date_format='DD-MON-YYYY'}
oraexec $cur
oraparse $cur {select sysdate from dual}
oraexec $cur
while [orafetch $cur -datavariable now] == 0] {
    puts $now
}

oraparse $cur {alter session set nls_date_format='DD-MON-YYYY HH:MI:SS'}
oraexec $cur
oraparse $cur {select sysdate from dual}
oraexec $cur
while [orafetch $cur -datavariable now] == 0] {
    puts $now
}
     

Section 5: Getting Help

Q5.1 How can I get help for Oratcl?

The Oratcl developers monitor the SourceForge Oratcl Forums and the Tcl Newsgroup as time permits.

You may also submit questions and/or concerns to Todd Helfter (Oratcl developer/maintainer) or Ben Lewis (documentation). We will try to respond in a timely manner.

Section 6: Contributing to Oratcl

Q6.1 How can I contribute to Oratcl?

The Oratcl developers welcome problem reports, feature suggestions, and especially patches from anyone that would like to contribute to the furtherment of the project. Below are some links to the various SourceForge features that allow the developers to keep track of these things:

• Bug Reporting Page
• Patch Page
• Oratcl Forums

Please be sure to include a complete description of the computing environment you are using and any necessary contact information with your Bug Reports. Patch submitters, please include the information we'll need to credit you properly!