Out of Sight! Putting your programs in deep background
From "VS Workshop",  Access to Wang, January 1993
[ Prior Article ]     [ Return to the Catalog of articles ]     [ Next Article ]

Seems to me that background processing (a.k.a. non-interactive tasks) is still one of the most neglected aspects of VS program practice. Many night operations continue to be performed from foreground (actual workstation screens) even when it would be relatively easy to use the Non-Interactive Queue for these jobs.

As an attempt to rectify this situation, I offer a new tool to submit programs and procedures and some experience converting interactive programs to run properly in both background and foreground. Read on if you wish to take best advantage of the power of your VS - no matter what the hour of day.

The power of SUBMIT

The sample procedure (see SB, Figure 1) replaces the function of the SUBMIT screen of the Command Processor. Why use a procedure like this instead of the screen provided for this purpose? The primary reason is that the SUBMIT verb in Procedure language is far more powerful than any other method of launching non-interactive tasks because it allows the user's environment to be passed to the task. The Procedure SUBMIT verb can also launch programs - not just other procedures - and can pass information to these programs using arguments. To understand these important differences, let's discuss how background jobs work.

Submitting a job to background creates a new task that is not connected with your interactive task and has no knowledge of your access privileges or usage constants. This means that system defaults are used instead of your usage constants. For example, print files are always spooled to class A - even if you don't want them printed that way. Thus, procedures written for background use must customarily define all aspects of the user environment - just as you would in a start-up procedure for a user.

By capturing the environment of the submitting user, the Procedure SUBMIT verb allows the background job to work the same as if you had run it on a terminal screen. The printer defaults you use will be preserved, and print files will be sent to your spool library. Of course, this may not always be what you wish for the job, but it is always possible to explicitly set these values as before with SET statements.

The SUBMIT verb can also submit programs - not just procedures - and these programs can even be subroutines - programs that require information passed to them at run-time through arguments.

(Normally, jobs submitted to background must be procedures, not programs.)

The tool

As written, SB accepts the file name and location of a program or procedure file and submits it to the background queue for processing. Much of this procedure was derived from an earlier project in this column - a text string location utility called GUMSHOE which appeared in an earlier column (see "The Cheap Detective", Access to Wang; pp. 14 - 16). The SB procedure performs the same task but allows any program to be submitted.

The execution of SB is straightforward: it declares variables, extracts the user's JOBCLASS and JOBQUEUE defaults (usage constants for that user), and accepts the name of a program or procedure. After checking for the existance of the file, it is submitted using the job class, run status selected by the user. The return code from the SUBMIT verb is captured, indicating whether the task was accepted by the Procedure Queue; note that this is not related in any way to the success of the submitted job itself. After concluding the SUBMIT operation, the procedure returns to the user for another job to submit. A sample of this screen is shown in Figure 2.

Some who have worked with procedures for a while may notice the comment area at the top of the procedure does not have the usual asterisks in column one. Square brackets are also valid comment delimiters in procedure. A left square bracket is used to start the comment, and a right square bracket to turn it off; the comment may span lines, as shown in this example. Remember this when you are tempted to use the brackets for other purposes in a procedure, or it will not behave as you expect!

Converting interactive programs

For those of you who would like to take more advantage of background processing but are saddled with a large load of programs with parameters entered on the screen, this discussion may seem academic. The effort to convert a program to non-interactive operation may seem daunting, but I performed one program conversion in less than fifteen minutes. Here are the steps to do it yourself:

Add a call to the EXTRACT subroutine to check the task type. The keyword for this is TT and requires a one-character receiver. EXTRACT returns an F for foreground tasks, a B for background. (Versions of the Procedure Interpreter beginning with 7.20 of the operating system also include a built-in EXTRACT verb - TASKTYPE - that returns the same information.)

Once the task type is extracted, bypass OPEN and CLOSE statements to the screen if the type is B. For example, change this:

OPEN I-O CRT-FILE.

to something like this:

IF NOT BACKGROUND-TASK OPEN I-O CRT-FILE.

(BACKGROUND-TASK is a condition (a COBOL 88-level data item) I defined in the program that is true if the task type is equal to B.)

Perform similar logic branches at every other point where the screen might be accessed - such as READ, WRITE, REWRITE, and DISPLAY AND READ statements.

Determine the minimum parameters that need to be given to the program and create an ACCEPT statement to gather this information. Place the ACCEPT in a similar place in the program where data items would normally be received from the user's entry - such as in a branch from a DISPLAY AND READ statement based on the task type.

Write a procedure to run this program and pass the required information into the ACCEPT verbs. A sample:

PROCEDURE TEST R: RUN MYPROG IN DSBPROC ON SYSX ENTER ACCEPT VAR1 = VALUE1, VAR2 = VALUE2 RETURN

Note that this procedure is optional; if the program does not require any input it may be submitted directly using SB.

In many cases, this is all that must be done to convert a program for dual use. It still works as it did before; you have merely added the capability of altering its operation based on the task type.

A caution on variable names: variables used by ACCEPT should be eight characters or less, since they are converted to GETPARM data items for the ACCEPT GETPARM; longer names will be truncated. In many cases this means that you will need to create new variables with short names to capture the information, then move it into the "real" variables for processing.

Try these techniques and let me know how they work for you.

Figure 1: Procedure SB

PROCEDURE SB - submits procedures [ This procedure accepts the name of a program or procedure and submits it to background, along with the current user's environment (usage constants). From "VS Workshop" by Dennis Barnes, ACCESS TO WANG, January 1993. ] DECLARE &JOBFIL STRING (08) DECLARE &JOBLIB STRING (08) initial "DSBPROC " DECLARE &JOBVOL STRING (06) initial "SYSTEM" DECLARE &RC INTEGER DECLARE &KEY INTEGER DECLARE &MSG STRING (70) INITIAL "Hot to go!" DECLARE &JOBCLASS STRING (01) DECLARE &JOBQUEUE STRING (01) DECLARE &JOBQ STRING (04) EXTRACT &JOBCLASS = JOBCLASS, &JOBQUEUE = JOBQUEUE MENU: PROMPT PFKEY = &KEY CENTER BRIGHT LINE "Procedure SB - submits jobs to background";; CENTER "Job file = ", UPPER &JOBFIL; CENTER " library = ", UPPER &JOBLIB; CENTER " volume = ", UPPER &JOBVOL, " ";; CENTER LINE "SUBMIT options"; CENTER "Job Class =", UPPER &JOBCLASS, " ['A' through 'Z']"; CENTER "Run Status =", UPPER &JOBQUEUE, " [(R)UN, (H)OLD ]";; CENTER "Press (RETURN) to continue, ", "PF16 to exit";; CENTER BRIGHT &MSG (1,*); IF &KEY = 0 GOTO SUBMITIT IF &KEY = 16 RETURN GOTO MENU * Subroutines follow MENU: ASSIGN &JOBQ = "HOLD" IF &JOBQUEUE = "H" GOTO M1 ASSIGN &JOBQ = "RUN " M1: IF EXISTS FILE &JOBFIL IN &JOBLIB ON &JOBVOL GOTO M2 ASSIGN &MSG = "Job file not found" END M2: SUBMIT &JOBFIL IN &JOBLIB ON &JOBVOL AS &JOBFIL, GLOBALS = YES, CLASS = &JOBCLASS, STATUS = &JOBQ, ENVIRONMENT = YES ASSIGN &RC = M2 ASSIGN &MSG = "SUBMIT completed with return code " !! &RC END

Figure 2: Sample SB screen

Procedure SB - submits jobs to background Job file = MYJOB*** library = DSBPROC* volume = SYSX** SUBMIT options Job Class = B ['A' through 'Z'] Run Status = R [(R)UN, (H)OLD ] Press (RETURN) to continue, PF16 to exit SUBMIT completed with return code 0