Admin Alert: A Skeleton Utility Program For Controlling IBM i Job Queues
October 8, 2014 Timothy Prickett Morgan
From an IBM i operations viewpoint, there are several scenarios where you need to automate job queue management. Situations where you may have to automatically change one or more parameters for a job waiting in job queue include:
To set up an automated job that collects information about and adjusts jobs waiting in queue, I created the WRKJOBQDB CL program. WRKJOBQDB is a skeleton program that collects data about all the running jobs in a specific job queue and then performs specific action on those jobs. In the sample program below, WRKJOBQDB collects job queue data and then changes all jobs with a specific job name to run at a lower priority than newer jobs (allowing newer jobs to run ahead of the changed jobs). WRKJOBQDB can easily be modified to perform other functions, serving as skeleton code for job queue management.
WRKJOBQDB has a very simple database and format. It gathers information about a specific job queue, creates a database containing information on jobs in that job queue, and performs actions against specific waiting jobs, if those jobs are found in queue.
Here’s the detailed code for the WRKJOBQPF database file and the WRKJOBQDB program.
The WRKJOBQPF Database
Job queue information is transferred from the printout that’s created when you run a Work with Job Queue (WRKJOBQ) command over your target job queue. Here’s the DDS and physical file layout for the WRKJOBQPF file used in this utility.
A R JOBQJOB A FILLER1 1A TEXT('FILLER FLD 1') A JOBNAME 10A TEXT('JOB NAME') A FILLER2 3A TEXT('FILLER FLD 2') A USERNAME 10A TEXT('USER NAME') A FILLER3 3A TEXT('FILLER FLD 3') A JOBNUM 6A TEXT('JOB NUMBER') A FILLER4 99A TEXT('Filler FLD 4') A K JOBNUM DESCEND
For the sample program, I created WRKJOBQPF in a library called RUNLIB.
This file is 132 characters long, the same report width as the QPRTSPLQ printer file output it originated from, as shown in the code. This file is the core engine your program uses to examine and modify jobs waiting in your target job queue.
WRKJOBQPF is keyed by each job’s job number in descending order (DESC). This is because we must process the oldest jobs in queue first, allowing us to change jobs in the order in which they were submitted. This prevents jobs from executing out of sequence as they are being changed.
Also notice that all of the WRKJOBQPF fields are alpha-numeric. This is because we will be dumping the entire contents of a QPRTSPLQ spooled file into the file, including the report headers, column headings, etc., making a database copy of a spooled file. The skeleton program sorts through the file records and only processes those job queue entries it’s interested in. It ignores irrelevant data in WRKJOBQPF, such as data from report headers.
Changing Your Waiting Jobs
The WRKJOBQDB CL program code shown below copies my target job queue contents (as passed into the program) into the WRKJOBQPF file, reads the file, and changes specific job queue entries to run at job priority six.
0001.00 PGM PARM(&JOBQNAME &JOBQLIB) 0002.00 DCLF FILE(RUNLIB/WRKJOBQPF) 0003.00 0004.00 DCL VAR(&JOBQLIB) TYPE(*CHAR) LEN(10) 0005.00 DCL VAR(&JOBQNAME) TYPE(*CHAR) LEN(10) 0006.00 0007.00 DLTF FILE(QTEMP/WRKJOBQPF) 0008.00 MONMSG MSGID(CPF0000) 0009.00 0010.00 0011.00 0012.00 CRTDUPOBJ OBJ(WRKJOBQPF) FROMLIB(RUNLIB) + 0013.00 OBJTYPE(*FILE) TOLIB(QTEMP) 0014.00 CHGPF FILE(QTEMP/WRKJOBQPF) MAXMBRS(*NOMAX) 0015.00 0016.00 OVRDBF FILE(WRKJOBQPF) TOFILE(QTEMP/WRKJOBQPF) + 0017.00 SECURE(*YES) 0018.00 0019.00 WRKJOBQ JOBQ(&JOBQLIB/&JOBQNAME) OUTPUT(*PRINT) /* + 0020.00 Retrieve job queue library information */ 0021.00 0022.00 CPYSPLF FILE(QPRTSPLQ) TOFILE(QTEMP/WRKJOBQPF) 0023.00 0024.00 LOOP: 0025.00 RCVF 0026.00 MONMSG MSGID(CPF0864) EXEC(GOTO CMDLBL(ENDLOOP)) 0027.00 0028.00 IF COND((&JOBNAME *EQ 'JOB1') *OR (&JOBNAME + 0029.00 *EQ 'JOB2')) THEN(DO) 0030.00 CHGJOB JOB(&JOBNUM/&USERNAME/ &JOBNAME) JOBPTY(6) 0031.00 MONMSG MSGID(CPA0701 CPF1321) 0032.00 ENDDO 0033.00 0034.00 GOTO CMDLBL(LOOP) 0035.00 0036.00 0037.00 ENDLOOP: DSPJOBLOG OUTPUT(*PRINT) 0038.00 0039.00 ENDPGM
Here’s what the code does.
Line 0001.00 declares that the program will be called with parameters equal to the jobq name (&JOBQNAME) and the jobq library (&JOBQLIB) that you want to examine. &JOBQNAME and &JOBQLIB are defined in lines 0004.00 and 0005.00.
Line 0002.00 defines the WRKJOBQPF file to the program.
Lines 0007.00 and 0008.00 look for instances of the WRKJOBQPF file in the QTEMP library and deletes that work file, if it’s present.
The Create Duplicate Object (CRTDUPOBJ) command in lines 0012.00 and 0013.00 creates a copy of the WRKJOBQPF file in the running job’s QTEMP library. This allows you to run multiple versions of the WRKJOBQDB program at the same time, since each copy will have its own copy of the database.
Line 0014.00 increases the number of records the WRKJOBQPF file can contain, in case there are more jobs in queue than available records in WRKJOBQPF.
Lines 0016.00 and 0017.00 override the WRKJOBQPF file to the new copy created in line 0014.00. Any references to WRKJOBQPF in this program will point to the copy in QTEMP.
The Work with Job Queue (WRKJOBQ) command in lines 0019.00 and 0020.00 creates the QPRTSPLQ spooled file containing information about the contents of the job queue.
Line 0022.00 copies the contents of the QPRTSPLQ spooled file created in lines 0019.00-0020.00 into the newly created WRKJOBQPF file in QTEMP.
Lines 0024.00 through 0034.00 create a loop that processes all the records in the QTEMP/WRKJOBQPF file. When the program gets to the end of the file (line 0026.00), it ends the program by branching to the ENDLOOP label in line 0037.00.
Lines 0028.00 through 32.00 examine each incoming record. If the job name is equal to ‘JOB1’ or ‘JOB2’, the Change Job (CHGJOB) command changes the job priority of the job to ‘6’. By default, most jobs enter the system at priority ‘5’. Changing a job to priority ‘6’ guarantees that any jobs entering the system before the JOB1 or JOB2 jobs are ready to start executing immediately. The new jobs will have priority and start running before the JOB1 and JOB2 jobs in queue are submitted for execution.
Also notice the Monitor Message (MONMSG) command on line 0031.00. MONMSG looks for the following messages when executing the CHGJOB command and tells WRKJOBQDB to ignore them.
This code is necessary in case the program is trying to change the priority on a job that has completed running and is no longer in the system.
Lines 0037.00 through 0039.00 print out the job log and end the program.
WRKJOBQDB is a simple program that allows you to look at job queue entries and make changes as needed. It’s a specialized tool that useful for known work flow situations, where one or more jobs is causing IBM i processing problems. Modify as needed.
Joe Hertvik is an IBM i subject matter expert (SME) and the owner of Hertvik Business Services, a content strategy organization servicing the computer industry. Email Joe for a free quote for any upcoming projects. He also runs a data center for two companies outside Chicago, featuring multiple IBM i ERP systems. Joe is a contributing editor for IT Jungle and has written the Admin Alert column since 2002. Check out his blog where he features practical information for tech users at joehertvik.com.