Managing batch jobs without losing your mind

"The batch started but it is not doing anything." Nine times out of ten the job has not started at all: it is queued and waiting. Working out what is holding it back means looking at three things in order — the queue, the subsystem that serves it, and how many jobs that subsystem will accept at once.

Where it stopped

The first command is always the same:

WRKSBMJOB

It shows the jobs you submitted, with the status beside each. The two statuses that matter:

• JOBQ — the job is queued and has not started yet.
• ACTIVE — it is running; if it seems to be doing nothing, the problem is inside the program.

If the status is JOBQ, look at the queue:

WRKJOBQ JOBQ(QGPL/QBATCH)

Check the number of jobs and, above all, the queue status: RLS (released) or HLD (held). A held queue is the most trivial and most frequent cause: somebody put it on hold and never released it.

The subsystem that serves the queue

A queue on its own runs nothing: an active subsystem has to take it on. Check with:

WRKSBS

If QBATCH does not appear in the list, jobs in that queue will sit there forever, even if the queue is released. Start it with STRSBS SBSD(QSYS/QBATCH).

When the subsystem is there but jobs come out one at a time while you need three in parallel, the limit is MAXACT on the queue entry:

DSPSBSD SBSD(QSYS/QBATCH)

Option 6, Job queue entries: the Max Active column says how many jobs from that queue may run at once. 1 is the default on many installations, and it is often a deliberate choice — batches writing to the same files, run in parallel, block each other. Before raising it, it is worth knowing why it was 1.

Submitting so it can be found later

A well-written SBMJOB can be traced; a hurried one cannot. It is always worth giving a meaningful name:

SBMJOB CMD(CALL PGM(MYLIB/MONTHEND) PARM('202607'))
       JOB(MEND202607)
       JOBQ(QGPL/QBATCH)
       JOBD(MYLIB/JOBDBATCH)
       LOG(4 00 *SECLVL)

LOG(4 00 *SECLVL) deserves a word: it asks the system to record everything, second-level messages included. The job log gets heavier, but when the batch fails at three in the morning it is the only thing that lets you understand what happened without running it again.

The JOBD decides many things that cannot then be changed once the job is running: library list, target queue, output queue. A frequent mistake is submitting a batch that works interactively but not in batch: almost always it is the library list in the JOBD, which differs from the one in your session.

Scheduling a run

You do not need an external scheduler to start a batch at a set time:

SBMJOB CMD(CALL PGM(MYLIB/OVERNIGHT))
       JOB(OVERNIGHT)
       SCDDATE(*CURRENT)
       SCDTIME('22:30:00')

The job stays in the queue with status SCD until the time arrives. For recurring runs there is the built-in scheduler, WRKJOBSCDE, which handles repetition and keeps track of the last successful run.

When a batch has to be stopped

ENDJOB has two modes and the difference matters:

ENDJOB JOB(123456/USER/MONTHEND) OPTION(*CNTRLD) DELAY(60)

*CNTRLD warns the program and gives it the stated number of seconds to close down in an orderly way: a well-written RPG notices and closes its files. *IMMED cuts everything off on the spot. With *IMMED on a program that was writing, you can be left with half-finished updates — and if the file is not journalled, there is no way to know how far it got.

It is worth adding SPLFILE(*YES): it keeps the spooled files the job has already produced, which are often the only trace of what it had done before being stopped.

Three habits that save time

• A name for every batch, consistent and recognisable. Searching through twenty jobs all called QDFTJOBD is not a job.
• Separate queues for different work. Putting long reports in their own queue stops them blocking month-end runs.
• Check WRKJOBQ before resubmitting. A batch launched twice because "it would not start" is a far more serious problem than a batch that is stuck.

Which versions this works on

All the commands used here — SBMJOB, WRKSBMJOB, WRKJOBQ, WRKSBS, ENDJOB, DSPSBSD, ADDJOBSCDE, WRKJOBSCDE — are long-standing CL commands, present for many releases and not tied to a Technology Refresh. On a machine at 7.3, 7.4, 7.5 or 7.6 they all behave the same way.

What changes between releases is not the command but the parameters available: new options are added over time. If a parameter shown here does not appear when you press F4 on the command, it is almost always because your release predates the one that introduced it. Each command's page in the IBM documentation is release-specific, and you only need to change the version number in the address to compare them.

As an alternative to the commands, on more recent releases the same data can be read in SQL through IBM i Services (QSYS2.ACTIVE_JOB_INFO, QSYS2.JOB_QUEUE_INFO). That is useful when you need to filter or export: a 5250 screen cannot be queried, an SQL view can. The availability of each service depends on the release and the PTF level.

Sources

• IBM i CL commands — IBM Documentation
• ACTIVE_JOB_INFO table function — IBM Documentation 7.5
• IBM i Technology Updates (what is new per release and TR)