The WORKBNCH Procedure An illustration of the FIND subroutine
From "VS Procedure",  Access 86, December 1986
[ Prior Article ]     [ Return to the Catalog of articles ]     [ Next Article ]

Regular readers of this column might guess what a rabid menu addict I am. Perhaps the regular intrusion of command-level applications on my personal computer sharpens my appreciation for a good menu-driven system! At any rate, here's a utility that could be used as a menu or as a specialized tool.

The design goals for WORKBNCH were threefold: first, to create a menu-driven utility similar in concept to a host of commercial "workbench" products; second, to explore the use of the FIND subroutine in the USERSUBS collection; finally, to make further use of the extensions offered by the Wang Procedure interpreter, release 3.00.10.

What WORKBNCH does

WORKBNCH (Figure 1) allows the user to enter a file, library, and volume MASK (see explanation below), then displays a list of up to ten files that match this description. The user may then position the cursor to a file name and press a PF key to perform a process using that file. While COPY, DISPLAY, EDITOR, and the space-releasing variation of UPDATFDR are included here, they are only a few examples of what could be done using this selection process.

If more than ten files meet the specified criteria, a press of the RETURN key will bring up the next ten files. New file, library, or volume criteria can be entered by pressing PF 16.

The FIND subroutine

The heart of WORKBNCH lies in the FIND subroutine, a Wang USERSUB. FIND allows the user to locate files, libraries, or volumes on a system by specifying full or partial names.

FIND and its USERAID cousin FILEDISP use a masking nomenclature that requires practice to appreciate. Basically, the user may enter any known part of the file, library, or volume name to be found, using a '?' to indicate areas of any (or no) number of characters of any type, and an asterisk ('*') to indicate missing characters on a one-to-one basis. Here are a few examples:

1. To locate all files that begin with 'FD' in a particular library, you would enter the file name as 'FD?' along with the library and volume names.

2. To select eight-character files that begin with 'FD', you would enter 'FD******'.

3. To locate files that begin with 'FD' and end with '1', you would enter 'FD?1'.

4. To locate files that have 'FD' in any portion, you would enter '?FD?'.

While these examples illustrate a search for a file name, the same may be done with library and volume names, or any combination. In larger VS systems, this is often the only way to find anything!)

Since similar masking conventions are used in the FILEDISP utility (among others), the neophyte is advised to start by practicing there. FILEDISP accepts your file parameters and returns a screen listing of the files (or libraries or volumes) meeting your requirements. (Caution: you'll soon find that FILEDISP will become a regular part of your VS tool box, supplanting more robust use of user memory!)

The information returned by FIND can be either a list in a buffer area (a variable, in other words) or added to a work file. This procedure uses FIND by returning up to ten file names at a time - a design limit. (Ambitious users will want to push this much farther; more on that later.)

How WORKBNCH works

After the variables to be used are declared, step S01 displays a screen PROMPTing the user for the file, library, and volume masks to be used. These elements are passed to FIND via a call to the GETFILE paragraph, which returns up to ten file names. These file names are stored as ten occurances of valid VOLUME/LIBRARY/FILE combinations in &FRCVR, a 220-character receiver. Note the use of the &FSTART variable; this signals to FIND the numeric point where you wish to begin the list. The initial value of &FSTART is set to '-9' so it will become '1' the first time through, after the file count increment - &FCOUNT - is added to it. Subsequent calls to GETFILE will place the starting position ten files further along each time.

If at least one file is found to meet the mask's specifications, the ten-file list is displayed through the PROMPT in step S03; otherwise, control returns to S01. S03 displays text descriptions of the functions available, along with translations of the ten-file array in the more meaningful file/library/volume form. Tab stops are placed at every file, and the numeric variables &ROW and &COL have been added to accept the cursor coordinates when a key is pressed.

When a key is pressed, the value of that key is examined. If PF 16 is pressed, control passes to the first screen for another set of file, library and volume specifications; if the RETURN key is pressed, the GETFILE routine is called again to produce the next ten files. If no more files are available, control again reverts to S00. All other key responses are examined for validity using the &LABEL function.

Step S04 determines the coordinates of the tab stop when the key was pressed and, thus, the location of the file name in &FRCVR. This is accomplished by subtracting the number of prior rows before the file displays begin from the row number returned, then multiplying this by 22, the length of each element and subtracting 21. The resulting variable - &P - contains the starting location of that file in &FRCVR. For example, the first file would start at position 1, the second at position 23, and so forth. CAUTION: the number of rows to be subtracted will change if any changes are made to the amount of text displayed on the screen, so be careful in making changes to the screen contents.

With the starting position identified, the values of the file, library, and volume are loaded into new variables for programming convenience. Now the process selected by the user may begin. As shown in last month's column ("Making a Procedure Menu"), these processes are enclosed in subroutines and CALLed from step S06. After completion, control returns to the file display screen (step S03) and another file or process may be selected.

Variations

The use of the CALL and END statements, along with the assignment of "soft" step labels for the subroutines, should make this procedure easy to customize. You may simply enter any new steps as subroutines and add appropriate text to explain them. For example, to add a step to call EZPATCH and assign it to PF 13, create a step called '@13' to run EZPATCH, then add descriptive text to the screen in S03. Be sure to pay attention to any row number shifts caused by addition of lines, as this must be accounted for in step S04 or the location calculation will not be correct.

A more complicated modification would be to display more information on the selected files. Information on the block allocation and usage, create date, owner ID, and protection class might be among the elements added. This could be accomplished by adding logic to call READFDR within the GETFILE paragraph, then looping ten times to process all valid files. Naturally, the display logic in step S03 would become somewhat more complicated.

Advanced "techies" will certainly not be satisfied with the ten file limit. That number can be boosted to twenty by simply increasing the size of &FRCVR to 440 and typing in the file display delimiters in S03 - a dreary job. Displays in excess of 23 file names require the use of two receiving variables, since they would require that the storage variable be greater than 512 characters, Procedure's current limit; note that this would also require at least two calls to FIND. Again, row number shift will have to be accounted for in S04.

Figure 1: The WORKBNCH Procedure

PROCEDURE WORKBNCH - an illustration of FIND DECLARE &FFIL STRING (08) DECLARE &FLIB STRING (08) DECLARE &FVOL STRING (06) DECLARE &FSTART INTEGER DECLARE &FCOUNT INTEGER INITIAL 10 DECLARE &FRCVR STRING (220) DECLARE &FFILES INTEGER DECLARE &FTYPE STRING (01) INITIAL "A" * Variables used by READFDR DECLARE &FDRMODE INTEGER DECLARE &FDRTYPE STRING (01) * Variables used by UPDATFDR DECLARE &DUMMY INTEGER * Screen control variables DECLARE &KEY, &ROW, &COL INTEGER DECLARE &RUNSTEP STRING (03) INITIAL "@ " * Program control variables DECLARE &P, &RC INTEGER DECLARE &INFIL STRING (08) DECLARE &INLIB STRING (08) DECLARE &INVOL STRING (06) S00: ASSIGN &FSTART = -9 [ Start-up value; yields '1' ] ASSIGN &FRCVR = " " [ Clear file name holder ] S01: PROMPT PFKEY = &RUNSTEP (2,2) CENTER BRIGHT LINE "Procedure WRKBNCH";; CENTER "Enter the compare strings to search for, using a '*' ", "to indicate"; CENTER "a single missing character and a '?' to indicate ", "any combination"; CENTER "of missing characters.";; CENTER "FILE =", UPPER &FFIL; CENTER "LIBRARY =", UPPER &FLIB; CENTER "VOLUME =", UPPER &FVOL, " ";; CENTER "Press PF(16) to exit program";; IF &RUNSTEP(2,2) = "16" GOTO S99 S02: CALL GETFILE IF &FRCVR = " " GOTO S00 S03: PROMPT PFKEY = &RUNSTEP (2,2), CURROW = &ROW, CURCOL = &COL CENTER BRIGHT LINE "Procedure WORKBNCH";; CENTER " TAB to the file desired and press a PFKey to per- "; CENTER " form any of the following tasks: "; CENTER " ------------------------------------------------- "; CENTER " PF(01) COPY PF(03) EDIT "; CENTER " PF(02) DISPLAY PF(04) Release space ";;; CENTER TAB " ", &FRCVR(015,8), " ", &FRCVR(007,8), " ", &FRCVR(001,6), " ", TAB " ", &FRCVR(125,8), " ", &FRCVR(117,8), " ", &FRCVR(111,6), " "; CENTER TAB " ", &FRCVR(037,8), " ", &FRCVR(029,8), " ", &FRCVR(023,6), " ", TAB " ", &FRCVR(147,8), " ", &FRCVR(139,8), " ", &FRCVR(133,6), " "; CENTER TAB " ", &FRCVR(059,8), " ", &FRCVR(051,8), " ", &FRCVR(045,6), " ", TAB " ", &FRCVR(169,8), " ", &FRCVR(161,8), " ", &FRCVR(155,6), " "; CENTER TAB " ", &FRCVR(081,8), " ", &FRCVR(073,8), " ", &FRCVR(067,6), " ", TAB " ", &FRCVR(191,8), " ", &FRCVR(183,8), " ", &FRCVR(177,6), " "; CENTER TAB " ", &FRCVR(103,8), " ", &FRCVR(095,8), " ", &FRCVR(089,6), " ", TAB " ", &FRCVR(213,8), " ", &FRCVR(205,8), " ", &FRCVR(199,6), " ";; CENTER BRIGHT "Press (RETURN) to get the next 10 files"; CENTER BRIGHT "Press PF(16) to select new files " IF &RUNSTEP (2,2) = "16" GOTO S00 IF &RUNSTEP (2,2) = "0 " GOTO S02 IF NOT &LABEL(&RUNSTEP) GOTO S03 S04: ASSIGN &P = ((&ROW - 12) * 22) -21 IF &COL > 40 ASSIGN &P = &P + 110 S05: ASSIGN &INVOL = &FRCVR(&P,6) ASSIGN &INLIB = &FRCVR(&P+6,8) ASSIGN &INFIL = &FRCVR(&P+14,8) S06: IF &INFIL <> " " CALL &RUNSTEP GOTO S03 S99: RETURN ******************************************************************* * Subroutines GETFILE: ASSIGN &FCOUNT = 10 ASSIGN &FSTART = &FSTART + &FCOUNT ASSIGN &FRCVR = " " RUN FIND IN VSSUBS USING &FFIL, &FLIB, &FVOL, &FSTART, &FCOUNT, &FRCVR, &FFILES, &FTYPE END * Run COPY with defaults set @1: RUN COPY ERROR EXIT IS C CANCEL EXIT IS C DISPLAY INPUT FILE = &INFIL, LIBRARY = &INLIB, VOLUME = &INVOL DISPLAY OUTPUT FILE = &INFIL, LIBRARY = &INLIB, VOLUME = &INVOL, RELEASE = YES ENTER EOJ 16 C: END * Run DISPLAY after checking file organization; use PRINT option if * CONSECUTIVE or PRINT file type @2: RUN READFDR IN VSSUBS USING &INFIL, &INLIB, &INVOL, &FDRMODE, "FT", &FDRTYPE, &RC IF &FDRTYPE = "C" GOTO @2A IF &FDRTYPE = "P" GOTO @2A RUN DISPLAY ERROR EXIT IS C CANCEL EXIT IS C ENTER INPUT FILE = &INFIL, LIBRARY = &INLIB, VOLUME = &INVOL ENTER EOJ 16 C: END @2A: RUN DISPLAY ERROR EXIT IS C CANCEL EXIT IS C ENTER INPUT FILE = &INFIL, LIBRARY = &INLIB, VOLUME = &INVOL, ACCESS = PRINT C: END * Run EDITOR with PROCEDURE defaults @3: RUN EDITOR ERROR EXIT IS C CANCEL EXIT IS C DISPLAY INPUT FILE = &INFIL, LIBRARY = &INLIB, VOLUME = &INVOL, PLIBRARY = " ", PVOLUME = " " ENTER DEFAULTS TABS = "06 26 36 46 56 66 71" ENTER OPTIONS REPLACE = YES, RENUMBER = YES C: END * Release unused file space with UPDATFDR @4: RUN UPDATFDR IN VSSUBS USING "F", &INFIL, &INLIB, &INVOL, "RS", &DUMMY, &RC END