Procedure Style and Standards A procedure writer's toolkit and how to influence style via the Editor
From "VS Procedure",  Access 86, June 1986
[ Prior Article ]     [ Return to the Catalog of articles ]     [ Next Article ]

This article will examine procedure style, list some tools for the procedure writer, and finally end with an example procedure to illustrate a method of using the Editor to influence style.

Procedure style

Like all languages, Procedure operates within a set of rules for it's usage. The rules used by Wang's Procedure language are very forgiving, allowing a tremendous variety of personal expressions to be logically evaluated. Thus, there is a functional level of operation, which I refer to as syntax. All elements beyond this functional level is style.

Here are some of the standards I have established for my procedures:

1. Create a tabbing standard. Establish standard tab settings and use them for all procedures. Write a procedure to control the Editor so implementing this standard is effortless (see example below).

2. Use labels consistently. Use the form of the label to indicate whether it refers to a program step or an intermediary operation within that step. Example: use a procedure step label of 'S01', but label the output file name within that step to 'F1'.

3. Use upper case for all functional elements. While the procedure interpreter allows a mix of upper and lower case, I reserve lower case for comments. This makes it easier to separate the functional elements from the comments. Using consistent case structures also simplifies searches for text items within procedures.

4. Branch consistently. Haphazard branching within a procedure can be confusing. Wherever possible, branch FORWARD to a single exit within a section. Likewise, try not to include RETURN statements in the middle of the procedure; instead, branch to a single exit point. Example: 'GOTO END', where a step labeled 'END' contains the RETURN keyword.

5. Enclose system parameters within quotes. Procedure will interpret most non-keyword elements as text to be passed to associated fields, sparing you the need to identify this text within quotation marks. I feel, however, that the quotes help to identify these elements and contribute to the readability of the procedure.

6. Use plenty of white space. Adding blank lines to separate sections does not appear to slow execution appreciably. Still, most procedure writers seem to feel that this extra space is unnecessary. I have found that the majority of time spent on any program or procedure lies in maintenance, and greater readability makes for easier maintenance.

7. Align similar items vertically. Put keywords, system parameters, labels, and comments in respective columns. This enhances the readability of the procedure - admittedly with some increase in the size of the procedure.

8. Use comments. Well-structured procedures almost speak for themselves. You should add comments where the purpose of the step is not immediately apparent. Use lower case for your comments as an aid in differentiating them from keywords and system specification items.

8. Use consistent screen design. If you use PF keys for menu selections, do so for all screens. Center the contents of the screen, or place lines in consistent locations. Use titles to identify the screens.

9. Include messages to the operator. Nothing is more frustrating than to start a long procedure and never know how far it has progressed. Use the MESSAGE keyword to indicate successful completion of major steps in long procedures.

10. Put modifiable items at the top of the procedure. Where practical, establish variables at the beginning of the procedure to carry the values of any necessary constants. If the value of any of these constants must change, only one element needs modification. Example: establish the variables &INLIB and &INVOL and use them wherever the input library and volume are required. (Alternatively, you may use the SET command to set user defaults, though I am annoyed to have my defaults reset whenever I run a procedure.)

11. Include modification history. Add appropriate comments to relay the modifications applied to the procedure. Use modifications codes to assist in identifying changes at the line level.

The procedure writer's toolkit

Here are several items I have assembled to assist in procedure writing:

1. A procedure to drive the editor: Realistic use of any standard tabs, case usage, or library naming convention requires that developers will not have to re-key all Editor defaults before beginning. This means that a procedure should be written to drive the Wang Editor, inserting these elements as necessary. An example of such a procedure follows.

2. Copies of relevant GETPARM screens: An important part of procedure writing is assembling existing utilities and other programs into executable units. This means that you will need to know what information the utility will expect (i.e. the GETPARM screens). While this information is available in text form at the back of some Wang manuals, I prefer to have a copy of the screen itself to see the default values, field usage etc. I have assembled a binder of such screen images.

3. Documentation for all subroutines: One of the strongest advantages to procedure over other methods lies in its easy access to subroutines. I keep information handy on all subroutines available to me, especially Wang Usersubs. If you don't have the Wang Usersubs manual (Document number 800-1315), look in the Usersubs and Useraids libraries for a file called SVCDOC; this describes most of the subroutines.

4. Standard library of routines: Many COBOL and RPGII programmers keep a library of commonly-used routines, copying them into new programs as needed. The same approach could be used with a procedure. Alternatively, standard subroutines could be written as procedures. (Naturally, you must keep the procedures in this library as universal as possible.

Example procedure

I use short procedures to drive the Wang Editor to set it up with the defaults I normally use. I have settled on the following Editor settings:

1. My default library is DSBPROC; e.g., my initials plus 'PROC'.

2. Tabs are set at columns 6, 26, 36, 46, 56, 66, and 71.

3. UPPER case is the default mode.

4. The procedure is automatically renumbered and replaced before every run or syntax check.

Here is the procedure I use to maintain those standards:

PROCEDURE EDITPROC **************************************************************** * * * This procedure sets Editor default values for editing * * procedures. * * * * Created 01/31/85 by Dennis S. Barnes * * * * MODIFICATION HISTORY: * * * * 03/25/85 Value of &INVOL changed to reflect renamed system * * volume. * * * **************************************************************** DECLARE &INLIB STRING (8) DECLARE &INVOL STRING (8) INITIAL "SYSVOL" [MOD. 03/25/86] DECLARE &ID STRING (3) S01: EXTRACT &ID = USERID * Set initial value of library S02: ASSIGN &INLIB = &ID(1,*) !! "PROC" S03: RUN EDITOR DISPLAY INPUT LANGUAGE = "PROCEDURE", LIBRARY = &INLIB, VOLUME = &INVOL, PLIBRARY = " ", PVOLUME = " " * Note that the TABS field is one area - not multiple fields ENTER DEFAULTS TABS = "06 26 36 46 56 66 71", MODE = "UPPER" * Set for automatic replace prior to run or syntax check ENTER OPTIONS REPLACE = "YES", RENUMBER = "YES", MODCODE = &ID RETURN

I use similar procedures for other languages, substituting other default values as appropriate. I find that it saves much time by eliminating need to re-enter the values with each program or procedure I edit.

What are your standards?

Style issues go far beyond the mere usability of a process. I realize that personal style is a sensitive issue with many users, and I encourage comments on the standards I have outlined above. Please send your thoughts to me at the address listed below.

Next month we'll create a utility to identify inappropriately large disk files and release unused space within those files.