|
Chapter 17 PLVhlp: Online Help for PL/SQL Programs |
|
There are two aspects to using the PLVhlp package:
Display help text using the show and more procedures. In the PLVhlp architecture, help text is stored with the program unit it documents in specially formatted comment areas. The show and more procedures then access that text. You can also fine-tune the display of help text by setting the size of a page of text.
Create help text to be inserted into stored code for use as online help text. For more details on how to set up this help text, see the sections "Creating Help Text" and "Implementing PLVhlp."
These aspects are covered in the following sections.
The show program initiates the display of help text on a topic. Its specification is as follows:
PROCEDURE show (context_in IN VARCHAR2, part_in IN VARCHAR2 := c_main);
where context_in is the context or program unit that contains the text and part_in is the specific topic to be displayed in response to this request. The following call to show , for example, requests that the help text in the PLVprs package specification covering the topic "examples" be displayed.
SQL> exec PLVhlp.show ('s:PLVprs', 'examples');
PLVhlp predefines two constants for commonly used help text topics: top-level or main help and examples help. The last call to PLVhlp.show could be rewritten using one of those constants as follows:
SQL> exec PLVhlp.show ('s:PLVprs', PLVhlp.c_examples);
You might even consider adding constants to the PLVhlp package to make it easier to create and access consistently named areas of help text.
The more procedure's specification is even simpler than that of show:
PROCEDURE more;
This procedure simply requests that the next page of text for the current help topic be displayed. If there is no more help text or if you have not previously called PLVhlp.show , more displays the following message:
SQL> exec PLVhlp.more No more help available...
PL/Vision also offers some SQL*Plus scripts to make it easier to request help. These scripts are help.sql and more.sql . The following lines compare the different approaches using PL/SQL program execution and SQL*Plus script execution.
Instead of typing:
SQL> exec PLV.help
you can simply enter:
SQL> @help plv
And instead of typing:
SQL> exec more
you can simply enter:
SQL> @more
One of the more interesting aspects of PLVhlp is that it allows developers to see limited amounts of text at a time (a single page). This makes the reading of help text much less frantic; users do not have to feel panicky about pages of text scrolling past their eyes.
The default page size is 25 lines, so that a page of text fits comfortably on a monitor. You can change this value by calling the set_pagesize procedure, whose header is shown below:
PROCEDURE set_pagesize (pagesize_in IN NUMBER);
In the following SQL*Plus session, for example, I move the pagesize up to 60, since SQL*Plus in Windows supports vertical scrolling:
SQL> exec PLVhlp.set_pagesize(60);
You can also find out the current size of the page by calling the pagesize function. The following little utility (not a part of PLVhlp) makes sure, for instance, that the pagesize is no larger than the default:
PROCEDURE limit_ps (size_in IN INTEGER := 25) IS BEGIN IF PLVhlp.pagesize > size_in THEN PLVhlp.set_pagesize (size_in); END IF; END;
The set_pagesize program is available to end users of PLVhlp. It can also be used by developers who construct help environments for PL/SQL development to arrange a comfortable viewing area.
A user cannot access help text unless you place that text inside the appropriate program unit. PLVhlp reads its text from the ALL_SOURCE data dictionary; the text is, in other words, stored with the program about which help is needed (the implementational aspects of this technique are explored later in the chapter).
To give you an idea of the format of this help text, consider the following fragment of a package specification:
PACKAGE call IS PROCEDURE maintain; /*ABOUT The maintain procedure maintains the current set of calls in the system. ABOUT*/ END call;
The strings /*ABOUT and ABOUT*/ follow the standard for the starting and ending strings, respectively, of a block of text that will be retrieved by this call to PLVhlp.show :
SQL> exec PLVhlp.show ('s:call', 'about');
PLVhlp provides two functions to help you follow the standard for help text comment blocks: help_start and help_end . With both functions, you provide the keyword for text block and receive in return the strings you need to wrap around your help text.
The PLVgen package uses these two functions to generate a block of help text you can then cut and paste into your own code. Here is the implementation of the PLVgen.helptext procedure:
PROCEDURE put_help (context_in IN VARCHAR2, indent_in IN INTEGER := 0) IS BEGIN IF using_hlp THEN put_line (PLVhlp.help_start (context_in), indent_in); put_line ('Add help text here...', indent_in); put_line (PLVhlp.help_end (context_in), indent_in, c_after); END IF; END;
and here is an example of the code it generates:
SQL> exec PLVgen.helptext ('constraints'); /*CONSTRAINTS Add help text here... CONSTRAINTS*/
You can also embed blank lines in your help text, which is useful in making text easy to read. If you CREATE OR REPLACE programs with these blank lines in SQL*Plus, however, those lines will be discarded before saving the source code to the database. You can avoid this white space destruction by either not using SQL*Plus or by using a "line separator" in place of a truly blank line. For more information about the line separator feature in PL/Vision, see Chapter 7, p: A Powerful Substitute for DBMS_OUTPUT .
The following scenario illustrates how to use these different elements to obtain help about the PLVprs package (PL/Vision PaRSe):
Step 1. Before I try to access the help text, I build a few components to make it easier to request the help. First, I add a help program to my PLVprs package specification and body as follows:
PACKAGE PLVprs IS ... other elements ... PROCEDURE help; END PLVprs; PACKAGE BODY PLVprs IS ... other elements ...
PROCEDURE help IS BEGIN
PLVhlp.show ('s:PLVprs'); END help; END PLVprs;
This provides a layer over the help package that allows me to ask for help within the context of the PLVprs package.
Step 2. I also create a SQL*Plus script ( more.sql ) that allows me to call the PLVhlp.more procedure with a minimum of typing:
SET FEEDBACK OFF exec PLVhlp.more;
Step 3. I start up a SQL*Plus session, set the pagesize to 10, and access the help text for the parsing package.
SQL> exec PLVhlp.set_pagesize(10); SQL> exec PLVprs.help Help for PLVPRS Overview: PLVprs provides a variety of PaRSing programs. It performs parsing for "generic" strings, but also performs parsing specifically for "PL/SQL strings", ie, lines of code from a PL/SQL program. Programs in PLVprs: next_atom_loc - Returns location of next atomic. ...more...
The first page of text has been displayed; the "...more..." indicates that there is more text to be viewed on this topic.
Step 4. So I will ask for more help:
SQL> @more Help for PLVPRS display_atomics - Displays distinct atomics in string. nth_atomic - Returns Nth atomic in string. number_of_atomics - Returns number of atomics in string. numinstr - Returns number of occurrences of substring in string. string - Returns string's atomics into a PL/SQL table. plsql_string - Returns PL/SQL code atomics into PL/SQL table. wrap - wraps a long string into a PL/SQL table. wrapped_string - wraps a long string into a string ...more...
And even more help....
SQL> @more Help for PLVPRS with carriage returns embedded. display_wrap - displays the wrapped string
Notice that I no longer receive the "...more..." indicator. Now when I ask for more help, I am told that the current topic is depleted:
SQL> @more No more help available...
What I've shown so far is general help for the PLVprs package. I can also provide more specialized areas of help. My PLVlex package, for example, contains the following help procedure:
PROCEDURE examples IS BEGIN PLVhlp.show ('s:PLVprs', PLVhlp.c_examples); END examples;
With this procedure in place I can now also ask for information about examples for the PLVlex package:
SQL> exec PLVlex.examples Help for PLVLEX Examples
Here is a call to get_next_token from PLVcase, which UPPER-lower cases PL/SQL programs:
LOOP PLVlex.get_next_token (text, curr_pos, token, next_pos, FALSE, text_len, TRUE); 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.
You are not restricted to creating help topics of "main" and "examples." You can use whatever designators you want. Suppose, for example, that you wanted to provide help on cursors available in the company package. You would create a block of comment text in that package specification as follows:
/*CURSORS Company-related Cursors: ... CURSORS*/
Then you could add another help-delivering procedure to that package:
PROCEDURE on_cursors IS BEGIN PLVhlp.show ('s:PLVprs', 'cursors'); END on_cursors;
With these pieces in place, the following command in SQL*Plus delivers the help you want:
SQL> exec company.on_cursors;
And that is how developers can use PLVhlp to get a handle on the stored code available to them. Obviously, someone has to spend the time to enter the help text, breaking it up into useful sections, etc. Once that is done, however, PLVhlp makes that information readily available to any user of the package.
|
|
|
|
| 17.3 What Is "Online Help" for Stored Code? |
|
17.5 Implementing PLVhlp |
Copyright (c) 2000 O'Reilly & Associates. All rights reserved.