Advanced Oracle PL/SQL Programming with Packages

Advanced Oracle PL/SQL Programming with PackagesSearch this book
Previous: 17.3 What Is "Online Help" for Stored Code?Chapter 17
PLVhlp: Online Help for PL/SQL Programs
Next: 17.5 Implementing PLVhlp
 

17.4 Using PLVhlp

There are two aspects to using the PLVhlp package:

  1. 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.

  2. 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.

17.4.1 Showing the Help Text

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

17.4.2 Setting the Page Size

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.

17.4.3 Creating Help Text

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.

17.4.4 A PLVhlp Tutorial

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...

17.4.4.1 Getting specialized help

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.


Previous: 17.3 What Is "Online Help" for Stored Code?Advanced Oracle PL/SQL Programming with PackagesNext: 17.5 Implementing PLVhlp
17.3 What Is "Online Help" for Stored Code?Book Index17.5 Implementing PLVhlp

The Oracle Library Navigation

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

Library Home Oracle PL/SQL Programming, 2nd. Ed. Guide to Oracle 8i Features Oracle Built-in Packages Advanced PL/SQL Programming with Packages Oracle Web Applications Oracle PL/SQL Language Pocket Reference Oracle PL/SQL Built-ins Pocket Reference
This HTML Help has been published using the chm2web software.