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