The Cheap Detective GUMSHOE tracks down SUBMIT and background processing
From "VS Workshop",  Access to Wang, March 1989
[ Prior Article ]     [ Return to the Catalog of articles ]     [ Next Article ]

In the August and September 1988 issues of Access to Wang, I covered general information on the use of the background queue. The advantages of using non-interactive processing include better system performance, better use of user time and workstation access. Unfortunately, it's often a programming chore to make best use of background processing.

Well, not entirely. Background procedures can be submitted using the SUBMIT function offered by the Procedure interpreter. Let's look further at some examples of this usage.

Review: submitting procedures

The most common method of submitting a job to the background queue is to use the Submit Procedure function of the Command Processor. To do this, the user presses HELP and PF'03, then enters the information related to the job. This information includes the name and location of the procedure to be submitted, whether a program dump will be generated after an abnormal job end and the type of dump produced, the time limit (in CPU time) for the job and the action to be taken when the job exceeds this limit, and the disposition (scratch or requeue) of the procedure queue entry after the job's conclusion. The user may also identify the job with an eight-character name, if desired.

Another method of submitting jobs is though the use of the SUBMIT ISWUSUB. This program subroutine allows a program to automate the submission, allowing control of all of the options described above. This subroutine is typically used with a high-level language (such as BASIC, COBOL, RPGII), but could also be used with Procedure.

The final method of job submission is through the SUBMIT verb in Procedure. The purpose of SUBMIT is to place a job in the procedure queue. All of the options described above apply, with these important additions:

1. Arguments: Information - such as dates, limits, file names, etc. - can be passed to the background procedure at run-time. This means that a generic procedure can be written without specific run information and this information can be passed by the calling procedure before each run.

2. Global variables: As with any other procedure running another procedure, variables can be defined as GLOBAL in the calling procedure with all data available in the receiving procedure.

3. User environment: Normally, background jobs assume system defaults for usage constants. This means that undesirable situations (such as print files spooled directly to the printers) are normal. While a SET statement can be inserted into the background procedure, a better way might be to use the ENVIRONMENT option to set the usage constants of the background job to those of the user submitting the procedure.

4. Status: Like the SUBMIT SVC and subroutine, a procedure can be submitted for later release. This job will remain on the Procedure Queue until released.

In addition to the above items, background procedures submitted from other procedures also can take advantage of the normal procedure advantages, such as backward references.

An example: GUMSHOE

Enough theory. I've devised a way of illustrating my point with a simple text search utility. I've tagged these utilities GUMSHOE - a term for a cheap detective - since they don't cost much and sneak around quietly, sniffing out clues. While the FINDTEXT utility (a ISWUAID) is used for this example, virtually any program capable of background execution could be handled the same.

The design goals were simple: find a way to conduct several searches in source libraries without tying up the user's workstation. To accomplish this, a foreground procedure ("front end") was constructed to accept the search string, library location, and background processing options (procedure class, run option). This procedure passed the information (via GLOBAL variables &TEXT, &SRCHLIB, and &SRCHVOL) to a standard background procedure, setting the background job's usage constants with the ENVIRONMENT clause in the process. Once initiated, the background procedure continued to completion; to the user, though, the front-end procedure returned immediately and allowed other use of the terminal during the search.

How it works

A few techniques used in the procedures require further explanation. As shown in Figure 1, the user's JOBCLASS and JOBQUEUE defaults have been extracted to become the defaults for GUMSHOEB's execution. Note that the Procedure STATUS clause requires the words 'RUN' or 'HOLD', not the single-character descriptions ('R' or 'H') offered by the EXTRACT verb. A simple solution is to set a default ('HOLD' in this case) and reset it if an exact condition (e.g. 'R') is met; in this way, erroneous entries will result in the comparatively harmless HOLD option, not RUN.

Figure 2 shows GUMSHOEB, the background procedure. This procedure is used as an example by the system, which creates a temporary procedure (see Figure 3) with the run-time information included. This clearly shows the effect of the ENVIRONMENT option, which results in the SET statements to set the defaults of the background job to those of the user. Procedures are generated by the system when the ENVIRONMENT option is used, when data is passed to the procedure with the USING.\.\. clause, or when a program file is specified instead of a procedure file.

The use of GLOBAL variables to pass information between the procedures was a discretionary choice on my part. A more straightforward approach is to use arguments (the USING.\.\. clause) instead. Remember when using GLOBALs that you cannot define them in the destination program, since that would eradicate their data values.

As a final touch, I have included a data entry screen (see Figure 4) and set up the print files to be prefaced by "FIND" for easier identification. The hidden GETPARM for the FINDTEXT print file (see the "ENTER PRINT" line, Figure 2) could also be used to enlarge the space allocated for the file when a large report is expected.

Other uses for SUBMIT

It should be clear that SUBMIT is a powerful component of Procedure. I hope that the example shown here gives you some ideas of how to run similar programs in background. To avoid disappointment, however, keep in mind the limitations of any background program:

1. Programs run in background must have NO reads or writes to the workstation. (As mentioned before in this column (VS Search Utilities; November, 1987; pp. 20 - 24), FINDTEXT suppresses the workstation screens if run as a background task.)

2. All information must be supplied to the program through GETPARMs or other program means. Workstation entry is not allowed.

3. There must be at least one open background slot on the system with a task initiator (scheduling) of the job class that the procedure was released under.

Happy hunting.

References:

• VS Procedure Language Reference
  #800-1205-05; January 1984
  Updated by the VS Procedure Language Reference Addendum (#800-1205-05.01).

• VS USERSUBS Reference
  #800-1315US-01; August 1982
  Soon to be replaced in function by the VSSUBS Reference (#715-0599; September 1988).

Figure 1: GUMSHOE - Foreground procedure

PROCEDURE GUMSHOE - foreground portion of GUMSHOEB DECLARE &TEXT GLOBAL STRING (66) DECLARE &SRCHLIB GLOBAL STRING (08) DECLARE &SRCHVOL GLOBAL STRING (06) DECLARE &RC INTEGER DECLARE &KEY INTEGER DECLARE &SYSVOL STRING (06) DECLARE &JOBCLASS STRING (01) DECLARE &JOBQUEUE STRING (01) DECLARE &JOBQ STRING (04) EXTRACT &SYSVOL = SYSVOL, &JOBCLASS = JOBCLASS, &JOBQUEUE = JOBQUEUE PROMPT PFKEY = &KEY CENTER BRIGHT LINE "GUMSHOE - front end for FINDTEXT";; CENTER "Text =", UPLOW LINE &TEXT;; CENTER "LIBRARY =", UPPER &SRCHLIB, " VOLUME =", UPPER &SRCHVOL;; CENTER LINE "SUBMIT options:";; CENTER "Job Class =", UPPER &JOBCLASS, " ['A' through 'Z']"; CENTER "Run Status =", UPPER &JOBQUEUE, " [(R)UN, (H)OLD ]";; CENTER "Press PF(16) to exit";; IF &KEY <> 0 GOTO S99 ASSIGN &JOBQ = "HOLD" IF &JOBQUEUE = "H" GOTO S01 ASSIGN &JOBQ = "RUN " S01: SUBMIT GUMSHOEB, GLOBALS = YES, CLASS = &JOBCLASS, STATUS = &JOBQ, ENVIRONMENT = YES ASSIGN &RC = S01 S99: RETURN CODE = &RC

Figure 2: GUMSHOEB - Background procedure

PROCEDURE GUMSHOEB - background portion of GUMSHOE DECLARE &SYSVOL STRING (06) EXTRACT &SYSVOL = SYSVOL S01: RUN FINDTEXT IN USERAIDS ON &SYSVOL ERROR EXIT IS S99 CANCEL EXIT IS S99 ENTER INPUT TEXT = &SEARCH, LIBRARY = &SRCHLIB, VOLUME = &SRCHVOL, SELECT = NO, SEARCH = NO, MODE = PRINT ENTER PRINT FILE = ##FIND ENTER EOJ 16 S99: RETURN

Figure 3: System-Generated Background Procedure

Procedure 07322661 created by @PROC@ 04.00.04 Set INLIB=' ', INVOL='VOL1 ', OUTLIB=' ', OUTVOL='VOL1 ', RUNLIB='USERAIDS', RUNVOL='VOL1 ', PROGLIB='DSBPROC ', PROGVOL='VOL2 ', SPOOLIB='#DSBPRT ', SPOOLVOL='VOL3 ', WORKVOL='VOL3 ', SPOOLSYS=' ', FILECLAS=' ' Set PRNTMODE='K', PRTCLASS='Z', PRTFCLAS='#', FORM#=0, PRINTER=0, LINES=58 Set JOBQUEUE='R', JOBCLASS='A', JOBLIMIT=0 Declare &SRCHVOL GLOBAL STRING (6) INITIAL 'VOLUME' Declare &SRCHLIB GLOBAL STRING (8) INITIAL 'SOURCE ' Declare &TEXT GLOBAL STRING (66) INITIAL 'TEST-STRING ' S1: Run GUMSHOEB in DSBPROC on VOL2 CANCEL EXIT is DP ERROR EXIT is DP DP: Destroy procedure

Figure 4: Screen Appearance of GUMSHOE

GUMSHOE - front end for FINDTEXT Text = ________________________________________________ Search LIBRARY = SOURCE__ VOLUME = VOL___ SUBMIT options: Job Class = A ['A' through 'Z'] Run Status = R [(R)UN, (H)OLD ] Press PF(16) to exit