This file contains hints and tips about Oraperl, dealing with problems which
have arisen in the past.

The topics dealt with are the following:

	Memory Usage
	Using bsdcurses.mus instead of curses.mus
	Building on a Convex machine
	Building on Dual Universe machines
	Building with Perl v3
	Using Bind Variables
	Building with Oracle v5


Memory Usage
============

With versions of Perl prior to 4.034, there is a memory leak when
repeated calls to &ora_fetch() are made within a while() loop.

The correct solution is to upgrade. However, if that is not possible
for some reason, there is a workaround.

Create a Perl subroutine which returns a row from a database and
call this instead. So instead of

	while (@data = &ora_fetch($csr))
	{
	    ...
	}

you should use something like this:

	sub getrow
	{
	    local($csr) = @_;
	    local(@data);

	    @data = &ora_fetch($csr);
	}

	...

	while (@data = &getrow($csr))
	{
	    ...
	}


Using bsdcurses.mus instead of curses.mus
=========================================

If you built curseperl using bsdcurses.mus (BSD curses) instead of
curses.mus (ATT curses), you must either:

1) #ifdef out the references to the testcallback usersub
   in bsdcurses.mus, or

2) Extract the callback routines from $SRC/usub/usersub.c into a
   separate file, and link it with coraperl.


Building on a Convex machine
============================

Comment out the definition of STRTOUL in the Makefile.


Building on Dual Universe machines
==================================

This was reported on a Pyramid machine, but I think it applies to most (if
not all) dual-universe systems (Sequent, Gould, etc).  Although packages
built in one universe will run correctly in the other, hybrids (packages
built partly in one universe and partly in the other) will not work
properly in either. On the Pyramid, the symptom was that output was being
lost, although a debugging trace showed that the program was working
properly.

Since Oracle specifies that it is to be installed in the ATT universe, you
must also compile Perl and Oraperl (and the curses usersubs, if you are
building Coraperl) in the ATT universe to allow them to be linked together.


Building with Perl v3
=====================

Ideally, get hold of v4. However, if you have to work with v3, uncomment
the definition of STR_2MORTAL in the Makefile. Note also the section on
memory usage above.


Using Bind Variables
====================

The support for bind variables does not reflect the full potential of Pro*C.

Firstly, bind variables may only be numeric; named bind variables are not
supported. They must run in sequence from 1. (This is to make it easy for
&ora_bind() to check that it has received the correct number of parameters.)

Secondly, they may only be used to modify values within the SQL statement,
not field or table names. Thus

	insert into telno values (:1, :2)

is valid, but

	select * from telno order by :1

is not. This made the interaction between &ora_open() and &ora_bind() simpler,
but if it's a serious restriction for you let me know, and I'll look into
extending it. (Of course, there's nothing to stop you doing:

	$order_by = "name";
	&ora_open($lda, "select * from telno order by $order_by");

so I don't think it should be too big a problem.)


Building with Oracle v5
=======================

[ This information was originally in a separate file, Oracle-v5)    ]
[ You will have to adapt this slightly as the Makefile has changed. ]

The Makefile includes library definitions which are suitable for Oracle v6
on an Encore Multimax running UMAX V. I do not have access to any other
configuration to test Oraperl.

Oraperl just links to the Oracle Pro*C libraries in the same way as any
other Pro*C program, so give it the same libraries as you would give one
of your own programs. See your Pro*C manual or example programs for details.

However, two people sent me their modified Makefiles for Oracle v5. Since
they are different in effect, not only in presentation, I assume that the
directory structure of Oracle varies between systems. The two setups I was
sent are reproduced below. Maybe one of them will be suitable for your
system if mine isn't.

First method - this assumes that the libraries live under $ORACLE_HOME/c/libs
and $ORACLE_HOME/rdbms/libs, as well as requiring an additional .o file.

> ORALIBS	= -locic -loracle -lupi -losd -losn -loracle \
>	$(ORACLE_HOME)/rdbms/libs/osntab.o -lutt -losd -losn -lclib0
>
> LDFLAGS	= -L$(ORACLE_HOME)/c/libs -L$(ORACLE_HOME)/rdbms/libs
>
> oraperl: $(SRC)/uperl.o $(OBJS)
> 	$(CC) -o oraperl $(LDFLAGS) $(SRC)/uperl.o $(OBJS) $(ORALIBS) $(LIBS)

Second method - much simpler. Only seems to require the first two libraries
(libocic and liboracle) of the previous method, but this time they live under
$ORACLE_HOME/pro.

> OTHERLIBS	=
> CLIBS		= $(OTHERLIBS)
> OCILIB	= $(ORACLE_HOME)/pro/libocic.a
> NETLIBS	=
> ORALIBS	= $(ORACLE_HOME)/pro/liboracle.a

Thanks to Mark Adams and Norman Frech for their help.
