Oracle

Solutions for High-End

Oracle® DBAs and Developers Professional

Object Types and

Inheritance: From
DBMS_OUTPUT to
Object-Oriented
Stream I/O April 2004
Volume 11, Number 4

Gary Menchen 1 Object Types and Inheritance:

From DBMS_OUTPUT to
Object-Oriented Stream I/O
Gary Menchen
Using DBMS_OUTPUT as a starting point, the inheritance and polymorphism of
Oracle’s object types are used to construct an object type hierarchy patterned 7 Exploring Options: Multiple
after the Java Stream OutputStream classes. Gary Menchen’s examples provide Paths to an Answer
convenient interfaces for debugging, as well as for generating output to CLOBs Steven Feuerstein
and BLOBs. 11 Using the Oracle9i R2
Templates Feature of DBCA

I
N the past two issues of Oracle Professional, I’ve written a pair of articles on Windows 2000
about Oracle’s object types that illustrated how they can be intelligent data Stan Novinsky
structures—that is, data structures bound to procedures and functions. 14 LOG4PLSQL Oracle Database
As a software tool, that was pretty much the limit of their capabilities prior Logging Tools
to Oracle9i. With Oracle9i, however, object types now have an even more Guillaume Moulard
powerful feature: inheritance.
16 April 2004 Downloads
In this article I discuss the construction of a “class hierarchy”: a group of
object types for managing unformatted output. This project began when I first
started thinking about writing an object type wrapper for dbms_output. I
initially had two primary motivations. First, I use dbms_output for debugging
purposes, but I also send the same information to other destinations, Indicates accompanying files are available online at
www.pinnaclepublishing.com.
particularly CLOBs. I thought object types could be used to make the
destination of logging information transparent. Second, I
wanted to have more control over the state of output than
just “on” and “off”—it’s common for me at entry to a
procedure to want to enable or disable output, and to
restore the previous state on exit. Using a stack to
maintain state is cleaner.
The main components of dbms_output are PUT
and PUT_LINE (I don’t use ENABLE or DISABLE).
Obviously these are trivial to implement. However, add a
constructor, flush, and close procedure and you have the
basic structure of the OutputStream classes in Java. Add a
couple of methods for maintaining state and you have the
framework of an object type that can be implemented for
many different types of output destinations, and for
managing and transforming that output as well. Once this
is realized, dbms_output becomes the least important use
for these object types.
I begin with the base object type, which I’ve named
OutputChannel, as shown in Listing 1. I use Channel
instead of Stream because Oracle is already using the term
“Stream” for some very different functionality. The root
object type is declared as NOT SUBSTANTIABLE NOT
FINAL. This means that I can’t actually create an instance
of an OutputChannel, but that I can define subtypes that
inherit from it. OutputChannel provides the template for
all of its subtypes.
Even though I can’t create an instance of an
OutputChannel, I can have variables declared as
OutputChannel, and I can pass parameters of
OutputChannel type. Any variable that’s of a type
declared under OutputChannel can be stored in an
OutputChannel variable or parameter, and any operation
declared in the OutputChannel class can be performed
on descendent type variables without actually knowing
their specific type.
Declaring the OutputChannel object type
I begin by declaring a VARRAY of INTEGER, to base my
state stack on:
CREATE OR REPLACE TYPE INTEGERLIST
AS VARYING ARRAY (20000) OF INTEGER
This is a generic integer VARRAY that I use for a
wide variety of purposes. If I were declaring a VARRAY
for use only as a stack for maintaining state in the
OutputChannel type, the size would be reduced by a
factor of 100.
Listing 1. OutputChannel object type specification.
CREATE OR REPLACE TYPE OUTPUTCHANNEL
AS OBJECT
(
state_stack integerList, -- Varray of integer
member procedure close,
2 Oracle Professional April 2004
not instantiable not final member procedure
write( pText in varchar2),
member procedure writeLn( pText in varchar2),
not instantiable member procedure
writeRaw( pRaw in raw ),
-- enable and disable push 1 and 0 respectively.
member procedure push( pInteger in number ),
member procedure enable,
member procedure disable,
-- restore does a pop from the state stack,
-- preventing any underflows.
member procedure restore,
-- isActive returns true if active
member function isActive return boolean,
-- some subtypes will do buffering, and may
-- require a method to flush the buffer
member procedure flush,
member procedure initializeStateStack
) NOT INSTANTIABLE NOT FINAL
There are a number of important points illustrated in
this type specification.
All of the procedures declared in this specification
will become part of the definition of any new object
types declared using OutputChannel. This is the basic
meaning of inheritance: Subtypes begin with all of the
variables, procedures, and functions declared in their
parent. They can add new variables, procedures, and
functions, and they can override any procedures or
functions in their parent—that is, implement them in
some different way. For example, in OutputChannel
the writeLn procedure is self.write( pText || chr(13)
||chr(10)), even though the write procedure itself is
not implemented. For most subtypes this will be
adequate, but when a different behavior is needed,
writeLn can be overridden, as you’ll see in the following
DbmsOutputChannel type. Only procedures and
functions declared as FINAL cannot be overridden.
Secondly, the procedures declared as NOT
INSTANTIABLE aren’t implemented in the TYPE
BODY. They must be implemented in any subtype of
OutputChannel that’s declared as INSTANTIABLE.
Because their presence is guaranteed in any subtype
variable that can be assigned to an OutputChannel
variable, PL/SQL allows those procedures to be invoked
regardless of which subtype is involved.
Procedure foo( pChannel IN OUT NOCOPY OutputChannel)
is
begin
pChannel.writeLn(‘I wonder what my actual type is’);
end;
OutputChannel doesn’t have a constructor. It’s not
instantiable, so it would seem pointless to have a
constructor, but even if I did declare a constructor, I’d still
place any actual initialization in a separate procedure
(initializeStateStack in this example) so that it can be
called by descendent types. Constructors aren’t inherited,
and I can find no mechanism that will allow a subtype
constructor to invoke its parent constructor upon itself, so
if significant initialization is done within a constructor it
www.pinnaclepublishing.com
must be repeated by each subtype’s constructor, if it’s
relevant to the subtype. Because of this, it seems best to
place the initialization in a separate procedure so that
it can be invoked by the constructor and all subtype
constructors.
If you were developing a complex application
environment with many object type hierarchies, it would
be wise to establish a policy to handle this problem—
something like “All type declarations must include an
Init[type-name] procedure that does all initialization that
might be required by its own subtype. If it is itself a
subtype, then this object type’s initialization routine must
also call its immediate parent’s initialization procedure.”
This would limit what each subtype needs to know about
its ancestry and its parent’s internal workings.
Another point, not directly related to object types: I
use different procedure names to write varchar2 and raw
output. I would have preferred to overload the write
procedure, rather than use a different procedure name to
output raw values. However, varchar2 and raw are
insufficiently distinct to allow that without forcing the use
of named parameters each time they’re called—that is,
pChannel.write( pText =>... or pChannel.write( pRaw=>...
Wrapping dbms_output in an
OutputChannel subtype
Now let’s define the simplest subtype, shown in Listing 2.
The specification for all subtypes will be very similar to
this, because all must implement the procedures declared
as not instantiable in the parent type.
Listing 2. DbmsOutputChannel specification.
CREATE OR REPLACE
TYPE DBMSOUTPUTCHANNEL UNDER OUTPUTCHANNEL
(
constructor function DbmsOutputChannel
return self as result,
overriding member procedure write(pText in varchar2),
overriding member procedure
writeLn(pText in varchar2),
overriding member procedure writeRaw(pRaw in raw),
overriding member procedure close,
static procedure test
) instantiable not final
/ advantages of working with hierarchies of object types
The constructor needs no parameters because there’s
nothing to initialize—its only content is a call to the
InitializeChannel procedure implemented by Channel.
The Flush and Close procedures aren’t implemented since
with dbms_output they have no function—so the null
procedures implemented at the parent level are fine.
WriteLn is implemented, overriding the writeLn
procedure in the OutputChannel type, because
dbms_output.put(pText ||chr(13)||chr(10)) isn’t the
same as dbms_output.put_line(pText)—if you end a script
in SQL*Plus with a dbms_output.put, instead of put_line,
the result will never be displayed, as you can see here:
www.pinnaclepublishing.com
SQL> set serveroutput on
SQL> begin
2 dbms_output.put_line('I am visible');
3 dbms_output.put('I am not');
4 end;
5 /
I am visible
PL/SQL procedure successfully completed.
WriteRaw is implemented as a straight pass-through
to the write procedure. This will cause the raw parameter
to be displayed as a hexadecimal string, which is
appropriate behavior for dbms_output.
Close is implemented as dbms_output.put_line(''), to
ensure that the buffer used by dbms_output is cleared.
Static procedures are much like the procedures of
conventional packages—they’re invoked by using
the following syntax: type-name.procedure-name. So,
in our case, we’ll use the following invocation:
DbmsOutputChannel.test. Having the test routine as
part of the type makes it very easy to repeat tests and
review just what aspects of the type you’ve tested.
An OutputChannel for CLOBs
The declaration for ClobOutputChannel follows the same
pattern and is shown in Listing 3.
Listing 3. The ClobOutputChannel specification.
CREATE OR REPLACE
TYPE CLOBOUTPUTCHANNEL UNDER OUTPUTCHANNEL
(
the_clob clob,
constructor function ClobOutputChannel(
pClob in out nocopy clob) return self as result,
overriding member procedure write(pText in varchar2),
overriding member procedure writeRaw( pRaw in raw),
-- and a function to retrieve the clob if not passed
-- by reference
member function getClob return clob,
static procedure test
) instantiable not final
/
Fill-in-the-blanks programming
If you check the source code available in the Download,
you’ll see how simple this is to implement. One of the
is that the parent establishes a template. All the
subtype must do is fill in those portions of the template
that apply specifically to it. Think of it as “fill-in-the-
blanks” programming.
The constructor function takes a CLOB as a
parameter. Even though the NOCOPY hint is used, I
haven’t found a way of enforcing that a temporary CLOB
be passed by reference, which is why the getClob function
has been added. Check the listings associated with this
article for an illustration: If you create a temporary CLOB,
pass the locator to the ClobOutputChannel constructor,
and write to it using one of the ClobOutputChannel
procedures; what you write won’t be visible to the
Oracle Professional April 2004 3
original LOB locator variable.
Because the CLOB is created outside of the object
type, I didn’t override the default close procedure (which
does nothing). The decision as to whether or not to use
the dbms_lob open and close procedures is left to the user.
I also didn’t override the writeLn procedure, since in this
case, the default procedure declared in OutputChannel
produces the desired result.
If you’re working with LOBs that are table-based,
remember that the LOB locators don’t span transactions.
Once a commit is issued, the LOB locator can no longer
be used. If this is an issue, it would probably be best to
create a subtype that receives a primary key into the table
containing the CLOBs and uses autonomous transactions
when it does writes, reloading the LOB locator after each
commit. If you don’t allow for this, you’re likely to see
the following:
ORA-22990: LOB locators cannot span transactions
Other OutputChannel types
There are numerous other OutputChannel subtypes
that we could define. I’ve included an implementation
of a BlobOutputChannel in the Download, and there
are some other obvious variations as well, such as a
PipeOutputChannel. So, given that we have some number
of different OutputChannel subtypes defined, what can
we do with them?
First of all, we can use them in a generic way
any time we need to send stream-oriented output to
a destination.
The procedure log in Listing 4 doesn’t know or
care whether pChannel is a ClobOutputChannel, a
DbmsOutpoutChannel, or some other type derived from
the OutputChannel parent. It can perform upon pChannel
any operation that’s defined in the OutputChannel
specification. This means that you can redirect output in a
manner that’s completely transparent to the code that’s
producing the output stream.
Listing 4. Use of OutputChannel variables as parameters.
1 declare
2 vChannel CloboutputChannel;
3 vClob clob;
4 procedure log(pChannel in out nocopy OutputChannel,
5 pText in varchar2) is
6 begin
7 pChannel.writeLn(pText);
8 end;
9 begin
10 dbms_lob.createTemporary(vClob,true);
11 vChannel := new ClobOutputChannel( vClob );
12 log(vChannel,'Hello world');
13 dbms_output.put_line(vChannel.getClob());
14 dbms_lob.freeTemporary(vClob);
15* end;
SQL> /
Hello world
PL/SQL procedure successfully completed.
4 Oracle Professional April 2004
Chaining types
OutputChannel subtypes can be used not only to send
output to a wide variety of destinations, but also to
manage the output regardless of the actual destination.
These sorts of OutputChannel subtypes can be used to
modify the text as it’s written, passing the modified data
onto another OutputChannel subtype, or they could
control the flow of data. Instead of writing to a final
destination (such as a LOB), these sorts of OutputChannel
descendents write to another OutputChannel that would
normally be specified in their constructors.
I think the most useful to implement is buffering. As
I discussed in “A First Look at Object Types” (see the
February 2004 issue of Oracle Professional), it’s a good
idea to buffer output to table-based LOBs because Oracle
itself does i/o to LOBs in blocks, referred to as chunksize
by Oracle.
Buffering would also make it practical to implement
a subtype for table-based LOBs of either type that uses
autonomous transactions for its write procedures.
Because LOB locators can’t span transactions, one needed
for a table-based LOB would need to be reset after
each commit.
A BufferOutputChannel object type
In the OutputChannel types, the data being output can be
either varchar2 or raw. Since write procedures for both
data types are defined in the parent type, it’s possible to
write a single BufferOutputChannel type that buffers both
data types in a single raw buffer, and passes along the
result using writeRaw.
The constructor for the BufferOutputChannel type
created in Listing 5 takes a parameter of OutputChannel
(which can be any OutputChannel subtype), as well as an
integer specifying the amount of data to be held in the
buffer before passing it along to the OutputChannel
contained in its child variable.
Listing 5. BufferOutputChannel specification.
CREATE OR REPLACE
TYPE BUFFEROUTPUTCHANNEL UNDER OUTPUTCHANNEL
(
buffer raw(32767),
writeSize integer,
child OutputChannel,
constructor function BufferOutputChannel(
pChannel in out nocopy OutputChannel,
pBufferSize in integer default 32767)
return self as result,
overriding member procedure close,
overriding member procedure write(
pText in varchar2),
overriding member procedure writeRaw( pRaw in raw),
overriding member procedure flush
) instantiable not final
/
For LOBs, the ideal buffer size is some multiple of the
chunksize less than or equal to the maximum size of the
www.pinnaclepublishing.com
buffer (see the script in Listing 6 for an example of this
calculation). However, a buffer might be used for
purposes other than buffering writes to a LOB, so
BufferOutputChannel makes no assumptions about what
an ideal buffer size might be. If no buffer size is specified,
the maximum length of a raw variable is used.
and compare the performance with three different
variations: writing directly to a CLOB (fastest), writing
using ClobOutputChannel, and writing using
BufferOutputChannel attached to a ClobOutputChannel.
Listing 7. Use and evaluation of write methods.

Listing 6. Buffering output. SQL> declare

2 vClob clob;
3 vClobOutput ClobOutputChannel;
overriding member procedure writeRaw(pRaw in raw) 4 vBuffer BufferOutputChannel;
is 5 vLength integer;
vAdd integer; 6 vString varchar2(256) := rpad('X',256);
vRaw raw(32767); 7 vStartTime integer;
vBufferLen integer; 8 vWriteSize integer;
vRawLen integer; 9 vMax integer := 5000;
begin 10 procedure showTime(pLabel in varchar2) is
if self.isActive then 11 begin
vRaw := pRaw; 12 dbms_output.put_line(pLabel||' Timing: '
vBufferLen := nvl(utl_raw.length(self.buffer),0); 13 || (dbms_utility.get_time - vStartTime)/100
vRawLen := nvl(utl_raw.length(vRaw),0); 14 ||' seconds');
while vBufferLen + vRawLen >= self.writeSize loop 15 end;
-- pad the buffer
16 begin
vAdd := self.writeSize - vBufferLen;
17 dbms_output.put_line('Timing for '
self.buffer :=
18 ||to_char(vMax)|| ' writes');
utl_raw.concat(self.buffer,
utl_raw.substr(vRaw,1,vAdd)); 19 dbms_lob.createTemporary(vClob,true);
self.flush(); 20 -- use dbms_lob.writeAppend
vRawLen := vRawLen - vAdd; 21 vLength := length(vString);
vBufferLen := 0; 22 vStartTime := dbms_utility.get_time;
if vRawLen > 0 then 23 for i in 1 .. vMax loop
vRaw := utl_raw.substr(vRaw,vAdd + 1, 24 dbms_lob.writeAppend(vClob, vLength, vString);
vRawLen); 25 end loop;
else 26 showTime('dbms_lob.writeAppend');
vRaw := utl_raw.cast_to_raw(''); 27 -- Use ClobOutputChannel (without buffer)
end if; 28 dbms_lob.trim(vClob,0);
end loop; 29 vClobOutPut := new ClobOutputChannel(vClob);
-- place whatever remains in the buffer 30 vStartTime := dbms_utility.get_time;
self.buffer := utl_raw.concat(self.buffer,vRaw); 31 for i in 1..vMax loop
end if; -- if isActive 32 vClobOutput.write(vString);
end; 33 end loop;
34 showTime('ClobOutputChannel');
35 -- and buffered
Buffering is done inside the write procedures. 36 dbms_lob.trim(vClob,0);
Write and WriteLn pass through to the writeRaw 37 vClobOutPut := new ClobOutputChannel(vClob);
38 -- Calculate buffersize
procedure defined in Listing 6. In writeRaw the length 39 vWriteSize := trunc(32767
of the pText or pRaw parameter is added to the length 40 / dbms_lob.getChunkSize(vClob))
41 * dbms_lob.getChunkSize(vClob);
of the content already in the buffer. While that total 42 vBuffer := new BufferOutputChannel(vClobOutput,
is greater than or equal to the writeSize variable, a 43 vWritesize);
44 vStartTime := dbms_utility.get_time;
substring of length writeSize is passed along to the 45 for i in 1 .. vMax loop
OutputChannel contained in the child variable using 46 vBuffer.write(vString);
47 end loop;
writeRaw. If or when the total length of whatever 48 vBuffer.flush();
remains in the buffer, and the remaining content of the 49 showTime('Buffered writeLn');
50 end;
parameter, is less than writeSize, the parameter content 51 /
is concatenated to the buffer. Timing for 5000 writes
dbms_lob.writeAppend Timing: .72 seconds
Buffering has other purposes than just writing to ClobOutputChannel Timing: 34.92 seconds
LOBs. For example, suppose you wanted to create an Buffered writeLn Timing: 1.67 seconds

OutputChannel subtype using the dbms_obfuscation PL/SQL procedure successfully completed.

package to encrypt text—the encryption procedures in
that package require blocks of eight characters to operate
on. Using a buffer that’s sized at some multiple of 8
would handle that very nicely. Flush would need to do
nothing in this case, while the close procedure would
need to handle any portion of the input that’s less than
eight characters.
Let’s look at the script in Listing 7, which displays
how OutputChannels are chained together and used,
This script illustrates several important points.
First of all, the difference in performance between the
unbuffered and the buffered writes is enormous—a
factor of 20 with writes of 256 characters each.
The instance of ClobOutputChannel that’s passed to
the constructor for BufferOutputChannel is declared
separately. Because it’s an IN OUT parameter, the
constructor for ClobOutputChannel can’t be placed in-line

www.pinnaclepublishing.com Oracle Professional April 2004 5

in the BufferOutputChannel constructor, as you can see in
Listing 8.
Listing 8. Attempting to use an object type constructor in a
parameter list.
SQL> declare
2 vClob clob;
3 vChannel BufferOutputChannel;
4 begin
5 dbms_lob.createTemporary(vClob,true);
6 vChannel := new BufferOutputChannel(
7 new ClobOutputChannel( vClob),1024);
8 end;
9 /
new ClobOutputChannel( vClob),1024);
*
ERROR at line 7:
ORA-06550: line 7, column 9:
PLS-00363: expression 'CLOBOUTPUTCHANNEL'
cannot be used as an assignment
target
ORA-06550: line 6, column 3:
PL/SQL: Statement ignored
Creating collections of the object types
Let’s finish up with one last subtype that illustrates a
principle that could be applied whenever you need to
invoke the same operation upon a group of object type
variables that all inherit from a common parent. With
OutputChannels we can imagine, for example, that we
want to send output to a CLOB and to a pipe at the same
time (I haven’t included a PipeOutputChannel in this
article—it makes no sense to do so without having a
corresponding PipeInputChannel).
Start with defining a VARRAY of the hierarchy’s
root type.
CREATE OR REPLACE
TYPE OUTPUTCHANNELCOLLECTION
AS VARYING ARRAY (20) OF CHANNEL.OUTPUTCHANNEL
/
Next, create another subtype under OutputChannel
that includes a variable of OutputChannelList type, as in
Listing 9.
Listing 9. OutputChannelCollection specification.
CREATE OR REPLACE
TYPE OUTPUTCHANNELCOLLECTION UNDER OUTPUTCHANNEL
( that could be implemented using OutputChannel
aList OutputChannelList,
constructor function OutputChannelCollection(
pChannel in out nocopy OutputChannel )
return self as result,
overriding member procedure close,
overriding member procedure write(
pText in varchar2),
overriding member procedure writeLn(
pText in varchar2),
overriding member procedure writeRaw(pRaw in raw),
overriding member procedure flush ,
member procedure addChannel( pChannel IN OUT
NOCOPY outputChannel),
member function getChannel(pChannel in number)
6 Oracle Professional April 2004
return OutputChannel
) instantiable not final
/
All of the procedures in this subtype simply traverse
aList, invoking the same procedure for each element of
the VARRAY. The code for the write procedure will serve
as an illustration for all.
overriding member procedure write( pText in varchar2)
is
begin
if self.isActive then
for i in self.aList.first .. self.aList.last loop
self.aList(i).write( pText );
end loop;
end if;
end write;
The self.isActive function is checked before
passing along the input, and will be rechecked by each
OutputChannel instance contained in aList. This allows
you to turn output on or off globally. If you wanted to be
able to activate or deactivate individual OutputChannels
contained in an OutputChannelCollection, you’d need to
directly access the variables as stored in the collection—
that is, vCollection.aList[1].disable()—not the original
outputChannel variable that was passed to the
OutputChannelCollection in its constructor or via the
addChannel procedure. A better solution would be to
change the addChannel procedure to a function that
returns a number representing the individual element’s
offset in the VARRAY, and add overloaded versions of
the other procedures that include a handle parameter
corresponding to that number. In the preceding example I
added a getChannel function to retrieve the individual
components, but that should be viewed as nothing more
than a kludge I put into place for use in a test script
available in the listings.
What’s next
In the course of this article I’ve defined half a dozen
object types, but the possibilities have hardly been
exhausted. What I haven’t gone into are types that
actually transform the stream of text being processed.
Encryption using the dbms_obfuscation package, base64
encoding now included in the utl_encode supplied
package, or compression using one of the Java data
compression routines are all examples of transformations
subtypes, making their use almost transparent to the
developer. Subtypes of that nature, of course, would also
require a method of un-transforming the contents—an
InputChannel, in other words. I hope to explore that topic
in an upcoming issue of Oracle Professional. ▲
404MENCHEN.ZIP at www.pinnaclepublishing.com
Gary Menchen is a senior programmer analyst at Dartmouth College in
Hanover, New Hampshire. Gary.E.Menchen@Dartmouth.edu.
www.pinnaclepublishing.com
 Oracle
Professional

Exploring Options: Multiple

Paths to an Answer
Steven Feuerstein
As the PL/SQL language grows increasingly rich and nuanced, INSERT INTO tickertable
(ticker, pricedate, pricetype, price
we developers confront both opportunity and dilemma. )
VALUES (rec.ticker, rec.trade_date, 'O'
There can be many different paths to a solution and multiple , rec.open_price
alternative implementations for a particular requirement. );
Various factors collude and sometimes collide in making the INSERT INTO tickertable
best decision, including runtime efficiency and simplicity of (ticker, pricedate, pricetype, price
)
code (and related maintenance costs). In this article, Steven VALUES (rec.ticker, rec.trade_date, 'C'
Feuerstein tackles a specific challenge and explores the , rec.close_price
);
different solutions possible. END LOOP;
END;

I
need to pivot data in a stock table. The structure of
The concept is straightforward, and the code is
this table is:
simple, as well. There is, however, a problem: This isn’t
CREATE TABLE stocktable ( a terribly efficient implementation. I’ll be comparing
ticker VARCHAR2(20), the performance of alternative approaches to solving
trade_date DATE,
open_price NUMBER, the pivot problem in this article. To do so, I’ll fill up the
close_price NUMBER stock table with 100,002 rows, as you can see in Listing
);
2. And with this data in place, it takes 36 seconds to
In other words, each row contains a ticker symbol, pivot the data using the good old cursor FOR loop in
the date of trade, the open price, and the close price on pivot_stock_data1. Given that my application will need
that day. I need to “pivot” this data, which in this case to pivot 10,000,000 rows of data, this performance is
means that I need to take a single row in stocktable and unacceptable. So what are my options?
transform it into two rows in the price table defined here:
Listing 2. Populating the stock table.
CREATE TABLE tickertable (
ticker VARCHAR2(20),
pricedate DATE, BEGIN
pricetype VARCHAR2(1), INSERT INTO stocktable
price NUMBER VALUES ('ORCL', SYSDATE, 13, 13.5);
);
INSERT INTO stocktable
VALUES ('MSFT', SYSDATE, 27, 27.04);
This pivot process shouldn’t conceptually cause any
FOR indx IN 1 .. 100000
reader of Oracle Professional to lie awake in bed at night. LOOP
There is, in fact, a very straightforward approach to INSERT INTO stocktable
VALUES ('STK' || indx, SYSDATE, indx, indx + 15);
performing this transformation, shown in Listing 1. What END LOOP;
could be simpler? Set up a cursor FOR loop to run COMMIT;
through the table and convert one row into two rows in END;
/
the tickertable.
Transformative functions to the rescue?
Listing 1. The traditional, aka “old fashioned,” approach to In the May 2002 issue of Oracle Professional (available on
pivoting the data. the Web site to subscribers), Bryn Llewellyn and I wrote
about the new table function capabilities in Oracle9i. A
PROCEDURE pivot_stock_data1 table function is a function that can be called in the FROM
IS
BEGIN clause of a SELECT statement. It accepts as its parameter a
FOR rec IN (SELECT * result set (rows and columns of data) in the form of a
FROM stocktable)
LOOP cursor variable, and returns a nested table.

www.pinnaclepublishing.com Oracle Professional April 2004 7

 Table functions offer a number of potentially useful EXIT WHEN dataset%NOTFOUND;
out_obj.ticker := in_rec.ticker;
features, including: out_obj.pricetype := 'O';
out_obj.price := in_rec.open_price;
• Parallel execution—You can execute the function in out_obj.pricedate := in_rec.trade_date;
parallel within the context of a parallel query, when retval.EXTEND;
retval (retval.LAST) := out_obj;
the function is defined as a PIPELINED program. out_obj.pricetype := 'C';
out_obj.price := in_rec.close_price;
This can greatly improve performance, since in out_obj.pricedate := in_rec.trade_date;
previous releases of Oracle, the use of a PL/SQL retval.EXTEND;
retval (retval.LAST) := out_obj;
function in a query forced serialization. END LOOP;
• Data transformation—Since the function can be called CLOSE dataset;
from within the FROM clause and accepts as its
RETURN retval;
parameter a set of data (logically equivalent to a END;
query), the function can perform arbitrarily complex /

and multiple transformations of data without ever

having to deposit the intermediate results in PL/SQL The name of the table function is stockpivot_nopl, to
program data structures. indicate that it’s not a PIPELINED function. This means
that it can’t execute in parallel; it still may, however, act as
Given these advantages, perhaps I can use a table a transformative function, which I demonstrate in the
function in place of the cursor FOR loop and see some INSERT-SELECT FROM statement here:
improvement.
INSERT INTO tickertable
Listing 3 shows an implementation of a table function SELECT *
FROM TABLE
that pivots the stock data into two tickertable rows. It (stockpivot_nopl
relies on a number of other elements, described here: (CURSOR (SELECT *
FROM stocktable)));
• An object type with the same structure as the
tickertable. To use table functions, I must define the
This single SQL statement replaces all the code shown
RETURN datatype as a nested table of object TYPEs,
in Listing 1! To understand how this INSERT can do all
hence this type:
the work of the cursor FOR loop, you must start from the
CREATE TYPE tickertype AS OBJECT (
“center” of the statement and work outwards. On lines 5
ticker VARCHAR2 (20) and 6, I query all the rows from the stocktable and place
, pricedate DATE
, pricetype VARCHAR2 (1) that query inside the CURSOR operator. CURSOR tells
, price NUMBER Oracle to treat that query as if it were a result set in
);
/ PL/SQL produced by a REF CURSOR or cursor variable.
That data (the contents of stocktable) is then passed
• A nested table TYPE based on the object type: as a parameter to the stockpivot_nopl function (line 4).
This function takes the 100,002 rows from stocktable
CREATE TYPE tickertypeset AS TABLE OF tickertype; and pivots them into 200,004 rows in a collection. The
/
collection is passed back to the outer query and, in line 3,
• A package that defines the REF CURSOR that I’ll use the TABLE operator instructs the SQL engine to treat that
for the IN parameter of the function: collection as if it were a relational table.
From that point, we’re back on familiar ground. The
CREATE OR REPLACE PACKAGE refcur_pkg SELECT * in line 2 retrieves all the data and passes it
IS
TYPE refcur_t IS REF CURSOR
directly into the tickertable. And when I run this code
RETURN stocktable%ROWTYPE; to populate the tickertable, I find that it only takes
END refcur_pkg;
/ approximately 14.4 seconds.
That’s a solid improvement. Can we do even better?
Well, what about using a PIPELINED function that can
Listing 3. Use of a table function to perform a pivot.
run in parallel? Listing 4 shows the changes required in
the stockpivot_nopl to use pipelining. If you haven’t seen
CREATE OR REPLACE FUNCTION stockpivot_nopl (
dataset refcur_pkg.refcur_t) a PIPELINED function before, you’re in for several
RETURN tickertypeset
IS
surprises. First and foremost, look at the bottom of the
out_obj tickertype := tickertype (NULL, NULL function. Notice the RETURN statement—it doesn’t seem
, NULL, NULL);
in_rec dataset%ROWTYPE; to be returning anything at all! In fact, by the time the
retval tickertypeset := tickertypeset (); PL/SQL runtime engine gets to this line, it doesn’t have
BEGIN
retval.DELETE; anything left to return. And that’s because I’ve used the
new PIPE ROW statement within the body of the loop to
LOOP
FETCH dataset INTO in_rec; return the data asynchronously to the termination of the

8 Oracle Professional April 2004 www.pinnaclepublishing.com

function itself. In other words, while the function is IS
curvar sys_refcursor;
executing—and before it’s completed—the PIPE ROW mystock tickertypeset := tickertypeset ();
indx PLS_INTEGER;
statement will send the data back to the calling program. BEGIN
This is very useful when you’re running the function OPEN curvar
FOR
simultaneously in a dozen different processes, but it SELECT *
doesn’t actually do us much good in this situation. FROM stocktable;

You see, I’m not running this function in parallel. I’m
calling it from my session just once, and I’m not going to
be doing anything with it until the function is completely
finished. I have found, in fact, that in this situation, the
non-pipelined version of the function generally runs just a
bit more efficiently. The stockpivot_pl program is
definitely and dramatically faster than the cursor FOR
loop approach, but the PIPELINED syntax doesn’t give
you any advantage.
Listing 4. A pipelined pivot function.
CREATE OR REPLACE FUNCTION stockpivot_pl (
dataset refcur_pkg.refcur_t
)
RETURN tickertypeset PIPELINED
IS
out_obj tickertype := tickertype (NULL, NULL, NULL, NULL);
in_rec dataset%ROWTYPE;
BEGIN
LOOP
FETCH dataset INTO in_rec;
EXIT WHEN dataset%NOTFOUND;
-- first row
out_obj.ticker := in_rec.ticker;
out_obj.pricetype := 'O';
out_obj.price := in_rec.open_price;
out_obj.pricedate := in_rec.trade_date;
PIPE ROW (out_obj);
-- second row
out_obj.pricetype := 'C';
out_obj.price := in_rec.close_price;
out_obj.pricedate := in_rec.trade_date;
PIPE ROW (out_obj);
END LOOP;
CLOSE dataset;
RETURN;
END;
/ possible, unfortunately, because there’s a restriction in
One of the key reasons that the transformative
function is so efficient has to do with the avoidance of
relying on intermediate data structures in PL/SQL.
To drive that point home, consider the implementation
in Listing 5. In this program, I use the efficient
stockpivot_nopl to pivot the data, and then dump the
data into a local nested table, mystock. I then use a FOR
loop to perform my inserts. This program takes more
than 43 seconds. It’s even slower than the cursor FOR
loop approach!
Listing 5. Relying on intermediate data structures in PL/SQL.
PROCEDURE intermediate_structure_pivot
/*
Use a nested table to retrieve the pivoted data
and then transfer to the database table.
*/
www.pinnaclepublishing.com
mystock := stockpivot_nopl (curvar);
indx := mystock.FIRST;
LOOP
EXIT WHEN indx IS NULL;
INSERT INTO tickertable
(ticker
, pricedate
, pricetype
, price
)
VALUES (mystock (indx).ticker
, mystock (indx).pricedate
, mystock (indx).pricetype
, mystock (indx).price
);
indx := mystock.NEXT (indx);
END LOOP;
END;
What about bulk processing?
Whenever you’re executing multiple rows of DML in a
PL/SQL program (and you’re using Oracle8i 8.1.7 and
above), you should always consider FORALL as an option
for executing that DML. With FORALL, you can process
multiple DML statements within the SQL engine, cutting
down dramatically on “context switches” (between SQL
and PL/SQL), which can degrade performance.
In fact, I imagine that many readers looked at the
code in Listing 5 and said to themselves, “What a cheater,
Steven is! He could make that program much faster by
using FORALL.” Let’s see if that’s the case.
I’ll now take Listing 5 and change it to use FORALL.
It’s not as easy as it first might seem. The code is shown in
Listing 6. I populate the mystock nested table the same
way that I did in Listing 4. Now, you might think I could
move immediately to a FORALL statement. That’s not
FORALL: I cannot reference individual attributes or fields
of a collection of records or objects.
In other words, I can’t execute code that looks
like this:
FORALL indx IN
l_tickertable.FIRST .. l_tickertable.LAST
INSERT INTO tickertable
(ticker, price)
VALUES (
l_tickertable (indx).ticker
, l_tickertable (indx).price);
So I either have to break up my single nested table
into four different nested tables (ugly!) or... I could take
advantage of another really nice Oracle9i feature: INSERT
a record, as opposed to individual column values.
I’ll go this second route, but in order to do that I’ll
need to copy the nested table of objects into an associative
array of records. Once I’ve done this, I can then use the
Oracle Professional April 2004 9
FORALL statement. The result is a significant boost in FROM stocktable;

performance. I can pivot 100,002 rows in approximately 18 FOR indx IN l_stocktable.FIRST .. l_stocktable.LAST
LOOP
seconds. It’s not as fast as the transformative function, but l_index := l_tickertable.COUNT + 1;
it’s a major improvement over the other implementations l_tickertable (l_index).ticker :=
l_stocktable (indx).ticker;
we’ve explored. l_tickertable (l_index).pricedate :=
l_stocktable (indx).trade_date;
l_tickertable (l_index).pricetype := 'O';
l_tickertable (l_index).price :=
Listing 6. Using FORALL and an intermediate collection. l_stocktable (indx).open_price;
l_index := l_tickertable.COUNT + 1;
l_tickertable (l_index).ticker :=
PROCEDURE intermediate_forall_1 l_stocktable (indx).ticker;
IS l_tickertable (l_index).pricedate :=
curvar sys_refcursor; l_stocktable (indx).trade_date;
mystock tickertypeset := tickertypeset (); l_tickertable (l_index).pricetype := 'C';
l_tickertable (l_index).price :=
TYPE tickertable_tt IS TABLE OF tickertable%ROWTYPE l_stocktable (indx).open_price;
INDEX BY BINARY_INTEGER; END LOOP;

l_tickertable tickertable_tt; FORALL indx IN l_tickertable.FIRST ..

BEGIN
init;
OPEN curvar
FOR
SELECT *
FROM stocktable;
mystock := stockpivot_nopl (curvar);
FOR indx IN mystock.FIRST .. mystock.LAST
LOOP
l_tickertable (indx).ticker :=
mystock (indx).ticker;
l_tickertable (indx).pricedate :=
mystock (indx).pricedate;
l_tickertable (indx).pricetype :=
mystock (indx).pricetype;
l_tickertable (indx).price :=
mystock (indx).price;
END LOOP;
FORALL indx IN l_tickertable.FIRST ..
l_tickertable.LAST
INSERT INTO tickertable
VALUES l_tickertable (indx);
END;
Perhaps there’s a way to improve the performance
of this FORALL approach. What if we skip the
transformative stockpivot function altogether, and instead
do it all in PL/SQL? Consider the code in Listing 7.
I use BULK COLLECT to grab the 100,002 rows from
stocktable and dump it into a local associative array. I
then use a numeric FOR loop to pivot the data into
200,004 rows, neatly depositing that doubled data into a
collection of records based on the ticker table. Finally, I
use FORALL to insert 200,004 records directly into the
ticker table.
This implementation completes in less than 9 seconds!
Listing 7. Using BULK COLLECT and FORALL to pivot data.
l_tickertable.LAST
INSERT INTO tickertable
VALUES l_tickertable (indx);
END;
Choices, choices, choices... and more choices
Sometimes I wish I was still writing code in the old,
simple days of Oracle6 and SQL*Forms 2.3. You didn’t
have a whole lot of choices (you didn’t even have
PL/SQL!). You just did the best you could with the
stepwise-logic available in Forms triggers.
Okay, so I’m joking. I don’t hanker for those days, no
sir! Yet if we’re to be honest, we must acknowledge some
level of discomfort with the growing complexity of the
Oracle environment. We have so many more tools and
techniques than ever before, but that doesn’t necessarily
make our jobs a whole lot easier.
There’s more to learn, more to master. We need
more time to play with new features, uncover the gotchas
and the glitches, and figure out what applies best where.
But how many development managers give us any time
to play?
Well, we’ll just have to make the best of what we
have—which is, when you think about it, rather
wonderful. Consider this: Our employers actually pay us
to sit around and think up solutions to problems, and
then type those solutions into computers, all this in
reasonably comfortable and safe environments. That’s a
pretty good deal, isn’t it?
So it’s time to stop our complaining, rejoice in our
many choices, remember to use BULK COLLECT and
FORALL whenever humanly possible, and pick up,
little by little, the latest tricks of the trade, such as
PIPELINED functions. ▲

PROCEDURE intermediate_forall_2 404FEUER.SQL at www.pinnaclepublishing.com

IS
TYPE stocktable_tt IS TABLE OF stocktable%ROWTYPE
INDEX BY BINARY_INTEGER; Steven Feuerstein is considered one of the world’s leading experts on the
Oracle PL/SQL language, having written nine books on PL/SQL, including
TYPE tickertable_tt IS TABLE OF tickertable%ROWTYPE
INDEX BY BINARY_INTEGER; Oracle PL/SQL Programming and Oracle PL/SQL Best Practices (all from
O’Reilly & Associates). Steven has been developing software since 1980
l_stocktable stocktable_tt;
l_tickertable tickertable_tt; and serves as a Senior Technology Advisor to Quest Software. His current
l_index PLS_INTEGER; projects include Swyg (www.Swyg.com) and the Refuser Solidarity
BEGIN
SELECT * Network (www.refusersolidarity.net), which supports the Israeli military
BULK COLLECT INTO l_stocktable refuser movement. steven@stevenfeuerstein.com.
10 Oracle Professional April 2004 www.pinnaclepublishing.com

Using the Oracle9i R2
Templates Feature of DBCA
on Windows 2000
Stan Novinsky
Templates are a new feature that was introduced in Oracle9i.
They provide the Database Administrator with an alternative
way to create a new database or to clone an existing
database. In this article, Stan Novinsky defines some of the
basic nomenclature involved in the process, explains the
benefits of using templates, lists the basic steps, and walks
you through a sample implementation.
F
IRST, let’s define what a template is. The American
Heritage Dictionary defines a template as “a
document or file having a preset format, used as a
starting point for a particular application so that the
format does not have to be recreated each time it is used:
a loan amortization template for a spreadsheet program.”
So, in Oracle9i, the same can be said about a database
template. It’s basically a file containing a format of a
database that can be used as a starting point to create a
new database or clone (duplicate) a database on another
platform. The primary purpose of the 9i database
templates is to remove the complexity for creating
multiple similar databases and transition databases from
one system to another. A database template is created by
using the 9i Database Configuration Assistant (DBCA).
Why use database templates?
Database templates allow DBAs to create new
databases using predefined templates, or create new
templates based on existing running databases that can
be used to create the databases at another time. This
serves as a robust new way of creating or duplicating
databases with or without the data. Here are some of
the advantages:
• It saves you time. If you use a template, you don’t
have to define the database.
• By creating a template containing your database, you
can easily create a cloned database without specifying
parameters twice.
• The templates are easy to modify. You can change
database options from the template settings.
• Templates can be shared among several computers.
www.pinnaclepublishing.com
Oracle
Professional
Cloning your database via database templates
To create a template of a database including the data, the
DBCA is used.
To start the DBCA from Windows Explorer, go to
Program Files | OraHome92 | Configuration and
Migration Tools. Note that the shortcut for the DBCA on
your machine may reside in a different folder than the one
specified here. Then, follow these steps:
1. Select the Manage Templates option.
2. Select either “From an existing database (structure
only)” or “From an existing database (structure as
well as data).”
3. Enter the Source Database that’s to be cloned—this
can be local or remote if Net services are set up.
4. Enter a name for your template along with
a description.
5. Select either “Maintain the file locations” or
“Convert the file locations to use OFA Structure.”
This process now jars all of the data files for your
database and places them in one large file (.dfj). The
.dfj and .dbc files are created in the ORACLE_HOME\
assistants\dbca\templates directory. You can now copy
these files to a new machine and have your data go along
with it. This is great for moving from a test platform DB
to a production environment, or from production to test
(when you want to test with real production data).
Note: Depending on the size of your database that’s to
be cloned, the size of the template files and the time
required to build them may come into play. If the
database is in the terabyte range, the .dfj file may
become too large for the ORACLE_HOME and may be
difficult to move across a network to a target computer.
An example
I was required to create an additional test database for our
project on another computer. The target and source PCs
were running Oracle9i R2 Enterprise Edition on Windows
2000 with SP2.
Oracle Professional April 2004 11
 Prior to Oracle9i, this task of duplicating a production After clicking the Finish button in Step 5, you’ll
or test database on another platform involved using the receive a Summary box (see Figure 6). After clicking on
export/import utility. Using export/import was a valid
method, but somewhat time-consuming and cumbersome.
Now, templates to the rescue!
By using templates, I saved several hours if not a day
or two to clone the test database onto the new PC. I
created a database template via DBCA from our existing
development database (structure as well as data) using
the OFA file structure. The process was as follows:
1. Select the Manage Templates option (see Figure 1).
2. Select the “From an existing database (structure as
well as data)” option (see Figure 2).
3. Select “AVTST” as the Source Database that’s to be
cloned (see Figure 3).
4. Enter “new_dev_db” as the name for the template
along with a description (see Figure 4).
5. Select the “Convert the file locations to use OFA
Structure” option (see Figure 5). Figure 3. Step 3: Select the database used for template creation.

Figure 1. Step 1: Select the Manage Templates option. Figure 4. Step 4: Select a new name for the new template.

Figure 2. Step 2: Select the option to create the template Figure 5. Step 5: Select the OFA option.
with data.

12 Oracle Professional April 2004 www.pinnaclepublishing.com

the OK button in the Summary box, the template creation
process begins (see Figure 7).
The source DB size was 12GB. The template build
completed in about 45 minutes, and the two required
template files (.dfj, .dbc), were created in the ORACLE_
HOME\assistants\dbca\templates directory.
I moved the two newly created template files
located in ORACLE_HOME\assistants\dbca\templates
from the development platform to a second PC that was
running the same 9.2 Enterprise Edition software. I
started the DBCA on the new platform and selected the
option to create the new DB. I selected the template name
that I copied over from the development platform to
create the new DB. After answering the basic questions,
the cloning process started and was completed in less
than one hour.
Caveats
Some of the issues that I encountered are reported to
have been corrected in Oracle10g, although I haven’t yet
experimented with the DBCA in 10g to verify the fixes.
After the cloning process completes, it may be
necessary to UNLOCK and RESET users’ passwords.
You can use OEM to verify and unlock any users.
Also, the listener and TNSNAMES file must be
configured via the Net Configuration Assistant.
During an initial attempt at creating a template, I
received the following error: Invalid Entry Size (expected
3130007552 but got –1164959744 bytes). The process
stopped at the UNDOTBS01 file creation, which was
created on the development platform with a size of
2.91GB.
After checking with Oracle, it turned out to be a bug
(2536772) in 9.2. On MetaLink, note 209516.1 lists a
workaround, which is to reduce the datafile size to less
than 2GB if possible.
According to reports, the bug has been fixed in 10g.
It’s not possible to fix this issue in 9i DBCA because of
Figure 6. The
Summary box.
Know a clever shortcut? Have an idea for an article for Oracle Professional?
Visit www.pinnaclepublishing.com and click on “Write For Us” to submit your ideas.
www.pinnaclepublishing.com
Java’s limitation with respect to its Zip classes.
As an option, if you’re considering using the
template feature to clone databases, you may want to
create your primary database with multiple .dbf files
for tablespaces under the 2GB size, prior to building
any templates.
And finally, I encountered another small problem
with DBCA. When using DBCA to create a template
from a running DB, the database is locked. After the
template creation process is completed, the DB remains
locked. There’s no notification given prior to or after
the process completes. According to Oracle, this appears
to be expected behavior. A bug was filed on this, and
development engineers said that it was expected behavior
and wouldn’t be fixed. However, they did suggest that at
some point they might put in a confirmation message
before the shutdown of the database occurs. So, the only
change in the behavior expected to be added is that there
will be a message to let the user know that the database
will be shut down.
Conclusion
Templates are a real time-saver and one of the finest
“new” features in Oracle9i that I’ve used. Thanks to
Oracle and the new 9i Database Templates feature, I
looked like a genius when I told my manager that the
second test DB was ready in less than two hours. ▲
Stan Novinsky works as an Oracle DBA for the PPSD/VIM group at The
Johns Hopkins University Applied Physics Lab. He specializes in Windows
and Oracle Database Administration. stan.novinsky@jhuapl.edu.
Figure 7. The DBCA template creation process.
Oracle Professional April 2004 13
 Oracle
Professional

LOG4PLSQL Oracle Database

Logging Tools
Guillaume Moulard
All users of Oracle databases are confronted with the the IsDebugEnabled function, like this:
recurring problem of trace generation in PL/SQL code. In
this article Guillaume Moulard explores LOG4PLSQL, which IF PLOG.isDebugEnabled then
PLOG.debug ('save your perf use isDebugEnabled');
offers the entire functionality necessary for coding, use, and END IF;
application traces in the Oracle database—and it’s free.
Log apart from the transaction

F
IRST, let’s review some of the features that
LOG4PLSQL offers. It’s easy to implement and use.
You’ll find adaptation of various logging levels
depending on user requirements, without modifying the
application code. It offers the capability to log in to a lot of
destinations—log file, NTEventLog, Mail, Syslog, JMS,
among others. It also offers the possibility to log apart
from a transaction.
LOG4PLSQL provides the same features in PL/SQL
that LOG4J does in Java (LOG4J is an Apache Jakarta
project—see http://jakarta.apache.org/log4j).
After you download and install the software from
http://log4plsql.sourceforge.net, logs are put in levels in
the PL/SQL code (function, procedure, package, and
trigger). You can organize it in hierarchical sections
(discussed later). Afterwards, it’s possible to choose the
trace and the destination according to the need. Every
parameter is stored out of the code. Here’s a sample:
Transactions are very important in a database, but for
logging problems, sometimes it’s necessary to log apart
from the SQL transaction. Here are some examples of
when this is desirable:
• When you want to roll back a transaction, but not the
log message at the same time
• When your code is quite long and you want to view
its progress
LOG4PLSQL has two solutions to log apart from your
transaction. The first one is the autonomous transaction to
log messages in a log table. The second one is DBMS_PIPE
to send the log message to the external LOG4J logger with
the log4plsql.backgroundProcess.
The autonomous transaction feature is a full PL/SQL
solution. It’s very easy to use the log message, as it’s
immediately accessible by issuing a SELECT from the
TLOG table or the VLOG view, as you can see here:

BEGIN SQL> Declare

… 2 pCTX PLOG.LOG_CTX := PLOG.init (
PLOG.error ('mess error'); 3 psection => 'out transaction',
… 4 plevel => PLOG.LINFO,
END; 5 plog4j => FALSE,
6 pout_trans => TRUE);
7 begin
Log levels 8 PLOG.info (pCTX, 'My information');
9 end;
The levels of preset logs by the framework correspond to 10 /
the levels of standard severity:
SQL> rollback;
• The DEBUG level is for fine-grained informational
events that are very useful in debugging an SQL> select * from vlog;

application.
• The INFO level is for informational messages that
highlight the progress of the application at a coarse-
grained level.
• The WARN level is for potentially harmful situations.
• The ERROR level is for error events that might still
allow the application to continue running.
• The FATAL level is for very severe error events that
might lead the application to abort.
Before logging in your code, it’s best to do a test using
LOG
-----------------------------
[12/06 12:54:01: 89][INFO]
[SCOTT][out transaction][My information]
To use the second method, you’ll have to start a
background process (/cmd/startLog4JbackgroundProcess
.bat or /cmd/startLog4JbackgroundProcess.sh). This
small Java application reads a log message directly from a
PIPE in the database and logs the message with LOG4J
capability. This method has two advantages:
• There’s no added I/O in the database.

14 Oracle Professional April 2004 www.pinnaclepublishing.com

 • You can choose the LOG4J PropertyConfigurator, PLOG.init('hierarchical', PLOG.LINFO);
begin
Appenders, Layouts, and Level capability. PLOG.SetBeginSection (pCTX, 'mySection');
PLOG.info (pCTX, 'mess 1');
PLOG.SetBeginSection (pCTX, 'mySubSection');
Declare PLOG.info (pCTX, 'mess 2');
pCTX PLOG.LOG_CTX := PLOG.init( PLOG.SetEndSection (pCTX, 'mySubSection');
psection => 'testLog4jFeatures', PLOG.setEndSection(pCTX);
plevel => PLOG.LDEBUG, end;
plog4j => TRUE, /
pout_trans => TRUE);
begin select * from vlog;
PLOG.info (pCTX,
'This message is sent to LOG4J'); LOG
End; ------------------------------------------------------
/ [INFO ][hierarchical.mySection][mess 1]
[INFO ][ULOG][hierarchical.mySection
.mySubSection][mess 2]
In this example, and with these parameters, I now
have a new message in my NT Event Loggers. Installation and settings
At the time of this writing, the version of LOG4PLSQL
Hierarchical log sections available is v2.1.1 using LOG4J 1.2.8. The ZIP distribution
You can organize the log in hierarchical sections. That file contains all files used by LOG4PLSQL. In each
makes it possible to know where the notation is. release, you’ll always find a good version of LOG4J.
For each node, it’s possible to finely set what you A complete release of LOG4J can be found at http://
want to log. And you can also add a message about the jakarta.apache.org/log4j/download.
step or state where you are in a functional process. All scripts in the /cmd folder use the same
By default, all logs use dynamic hierarchical PL/SQL variable parameters: setVariable.bat for Windows
call stacks. Thus it’s possible to follow the sequence of and setVariable.sh for Unix systems. This file is used
package, procedure, function, and trigger calls. For each during the installation. If you want to use all LOG4J
object in the call stack, the owner and the name are stored. capabilities, you must modify the /properties/
When you define a hierarchical section, you use a log4plsql.xml file. If you want to customize the LOG4J
functional part in your PL/SQL application. The steps are: Appender, Layout, and Level, you have to change the
1. Initialize the command. parameters in the LOG4J configuration file. I’ll describe
2. Verify the stack. these files in the next sections.
3. Ask for a delivery. After you complete the /cmd/ install, it’s possible
4. Ask for an invoice. to read the logs under /sql/grantsys.log and /sql/
Declare
install.log. For the /cmd/ uninstall, refer to the /sql/
pCTX PLOG.LOG_CTX := unInstall.log file.

Don’t miss another issue! Subscribe now and save!

Subscribe to Oracle Professional today and receive a special one-year introductory rate:
Just $179* for 12 issues (that’s $20 off the regular rate)

NAME ❑ Check enclosed (payable to Pinnacle Publishing)

❑ Purchase order (in U.S. and Canada only); mail or fax copy
COMPANY
❑ Bill me later
❑ Credit card: __ VISA __MasterCard __American Express
ADDRESS
CARD NUMBER EXP. DATE

CITY STATE/PROVINCE ZIP/POSTAL CODE

SIGNATURE (REQUIRED FOR CARD ORDERS)

COUNTRY IF OTHER THAN U.S.

Detach and return to:
Pinnacle Publishing ▲ 316 N. Michigan Ave. ▲ Chicago, IL 60601
E-MAIL Or fax to 312-960-4106

* Outside the U.S. add $30. Orders payable in

404INS
PHONE (IN CASE WE HAVE A QUESTION ABOUT YOUR ORDER) U.S. funds drawn on a U.S. or Canadian bank.

Pinnacle, A Division of Lawrence Ragan Communications, Inc. ▲ 800-493-4867 x.4209 or 312-960-4100 ▲ Fax 312-960-4106

www.pinnaclepublishing.com Oracle Professional April 2004 15

The setVariable file
All parameters in this file are very easy to understand.
Here are descriptions of some of them:
• ORACLE_HOME and LOG4PLSQL_HOME are for
the path of Oracle and LOG4PLSQL.
• LOG_SID is for the database alias in tnsnames.ora.
• LOG_USER and LOG_PASSW_USER are for the user
in the database. This user should be able to use
DBMS_PIPE, so check your privileges. In scripts
there’s never a specification for storage management.
• SYS_USER and SYS_PASSW_USER are used only
during the installation phase.
• OracleVersion is used to compute a connection
string in SYS user. Use OracleVersion=9.2 or
OracleVersion=before9.2.
• CLASSPATH is used for the links to log4plsql.jar,
log4j-X.X.X.jar, xmlparserv2.jar, xmlcomp.jar,
classes12.jar, nls_charset12.jar, and runtime12.jar.
The log4plsql.xml file
In this file, you configure your parameter file for the
LOG4J (Configuration type and file) database for
April 2004 Downloads
• 404MENCHEN.ZIP—Source code to accompany Gary
Menchen’s article, “Object Types and Inheritance: From
DBMS_OUTPUT to Object-Oriented Stream I/O.”
For access to current and archive content and source code, log in at www.pinnaclepublishing.com.
Editor: Garry Chan (gchan@procaseconsulting.com)
Contributing Editor: Bryan Boulton
CEO & Publisher: Mark Ragan
Group Publisher: Michael King
Executive Editor: Farion Grove
Questions?
Customer Service:
Phone: 800-493-4867 x.4209 or 312-960-4100
Fax: 312-960-4106
Email: PinPub@Ragan.com
Advertising: RogerS@Ragan.com
Editorial: FarionG@Ragan.com
Pinnacle Web Site: www.pinnaclepublishing.com
Subscription rates
United States: One year (12 issues): $199; two years (24 issues): $348
Other:* One year: $229; two years: $408
Single issue rate:
$27.50 ($32.50 outside United States)*
* Funds must be in U.S. currency.
16 Oracle Professional April 2004
your Oracle connections.
The log4j configuration file
This file is referenced in log4plsq.xml; the structure and
the entry are LOG4J-dependent. See the “Configuration”
section at http://jakarta.apache.org/log4j/docs/
manual.html for more information.
Conclusion
In LOG4PLSQL, you should find all the functionality
you need to manage your logs in your PL/SQL code—
these features are the result of LOG4J and LOG4PLSQL
projects. It’s easy to implement, and provides great
flexibility regardless of the logging needs of your
application. For more information, new feature requests,
and comments, sign up for the log4plsql-all-info@
lists.sourceforge.net mailing list. ▲
Guillaume Moulard works for France Telecom. He’s a key contributor
to the LOG4PLSQL project. He teaches XML and SGBD at Paris Sud
Orsay University and worked at Oracle France for four years.
gmoulard@users.sourceforge.net.
• 404FEUER.SQL—Source code to accompany Steven
Feuerstein’s article, “Exploring Options: Multiple Paths
to an Answer.”
Oracle Professional (ISSN 1525-1756)
is published monthly (12 times per year) by:
Pinnacle Publishing
A Division of Lawrence Ragan Communications, Inc.
316 N. Michigan Ave., Suite 300
Chicago, IL 60601
POSTMASTER: Send address changes to Lawrence Ragan Communications, Inc., 316
N. Michigan Ave., Suite 300, Chicago, IL 60601.
Copyright © 2004 by Lawrence Ragan Communications, Inc. All rights reserved. No part
of this periodical may be used or reproduced in any fashion whatsoever (except in the
case of brief quotations embodied in critical articles and reviews) without the prior
written consent of Lawrence Ragan Communications, Inc. Printed in the United States
of America.
Oracle, Oracle 8i, Oracle 9i, PL/SQL, and SQL*Plus are trademarks or registered trademarks of
Oracle Corporation. Other brand and product names are trademarks or registered trademarks
of their respective holders. Oracle Professional is an independent publication not affiliated
with Oracle Corporation. Oracle Corporation is not responsible in any way for the editorial
policy or other contents of the publication.
This publication is intended as a general guide. It covers a highly technical and complex
subject and should not be used for making decisions concerning specific products or
applications. This publication is sold as is, without warranty of any kind, either express or
implied, respecting the contents of this publication, including but not limited to implied
warranties for the publication, performance, quality, merchantability, or fitness for any particular
purpose. Lawrence Ragan Communications, Inc., shall not be liable to the purchaser or any
other person or entity with respect to any liability, loss, or damage caused or alleged to be
caused directly or indirectly by this publication. Articles published in Oracle Professional
reflect the views of their authors; they may or may not reflect the view of Lawrence Ragan
Communications, Inc. Inclusion of advertising inserts does not constitute an endorsement by
Lawrence Ragan Communications, Inc., or Oracle Professional.
www.pinnaclepublishing.com