Possible book on Oratcl if there is enough interest ... what would we like to see in it?
ewils...@gmail.com
In another thread Todd Helfter, the current maintainer of the Oratcl
package, said that he may write a book on Oratcl if there is
sufficient interest (6 or more people interested).
Oratcl is a well-maintained extension suitable and used for mission
critical work: http://oratcl.sourceforge.net/
For me this offer by Todd is the most exciting development in the Tcl
community for a while. There are only 2 books on Tcl of recent
vintage: that of Flynt and that of Welch/Jones/Hobbs. Apart from the
intrinsic value of a book on Oratcl, we are for the first time in many
years seeing the possibilty of a book on a specific Tcl extension.
The one or two books that had information on Oratcl (and other
extensions) are sadly out of print and 2nd hand copies are very
expensive.
My hope is that the community will get behind Todd. This really is a
very exciting opportunity for us. If we can show potential authors
that we a willing to pay for their hard work, this can only result in
more books. And more books means less time guessing, better
information, better code, fewer bugs and more fun with Tcl.
My feeling is that this book will be self-published - this normally
entails more affordable pricing. So if you have ever lamented the
lack of documentation, worried about not being able to contribute to
Tcl, worried about the profile of Tcl. worried about the future of Tcl
or worried about anything at all, please undertake to buy a copy by
replying to this mail on the list to show your support. We may even
see more books from other authors (Tcl internals, IncrTcl, Tcl3D, Tcl
gotchas, Tile, Sqlite, XoTcl, Snit, etc)
I'm thinking not of door-stopping books but shorter, more focussed
things between a booklet and a book -- easier to get done and cheaper.
Lets say "yes please" or "+1" in this thread and get Tcl moving again.
Regards
E Wilson
ewils...@gmail.com
> Hello Tclers
>
> In another thread Todd Helfter, the current maintainer of the Oratcl
> package, said that he may write a book on Oratcl if there is
> sufficient interest (6 or more people interested).
+1
Please also feel free to say what material you may want to see in the
book.
E Wilson.
Larry W. Virden
As for material to cover - the questions I most frequently get are
ones about proper error handling, conversion questions from previous
versions, and questions about whether oratcl supports accessing tables
on various oracle version instances.
Probably none of that is particularly useful to the writer.
Cameron Laird
Ha! Nothing about installation/configuration/security/networking?
Well, you do mention "conversion questions" ...
Arnulf Wiedemann
+1 from me
Arnulf
Michael Schlenker
> Hello Tclers
>
> In another thread Todd Helfter, the current maintainer of the Oratcl
> package, said that he may write a book on Oratcl if there is
> sufficient interest (6 or more people interested).
>
> Oratcl is a well-maintained extension suitable and used for mission
> critical work: http://oratcl.sourceforge.net/
>
nice treatment of using oratcl as a nonblocking db interface with Tcl's
event loop would be nice.
Other topics of interest: Handling encodings/data formats when binding,
proper error handling, advanced connection setup.
Michael
thel...@gmail.com
wrote:
> ewilsonm...@gmail.com schrieb:> Hello Tclers
Ok, I'll get busy. FYI if there are any people out there that truely
understand Unicode and are willing to help out with some tricky
stupidity I'm seeing in the Oratcl 4.5 development tree. Give me a
jingle
In the meantime, file this little trick under 'advanced connection
setup.'
It is possible to utilize Oracle's Proxy Authentication.. I.E. log in
as user X using user Y's credentials.
I.E. using the alter user X grant connect through Y;
create user x identified by "x";
grant create session to x;
create user y identified by "y";
grant create session to y;
alter user x grant connect through y;
is Sqlplus you could connect to 'x' using 'y's credentials like this.
connect y[x]/y
In oratcl you can do this as well (but due to tcl using [] for a few
things, we have to escape them)
oralogon y\[x\]/y
that and alot of other goodies are sitting around in my tricks bag.
-Todd
Robert Hicks
+1
Examples! : )
Robert
Robert Hicks
<snip>
> >Probably none of that is particularly useful to the writer.
>
> Ha! Nothing about installation/configuration/security/networking?
Heh, all of those! : )
I am not a full time Tcl'er and sometimes when I try to use Oratcl
with my limited knowledge of Tcl it gets me in trouble.
Robert
ewils...@gmail.com
>
> In another thread Todd Helfter, the current maintainer of the Oratcl
> package, said that he may write a book on Oratcl if there is
> sufficient interest (6 or more people interested).
>
> Oratcl is a well-maintained extension suitable and used for mission
> critical work:http://oratcl.sourceforge.net/
>
> For me this offer by Todd is the most exciting development in the Tcl
> community for a while.
[snip]
outside of code developments I should clarify.
E Wilson
mvst
>>
>> Regards
>> E Wilson
+1
Michel.
ewils...@gmail.com
> On Nov 12, 3:44 pm, Michael Schlenker <schl...@uni-oldenburg.de>
>
> > nice treatment of using oratcl as a nonblocking db interface with Tcl's
> > event loop would be nice.
>
> > Other topics of interest: Handling encodings/data formats when binding,
> > proper error handling, advanced connection setup.
>
> > Michael
I'm hoping that we will get more messages like the above from Michael
and other experienced users of Oratcl since I'm coming to this as a
newbie.
> Ok, I'll get busy. FYI if there are any people out there that truely
> understand Unicode and are willing to help out with some tricky
> stupidity I'm seeing in the Oratcl 4.5 development tree. Give me a
> jingle
>
> In the meantime, file this little trick under 'advanced connection
> setup.'
>
> It is possible to utilize Oracle's Proxy Authentication.. I.E. log in
> as user X using user Y's credentials.
> I.E. using the alter user X grant connect through Y;
>
> create user x identified by "x";
> grant create session to x;
> create user y identified by "y";
> grant create session to y;
> alter user x grant connect through y;
>
> is Sqlplus you could connect to 'x' using 'y's credentials like this.
>
> connect y[x]/y
>
> In oratcl you can do this as well (but due to tcl using [] for a few
> things, we have to escape them)
>
> oralogon y\[x\]/y
>
> that and alot of other goodies are sitting around in my tricks bag.
>
> -Todd
Way to go! And thank you.
Here are some general thoughts ... from someone who has never used
Oratcl but is serious about getting stuck in. I don't have the
specific requests that Michael has (for obvious reasons). Please take
everything I say as a suggestion for you merely to think about only.
You may want to use certain things (indeed, you may have decided on
these things already) and find other things not so compelling. I've
written it quickly and have chosen to get to you rather than polish
it. If I come across as brusque, please know that it is not
intended ... I just want to get this off before I go to bed :-)
The book could be both a tutorial and reference that is just
as readable in an armchair away from the computer.
This is my hope: that when we finish the book, we will be
able to write a real (as opposed to a toy) database-backed
application using Oratcl and Oracle that consists of a set
of Tcl scripts to be called from the command line. If we
know Tk, we will also be able to write an app with a GUI
frontend.
that when we finish the book, we will keep it handy as a
complete reference on Oratcl commands, their usage, the
errors they throw, and as a source of high quality code with
complete error handling.
Some thoughts:
- Do not assume any knowledge of OCI programming.
- Assume Tcl as covered by the Official Tcl Tutorial. Add
any further Tcl specific material as necessary.
- Assume knowledge of SQL and relational db theory.
- Use Oracle Database Express, perhaps some advice on
setting environment variables. (Don't know if you need to
talk about installation)
- Some material on how Oracle database system works (the
client, listener,etc)
- Include security considerations.
- Include configuration.
- Use SQL*Plus (instead of the GUI) since it is less likely
date.
Use a simple database (set up with a Tcl script); only rich
enough to carry the examples of all commands.
You could provide a larger project in the second part of the
book, using Oratcl for all aspects from creating the
database to scripts that provide reports. Even if it isn't
much more complex, you could use this as a means of showing
the use of Oratcl commands in real-world sequence; whereas
in the case of the first database with which you explain all
the commands, you may choose a sequence that is optimised
for quicker understanding. At any rate, a more complete
project will certainly enhance the book considerably. It
will show the reader how to go about creating a real db
application using Oratcl.
Back to the first part of the book ...
For *each* Oratcl command:
- explain it and in context i.e.
* what it does, when to use it, how to use it
* what's good about it, what's bad about it
* what Tcl statement or Oratcl statement should precede
it and what should follow it
* gotchas
* the various options
* give as many simple examples as necessary to explain
the options of each command
This possible sequence may provide an idea:
1. give the name of the command, what sort of thing it is
used for, describe it
2. give a simple example, 3. then the complete
specification 4. and then more examples.
What's different here, is giving a small example before the
specification.
------------------------[OT]-------------------------------
I liked the way a brilliant professor of mine taught math:
show concrete examples, generalise, prove. This was in stark
contrast to those who started the lecture with a theorem.
------------------------------------------------------------
For me, just as vital in the manpages are the examples that:
1. make real (instantiate) the specification
2. clarify the semantics (e.g. the dict manpage - kudos ...
and more please!)
Also, by all means show examples at the Tcl shell but please
don't eschew complete examples in Tcl scripts.
Please include error checking in the code - assume that we
will copy and paste your code into real applications. Cover
every error that can be thrown by every command:
* when/why the error can occur
* how to catch and handle each one, what to do next
* don't assume we know about Oracle errors
I have yet to hear of anyone complaining about too many
examples in a book. I have heard complaints about examples
that are too long or require the reading of other examples
to understand the current one, resulting in annoying
back-n-forthness. The "not enough examples" or "examples are
not explained and hard to follow" or "examples have typos
and are wrong" reviews are a sure killer on Amazon.
Examples/scripts of more advanced usage (event-driven
callbacks, persistent connections, multiple threads, how
these things can interact and explode in our faces if we do
X instead of Y), tricks and gotchas at appropriate points. I
haven't a clue about which points are appropriate.
No need to give examples with Tk unless there is something
that is done differently in that environment. Or there are
certain things we shouldn't do or certain gotchas that we
need to know. Remark on similarities or differences.
Hopefully, the code should run perfectly. I and probably
others much more qualified than me can help test.
Although you don't need to teach PL/SQL, just like you won't
teach SQL, it would be good if you showed us how to use
PL/SQL from Oratcl in all its glory.
In summary, all you need to do is take us from zero to
hero ;-)
Here is a link you may have already - it could provide some
little help:
http://www.oracle.com/technology/tech/php/pdf/underground-php-oracle-manual.pdf
Regards
Edward Wilson
Robert Hicks
<snip>
What *kind* of book are we talking about? A commercial book through
one of the big vendors? Something out of the goodness of your heart?
Something in-between?
Robert
ewils...@gmail.com
Whatever Todd decides but I imagine a "commercial" book that is self-
published and printed on demand.
Regards
E Wilson
Bezoar
+1
thel...@gmail.com
These are all great suggestions. And as some have asked.. What am I
thinking... Well, I am thinking of a book which is more than a man
page and a test suite. The book would be sent to the publishers to
see if they are interested. If not, well then it would be a download
document, likely from the sourceforge site. In either case, any email
address in this thread will be given 'beta' copies upon request when I
actually get something together.
I've been using Oratcl professionally since 1994 and there are some
seriously cool things about it that were not to be found anywhere else
for some time. There are still many things I'd like to add to the
code base. Some of them beyond my comprehension.
The book will NOT be a primer on OCI programming. Occasionally, I
might throw in a grey box to indicate which OCI calls are being
utilized. There are about 10,000 OCI library functions. Oratcl uses
maybe 60. The most complicated thing of all is to not rely on
features available in only certain versions of Oracle and also TCL.
Some of the new things coming in Tcl 8.5 have profound implications on
my code base, but until 8.4 is dust... I have to find other
methods. The same is true of Oracle.
The syntax of Oratcl is old school. Before Tcl adopted the Tk way of
returning and object name as a function. Thus we have many ora***
commands instead of the more modern
handle = [logon]
$handle open
$handle close
type syntax that Tcl has evolved too.
Oratcl was written in the early days of Tcl 7. ( I think... I will
have to get Tom Poindexter to write the early history chapter)..
Before namespaces, before slave interpreters, before threading, before
Unicode, before Tcl Objects. It has evolved to use all of those new
features and some not listed, while maintaining an almost 90%
backwards compatibility... Only the advent of threading in Tcl
forced a change in the 'orafetch' model and removed the old Global
Array 'oramsg' in favor of a new command.
If I were writing this today from scratch, the command syntax would be
radically different.
One of the things I'm most proud of is Oratcl 4.4 which has the
ability to be compiled 'without' any Oracle code on the system. It
loads the OCI libraries at runtime and dynamically links to the proper
functions. This is one of the reasons why it is now in the ActiveTcl
distribution.
Oratcl works perfectly with the Oracle instant client and vs. the free
Oracle Express Edition (XE). These will be referenced in any work as
will Oracle 9i -> 11g.
I've no intention whatsoever of revisiting Oracle older than 8i or in
Oratcl versions older than 3.3 which is the last version to use the
old Oracle 7 call interface.
My Preliminary Chapter list (besides the blather at the beginning)
is:
Getting Started: What you need to have on your computer, What ENV
variables are used and how
Getting connected: oralogon, oralogoff, oraopen, oraclose
Enabling options : oraconfig
Performing SQL : oraparse, orabind, oraexec
Fetching results : orafetch (including all possible options, coolness
and lots of examples)
Execution of PL/SQL : including ref_cursors, and other things that can
be done in PL/SQL
Oracle Introspection : oradesc, orainfo, oracols
Historic (backwards compatible) oratcl functions : orasql,
orabindexec, and oraplexec
(note these are now just wrappers to the
oraparse,orabind,oraexec,orafetch primitives and using the primitives
is faster :) )
Accessing Long and Long Raw columns : oralong
Accessing large objects (CLOB and BLOB) : oraparse,orabind,oraexec,
and the oralob function
Running Oratcl in slave interpreters.. : great for GUI's
Running Oratcl in multithreaded mode
Running Oratcl in asynchronous mode.
more stuff....
Building and installing Tcl/Tk and Oratcl (multiple versions, options
and how to get them from CVS) Unix only.
** It used to be extremely simple to build Oratcl for windows when Tcl
could be built in cygwin. Now even I don't know how to do it and I've
even got Microsoft Dev Studio. The ActiveState guys have to build the
windows binaries for me because they can build Tcl for windows.
Linking Oratcl directly into 'C' programs. The combination of 'C'
daemon code with embedded interpreters can make for a very fast and
extremely flexible application servers.
At this point I want to do some real world examples. provide some
useful snippets of code, etc.
Did you know that if you combine.. Tcl, Tk, Oratcl, mclistbox, tile,
and a piece of my tcl code,
you can build beautiful insert/update/delete/search boxes using only 3
or 4 lines of code.
I'll show you how.
High Security. Combining a fast GUI frontend + Oratcl + PL/Sql
Packages with REF_CURSOR types on the database end, you can build
front end applications that have only 2 Oracle permissions. create
session and execute package.
Combined with Autonomous PL/SQL functions for logging. Add in a
little 'tclpro' magic :: tclcompile and tbcload, your users won't be
able to read your application code either.
For 10+ years, I built and deployed real time applications and daemons
using these techniques for a major university. (They will remain
unnamed until they give permission, but HINT it's in my old email
address in the change log)
Oratcl is used in many other extensions available from sourceforge.
Ones that come to mind is the benchmarking software 'hammerora' and
I'm sure others might come forward. I would like them to comment as
well.
I'm taking this project seriously, there should be some product to
review in a month or two.
Thanks for your support
-Todd
Robert Hicks
If the publishers don't bite then I am sure I would pay some for your
time and effort. I posted a "minibook" question on the group. Grails
has a 131pp book and you can download the PDF or pay $19.95 to get a
dead tree copy of it. I can see something about that long pages wise
to learn Oratcl with examples and such.
Oh, and I would gladly proof read it as well.
Robert
Link to Grails book for example only: http://www.infoq.com/minibooks/grails
Robert Hicks
Oratcl is now installed when you install ActiveTcl. : )
thel...@gmail.com
And has been for over a year.
Robert Hicks
Ah, I misread your earlier post. I thought you said you were doing the
Unix only build process because it sucks to do on Windows but that
isn't what you said at all. My bad...
Robert
thel...@gmail.com
No you more or less are correct. It's not that the windows build
process sucks, it's that I no longer know how its done.