Guru: Single Threading A Program Execution
June 15, 2026 Chris Ringer
A paceline in cycling is a formation where all the cyclists ride in a single file line and the lead bike is pulling the group along as everyone else is drafting behind. Eventually the lead bike will drift to the side and to the back of the line, and the next bike will take the lead for the group.
If a spirited cyclist leaves the paceline and goes alone, all the aerodynamic benefits of drafting are lost.
Likewise, at my organization, we have a CL job that is submitted hourly throughout the day every day. Normally the submitted job completes before the next job submits. We never want two of these jobs running simultaneously (“leaving the paceline”). In small “mom and pop” shops, each job could be submitted to a new single threaded JOBQ or the existing JOBQ could be made single threaded. But in a larger company, perhaps beholden to SOX, JOBQ changes could require extensive regression testing.
Object Locking
Another method to prevent two CL programs from running simultaneously is to use object locking via the ALCOBJ command with an *EXCL (exclusive) lock. Only one job on the system may hold an exclusive lock on a given object.
Years ago, my first impulse was to just lock the *PGM object itself but this simply doesn’t work. The IBM documentation explicitly states “When ALCOBJ is executed to get an EXCL lock on a program (*PGM), only the program object description is locked. The program code is not locked exclusively. Therefore, the program may still be run by another user.” So my preference is to create a permanent data area object (CRTDTAARA) with the same name as the CL program and then lock that data area. Run this command to create a data area:
CRTDTAARA DTAARA(TESTLIB1/OEM001) TYPE(*CHAR) LEN(100)
VALUE('OEM001 data area for ALCOBJ *EXCL locks')
TEXT('OEM001 ALCOBJ *EXCL data area') AUT(*USE)
The Wait Is Finally Over
And let’s walk through a sample CL program to demonstrate this locking technique.
01 OEM001: PGM
02 DCL var(&wkGotLock) Type(*Lgl ) Len(1) Value('0')
03 DCL var(&wkDlySecs) Type(*Dec ) Len(5 0) Value(2)
04 DCL var(&wkTotSecs) Type(*Dec ) Len(5 0) Value(0)
05 DCL var(&wkMaxSecs) Type(*Dec ) Len(5 0) Value(30)
06 DoUntil Cond(&wkGotLock)
07 ALCOBJ OBJ((TESTLIB1/OEM001 *DTAARA *EXCL)) WAIT(0) SCOPE(*JOB)
08 MONMSG MSGID(CPF1002) EXEC(Do) /* Cannot allocate object &1. */
09 DLYJOB DLY(&wkDlySecs)
10 ChgVar Var(&wkTotSecs) Value(&wkTotSecs + &wkDlySecs)
11 If Cond(&wkTotSecs *GE &wkMaxSecs) Then(Do)
12 SNDPGMMSG MSG('WARNING: Could not get object Lock, exiting!')
13 Return
14 EndDo
15 Iterate
16 EndDo
17 ChgVar Var(&wkGotLock) Value('1')
18 EndDo
19 ALCOBJ OBJ((TESTLIB1/OEM001 *DTAARA *SHRRD)) WAIT(0) SCOPE(*JOB)
20 DLCOBJ OBJ((TESTLIB1/OEM001 *DTAARA *EXCL)) SCOPE(*JOB)
21 /* do business logic here ... */
22 DLCOBJ OBJ((TESTLIB1/OEM001 *DTAARA *SHRRD)) SCOPE(*JOB)
23 EndPgm
Let’s walk through the code.
Line 01: The start of the CL program.
Line 02: A Boolean variable to indicate if we got the exclusive object lock.
Lines 03 – 05: Variables for the delay seconds when cannot lock the object, total seconds delayed so far and maximum seconds to delay.
Line 06: A DO Loop when attempting to lock the data area.
Line 07: Attempt to get exclusive lock on the data area and try for 0 seconds (no delay).
Line 08: Message ID CPF1002 is thrown when “Cannot allocate object “.
Line 09: Delay the job two seconds. As an alternative you may wish to delay for a fraction of a second with usleep.
Line 10: Calculate the total delayed seconds so far.
Line 11: If the maximum wait seconds is reached, will exit the program (or whatever you want to do).
Line 12: Write a helpful message to the job log.
Line 13: Exit the program.
Line 14: End of IF statement.
Line 15: Loop again.
Line 16: End of MONMSG.
Line 17: Got the exclusive lock. Will cause DO loop to exit.
Line 18: End of the DO loop.
Line 19: Get a second lock on the same object, this time a “shared read” (source: Ernie Malaga circa early 1990s). This will allow other jobs (and users) to view the object attributes and the data area contents. Retaining an exclusive lock any longer than necessary feels a bit harsh to me. Other jobs (and users) are unable to see any of the object attributes when an exclusive lock is held (see figure below).
Line 20: Release the *EXCL lock (but still hold the *SHRRD lock). For a batch job, this statement is not necessary since all locks are automatically released when the job ends.
If you set a debug breakpoint on this statement and run command WRKOBJLCK TESTLIB1/OEM001 *DTAARA, you can see the two locks:
Line 21: Do the core business logic here.
Line 22: Release the *EXCL lock. Now the next job in line may attempt to get the *EXCL lock.
Line 23: Exit the program.
If you CALL the CL program in debug from two different sessions and step through, you can see how the two jobs deal with the exclusive object lock.
Well, that’s it for now. I hope you’re able to apply this technique down the road. Thanks for reading my tech tip and until next time, keep coding!
Chris Ringer began coding RPG programs in 1989, and after a recent unexpected but valuable detour to C# is happy to be back in the IBM world. In his spare time he enjoys cycling and running – and taking the family dog Eddie for walks.
RELATED STORIES
Guru: A Faster Way To Sign A JWT
Guru: Web Concepts For The RPG Developer, Part 4
Guru: Web Concepts For The RPG Developer, Part 3
Guru: Web Concepts For The RPG Developer, Part 2
Guru: Web Concepts For The RPG Developer, Part 1
Guru: The PHP Path To Victory, Part 1
Simplified version of this program; instead of going through a loop of 15 times waiting for 2 seconds, this program waits for maximum (!) 30 seconds to get the lock.
Pgm
ALCOBJ OBJ((TESTLIB1/OEM001 *DTAARA *EXCL)) WAIT(30) SCOPE(*JOB)
Monmsg cpf1002 Exec( Do )
SNDPGMMSG MSG(‘WARNING: Could not get object Lock, exiting!’)
Return
Enddo
ALCOBJ OBJ((TESTLIB1/OEM001 *DTAARA *SHRRD)) WAIT(0) SCOPE(*JOB)
DLCOBJ OBJ((TESTLIB1/OEM001 *DTAARA *EXCL)) SCOPE(*JOB)
/* do business logic here … */
DLCOBJ OBJ((TESTLIB1/OEM001 *DTAARA *SHRRD)) SCOPE(*JOB)
Endpgm
Should do the same but with less coding.
rgds,
Peter