What would happen if people kept adding requests to your in-basket faster than you could fulfill them? The pile would continue to get larger, even though you are removing requests. The same thing can happen on your AS/400 when the job queues get backed up. This could be caused by people submitting jobs faster than the system can keep up, an error or tape-mount message on a job already in the subsystem, or even a job queue that isn't being served by a subsystem.

If your in-basket is within sight, you will see that it is backing up, and, even if you can't do anything about it, you will know the situation. Job queues on the AS/400 are not as visible. Sure, you could use the Work with Job Queues (WRKJOBQ) command to check for backlogs, but you have better things to do with your time than watch the system to make sure batch jobs are being processed in a timely manner. With the job queue monitor utility presented in this article, you can let the system do this for you. You can set a maximum number of jobs you want in one or more job queues, and the monitor will send you a message letting you know if the maximum has been exceeded.

There are three main components to the monitor: one each to start and end monitoring a job queue, and the actual monitor itself. Commands STRJOBQMON (see 1) and ENDJOBQMON are the user interfaces to start and end job queue monitoring. The monitor job itself runs in batch in the QSYSWRK subsystem and handles all the job queues being monitored on the system.

There are three main components to the monitor: one each to start and end monitoring a job queue, and the actual monitor itself. Commands STRJOBQMON (see Figure 1) and ENDJOBQMON are the user interfaces to start and end job queue monitoring. The monitor job itself runs in batch in the QSYSWRK subsystem and handles all the job queues being monitored on the system.

The start and end components communicate with the monitor job through data queue JBQ001DQ. They add entries that begin with STR or END and contain the job queue and library affected. The start entries include the maximum number of jobs for the job queue and specify the message queue to receive the warning messages for that job queue.

JBQ001CL (see 2) is the command processing program for the STRJOBQMON command. If *USRPRF is specified on the MSGQ parameter, the value is changed to an actual message queue name and library-in case the monitor job is running under another user profile that may not be authorized to the one submitting the start request. The library names are converted from *LIBL to the actual library names for a similar reason-the monitor job may have a different library list, and we want the library list of the requesting job to be used to find the job queue.

JBQ001CL (see Figure 2) is the command processing program for the STRJOBQMON command. If *USRPRF is specified on the MSGQ parameter, the value is changed to an actual message queue name and library-in case the monitor job is running under another user profile that may not be authorized to the one submitting the start request. The library names are converted from *LIBL to the actual library names for a similar reason-the monitor job may have a different library list, and we want the library list of the requesting job to be used to find the job queue.

Once this editing is done, the start entry is added to the data queue. The allocation status of the data queue is checked to make sure only one monitor job is running. If the data queue is allocated, and therefore no monitor job is running, one is submitted. Job queue QSYSNOMAX is used to ensure the job will be active and will run in the QSYSWRK subsystem.

The ENDJOBQMON command and its command processing program, JBQ003CL, (see Figures 3 and 4), are subsets of STRJOBQMON and JBQ001CL. They only need to add an entry to data queue JBQ001DQ that contains the name of the job queue to end monitoring. The ENDJOBQMON command never ends the monitor job; it only stops monitoring a job queue.

The monitor program, JBQ002CL, (see 5) handles all job queues being monitored on the system. Two data queues are used: JBQ001DQ to receive the start and end monitoring requests, and JBQ002DQ to keep track of the job queues being monitored. The retrieve job queue information API QSPRJOBQ is used to retrieve the number of jobs in the job queue.

The monitor program, JBQ002CL, (see Figure 5) handles all job queues being monitored on the system. Two data queues are used: JBQ001DQ to receive the start and end monitoring requests, and JBQ002DQ to keep track of the job queues being monitored. The retrieve job queue information API QSPRJOBQ is used to retrieve the number of jobs in the job queue.

Data queue JBQ001DQ is allocated to prevent other monitors from being submitted and is checked for start and end requests. For a start request, data queue JBQ002DQ is searched to see if the job queue to be started is already being monitored. Duplicate entries replace the old. If it isn't a duplicate, the new entry is added. An end request simply removes the entry for that job queue from JBQ002DQ. For both request types, messages are sent so that the person executing the start or end request knows the monitor fulfilled the request.

When there are no more control entries in JBQ001DQ, the program reads each entry in JBQ002DQ to determine the job queues that should be checked. If the number of jobs in the job queue is more than was passed in the MAXJOBS parameter from the STRJOBQMON command, a message is sent.

When there are no more entries in JBQ002DQ, the control data queue (JBQ001DQ) is read again, waiting up to five minutes. This is so the start and end requests are acknowledged quickly, but, if there are no control entries, there will be a delay between messages warning about job queues exceeding the threshold.

Many of the techniques used for this utility can be used for other monitors. Data queues can be used to communicate between jobs and to track a large number of items. Other user interface commands could be added to show such things as a list of the items being monitored or an editable list of items that can be changed or ended.

This utility will save you time by making sure work is flowing through the system in a timely manner and by freeing you from having to make sure it does.

John Geurink is the IS manager at Federated Business Systems, an accounting firm in Springfield, Illinois. He holds a BS in Computer Science from the University of Iowa.

Martin Pluth is a senior technical editor at Midrange Computing. He can be reached by E-mail at This email address is being protected from spambots. You need JavaScript enabled to view it..

Job Queue Monitor Utility

Figure 1: The STRJOBQMON Command

 /*===============================================================*/ /* To compile: */ /* */ /* CRTCMD CMD(XXX/STRJOBQMON) PGM(XXX/JBQ001CL) + */ /* SRCFILE(XXX/QCMDSRC) */ /* */ /*===============================================================*/ CMD PROMPT('Start Job Queue Monitor') PARM KWD(JOBQ) TYPE(JOBQ) MIN(1) PROMPT('Job queue') JOBQ: QUAL TYPE(*NAME) QUAL TYPE(*NAME) DFT(*LIBL) SPCVAL((*LIBL)) + PROMPT('Library') PARM KWD(MAXJOBS) TYPE(*DEC) LEN(3) DFT(5) + REL(*GT 0) PROMPT('Maximum number of jobs') PARM KWD(MSGQ) TYPE(MSGQ) DFT(*USRPRF) + SNGVAL((*USRPRF)) PROMPT('Message queue') MSGQ: QUAL TYPE(*NAME) QUAL TYPE(*NAME) DFT(*LIBL) SPCVAL((*LIBL)) + PROMPT('Library') 
 
Job Queue Monitor Utility
 
Figure 2: The JBQ001CL Program
 
 /*===============================================================*/ /* To compile: */ /* */ /* CRTCLPGM PGM(XXX/JBQ001CL) SRCFILE(XXX/QCLSRC) */ /* */ /*===============================================================*/ JBQ001CL: PGM PARM(&JOBQFULL &MAXJOBS &MSGQFULL) DCL VAR(&JOBQFULL) TYPE(*CHAR) LEN(20) DCL VAR(&MAXJOBS) TYPE(*DEC) LEN(3 0) DCL VAR(&MSGQFULL) TYPE(*CHAR) LEN(20) DCL VAR(&MSGQ) TYPE(*CHAR) LEN(10) DCL VAR(&MSGQLIB) TYPE(*CHAR) LEN(10) DCL VAR(&MAXJOBSA) TYPE(*CHAR) LEN(3) DCL VAR(&DTA) TYPE(*CHAR) LEN(46) DCL VAR(&DTALEN) TYPE(*DEC) LEN(5 0) VALUE(46) DCL VAR(&RTNLIB) TYPE(*CHAR) LEN(10) DCL VAR(&MSGID) TYPE(*CHAR) LEN(7) DCL VAR(&MSGDTA) TYPE(*CHAR) LEN(132) MONMSG MSGID(CPF0000) EXEC(GOTO CMDLBL(ERROR)) CHKOBJ OBJ(JBQ001DQ) OBJTYPE(*DTAQ) MONMSG MSGID(CPF0000) EXEC(DO) CRTDTAQ DTAQ(QGPL/JBQ001DQ) MAXLEN(46) TEXT('Data + Queue for Job Queue Monitor') ENDDO /* Make sure that we have an actual library name, and also see if */ /* the objects exist */ IF COND(&MSGQFULL *EQ '*USRPRF') THEN(DO) RTVUSRPRF MSGQ(&MSGQ) MSGQLIB(&MSGQLIB) CHGVAR VAR(&MSGQFULL) VALUE(&MSGQ *CAT &MSGQLIB) ENDDO RTVOBJD OBJ(%SST(&MSGQFULL 11 10)/%SST(&MSGQFULL 1 + 10)) OBJTYPE(*MSGQ) RTNLIB(&RTNLIB) CHGVAR VAR(%SST(&MSGQFULL 11 10)) VALUE(&RTNLIB) RTVOBJD OBJ(%SST(&JOBQFULL 11 10)/%SST(&JOBQFULL 1 + 10)) OBJTYPE(*JOBQ) RTNLIB(&RTNLIB) CHGVAR VAR(%SST(&JOBQFULL 11 10)) VALUE(&RTNLIB) /* Send the data queue entry to start monitoring this job queue */ CHGVAR VAR(&MAXJOBSA) VALUE(&MAXJOBS) CHGVAR VAR(&DTA) VALUE('STR' *CAT &JOBQFULL *CAT + &MAXJOBSA *CAT &MSGQFULL) CALL PGM(QSNDDTAQ) PARM(JBQ001DQ 'QGPL' &DTALEN + &DTA) SNDPGMMSG MSG('Job queue monitor start request + submitted for job queue ' *CAT + %SST(&JOBQFULL 11 10) *TCAT '/' *CAT + %SST(&JOBQFULL 1 10) *TCAT '.') /* If the data queue can't be allocated, the server job is already */ /* running */ ALCOBJ OBJ((JBQ001DQ *DTAQ *EXCLRD)) WAIT(1) MONMSG MSGID(CPF0000) EXEC(GOTO CMDLBL(ENDPGM)) DLCOBJ OBJ((JBQ001DQ *DTAQ *EXCLRD)) SBMJOB CMD(CALL PGM(JBQ002CL)) JOB(JOBQMON) + JOBQ(QSYSNOMAX) DSPSBMJOB(*NO) MSGQ(*NONE) GOTO CMDLBL(ENDPGM) ERROR: RCVMSG MSGTYPE(*EXCP) MSGDTA(&MSGDTA) MSGID(&MSGID) SNDPGMMSG MSGID(&MSGID) MSGF(QCPFMSG) MSGDTA(&MSGDTA) + MSGTYPE(*ESCAPE) ENDPGM: ENDPGM 
 
Job Queue Monitor Utility
 
Figure 3: The ENDJOBQMON Command
 
 /*===============================================================*/ /* To compile: */ /* */ /* CRTCMD CMD(XXX/ENDJOBQMON) PGM(XXX/JBQ003CL) + */ /* SRCFILE(XXX/QCMDSRC) */ /* */ /*===============================================================*/ CMD PROMPT('End Job Queue Monitor') PARM KWD(JOBQ) TYPE(JOBQ) MIN(1) PROMPT('Job queue') JOBQ: QUAL TYPE(*NAME) QUAL TYPE(*NAME) DFT(*LIBL) SPCVAL((*LIBL)) + PROMPT('Library') 
 
Job Queue Monitor Utility
 
Figure 4: The JBQ003CL Program
 
 /*===============================================================*/ /* To compile: */ /* */ /* CRTCLPGM PGM(XXX/JBQ003CL) SRCFILE(XXX/QCLSRC) */ /* */ /*===============================================================*/ JBQ003CL: PGM PARM(&JOBQFULL) DCL VAR(&JOBQFULL) TYPE(*CHAR) LEN(20) DCL VAR(&DTA) TYPE(*CHAR) LEN(13) DCL VAR(&DTALEN) TYPE(*DEC) LEN(5 0) VALUE(13) DCL VAR(&RTNLIB) TYPE(*CHAR) LEN(10) DCL VAR(&MSGID) TYPE(*CHAR) LEN(7) DCL VAR(&MSGDTA) TYPE(*CHAR) LEN(132) MONMSG MSGID(CPF0000) EXEC(GOTO CMDLBL(ERROR)) /* If the data queue doesn't exist, the monitor job can't be active */ CHKOBJ OBJ(JBQ001DQ) OBJTYPE(*DTAQ) MONMSG MSGID(CPF0000) EXEC(GOTO CMDLBL(ENDPGM)) /* If the data queue can be allocated, the monitor job isn't */ /* running, so there is no point in sending the end entry. */ ALCOBJ OBJ((JBQ001DQ *DTAQ *EXCLRD)) WAIT(1) MONMSG MSGID(CPF0000) EXEC(GOTO CMDLBL(SNDEND)) DLCOBJ OBJ((JBQ001DQ *DTAQ *EXCLRD)) SNDPGMMSG MSGID(CPF9898) MSGF(QCPFMSG) MSGDTA('The job + queue monitor is not running') + MSGTYPE(*ESCAPE) /* Make sure that we have an actual library name, and also see if */ /* the job queue exists */ SNDEND: RTVOBJD OBJ(%SST(&JOBQFULL 11 10)/%SST(&JOBQFULL 1 + 10)) OBJTYPE(*JOBQ) RTNLIB(&RTNLIB) CHGVAR VAR(%SST(&JOBQFULL 11 10)) VALUE(&RTNLIB) /* Send the data queue entry to end monitoring this job queue */ CHGVAR VAR(&DTA) VALUE('END' *CAT &JOBQFULL) CALL PGM(QSNDDTAQ) PARM(JBQ001DQ 'QGPL' &DTALEN + &DTA) SNDPGMMSG MSG('Job queue monitor end request submitted + for job queue ' *CAT %SST(&JOBQFULL 11 + 10) *TCAT '/' *CAT %SST(&JOBQFULL 1 10) + *TCAT '.') GOTO CMDLBL(ENDPGM) ERROR: RCVMSG MSGTYPE(*EXCP) MSGDTA(&MSGDTA) MSGID(&MSGID) SNDPGMMSG MSGID(&MSGID) MSGF(QCPFMSG) MSGDTA(&MSGDTA) + MSGTYPE(*ESCAPE) ENDPGM: ENDPGM 
 
Job Queue Monitor Utility
 
Figure 5: The JBQ002CL Program
 
 /*===============================================================*/ /* To compile: */ /* */ /* CRTCLPGM PGM(XXX/JBQ002CL) SRCFILE(XXX/QCLSRC) */ /* */ /*===============================================================*/ JBQ002CL: PGM DCL VAR(&COUNTER) TYPE(*DEC) LEN(5 0) DCL VAR(&DTA001) TYPE(*CHAR) LEN(46) DCL VAR(&DTA002) TYPE(*CHAR) LEN(43) DCL VAR(&DTALEN001) TYPE(*DEC) LEN(5 0) DCL VAR(&DTALEN002) TYPE(*DEC) LEN(5 0) DCL VAR(&ERRORCODE) TYPE(*CHAR) LEN(16) DCL VAR(&JOBQFULL) TYPE(*CHAR) LEN(20) DCL VAR(&MAXJOBS) TYPE(*DEC) LEN(4 0) DCL VAR(&MAXJOBSA) TYPE(*CHAR) LEN(4) DCL VAR(&MSG) TYPE(*CHAR) LEN(132) DCL VAR(&NBRJOBQS) TYPE(*DEC) LEN(5 0) DCL VAR(&NBRJOBS) TYPE(*DEC) LEN(4 0) DCL VAR(&NBRJOBSA) TYPE(*CHAR) LEN(4) DCL VAR(&RECVERLEN) TYPE(*CHAR) LEN(4) DCL VAR(&RECVERVAR) TYPE(*CHAR) LEN(122) DCL VAR(&WAIT) TYPE(*DEC) LEN(5 0) VALUE(0) DCL VAR(&WAIT5) TYPE(*DEC) LEN(5 0) VALUE(300) DCL VAR(&WORK) TYPE(*CHAR) LEN(4) DCL VAR(&WORK2) TYPE(*DEC) LEN(5 0) /* If the data queue can't be allocated, another monitor is running */ ALCOBJ OBJ((JBQ001DQ *DTAQ *EXCLRD)) WAIT(1) MONMSG MSGID(CPF0000) EXEC(GOTO CMDLBL(ENDPGM)) CRTDTAQ DTAQ(QTEMP/JBQ002DQ) MAXLEN(43) SEQ(*FIFO) + TEXT('For tracking job queues being + monitored') /* Check for control entries coming in from the STRJOBQMON or */ /* ENDJOBQMON commands */ CHKCONTROL: CALL PGM(QRCVDTAQ) PARM(JBQ001DQ '*LIBL' + &DTALEN001 &DTA001 &WAIT) CHKSTREND: IF COND(&DTALEN001 *EQ 0) THEN(GOTO + CMDLBL(CHKJOBQS)) IF COND(%SST(&DTA001 1 3) *EQ 'STR') THEN(DO) /* Loop through the existing job queues being monitored, and add */ /* them back if they aren't the same as the new one. The new one */ /* will be added in at the end. */ CHGVAR VAR(&COUNTER) VALUE(&NBRJOBQS) RCVSTR: IF COND(&COUNTER *EQ 0) THEN(GOTO CMDLBL(ADDNEW)) CHGVAR VAR(&COUNTER) VALUE(&COUNTER - 1) CALL PGM(QRCVDTAQ) PARM(JBQ002DQ QTEMP &DTALEN002 + &DTA002 &WAIT) IF COND(%SST(&DTA001 4 20) *EQ %SST(&DTA002 1 + 20)) THEN(DO) CHGVAR VAR(&NBRJOBQS) VALUE(&NBRJOBQS - 1) GOTO CMDLBL(RCVSTR) ENDDO CALL PGM(QSNDDTAQ) PARM(JBQ002DQ QTEMP &DTALEN002 + &DTA002) GOTO CMDLBL(RCVSTR) ADDNEW: CHGVAR VAR(&DTA002) VALUE(%SST(&DTA001 4 43)) CHGVAR VAR(&DTALEN002) VALUE(43) CALL PGM(QSNDDTAQ) PARM(JBQ002DQ QTEMP &DTALEN002 + &DTA002) SNDPGMMSG MSGID(CPF9898) MSGF(QCPFMSG) MSGDTA('Job + queue monitor started for job queue ' + *CAT %SST(&DTA002 11 10) *TCAT '/' *CAT + %SST(&DTA002 1 10) *TCAT ', MAXJOBS=' + *CAT %SST(&DTA002 21 3)) + TOMSGQ(%SST(&DTA002 34 10)/%SST(&DTA002 + 24 10)) CHGVAR VAR(&NBRJOBQS) VALUE(&NBRJOBQS + 1) GOTO CMDLBL(CHKCONTROL) ENDDO IF COND(%SST(&DTA001 1 3) *EQ 'END') THEN(DO) /* Loop through the existing job queues being monitored, and add */ /* them back if they aren't the same as the one being ended. */ CHGVAR VAR(&COUNTER) VALUE(&NBRJOBQS) RCVEND: IF COND(&COUNTER *EQ 0) THEN(GOTO + CMDLBL(CHKCONTROL)) CHGVAR VAR(&COUNTER) VALUE(&COUNTER - 1) CALL PGM(QRCVDTAQ) PARM(JBQ002DQ QTEMP &DTALEN002 + &DTA002 &WAIT) IF COND(%SST(&DTA001 4 20) *EQ %SST(&DTA002 1 + 20)) THEN(DO) CHGVAR VAR(&NBRJOBQS) VALUE(&NBRJOBQS - 1) SNDPGMMSG MSGID(CPF9898) MSGF(QCPFMSG) MSGDTA('Job + queue monitor ended for job queue ' *CAT + %SST(&DTA002 11 10) *TCAT '/' *CAT + %SST(&DTA002 1 10)) TOMSGQ(%SST(&DTA002 + 34 10)/%SST(&DTA002 24 10)) ENDDO ELSE CMD(DO) CALL PGM(QSNDDTAQ) PARM(JBQ002DQ QTEMP &DTALEN002 + &DTA002) ENDDO GOTO CMDLBL(RCVEND) ENDDO GOTO CMDLBL(CHKCONTROL) /* Read through the "memory" data queue, checking to see if the */ /* threshold has been exceeded. */ CHKJOBQS: CHGVAR VAR(&COUNTER) VALUE(&NBRJOBQS) CHKCOUNTER: IF COND(&COUNTER *EQ 0) THEN(DO) CALL PGM(QRCVDTAQ) PARM(JBQ001DQ '*LIBL' + &DTALEN001 &DTA001 &WAIT5) GOTO CMDLBL(CHKSTREND) ENDDO CHGVAR VAR(&COUNTER) VALUE(&COUNTER - 1) CALL PGM(QRCVDTAQ) PARM(JBQ002DQ QTEMP &DTALEN002 + &DTA002 &WAIT) CALL PGM(QSNDDTAQ) PARM(JBQ002DQ QTEMP &DTALEN002 + &DTA002) CHGVAR VAR(&JOBQFULL) VALUE(&DTA002) CHGVAR VAR(&MAXJOBS) VALUE(%SST(&DTA002 21 3)) /* Build receiver variable and other parameters for the job queue */ /* information API */ CHGVAR VAR(&WORK2) VALUE(0) CHGVAR VAR(%BIN(&WORK)) VALUE(&WORK2) CHGVAR VAR(%SST(&RECVERVAR 1 4)) VALUE(&WORK) CHGVAR VAR(%SST(&RECVERVAR 5 4)) VALUE(&WORK) CHGVAR VAR(%SST(&RECVERVAR 49 4)) VALUE(&WORK) CHGVAR VAR(&WORK2) VALUE(16) CHGVAR VAR(%BIN(&WORK)) VALUE(&WORK2) CHGVAR VAR(&ERRORCODE) VALUE(&WORK) CHGVAR VAR(&WORK2) VALUE(122) CHGVAR VAR(%BIN(&WORK)) VALUE(&WORK2) CHGVAR VAR(&RECVERLEN) VALUE(&WORK) CALL PGM(QSPRJOBQ) PARM(&RECVERVAR &RECVERLEN + 'JOBQ0100' &JOBQFULL &ERRORCODE) CHGVAR VAR(&WORK) VALUE(%SST(&RECVERVAR 49 4)) CHGVAR VAR(&NBRJOBS) VALUE(%BIN(&WORK)) /* Send a message if there are more jobs in the queue than the max */ IF COND(&NBRJOBS *GT &MAXJOBS) THEN(DO) CHGVAR VAR(&NBRJOBSA) VALUE(&NBRJOBS) CHGVAR VAR(&MAXJOBSA) VALUE(&MAXJOBS) CHGVAR VAR(&MSG) VALUE('Job queue ' *CAT + %SST(&JOBQFULL 11 10) *TCAT '/' *CAT + %SST(&JOBQFULL 1 10) *TCAT ' has ' *CAT + &NBRJOBSA *TCAT ' jobs queued, and the + threshold is set at ' *CAT &MAXJOBSA + *TCAT '.') SNDBRKMSG MSG(&MSG) TOMSGQ(%SST(&DTA002 34 + 10)/%SST(&DTA002 24 10)) /* Break messages can only be sent to workstation message queues */ MONMSG MSGID(CPF0000) EXEC(DO) SNDMSG MSG(&MSG) TOMSGQ(%SST(&DTA002 34 + 10)/%SST(&DTA002 24 10)) ENDDO ENDDO GOTO CMDLBL(CHKCOUNTER) ENDPGM: ENDPGM 

Also Read

Practical Middleware: Starting the Journey

IBM i 7.2: The Carrot Versus the Stick

A Renaissance for Domino