IBM i jobs, subsystems, and job logs: WRKACTJOB, WRKSBS, DSPJOBLOG, and ending a job safely

What it is

Every unit of work on IBM i — an interactive 5250 session, a batch job, a PASE process started over SSH, a TCP/IP server job — runs as a job inside a subsystem, a runtime environment with its own storage pools and job queues (QINTER for interactive, QBATCH for batch, QSYSWRK and QUSRWRK for many server jobs). WRKACTJOB lists all currently active jobs across subsystems with CPU and status information; WRKSBS lists the active subsystems themselves.

Each job accumulates a job log: the commands it ran and the messages it received or sent, useful for diagnosing why a CL command behaved unexpectedly. DSPJOBLOG shows the log of a job that is still active or whose log is pending (not yet written out); once written, the log is the spooled file QPJOBLOG of that job; DSPJOB or WRKJOB can display a job in active, job-queue, or output-queue status, and WRKUSRJOB lists all jobs — active, queued, or with pending output — submitted under a given user profile. The message logging level and text attributes on the job description control how much detail ends up in the log.

System-wide operator messages — server start/stop notices, device and communications errors, security warnings — land in the QSYSOPR message queue rather than in any one job's log. DSPMSG QSYSOPR displays it, which the system PASE utility (see the SSH/PASE article) makes visible to an SSH session run remotely.

Ending a job is not simply "kill it": ENDJOB takes an OPTION value. OPTION(*CNTRLD), the default, asks the job to end in a controlled manner within the DELAY time (default 30 seconds); if the job has registered a signal handler and expressed interest in asynchronous signals, the operating system generates the SIGTERM signal so the application can clean up, and only forces termination if the delay expires. OPTION(*IMMED) skips that cooperative phase and ends the job at once, with no SIGTERM guarantee — appropriate only for a job that is already hung or unresponsive.

Why it matters

An agent scripting job control needs to distinguish "I want this job to shut down cleanly" (*CNTRLD, with a delay long enough for any multi-threaded cleanup) from "this job is stuck and I need it gone" (*IMMED), and needs to know which message queue (a job's own log versus QSYSOPR) will actually contain the evidence of what went wrong.

How to apply

• Use WRKACTJOB or WRKUSRJOB user-id to locate a job before acting on it, rather than guessing a job number.
• Use the fully qualified name, ENDJOB JOB(number/user/name) OPTION(*CNTRLD) DELAY(nnn); a bare job name can match several jobs. Reserve *IMMED for jobs that do not respond to a controlled end. Ending other users' jobs normally requires *JOBCTL special authority.
• Check DSPMSG QSYSOPR for system-level failures (server down, device error) that will not appear in an application job's own log.
• If a job's log is thin, check its logging level in the job description before assuming nothing happened.

Pitfalls

• Ending a multi-threaded job with a delay too short for its threads to notice SIGTERM and clean up, which just becomes a slower *IMMED.
• Looking for a startup or server failure in a job log when it was actually posted to QSYSOPR.