12. PLVio: Reading and Writing PL/SQL Source Code

Contents:
Why PLVio?
Code Repositories Supported by PLVio
Managing the Source Repository
The Source WHERE Clause
Managing the Target Repository
Reading From the Source
Writing to the Target
Saving and Restoring Settings
Cleaning Up Source and Target

The PLVio (PL/Vision Input/Output) package consolidates all the logic required to read from and write to repositories for PL/SQL source code. The PLVio package supports operating system files (as of Release 2.3), database tables, strings, and PL/SQL tables as both input and output sources. It hides all of the complexities of this I/O from users of the PLVio package. By relying on PLVio, other PL/Vision packages, such as PLVhlp and PLVcase, can pass on support for these varying repositories with minimal effort and maximum flexibility.

PLVio is a large package with many different elements. Generally, PLVio activity breaks down into the following areas:

Set and manage the source repository, including the WHERE clause of the SQL statement used to define the source if it is a database table. Among other things, you can initialize and close the source.
Set and manage the target repository. You can display, close, and clear the target.
Read from the source and write to the target. You can even transfer the contents of the source repository to the target in a single step with the src2trg procedure.
Save and restore repository settings. This is useful when you are using PLVio simultaneously in different contexts.
Trace PLVio activity with a package window.

You can also use PLVio to manipulate text that is not PL/SQL source. Indeed, you can use PLVio to more easily write text out to operating system files (an interface to PLVfile and, underneath that, the builtin UTL_FILE package).

12.1 Why PLVio?

When you use PLVio, you can step away from the details of reading to and writing from specific types of text repositories. You build programs and utilities which get lines from the source and/or put lines to the target. But your code is not necessarily tied down to any specific type of repository. Consequently, your code can work with any of these different repositories without undergoing radical change.

The PLVhlp package's use of PLVio shows the power of abstracting the concept of source and repository for PL/SQL code. PLVhlp offers an architecture for displaying online help text for your own PL/SQL programs. The default mode for PLVhlp is to display the help text to standard output or your screen. Thus, I can call PLVhlp (through a frontend procedure in the PLV package) as shown below to get high-level information about PL/Vision itself:

SQL> exec PLV.help Help for PLV Overview of PL/Vision  PL/Vision is a development accelerator for PL/SQL programmers. It is made up of a set of packages which you can use as plug-and-play components in your own applications. Here is a quick overview of some of the available packages:  PLVdyn - performs dynamic SQL and PL/SQL operations. PLVexc - High-level exception handling capabilities. PLVlog - Generic log mechanism. PLVvu - View stored code and compile errors.

What if you are not developing applications in SQL*Plus and you cannot rely on DBMS_OUTPUT.PUT_LINE to display the help text? Instead of abandoning online help, you can instead redirect the output of the PLVhlp package to a PL/SQL table, for example, as shown below:

PLVio.settrg (PLV.pstab);

After this call, any attempts to display the help text will send that information to a PL/SQL table (PLVio.target_table , to be precise). You can then build your own program to read from this PL/SQL table and display the results in your development environment. You could even display this information (to reassure yourself, perhaps, that it really is there) with this command:

PLVio.disptrg;

Notice that I did not have to make any changes to the PLVhlp package to achieve this redirection; nor does any of the code you have built to extract the help text from your own program units need to be modified.

PL/Vision packages make extensive use of the PLVio package. To use it yourself, you will first set your source and target. Then you must use get_line to read from the source and put_line to write to the target. To make this package as flexible as possible, PLVio offers lots of additional programs, constants, and data structures. Don't be intimidated by the number and variety. Dip into the package as you need it, experiment with its nuances, and look at the examples of its usage in PL/Vision.

The following sections show how to use each of the different elements of the PLVio package.


11.8 Tracing PLVobj Activity		12.2 Code Repositories Supported by PLVio