2.6 Building Flexibility Into Your Packages

Chapter 2
Best Practices for Packages

 

---

Who is going to argue with this one? Sure, we want our code to be flexible, in a practical sort of way. It is quite another thing to internalize this issue in the context of packages and figure out how to take full advantage of the package structure to offer maximum flexibility.

If a program is going to be widely reusable, it should be able to adapt to different circumstances to meet different needs. It is easy to talk about flexibility. I have found that when it comes to packages there are two basic ways to be flexible when writing programs for others to use:

1. Offer lots of parameters in the parameter lists of the package's functions and procedures. This is the traditional, well-worn path.

2. Provide toggles or on-off switches, distinct from the main programs of the package, which modify the behavior of those programs. This approach takes advantage of the package structure to offer a new way of doing things.

It certainly makes sense to offer arguments in a packaged program unit to improve the flexibility of that individual program. Consider the display procedure of the PLVtab package, whose header is shown below:

   PROCEDURE display      (table_in IN date_table,       end_row_in IN INTEGER,      header_in IN VARCHAR2 := NULL,      start_row_in IN INTEGER := 1,      failure_threshold_in IN INTEGER := 0,      increment_in IN INTEGER := +1);

This procedure has a whole bunch of parameters, and every one of them makes sense for the display of a particular table. Do you want to provide a header different from the default "Contents of Table"? Provide an argument to the header_in parameter. Do you want to display every fifth row? Pass in 5 for increment_in. Sensible defaults are, on the other hand, provided for almost every parameter, so you only need to provide values if you want to override these defaults.

What do you do, however, when you want to provide flexibility that affects the behavior of the package as a whole, not just for a particular program? What if you want to alter the configuration of a package for an entire session? Furthermore, what if you want to change the behavior of your package without changing the application code that uses your package?

Again, let's take a look at the PLVtab package for an illustration of this situation. PLVtab is a low-level package used throughout PL/Vision under many different circumstances. In some situations, I wanted to be able to display the row number in which the data is found. In other scenarios, I did not want any header to display before the table data was shown. Finally, I thought it would be useful to be able to see a translation of a blank line (i.e., does the line contain actual blanks or is it NULL or is it some other non-printing character?).

I could simply have kept adding new parameters to the display procedure (actually, adding new parameters to the nine different overloaded versions of display) to handle all of these variations. I would then end up with a header for display that looked like this:

   PROCEDURE display      (table_in IN date_table,       end_row_in IN INTEGER,      header_in IN VARCHAR2 := NULL,      start_row_in IN INTEGER := 1,      failure_threshold_in IN INTEGER := 0,      increment_in IN INTEGER := +1,      use_header_in IN BOOLEAN := TRUE,      show_rownums_in IN BOOLEAN := FALSE,      show_blanks_in IN BOOLEAN := FALSE);

I don't know about you, but when I look at programs with more than six or seven parameters, my head starts to spin. Human brains are not, according to numerous studies, well equipped to deal with more than seven items at once. You could contend that these additional parameters increase the flexibility of the display procedure. I would argue, instead, that these additional parameters doom the PLVtab.display procedure to the dustbin of history. Few people will be brave enough to try to use it, particularly if they have to modify the default values of those trailing arguments.

Fortunately, certain aspects of the PL/SQL package provide an alternative to turning your procedure into a sinking ship (weighed down by too many parameters): you can build toggles into your packages that allow a user of the package to change the behavior of the utility with the "flip of a switch."

2.6.1 Toggling Package Behavior

You will find toggles appearing throughout the PL/Vision packages. A toggle is a set of three programs: two procedures that allow you to turn a feature on or off, and a function to tell you the current status (on or off). The liberal application of toggles can transform the usability of your packages. The easiest way to teach you this technique is to show you how I use it in PL/Vision.

In PLVtab, I did not add a use header argument to the nine display procedures. Instead, I offer a toggle or on-off switch using these three programs:

   PROCEDURE showhdr;    PROCEDURE noshowhdr;    FUNCTION showing_header RETURN BOOLEAN;

The showhdr program turns on the showing of the header. The noshowhdr turns off the display of the header. The showing_header function returns TRUE if the header is currently set to be shown. These three programs contain very little. They simply maintain and access a private global variable, as shown below:

   v_display_header BOOLEAN := TRUE;    PROCEDURE showhdr IS    BEGIN      v_display_header := TRUE;    END;    PROCEDURE noshowhdr IS    BEGIN      v_display_header := FALSE;    END;    FUNCTION showing_header RETURN BOOLEAN IS    BEGIN      RETURN v_display_header;    END;

How do I put these toggles to use? Suppose that in most cases in my application I wish to hide the header. Since the default value for v_display_header is TRUE, I must turn off the display of the header at the start of my session. I could do that in my SQL*Plus login.sql script as follows:

exec PLVtab.noshowhdr;

Alternatively, if I am using PLVtab within an Oracle Developer/2000 Oracle Forms screen, I might place this call inside the When-New-Form-Instance trigger:

PLVtab.noshowhdr;

If, at some point in my application, I want to display a table with its header, I can temporarily override the default setting as follows:

PLVtab.showhdr; PLVtab.display (selected_comp_tab, v_tot_selected, 'Selected Companies'); PLVtab.noshowhdr;