Learn how to execute commands in batch using SBMJOB in this excerpt from the MC Press book Control Language Programming for IBM i.

Written by Jim Buck, Bryan Myers, and Dan Riehl

The SBMJOB (Submit Job) CL command lets you submit a batch job to a job queue. This command has many parameters, but in its simplest form it is expressed as follows:

SBMJOB CMD(CL-command)

Once you have submitted a batch job, you are allowed little or no interaction with the job. For example, a batch job normally does not display a screen on your workstation and wait for your input. You can, however, monitor the progress of your batch job using the WRKSBMJOB (Work with Submitted Jobs) command. Batch processing typically is used for long-running jobs that require no workstation input, such as those that produce printed reports or process many transactions. A batch job is entirely separate from the job that submitted it, with its own call stack and its own main storage requirements.

You usually submit a batch job from an interactive workstation. A main advantage of batch processing is that you can continue to do other work on your workstation without waiting for the batch job to finish. Unlike an interactive job, when a batch job is executing, it does not prevent you from using your workstation. Batch processing typically occurs at a lower priority than interactive processing, taking advantage of "lulls in the action" when the computer is not servicing higher-priority work, such as interactive workstation jobs. By running long processes in batch, you can improve overall system throughput and maintain faster interactive response times. Running long processes interactively at a high priority, on the other hand, drags down the interactive performance of the server and can affect every user on the system.

The CMD Parameter of the SBMJOB Command

Let's look at an example of the SBMJOB command:

SBMJOB CMD(DSPTAP DEV(TAP01) OUTPUT(*PRINT))

This example uses the DSPTAP (Display Tape) command to print a report of a tape's contents. Notice that the entire DSPTAP command, including all its parameters, is enclosed within the parentheses of the CMD parameter keyword. You may also have noticed that this command appears to break some of the rules you are used to for command parameters. At first glance, the value of the CMD parameter appears to be a character string, but it is not presented as a quoted string. Also, because the value is not a quoted string, you might think CL would interpret the values within the parentheses as a list of values instead of a single command.

The CMD parameter of the SBMJOB command is a special type of parameter, called a command string (*CMDSTR) parameter. The correct value for a *CMDSTR parameter is any valid CL command, but it cannot be enclosed in apostrophes ('). Because the system expects a CL command as the value for this parameter, it does not require, and will not allow, a quoted string. Instead, the system checks the command within the CMD parameter separately from the SBMJOB command to be sure the specified command is valid. When you key the SBMJOB command into a CL source member, you must be careful to match beginning and ending parentheses, both for command parameters within the CMD parameter value and to enclose the entire command string itself. This task can be particularly complex if you use keyword notation for the command within the CMD parameter, as we did in the example above. The CL compiler (as well as the editor's syntax-checking mechanisms) will reject unmatched parentheses.

A *CMDSTR type parameter also offers you "prompting within prompting" so that you can key the command string using the CL command prompter. When you type SBMJOB and then press F4=Prompt to invoke the CL prompter, you can position the cursor on the input line for the CMD parameter value and type a valid command. Then, if you press F4=Prompt again, the CL prompter is invoked a second time, this time for the CL command you typed on the input line. When you fill in the correct parameters for the prompted command, the correct command string is returned within the CMD parameter of the SBMJOB command.

What if you want to run a program rather than execute a CL command when you submit a batch job? That's easy to accomplish. On the SBMJOB command, simply specify the CALL command for the value of the CMD parameter:

SBMJOB CMD(CALL PGM(UPDCUST) +

PARM('UPDATE' 1357.92))

You might be wondering what a batch job's call stack looks like. Normally, when you use SBMJOB to submit a job for batch processing, the System i puts its own command request processing program, QCMD, at the top of the stack. After that, whatever programs are needed are included in the stack, following the customary logic used for program execution.

Other SBMJOB Parameters

The SBMJOB command offers many parameters to help you specify the environment in which you want a batch job to be executed, as well as the job's attributes. Under most circumstances, you will not need to specify these additional parameters, although you may find that using them can make your batch job easier to identify or help you customize the processing of a specific job. We look at only a few of these parameters in this text.

Job Definition Parameters for SBMJOB

The job definition parameters of the SBMJOB command help define the attributes of the submitted job and the job queue through which the job will be submitted. The JOB (Job name) parameter specifies the name of the job to be submitted; this parameter can help you to identify a batch job by name. You can type a simple job name in this parameter or use the default special value *JOBD to indicate that the name will come from the entry in the JOBD parameter.

SBMJOB uses the value of the JOBQ (Job queue) parameter to specify the name of the job queue to which the batch job will be submitted. You can type the qualified name of an existing job queue or accept the default special value *JOBD, indicating that you want the system to use the JOBQ associated with the job description in the JOBD parameter.

The JOBD (Job description) parameter identifies the job description that will be used for the batch job. This parameter's default value is *USRPRF (to use the job description specified in your user profile), but you can specify the qualified name of another job description, if necessary.

Library List Parameters for SBMJOB

The library list parameters of the SBMJOB command define the library list a batch job will use to find programs, files, or other objects.

The SYSLIBL (System library list) parameter determines which libraries will appear in the system portion of the library list for the batch job. You cannot specify individual library names for this parameter; you must use either the default special value *CURRENT or the other allowable special value, *SYSVAL. *CURRENT tells the system to use the submitting job's current system library list. *SYSVAL indicates that the batch job is to take its system library list from entries in system value QSYSLIBL.

The CURLIB (Current library) parameter lets you specify the current library for the batch job. You can specify the name of an existing library, leave the default value of *CURRENT (to use the submitting job's current library), or specify either of the additional special values: *USRPRF (use the current library indicated in your user profile) or *CRTDFT (use the system's default current library, QGPL, for newly created objects).

The INLLIBL (Initial library list) parameter lets you specify a list of libraries that will initially be in the user portion of the library list. This is the library list option that gives you the most flexibility in determining the library list. You can list up to 250 library names in this parameter, but you cannot duplicate a name that already appears in any other portion of the library list. You also can use any of the following special values: the default *CURRENT (use the submitting job's user library list), *JOBD (use the library list entries specified in the job description), *SYSVAL (use the library list entries specified in system value QUSRLIBL), or *NONE (the submitted job's user library list will be empty).

SBMJOB Output Parameters

You use the SBMJOB command's output parameters to determine which printer will be used for reports generated by the batch job. Usually, reports are not printed directly on the printer. Instead, they are stored on an output queue (an object used to hold reports until a printer has time to print them). Usually, the name of the output queue matches the name of the actual printer device.

The PRTDEV (Print device) parameter specifies the name of the default printer device for the batch job. You can supply the name of a printer device for this parameter or use any of the allowed special values: *CURRENT (the default) tells the batch job to use the same printer that the submitting job (usually your interactive job) is using; *USRPRF indicates that the batch job is to use the device named in your user profile; *SYSVAL uses the device named in system value QPRTDEV; and *JOBD specifies that the batch job should use the printer device named in the job description.

The OUTQ (Output queue) parameter specifies the qualified name of the output queue into which the batch job will place its reports. You can specify the qualified name of an actual output queue or use one of the following special values: *CURRENT (the default) uses the output queue associated with the submitting job; *USRPRF specifies that the batch job will use the output queue specified in your user profile; *DEV tells the batch job to use the output queue that is associated with the printer device named in the PRTDEV parameter; and *JOBD uses the output queue named in the job description.

Scheduling Parameters for SBMJOB

If you specify the value *YES for the SBMJOB command's HOLD (Hold on job queue) parameter, the batch job will be held on the job queue and will not be processed until someone (usually the system operator) releases it with the RLSJOB (Release Job) command. If you specify HOLD(*NO), the job will not be held on the job queue and will be processed when its turn comes up. You also can use the default HOLD(*JOBD) to indicate that the hold attribute of a job is to be taken from its job description.

The SCDDATE (Schedule date) and SCDTIME (Schedule time) parameters let you schedule a batch job to run on a specific date at a specific time. If you use the default values of SCDDATE(*CURRENT) and SCDTIME(*CURRENT), the job will be processed as soon as resources are available. In place of *CURRENT, you can specify a specific date and time for the job to run. For example, you could use the following command to submit a job to run on January 15, 2010, at 2:00 P.M.

SBMJOB CMD(CALL MYPGM) +

SCDDATE(011510) +

SCDTIME(140000)

Notice that the time is specified in 24-hour (military) format. It's also worth noting that the date must be in the same format as your job's date format. In the United States, this usually will be month/day/year format, but in other countries it may be different.

The SCDDATE parameter also allows some extra flexibility in scheduling. You can specify special values to run a job on a particular day (e.g., *SUN for Sunday, *MON for Monday, *TUE, *WED, *THU, *FRI, or *SAT). In addition, the special values *MONTHSTR and *MONTHEND let you specify that a job should run on the first or last day of the month, respectively. The system also considers the SCDTIME parameter value in determining the date on which to run the job. If, for example, it is Monday morning and you specify the following command, the job will run the same day.

SBMJOB CMD(CALL MYPGM) +

SCDDATE(*MON) +

SCDTIME(120100)

If, on the other hand, it is Monday evening and you enter this command, the job will run the following Monday because the scheduled time has passed.

The Self-Submitting Program

Submitting long-running jobs to batch enhances your computer's overall performance and should be encouraged wherever it is practical to do so. One way you can enforce the batch processing of a specific program is to have the program submit itself for batch processing. You can do this by taking advantage of one of the job's attributes, the job type, which indicates the environment in which the job is running: interactive or batch. It is possible to retrieve this information within a CL program using the RTVJOBA (Retrieve Job Attributes) command.

The following program illustrates a method of enforcing batch processing of a program.

MYPGM: PGM PARM(&mode &custnbr)

DCL &mode *CHAR 6

DCL &custnbr *DEC (15 5)

DCL &jobtype *CHAR 1

RTVJOBA TYPE(&jobtype)

IF (&jobtype = '1') DO

SBMJOB CMD(CALL PGM(MYPGM) +

PARM(&mode &custnbr))

RETURN

ENDDO

.

. /* (Continue processing) */

.

ENDPGM

This program, MYPGM, receives two parameters and declares a one-character variable called &jobtype, which will be used to store the job's environment (batch or interactive). The RTVJOBA command that follows the declaration of variables retrieves the job attribute TYPE. If the job is interactive, the TYPE attribute placed in the &jobtype variable will be a 1; if the job is running in batch, a 0 is placed in variable &jobtype.

Next, the program tests the value of variable &jobtype. If the variable has a value of '1', indicating that it is running interactively, the program executes a SBMJOB command. This command submits a job for batch processing that will CALL the same program and pass the same parameters; it then ends with a RETURN command. If, on the other hand, variable &jobtype has a value of '0', indicating the job already is running in batch, the program skips over the DO/ENDDO group and continues with its processing.

If you use this technique, the program will always do the bulk of its processing in batch, even if the user runs the program interactively with the CALL command:

CALL PGM(MYPGM) +

PARM('UPDATE' 1357.92)

Notice that even after the program executes the SBMJOB command, the program continues to execute. You could follow the SBMJOB command with a message to the user informing him or her that the job was submitted. Remember to follow the SBMJOB command with a RETURN command; otherwise, the program will continue to execute subsequent commands. The submitted job executes independently of the submitting (interactive) job.

This article is an excerpt from the MC Press book Control Language Programming for IBM i.