#

| Chapter 17 PLVhlp: Online Help for PL/SQL Programs |

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

17.3 What Is "Online Help" for Stored Code? |  | 17.5 Implementing PLVhlp

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