The Procedure Police A quick, standard method for updating and documenting procedure code
From "VS Workshop",  Access to Wang, August 1992
[ Prior Article ]     [ Return to the Catalog of articles ]     [ Next Article ]

Last month I covered some of the philosophical and practical aspects of a change control process, with examples based on the needs of a development shop working in COBOL, BASIC, or RPGII. Many of us do little or no programming of this sort, but would like to better manage the changes we perform to the operating environment. Many times these operating changes occur to procedures, so this time I will present an example based on such needs.

Nearly all system administrators and operators have occasion to write and maintain procedures to automate daily tasks. Tracking changes to these procedures is difficult; modification codes are only three characters in length and the use of too many comment lines will slow the execution of the procedure noticeably. Procedures are also frequently modified. All of these facts heighten the need for a quick, standard method for updating and documenting procedure code.

Example: Procedure MP

The MP procedure (Figure 1, below) attempts to do just that. It allows files to be copied from production library, edited, compared with the original, and installed (moved) into production. Selection of files is made through screens that show all files in the library, allowing easy review of work in process. While visually complex, MP is conceptually simple: for each menu item, a selection routine is called and the results used for the copy, edit, or compare operation.

File movements use the COPY utility, with checks for the existence or non-existence of the library prior to the copy. The comparison option uses Wang's COMPARE utility with the SRCDIFF option to isolate and list adds and changes between the two files. These change listings can be printed and filed with the documentation for the procedure.

As written, the MP procedure assumes a single production procedure library (PRODPROC on SYSTEM) and a single work file library (WORKPROC on SYSTEM). These values are stored at the top of the procedure in variables, and the initial value of these variables should be changed to fit your shop's needs. The exact location of the COMPARE and SELECTER utilities may also need to be adjusted.

Choosing files with SELECTER

The selection approach used by MP relies on SELECTER, a handy utility program that displays listings of files or libraries and allows the user to select an entry. SELECTER is offered as a part of the VSAIDS collection from the United States Society of Wang Users (USSWU); earlier versions may already be on your system in the USERAID or USERAIDS libraries.

SELECTER consists of two entry screens - both GETPARMs - and a file or library name display. The OPTIONS screen accepts the name of the volume and library to be listed, the program option (list libraries on a volume or files in a library), and a screen title. The files or libraries are listed in columns over one or more screen pages. To select a library or file, tab to its name and press ENTER; press PF16 to exit without making a selection.

The selected file or library name is shown in the SELECT field of the RESULT screen, which can be extracted using a backwards reference in a procedure. In this example the ENTER RESULT statement in the procedure has a label (O1:) that is referred to in the line below (e.g. ASSIGN &SELFIL = (O1.SELECT)), resulting in &SELFIL containing the value of SELECT on the RESULT screen.

Variations

The MP procedure could be enhanced to include file copies, text searches, or any number of other features. The individual sections could be broken into separate procedures for ease of maintenance.

The file selection could be enhanced to include libraries through the SELECTOR utility through the use of an L (library) for the OPTION variable on the OPTIONS screen instead of F (file). Naturally, this would require additional code to accept and use the selected library name.

I hope you find this procedure of help in maintaining your code - and your sanity!

Figure 1: Procedure MP - Maintains Procedure Code

PROCEDURE MP - maintain procedures in a library * Library location literals DECLARE &SRCLIB STRING (8) INITIAL "PRODPROC" DECLARE &SRCVOL STRING (6) INITIAL "SYSTEM" DECLARE &WRKLIB STRING (8) INITIAL "WORKPROC" DECLARE &WRKVOL STRING (6) INITIAL "SYSTEM" * File location variables DECLARE &SELFIL STRING (8) DECLARE &SELLIB STRING (8) DECLARE &SELVOL STRING (6) * Misc. items DECLARE &KEY STRING (3) INITIAL "@ " DECLARE &MSG STRING (60) INITIAL "Please select option" DECLARE &SELMSG STRING (80) DECLARE &SPOOLIB STRING (8) EXTRACT &SPOOLIB = SPOOLIB *** Main menu ********************************************** MENU: PROMPT PFKEY = &KEY (2,2) CENTER BRIGHT LINE "PM: Procedure maintenance system";; CENTER "Please select option:";; CENTER "PF1 - Copy files to work library "; CENTER "PF4 - Edit files currently in work"; CENTER "PF5 - Perform source comparison "; CENTER "PF8 - Install edited procedure ";; CENTER "PF16 - Exit PM ";; CENTER BRIGHT &MSG(1,*); IF &LABEL (&KEY) CALL &KEY GOTO MENU *** Select and copy procedure file ************************* @1: ASSIGN &SELLIB = &SRCLIB ASSIGN &SELVOL = &SRCVOL ASSIGN &SELMSG = "Select file to be maintained:" CALL SELECTIT IF &SELFIL = " " END * Check to see if already in working library IF NOT EXISTS FILE &SELFIL IN &WRKLIB ON &WRKVOL GOTO C1 ASSIGN &MSG = "Procedure already in work library" END C1: RUN COPY IN @SYSTEM@ ENTER INPUT FILE = &SELFIL, LIBRARY = &SRCLIB, VOLUME = &SRCVOL ENTER OPTIONS ENTER OUTPUT FILE = &SELFIL, LIBRARY = &WRKLIB, VOLUME = &WRKVOL, RETAIN = 0 ENTER EOJ 16 @1X: END *** Select and edit procedure ******************************** @4: IF NOT EXISTS LIBRARY &WRKLIB ON &WRKVOL END ASSIGN &SELLIB = &WRKLIB ASSIGN &SELVOL = &WRKVOL ASSIGN &SELMSG = "Select work file to be edited:" CALL SELECTIT IF &SELFIL = " " END RUN EDITOR IN @SYSTEM@ ENTER INPUT LANGUAGE = PROCEDURE, FILE = &SELFIL, LIBRARY = &WRKLIB, VOLUME = &WRKVOL ENTER DEFAULTS TABS = "06 26 36 46 56 66 71", MODE = UPLOW, CASE = ANY ENTER OPTIONS SCRATCH = YES, REPLACE = YES, RENUMBER = YES, NUMBER = 100, INCR = 100 @4X: END *** Perform source file comparison ************************** @5: IF NOT EXISTS LIBRARY &WRKLIB ON &WRKVOL END ASSIGN &SELLIB = &WRKLIB ASSIGN &SELVOL = &WRKVOL ASSIGN &SELMSG = "Select work file to be compared with production:" CALL SELECTIT IF &SELFIL = " " END RUN COMPARE IN @SYSTEM@ ENTER INPUT FILE1 = &SELFIL, LIBRARY1 = &SRCLIB, VOLUME1 = &SRCVOL, FILE2 = &SELFIL, LIBRARY2 = &WRKLIB, VOLUME2 = &WRKVOL, MODE = SRCDIFF ENTER DIFFOPTS LANGUAGE = PROCEDURE, LIBRARY = &SPOOLIB, REPLACE = NO ENTER PRINT FILE = #DIFF ENTER EOJ 14 [ display file ] ENTER EOJ 16 @5X: END *** Copy work procedure into production library ************* @8: IF NOT EXISTS LIBRARY &WRKLIB ON &WRKVOL END ASSIGN &SELLIB = &WRKLIB ASSIGN &SELVOL = &WRKVOL ASSIGN &SELMSG = "Select file to be installed:" CALL SELECTIT IF &SELFIL = " " END * Scratch prior version of procedure PROTECT &SELFIL IN &SRCLIB ON &SRCVOL TO PERIOD = 0 SCRATCH &SELFIL IN &SRCLIB ON &SRCVOL C1: RUN COPY IN @SYSTEM@ ENTER INPUT FILE = &SELFIL, LIBRARY = &WRKLIB, VOLUME = &WRKVOL ENTER OPTIONS ENTER OUTPUT FILE = &SELFIL, LIBRARY = &SRCLIB, VOLUME = &SRCVOL, CLASS = Q ENTER EOJ 16 IF C1 = 0 GOTO C2 ASSIGN &MSG = "COPY failed! Procedure not installed!" END C2: SCRATCH &SELFIL IN &WRKLIB ON &WRKVOL @8X: END *** Procedure exit ****************************************** @16: RETURN *** General-purpose file selection routine ****************** SELECTIT: IF NOT EXISTS LIBRARY &SELLIB ON &SELVOL END ASSIGN &MSG = " " ASSIGN &SELFIL = " " RUN SELECTER IN VSAIDS ON SYSTEM CANCEL EXIT IS SELOUT ERROR EXIT IS SELOUT ENTER OPTIONS OPTION = F, [ select a file ] LIBRARY = &SELLIB, VOLUME = &SELVOL, HEADING1 = &SELMSG (1,40), HEADING2 = &SELMSG (41,40) O1: ENTER RESULT ASSIGN &SELFIL = (O1.SELECT) SELOUT: END