Tải bản đầy đủ
PLVhlp: Online Help for PL/SQL Programs

PLVhlp: Online Help for PL/SQL Programs

Tải bản đầy đủ

[Appendix A] Appendix: PL/SQL Exercises
PL/SQL: Statement ignored

Well, that didn't work. I guess it's not called getnext after all. Well, what the heck is it called? Oh yeah! It's
get_next_token.
SQL> exec :toke := PLVlex.get_next_token ('this is it');
begin :toke := PLVlex.get_next_token ('this is it'); end;
*
ERROR at line 1:
ORA−06550: line 1, column 23:
PLS−00302: component 'GET_NEXT_TOKEN' must be declared
ORA−06550: line 1, column 7:
PL/SQL: Statement ignored

#$%!! No, that's not correct either! Now I am really frustrated. Sigh... guess it is time to go into Codewright,
open up the source code and take a look around... well, I'm lucky to at least have ready access to my code...
Have you ever had this kind of problem? The database is jam−packed with all sorts of goodies, but how are
you supposed to know what's there and what it's good for? Stored code is wonderful, but there is no easy way
at the moment to view that stored source code −− a necessary step to figure out how to call a particular
program or understand what happens when you do run the program. This is most crucial when working with
packages. In this case, the package specification is supposed to contain all the information you will ever need
to use that package, but how do you find and view that specification?

16.4 Implementing PLVgen

17.2 Current Sources of
Information

Copyright (c) 2000 O'Reilly Associates. All rights reserved.

17. PLVhlp: Online Help for PL/SQL Programs

479

Chapter 17
PLVhlp: Online Help for
PL/SQL Programs

17.2 Current Sources of Information
OK, you've got the DESCRIBE command in SQL*Plus. This command displays the parameters of a stored
program (either standalone or package−based). For example, if I want to know about the call interface to my
PLVvu.code procedure, this is what I do:
SQL> desc PLVvu.code
PROCEDURE PLVvu.code
Argument Name
Type
−−−−−−−−−−−−−−− −−−−−−−−−−−−−−
NAME_IN
VARCHAR2
START_IN
NUMBER(38)
END_IN
NUMBER(38)
HEADER_IN
VARCHAR2
TYPE_IN
VARCHAR2

In/Out
−−−−−−
IN
IN
IN
IN
IN

Default?
−−−−−−−−
DEFAULT
DEFAULT
DEFAULT
DEFAULT
DEFAULT

The DESCRIBE command even tells me the return datatype of a function:
SQL> desc PLVtkn.is_keyword
FUNCTION PLVtkn.is_keyword RETURNS BOOLEAN
Argument Name
Type
In/Out Default?
−−−−−−−−−−−−−−− −−−−−−−−−−−−−− −−−−−− −−−−−−−−
TOKEN_IN
VARCHAR
IN
TYPE_IN
VARCHAR2
IN
DEFAULT

The DESCRIBE command, by the way, makes use of the DESCRIBE_PROCEDURE procedure of the builtin
DBMS_DESCRIBE package. This program returns a program's arguments in a series of PL/SQL tables. It's a
great utility, except it doesn't tell me anything about what the program does −− only how to call it.
Furthermore, you need to know the name of the program to use DESCRIBE. The DESCRIBE command does
not, in other words, offer online documentation or help for this code.
Another option is to view the source code (assuming that you have access to it, which is far from certain). The
PLVvu package provides the code and code_after procedures for just this purpose. For example, I can
view the first ten lines of the PLVvu package itself as follows:
SQL> exec PLVvu.code ('b:PLVvu', 1, 10);
−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−
Code for PACKAGE BODY PLVVU
−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−
Line# Source
−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−
1 PACKAGE BODY PLVvu
2 IS
3
c_product_header VARCHAR2(30) := 'PL/Vision';
4
c_linelen INTEGER := 77;
5
v_last_border BOOLEAN := FALSE;
6
v_overlap INTEGER := c_overlap;
7
/*−−−−−−−−−−−−−−− Private Modules −−−−−−−−−−−−−−−−−*/
8
PROCEDURE disp_border
9
(line_in IN INTEGER := NULL,
10
err_line_in IN INTEGER := NULL,

480

[Appendix A] Appendix: PL/SQL Exercises
Unfortunately, both DESCRIBE and the PLVvu.code approach are still fairly crude and heavy−handed
solutions to a basic problem in PL/SQL: the lack of an online help facility for one's code.
In the remainder of this chapter I present an architecture (and, of course, a PL/SQL package) for
implementing online help for PL/SQL programs. The resulting PLVhlp package may not the most elegant
approach one would want to take, but it has lots of potential for improving the lot of developers.

17.1 Who Needs Online
Help?

17.3 What Is "Online Help"
for Stored Code?

Copyright (c) 2000 O'Reilly Associates. All rights reserved.

481

Chapter 17
PLVhlp: Online Help for
PL/SQL Programs

17.3 What Is "Online Help" for Stored Code?
First of all, let me make a distinction and set some scope for this chapter: I am not talking about online help
for PL/SQL itself (such as "what is the syntax of the OPEN statement?"). Instead, I want to address how to
provide online help for PL/SQL programs that you or I might write and then make available to others. So
when I say "online help for PL/SQL," I mean online instructions on how to use custom−built and prebuilt
PL/SQL programs that have been stored in a database and on which you have execute authority.[1]
[1] You could, by the way, also use this package and techniques to provide online help for
builtins of the PL/SQL language.
Let's now run through the same scenario I presented at the beginning of the chapter, this time with online help
for PL/SQL available.
All right, now I want to parse a string into separate tokens. Let's see, that's gotta be the PLVlex package and
the getnext function.
SQL> VARIABLE toke VARCHAR2(30);
SQL> exec :toke := PLVlex.getnext ('this is it');
begin :toke := PLVlex.getnext ('this is it'); end;
*
ERROR at line 1:
ORA−06550: line 1, column 23:
PLS−00302: component 'GETNEXT' must be declared
ORA−06550: line 1, column 7:
PL/SQL: Statement ignored

Well, that didn't work. Admit it, Steven, you forgot how to use your own code. Time to get some help.
SQL> exec PLVlex.help
Help for PLVLEX
Overview: provides lexical analysis and functions for strings.
===================================================================
Element − Description
===================================================================
FUNCTION is_delimiter − Returns TRUE if string is a delimiter.
PROCEDURE get_next_token − Returns next token in string.
PROCEDURE get_next_atomic − Returns next atomic in string.

Now I know what's in the package. What I'd really like are examples of the ways these programs can be used.
SQL> @examples PLVlex
Examples for PLVLEX
Here is a call to get_next_token as used by PLVcase,
which UPPER−lower cases PL/SQL programs:
LOOP
PLVlex.get_next_token
(text, curr_pos, token, next_pos, FALSE, text_len, TRUE);

482

[Appendix A] Appendix: PL/SQL Exercises

EXIT WHEN v_token IS NULL OR line_in.pos > line_in.len;
END LOOP;
The FALSE indicates that I do not want to skip over spaces. This
maintains the program's indentation. The TRUE indicates that I want
qualified names (X.Y.Z) to be returned as one token.

I am now ready to roll. That is just the information I needed to move into high gear!
That is the kind of help I would love to be able to get from a PL/SQL environment. Of course, the help itself
is only as good as the text you enter. In addition, you need to at least know the name of the package you want
to be using... well, I take that back. After all, once the help mechanism is in place, you could provide a very
high−level "table of contents" or index into your programs, as I show below.
SQL> @help
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.
PLVlex − Lexical analysis and parsing of strings.
PLVlog − Generic log mechanism.
PLVvu − View stored code and compile errors.

At this point I imagine you understand the idea −− and I hope you like it. If not, skip the rest of this chapter.
If so, I first provide the basic information ("user's guide") you need to use the PLVhlp package. After that I
move on to the underlying principles, architecture, and implementation of online help for your PL/SQL
programs so that you can get a better understanding of how I went about constructing this utility.

17.2 Current Sources of
Information

17.4 Using PLVhlp

Copyright (c) 2000 O'Reilly Associates. All rights reserved.

483