jBASE developer on retainer: ORDPRC READL on ORDER-MASTER holds record lock when GOTO skips WRITE and RELEASE on already-picked validation path — warehouse picker gets 30-second lock timeout in ORDPCK — jBASE developer on monthly retainer

jBASE 5.7.4 • RHEL 8.5 • READL without RELEASE • jSHOW LOCKS • GOTO skips non-WRITE exit • lock timeout • retainer billing

At Southwest Beverage Distributors, the warehouse picking confirmation terminal started producing a “Record is locked — try later” error on specific orders. A picker would scan an order barcode to confirm picking, the ORDPCK program would retrieve the order, and instead of confirming, it would pause for thirty seconds and then reject with a lock message. The picker would try again a few minutes later and sometimes succeed, sometimes fail. The pattern was intermittent but reproducible on the same set of order IDs.

The jBASE retainer developer was called in. The diagnosis took 45 minutes. The root cause was a single missing RELEASE statement in the ORDPRC order processing program — a lock acquired by READL on the ORDER-MASTER file was never released when ORDPRC determined an order was already in the “PICKED” status and exited the order loop through a GOTO NEXT_ORDER path that bypassed the normal WRITE and never explicitly called RELEASE.

READL and how jBASE record locks work

In jBASE BASIC, READL acquires an exclusive record-level lock on the specified item before reading it. The lock is held until one of three things happens:

• WRITE — writes the record back to the file and implicitly releases the lock.
• WRITEU — writes the record but does not release the lock (used when you need to hold the lock across multiple writes).
• RELEASE — explicitly releases the lock without writing the record.

Unlike SQL row locks that are automatically released at the end of a transaction or statement, jBASE READL locks have no automatic transaction scope. A lock acquired by READL in a long-running jBASE program persists for the lifetime of that program’s session — or until the program explicitly releases it. If the program exits a code path that needed the lock (validation, inspection, comparison) without writing and without releasing, the lock remains held by the originating port until that port’s session ends.

This is a known pattern in MultiValue environments (jBASE, Universe, UniData, D3, QM, Reality) and is the direct equivalent of an “open file without close” bug in other languages. The difference is that in file I/O, an unclosed file handle is usually harmless for readers — in jBASE READL, an unreleased lock prevents any other program from acquiring a lock on that record, causing lock timeouts for all concurrent users who need to update or lock-read the same item.

The ORDPRC program and the already-picked exit path

The ORDPRC order processing program ran continuously on a shared terminal as the day’s orders were dispatched to the warehouse. For each order, ORDPRC acquired an exclusive lock on the ORDER-MASTER record to prevent two dispatchers from sending the same order simultaneously:

OPEN 'ORDER-MASTER' TO F.ORDERS ELSE STOP 201, 'ORDER-MASTER'

LOOP
   INPUT ORD.ID, 8:   ;* dispatcher scans order barcode
   IF ORD.ID = '' THEN GOTO DONE

   READL ORD.REC FROM F.ORDERS, ORD.ID LOCKED
      PRINT 'Order ': ORD.ID: ' is locked. Try again.'
      GOTO NEXT_ORDER
   END ELSE
      PRINT 'Order ': ORD.ID: ' not found.'
      GOTO NEXT_ORDER
   END

   * Validate order status
   ORD.STATUS = ORD.REC<3>    ;* attribute 3 = ORDER_STATUS

   IF ORD.STATUS = 'PICKED' THEN
      PRINT 'Order ': ORD.ID: ' already picked. Skipping.'
      GOTO NEXT_ORDER            ;* ← BUG: no RELEASE, no WRITE
   END

   IF ORD.STATUS = 'CANCELLED' THEN
      PRINT 'Order ': ORD.ID: ' cancelled. Skipping.'
      GOTO NEXT_ORDER            ;* ← BUG: no RELEASE, no WRITE
   END

   * Dispatch the order
   ORD.REC<3> = 'DISPATCHED'
   ORD.REC<9> = TIMEDATE()     ;* attribute 9 = DISPATCH_TIME
   WRITE ORD.REC ON F.ORDERS, ORD.ID   ;* releases lock

   PRINT 'Order ': ORD.ID: ' dispatched.'

NEXT_ORDER: *
REPEAT

DONE: *

The READL on line 6 acquires an exclusive lock on the ORDER-MASTER record for ORD.ID. When ORD.STATUS = 'PICKED' is true, the program prints a message and jumps to NEXT_ORDER via GOTO NEXT_ORDER. This GOTO skips the WRITE on line 22 — and there is no RELEASE F.ORDERS, ORD.ID anywhere on the PICKED or CANCELLED exit paths. The lock acquired by READL remains held.

The dispatch terminal ran ORDPRC in a loop from 06:00 to 18:00. Any order that was scanned and found to be already-picked had its ORDER-MASTER record locked by the ORDPRC port (port 7, PID 14823) from the moment the dispatcher scanned it until 18:00 when ORDPRC terminated and jBASE released all locks held by that session.

jSHOW LOCKS: identifying the lock holder

The retainer developer ran jSHOW LOCKS from a jSHELL session while the ORDPCK lock timeout was actively occurring:

jSHELL> SHOW-LOCKS

Port  PID    User      File              Item ID      Time
----  -----  --------  ----------------  -----------  --------
  7   14823  DISPATCH  ORDER-MASTER      ORD004821    09:14:32
  7   14823  DISPATCH  ORDER-MASTER      ORD003977    10:02:18
  7   14823  DISPATCH  ORDER-MASTER      ORD004156    11:47:41
 12   18204  PICKER1   ORDER-MASTER      ORD006142    14:22:09

Port 7 (the ORDPRC dispatch terminal session, user DISPATCH, PID 14823) held locks on three ORDER-MASTER records. The lock times showed that ORD004821 had been locked since 09:14:32 — over five hours earlier. ORD003977 since 10:02. ORD004156 since 11:47. These were orders that ORDPRC had scanned and found to be already-picked at those times, never released. Port 12 (a ORDPCK picker session) held one lock, which was expected — that was the normal active READL for a picking confirmation in progress.

The developer cross-referenced the locked item IDs against the ORDER-MASTER records. Each had ORDER-STATUS = 'PICKED' — confirming they were the already-picked orders that ORDPRC had scanned and skipped. The ORDPCK lock timeouts occurred because pickers had been trying to rescan those same orders to re-confirm picking (the warehouse system occasionally required re-confirmation for quality checks), and each attempt got the lock timeout from port 7.

Fix: RELEASE before each non-WRITE GOTO

The fix was to add RELEASE F.ORDERS, ORD.ID on every exit path that had a GOTO NEXT_ORDER without a preceding WRITE:

   IF ORD.STATUS = 'PICKED' THEN
      RELEASE F.ORDERS, ORD.ID   ;* ← added
      PRINT 'Order ': ORD.ID: ' already picked. Skipping.'
      GOTO NEXT_ORDER
   END

   IF ORD.STATUS = 'CANCELLED' THEN
      RELEASE F.ORDERS, ORD.ID   ;* ← added
      PRINT 'Order ': ORD.ID: ' cancelled. Skipping.'
      GOTO NEXT_ORDER
   END

The developer reviewed the entire ORDPRC source for every GOTO and RETURN that could be reached after a successful READL without a WRITE. In addition to the PICKED and CANCELLED paths, a third path was found: a data integrity check at line 81 that verified the order’s warehouse zone was in the current dispatcher’s assigned zone list — a mismatch printed “Order outside your zone” and jumped to NEXT_ORDER without releasing. RELEASE F.ORDERS, ORD.ID was added there as well.

After the fix, ORDPRC was recompiled with BASIC BP ORDPRC and recatalogued with CATALOG BP ORDPRC. The ORDPRC session was restarted. The three previously-held locks were gone. A test run scanning an already-picked order confirmed that the READL lock was acquired, the PICKED path was taken, RELEASE executed, and jSHOW LOCKS showed no residual lock on that item. ORDPCK lock timeout incidents dropped to zero.

The READL/RELEASE pattern in jBASE: the full correct form

The correct pattern for any jBASE READL operation is to enumerate every possible exit from the code block that follows the lock acquisition and ensure each one either writes (releasing the lock automatically) or explicitly releases:

READL REC FROM F.FILE, ITEM.ID LOCKED
   * Another process holds the lock
   PRINT 'Item locked'
   GOTO NEXT     ;* no RELEASE needed: we never got the lock
END ELSE
   * Item doesn't exist
   PRINT 'Item not found'
   GOTO NEXT     ;* no RELEASE needed: we never got the lock
END

* At this point: we hold the lock on ITEM.ID
* Every exit from here must WRITE or RELEASE

IF REC<1> = 'DONE' THEN
   RELEASE F.FILE, ITEM.ID   ;* exit 1: no update needed
   GOTO NEXT
END

IF REC<2> < 0 THEN
   RELEASE F.FILE, ITEM.ID   ;* exit 2: validation failure
   PRINT 'Invalid record'
   GOTO NEXT
END

REC<5> = TIMEDATE()
WRITE REC ON F.FILE, ITEM.ID  ;* normal exit: WRITE releases lock

NEXT: *

The key discipline: after a successful READL (reaching the code after the LOCKED and ELSE clauses), the developer must treat lock release as a responsibility as explicit as file close in C or connection close in JDBC. jBASE will not do it automatically before the program’s next iteration.

One additional hardening approach used at Southwest Beverage: a post-incident code review of all ORDPRC, ORDPCK, ORDENT, and INVADJ programs identified seven additional READL calls across four programs where at least one exit path lacked a RELEASE. None of those had caused reported incidents (the orders involved were not scanned again during the same session), but they were all fixed preventively. The retainer developer documented each fix with the program name, line number, and the business condition that the missing-RELEASE path handled.

How HourTab helps jBASE retainer developers

The diagnosis and fix took two hours. But the retainer developer also spent thirty minutes walking the distributor’s in-house developer through the READL/WRITE/RELEASE triad and why jBASE locks differ from SQL transaction-scoped row locks. That explanation is what prevents the same bug from recurring in the next program the in-house developer writes, and it is billable retainer work — not a courtesy overhead absorbed into the fix time.

In a HourTab log, the session appears as: “ORDPRC READL lock not released on PICKED/CANCELLED/wrong-zone exit paths: traced via jSHOW LOCKS, 3 orders locked since morning; added RELEASE F.ORDERS,ORD.ID on 3 non-WRITE GOTO paths; preventive audit found 7 more in ORDPCK/ORDENT/INVADJ; READL vs SQL lock semantics walkthrough with dev team, 2.5h.” The warehouse operations manager reads that entry and sees exactly why the lock timeouts were happening and why 2.5 hours of retainer time was the right investment.

HourTab turns a time-tracker CSV into a public retainer-hours URL your client can bookmark — no login, no portal, no “how many hours do I have left?” emails. Free for one retainer. $9/mo for up to ten.

FAQ: jBASE developer retainers

See also: Progress 4GL developer retainer · Informix developer retainer · COBOL developer retainer