Use logical files in the command input stream.

Batch job commands, such as Submit Database Jobs (SBMDBJOB) and Start Database Reader (STRDBRDR), allow programmers to submit batch jobs to job queues so that CL commands stored in database files can be run in the submitted jobs sequentially. These batch job commands are friends of system administrators who want jobs done in batch and/or automatically.

According to IBM's documents, the specified database file either must consist of single-field records and have an arrival sequence access path or must be a standard database source file. Actually, these batch job commands can also work with database files that have multiple fields or even logical files (LFs) with key fields and select/omit fields. This means more flexibility for how IBM i developers manage batch jobs. For example, you can set the execution sequence of CL commands to be executed according to a key field in the input LF, or you can decide whether to execute a specific CL command by setting or clearing an indicator field in the input-command file. Of course, to do that needs a little trick.

In this article, I will show you…

• How to drive a batch job via a logical file with key fields and select fields. This way, you can conveniently decide which commands are to be run in the batch job and the order the commands are to be run.
• How to troubleshoot failures when running a batch job using SBMDBJOB or STRDBRDR.

Driving a Batch Job via a Logical File with Key Fields and Select Fields

Physical or logical files having multiple fields and a keyed access path can be used as input-command files for SBMDBJOB and STRDBRDR, once they match the following criteria:

• Each record (even if composed with multiple fields) read from the input-command file is a valid CL command. According to the CL Programmer's Guide, CL commands have the following general syntax.

• For a record that represents a job input command, such as Batch Job (BCHJOB), Data (DATA), and End Input (ENDINP), the beginning two characters of the record must be two slashes (//).

Now I will use a practical example to show you the trick to implementing the tasks mentioned. Say that you store your CL commands to be run in a batch job in a physical file named BCHCMD, whose DDS source is the following:

In the sample input-command file, we have the following:

• The Command String (CMDSTR) field is used to store the CL command string to be run by the SBMDBJOB or STRDBRDR commands.
• Fields BEGCOMT and ENDCOMT default to /* and */, respectively. These two fields comment out all the other fields except CMDSTR in a record read from the input-command file. Using this little trick, you can add any character fields between BEGCOMT and ENDCOMT without affecting the validity of the CL command string represented by a record in the input-command file.
• The Sequence Number (CMDSEQ) field is used to sort CL commands in the input-command file.
• The Control Flag (CTLFLAG) field can be used as a select field in logical files built on the input-command file so that only the records with the expected value of the CTLFLAG field can be seen by the SBMDBJOB or STRDBRDR commands.

After compiling the input-command physical file, you can build logical files upon it to categorize CL commands stored in BCHCMD into different categories. Imagine that you have a bundle of commands that are related to a backup process and are expected to be scheduled to run nightly via the SBMDBJOB command. Your logical file for the backup process might look like the following.

Notes on bckupcmd.lf:

• Commands selected from this logical file are keyed by the Sequence Number (CMDSEQ) field.

• Records representing commands to be run in the backup process are expected to have their CTLFLAG filed set to 'B'. Since the job input commands, BCHJOB and ENDINP, are common to all tasks, records with CMDSEQ set to 0 or 9999 are also selected.

Now you can configure your nightly backup process by inserting commands into PF BCHCMD using SQL. After setting your configuration, select your logical file BCKUPCMD, and the result might look like Figure 1.

Figure 1: Your configuration is set! (Click image to enlarge.)

Run the SBMDBJOB or STRDBRDR command against logical file BCKUPCMD interactively like the following.

Checking your QSYSOPR message queue, you might get the following result.

Now you have implemented a configuration-based batch-job utility. You can enable or disable a specific item in your configuration by changing the value of its CTLFLAG. You can also insert a new item into the existing configuration at a specific position by setting the proper value for the CMDSEQ field. You can also change the order of items to be run by changing their CMDSEQ values.

Troubleshooting Failures when Running a Batch Job Using SBMDBJOB or STRDBRDR

The most direct way to determine which failures occurred in a submitted job is by reviewing its job log. After submitting a batch job, the SBMDBJOB comand will send a completion message containing the job ID of the submitted job to the current job's call message queue. You can refer to the job log of the submitted job by issuing command WRKJOB JOB(job-id) OPTION(*JOBLOG) if the submitted job is active or by issuing command WRKJOB JOB(job-id) OPTION(*SPLF) if the submitted job has already ended abnormally. The Work with Submitted Jobs (WRKSBMJOB) command can also be used to locate the submitted job if the job is submitted with SBMDBJOB DSPSBMJOB(*YES).

Unlike SBMDBJOB, the STRDBRDR command sends messages containing the job ID of the submitted job to the message queue specified by the MSGQ parameter of STRDBRDR, which defaults to QSYSOPR.

as/400, os/400, iseries, system i, i5/os, ibm i, power systems, 6.1, 7.1, V7,

Junlei Li is a programmer from Tianjin, China, with 10 years of experience in software design and programming. Junlei Li began programming under i5/OS (formerly known as AS/400, iSeries) in late 2005. He is familiar with most programming languages available on i5/OS—from special-purpose languages such as OPM/ILE RPG to CL to general-purpose languages such as C, C++, Java; from strong-typed languages to script languages such as QShell and REXX. One of his favorite programming languages on i5/OS is machine interface (MI) instructions, through which one can discover some of the internal behaviors of i5/OS and some of the highlights of i5/OS in terms of operating system design.

 

Junlei Li's Web site is http://i5toolkit.sourceforge.net/, where his open-source project i5/OS Programmer's Toolkit (https://sourceforge.net/projects/i5toolkit/) is documented.