Btrieve developer on retainer: TAXUPD opens TAXROLL.BTR with mode 4 Exclusive and exits without Close on validation error — all other users get Btrieve status 85 File Locked

Pervasive PSQL v11.3 • Windows Server 2019 • Btrieve Op 0 mode byte 4 • status 85 File Locked • PCC ghost connection • retainer billing

Hampton County Tax Office ran its property assessment workflow on a legacy Btrieve application that had worked reliably for over fifteen years. The Btrieve engine — Pervasive PSQL v11.3 running in client-server mode on Windows Server 2019 — managed TAXROLL.BTR, the property tax roll file for 12,847 assessed properties. The assessment cycle ran once a quarter: a batch C++ program, TAXUPD.EXE, read the appraisal district feed, validated each property record, and updated the assessed values. During the third-quarter cycle, a tax clerk who opened the tax roll in the property search application got a message she had never seen: Btrieve Error 85: The file is locked by another user.

The error spread to all twelve workstations that accessed TAXROLL.BTR. TAXUPD.EXE had already finished — or rather, it had crashed. But the lock remained. The Btrieve retainer developer was called within the hour.

The TAXUPD program and the Exclusive open

TAXUPD.EXE was a 2003-era C++ program using the Btrieve C API directly via the BTRV() function. It opened TAXROLL.BTR at startup and processed records sequentially. The relevant excerpt from the source code (recovered from version control):

/* Open TAXROLL.BTR in Exclusive mode */
status = BTRV(0, posBlock, &dataLen, dataBuffer, keyBuffer, 4);
if (status != 0) {
    fprintf(stderr, "ERROR: Open failed, status %d\n", status);
    exit(1);
}

/* Get first record */
status = BTRV(12, posBlock, &dataLen, dataBuffer, keyBuffer, 0);
while (status == 0) {
    /* Validate ASSESSED_VALUE field (bytes 48-57, 10 digits) */
    if (!isNumeric(dataBuffer + 48, 10)) {
        fprintf(stderr, "ERROR: non-numeric ASSESSED_VALUE\n");
        exit(1);          /* ← exits without BTRV(1,...) Close */
    }

    /* Parse and update assessed value */
    newValue = lookupAppraisalValue(dataBuffer);
    memcpy(dataBuffer + 48, newValue, 10);
    status = BTRV(3, posBlock, &dataLen, dataBuffer, keyBuffer, 0);

    /* Get next record */
    status = BTRV(6, posBlock, &dataLen, dataBuffer, keyBuffer, 0);
}

/* Close the file */
BTRV(1, posBlock, &dataLen, dataBuffer, keyBuffer, 0);
printf("TAXROLL updated successfully.\n");

The first BTRV call uses op code 0 (Open) with the last parameter 4 (Exclusive mode). In Pervasive PSQL, opening a file with mode byte 4 grants the opening process exclusive access to the entire file. No other user or application can open the same file while the exclusive open is held. This is appropriate for batch programs that need to prevent all concurrent access during a bulk update. The exclusive open is held until the program issues op code 1 (Close).

The bug: the validation error path on line 12 calls exit(1) without first issuing BTRV(1,...). When the program terminates without closing the file, the Pervasive PSQL MKDE (MicroKernel Database Engine) does not immediately release the exclusive open. The engine waits for the client to explicitly disconnect or for the session timeout to expire. On this network configuration (VPN clients with a 15-minute session timeout), the exclusive lock held for up to fifteen minutes after TAXUPD.EXE had already crashed.

Btrieve status 85 and the Pervasive Control Center diagnosis

The retainer developer opened the Pervasive PSQL Control Center (PCC) on the server and navigated to Monitor → Active Connections. The connection list showed one entry for TAXROLL.BTR: workstation TAXSRV01, user TAXBATCH, file access Exclusive. But Task Manager on TAXSRV01 showed no running TAXUPD.EXE process. The connection was a ghost — an artifact of the engine’s session state machine that still tracked the file open after the client process had terminated.

PCC Monitor → Active Connections:
  Workstation: TAXSRV01
  User:        TAXBATCH
  File:        C:\PSQL\DATA\TAXROLL.BTR
  Access:      Exclusive
  Open Time:   09:47:23
  Last Access: 09:51:14  ← last Op 6 Get Next before crash

PCC Monitor → Files In Use:
  TAXROLL.BTR   Exclusive   1 user   C:\PSQL\DATA\TAXROLL.BTR

The immediate fix was straightforward: in PCC, right-click the ghost connection and select Disconnect Session. The engine dropped the stale exclusive open. Within seconds, all twelve workstations could open TAXROLL.BTR again — Btrieve status 85 cleared immediately. The property search application resumed on all terminals.

But the underlying code problem remained. The next quarter’s assessment run would trigger the same issue the first time TAXUPD.EXE encountered a validation error in the appraisal district feed.

Finding all seven exit paths without Close

The retainer developer audited TAXUPD.EXE’s source code for every exit path that followed a successful BTRV(0,...) open. A successful Op 0 Open means the exclusive lock is held from that point forward. Every subsequent exit(), return from main, or unhandled exception must first call BTRV(1,...).

The audit found seven exit paths. Three had a BTRV(1) close. Four did not:

Line  87: non-numeric ASSESSED_VALUE validation — exit(1)       ← missing Close
Line 104: parcel ID length != 10 validation — exit(1)           ← missing Close
Line 121: appraisal lookup returned NULL — exit(1)              ← missing Close
Line 139: BTRV(3) Update returned non-zero status — exit(1)     ← missing Close
Line 156: EOF loop (status == 9) — BTRV(1) present             ✓
Line 163: Get Next returned status 64 (lost position) — exit(1) ← missing Close
Line 178: main() return 0 — BTRV(1) present                    ✓
Line 182: signal handler SIGTERM — exit(0)                      ← missing Close

The fix added BTRV(1, posBlock, &dataLen, dataBuffer, keyBuffer, 0) before each of the five missing-Close exit paths, and updated the SIGTERM signal handler to call a cleanup function before terminating.

The second change was more significant: the Op 0 mode byte was changed from 4 (Exclusive) to 0 (Normal). Mode 0 opens the file in normal shared mode — multiple users can have the file open simultaneously, with record-level locking for individual update operations. TAXUPD.EXE never required exclusive file-level access. The original developer had used mode 4 from a code template without considering the implications. With mode 0, even if TAXUPD.EXE exits without closing the file, other users are not blocked — they share the file normally. The ghost session at worst holds a stale normal open, which has no blocking effect on reads or updates by other processes.

After the fix: mode 0 behavior verified

To verify, the developer ran a modified test version of TAXUPD.EXE that deliberately triggered the validation error and exited without closing. In PCC, the ghost connection appeared as expected — but with access mode Normal instead of Exclusive. All twelve workstations opened TAXROLL.BTR and queried records without receiving status 85. The mode 0 ghost connection caused no blocking at all.

After production deployment: status 85 File Locked incidents dropped from one or two per quarterly assessment cycle to zero. The PCC Monitor was added to the quarterly assessment runbook: if TAXUPD.EXE fails, check Active Connections before investigating data issues.

The retainer developer also added a code review note to the TAXUPD source: Op 0 mode byte 4 (Exclusive) should be reserved for file restructuring operations (creating indexes, rebuilding the file) where no other access can be tolerated. Batch update programs that use Op 3 (Update) with standard record-level locking should use mode 0 (Normal) or mode 8 (Read-Only for read-only access). The fifteen-year history of the program showed that no concurrent user had ever caused a conflict during a quarterly run — the exclusive mode was always unnecessary.

How HourTab helps Btrieve retainer developers

The investigation took 3 hours. The PCC diagnosis took 20 minutes. The source audit of seven exit paths took 1 hour. The fix and regression test took 1.5 hours. The Btrieve retainer consultant also spent 30 minutes explaining to the tax office IT manager why changing a single number (mode byte 4 to 0) eliminated the entire class of incident going forward. That explanation time is worth logging separately: a Btrieve expert explaining why Exclusive mode should only be used for file restructuring is worth more in long-term maintenance cost than the one-line code fix.

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: Btrieve developer retainers

See also: RPG / ILE RPG developer retainer · COBOL developer retainer · Db2 developer retainer