Watches and Job Log Messages
Watches make life easier if you need to track down an intermittent error or a difficult-to-find issue in a prestart job
Trying to track down a message sent to the job log of a prestart job is much like looking for a needle in a haystack; on busy systems, there could be hundreds of jobs to look through. If the error was relatively minor, the jobs may end and not generate a job log.
Watches make life easier if you need to track down an intermittent error or a difficult-to-find issue in a prestart job.
Watches allow you to take action, immediately, when a message has been sent to a message queue, the history log, or, what this blog is interested in: a job log. Watches are similar to an exit point—the Message Handing component in the operating system checks for the watched message every time a message is sent. If the message matches the watch criteria, the watch exit program is invoked, out of band, in a QSCWCHPS prestart job that runs in QUSRWRK (the irony that my watch program to debug a prestart job runs in a prestart job did not slip past me). Your program gets control and receives parameters which include the job where the message occurred along with information about that message. If you’re trying to track down a tricky, intermittent problem, your exit program may do things such as display the job log to *PRINT, dump the job call stack, hold the job so it can be examined manually, or whatever actions needed for problem resolution.
If you want to take immediate action, you could send a text message using the SNDDST command, or send an email message with the SNDSMPTEMM command; the job name in which the message occurred could be included in the message and the recipient has the information needed to look at that job.
You do have to write a watch exit program; the IBM Rochester Support Center team has an article, STRWCH – Watch Exit Programs Explained with CL Example, which helps you get started with the watch exit program. This example involves getting job log information with CL.
I do need to mention the IBM i Service, QSYS2.JOBLOG_INFO(). While you could use this service to retrieve messages from a job log, under the covers, this service uses the List Job Log Messages (QMHLJOBL) API; thus, you’re reading through the job log. While this is a useful service, it isn’t the best option if you want to capture a message that could happen in an arbitrary set of jobs. Watches are very efficient—much more efficient than using APIs to search thru the contents of a job log, and they return information to you in near-real-time, as the messages happen, rather than after the fact. Watches also support generic job names, which makes it easy to watch many jobs for a specific error.
I’ve written about watches before in Watches are Wonderful! and Automate Monitoring with Watches.
Remember too, that job logs for prestart jobs are pending by default. If you think a job should have generated a job log due to an error condition, use the WRKJOBLOG command to find jobs with pending job logs.