Blog › ICP guides

ToolBook developer on retainer: shared file exclusive lock, Asymetrix ToolBook, OpenText ToolBook developer on monthly retainer

October 8, 2026 · ~15 min read

A ToolBook developer was maintaining a corporate training courseware application built in Asymetrix ToolBook II Instructor 5.5 for a regional insurance company. The courseware had been used for new-employee compliance training for several years; recently the company had moved to a networked deployment where multiple training workstations ran the ToolBook Runtime client against a shared application on a mapped network drive. One module — the “Claims Compliance Quiz” — had an OpenScript handler in its closing page that wrote the student’s quiz results to a shared results file on the network drive: FileOpen("\\server\training\results\compliance_results.txt", "a", fileNum) followed by FilePrint fileNum, sStudentID & "," & sScore & "," & Now() and FileClose fileNum. The developer had tested the quiz with one student session at a time and confirmed it worked correctly. When the insurance company ran a group training session with 12 employees on 12 workstations simultaneously, and 2 students completed the quiz within the same 1–2 second window, the second student’s ToolBook FileOpen call received a ToolBook runtime error “File in use” (Windows OS error 32 — sharing violation, because the first student’s FileOpen had opened the file in exclusive mode). The second student’s quiz result record was silently lost — the error was caught by ToolBook’s default error handler, which dismissed it without displaying any message to the student. The compliance records for the group training session showed 11 completions out of 12 participants; the missing record was discovered only during the post-training audit. Silent quiz result records lost in simultaneous session: 1 → 0 after rewriting the handler to write per-student files and consolidating them server-side.

The root cause was ToolBook’s default FileOpen mode acquiring an exclusive Windows OS file lock on the shared network results file. ToolBook II’s OpenScript FileOpen function, when called with mode “a” (append) or “w” (write), opens the file using the Windows CreateFile API with dwShareMode = 0 (exclusive access, no sharing) — the default behavior for ToolBook file I/O. This means that while one ToolBook session has the file open (even briefly, for the duration of the FilePrint + FileClose sequence), no other process can open the file for any access mode. On a local single-user workstation this is never a problem because only one ToolBook session runs at a time and the FileOpen → FilePrint → FileClose sequence completes in milliseconds. On a networked deployment where multiple ToolBook Runtime instances run concurrently, the probability of two sessions attempting FileOpen simultaneously is proportional to the number of concurrent sessions and the file-open window duration. With 12 simultaneous students completing the quiz within the same 10-minute window, collisions are not rare — they are statistically expected. ToolBook’s error handling in the quiz script used on error resume next semantics (implicitly — the FilePrint error was not handled, causing the handler to silently skip the write). The fix: replace the shared results file with per-student files (one .txt file per sStudentID) written to the shared drive; consolidate server-side by a separate batch process. Per-student files do not collide because each student writes to a uniquely named file.

ToolBook II’s FileOpen function maps directly to the Windows CreateFile / OpenFile API family. The dwShareMode parameter controls file sharing: FILE_SHARE_READ (0x01), FILE_SHARE_WRITE (0x02), and FILE_SHARE_DELETE (0x04) can be combined to allow concurrent access. ToolBook II does not expose the dwShareMode parameter in the FileOpen syntax — it always uses exclusive access (no sharing) for write-mode opens. Developers who need shared-write access to a network file from ToolBook have limited options within ToolBook’s built-in file I/O: (1) use per-student files (unique filenames, no collision risk), (2) use an intermediate Windows DLL or COM object with explicit FILE_SHARE_WRITE sharing mode and atomic-append semantics, or (3) use an ODBC or ADO connection to a database (Access MDB or SQL Server) instead of flat-file I/O. The third option (database) is the most robust for production deployments with high concurrent user counts. ToolBook II supports ODBC via the ODBC_Connect, ODBC_Exec, and ODBC_Disconnect OpenScript commands — available in ToolBook II Instructor (authoring) but also callable from ToolBook II Student (runtime) if the ODBC driver is installed on the workstation. For the insurance company’s compliance tracking use case, writing to an Access MDB file via ODBC and using Access’s record-level locking eliminated both the file-in-use collision and the silent data loss.

Asymetrix ToolBook, OpenScript, and Windows file I/O in network deployments

Asymetrix Corporation — founded by Microsoft co-founder Paul Allen in 1985 — released ToolBook 1.0 in 1990 for Windows 3.0, positioning it as a multimedia authoring and interactive application development tool for Windows. ToolBook’s central metaphor is the book: an application is a book, a book contains pages, and each page contains objects (buttons, fields, and graphics). This book metaphor maps directly to its primary use case: interactive courseware, training simulations, and reference materials where each screen corresponds to a page in a book. Asymetrix expanded the product with ToolBook II, splitting the product into two editions: ToolBook II Instructor (the full authoring environment for developers) and ToolBook II Student (the runtime-only player for end users, later renamed ToolBook Runtime). The split occurred at version 3.0 and persisted through the product’s lifecycle.

ToolBook’s programming language is OpenScript — Object-oriented Script Language for Windows — an event-driven, object-oriented scripting language organized around messages and handlers. Every user interaction (button click, page turn, keystroke) generates a message that travels up ToolBook’s object hierarchy: from the object that received the interaction (a button or field), up through the page foreground, the page, the background, the book, and finally to the mainWindow. Each object in the hierarchy can define an OpenScript handler for any message using the to handle messageName syntax; a handler can pass the message up the hierarchy using forward or stop its propagation by handling it without forwarding. The hierarchy is: mainWindow > book > background > page > foreground > object. Messages cascade downward for notifications (such as enterPage and leavePage) and upward for commands (such as buttonClick). sendMessage sends a message to a specific object; forwardMessage passes the current message to the next object in the hierarchy.

OpenScript’s file I/O commands provide direct access to the Windows file system. FileOpen(path, mode, fileNum) opens a file: mode “r” opens for reading, mode “w” creates or overwrites for writing, mode “a” opens for appending. FilePrint fileNum, expression writes a line to an open file. FileRead fileNum, variable reads a line from an open file into a variable. FileClose fileNum closes the file and releases the file handle. FileExists(path) tests whether a file exists without opening it. ToolBook error 2701 is “File in use” (Windows OS error 32, sharing violation — another process holds an exclusive lock on the file). ToolBook error 2702 is “File not found.” In ToolBook II’s network deployment model, the .tbk book file resides on a mapped network drive; all ToolBook Runtime instances on the training workstations open and execute the same shared .tbk file. This is safe because ToolBook opens the .tbk book file for reading only — the exclusive lock problem arises only when OpenScript handlers call FileOpen in write or append mode on a separate shared file (such as a results log).

ToolBook’s corporate ownership history spans three companies. Asymetrix Corporation developed ToolBook 1.0 through ToolBook II Instructor 8.0. In 2006, SumTotal Systems (an eLearning platform company formed from the merger of Docent and Click2Learn) acquired the ToolBook product line and released SumTotal ToolBook versions 9.x and 10.x, adding SCORM 2004 compliance, improved DHTML export, and LMS integration features. OpenText Corporation subsequently acquired SumTotal and continues the product as OpenText ToolBook (version 11.x, part of the OpenText eLearning Suite). ToolBook’s version history — ToolBook II Instructor 5.5, 6.0, 7.0, 8.0; SumTotal ToolBook 9.x, 10.x; OpenText ToolBook 11.x — spans more than three decades of Windows eLearning courseware; retainer developers maintaining corporate compliance and onboarding courseware may encounter any version of these builds in production. The ToolBook .tbk binary file format is version-specific; books authored in ToolBook II Instructor 5.5 require ToolBook Runtime 5.5 (or later runtime versions with backward-compatibility mode) to execute. DHTML export — introduced in ToolBook II 8.0 and enhanced in SumTotal and OpenText versions — converts .tbk books to HTML, JavaScript, and CSS packages for web-based delivery without the ToolBook Runtime, supporting the migration of legacy courseware to modern browsers.

Typical ToolBook developer retainer work and what it looks like in a work log

Shared results file exclusive lock collision is the canonical ToolBook invisible production network deployment bug. The pattern is consistent: an OpenScript handler on a page’s closeBook or button’s buttonClick event calls FileOpen("\\server\training\results\compliance_results.txt", "a", fileNum) to append the student’s result to a shared log file; FilePrint writes the record; FileClose closes the file. The developer tests with one student session at a time — no collision possible. In production, 12 students complete the quiz within the same group training window; two students finish within the same 1-second window; the second student’s FileOpen receives ToolBook error 2701 “File in use”; ToolBook’s default error handler dismisses the error silently; the second student’s result record is never written. The post-training audit shows 11 completions out of 12. Fix: replace compliance_results.txt with per-student files (compliance_results_sStudentID.txt); a server-side batch script consolidates all per-student files nightly. Per-student files do not collide because each student’s sStudentID is unique. Silent result records lost per group session: 1 → 0. Work log: “Claims Compliance Quiz closing-page handler; FileOpen("\\server\training\results\compliance_results.txt", "a", fileNum); 12 concurrent students; second-student FileOpen receives ToolBook error 2701 (Windows error 32, exclusive lock); result record silently lost; fix: per-student files (compliance_results_sStudentID.txt); server-side consolidation batch; silent result losses: 1 per group session → 0; 2h.”

ToolBook book file performance degradation on large .tbk with embedded media is the second most common ToolBook retainer pattern in long-running corporate deployments. A ToolBook II Instructor book for a corporate onboarding course has grown over several years to 850 pages with embedded media: every screenshot was pasted directly into ToolBook as an embedded bitmap, and every audio narration track was imported as an embedded uncompressed WAV file. The .tbk binary file has grown to 180 MB. ToolBook Runtime loads the entire .tbk file into memory at startup; over a 100 Mbps network, loading a 180 MB file takes 45–90 seconds — unacceptable for a new-employee onboarding course where the first impression is a loading screen. Fix: extract all embedded bitmaps to external BMP files (referenced by file path in the ToolBook object’s filename property) and all embedded WAV files to external WAV files (referenced by path in the clipFilename or filename property of the ToolBook media object). After extraction, the .tbk file shrinks to 12 MB; ToolBook Runtime load time drops to 3–5 seconds over the same network. External media files are loaded on demand (only when the page containing them is displayed), so initial load time is determined by the .tbk structure file size, not the total media size. Work log: “Corporate Onboarding course onboarding.tbk; 850 pages; 180 MB embedded bitmaps + WAV audio; ToolBook Runtime load time 45–90s over 100 Mbps LAN; extracted bitmaps to \\server\training\media\*.bmp, WAV audio to \\server\training\audio\*.wav; .tbk reduced to 12 MB; load time 3–5s; 3h.”

OpenScript conditional navigation off-by-one in branching assessment is the third common ToolBook retainer pattern. A ToolBook II Instructor branching assessment routes students to different feedback pages based on their quiz score: students scoring 6 or more correct answers out of 10 go to the “Passed” feedback page; students scoring 5 or fewer go to the “Review Required” feedback page. The OpenScript goNextPage handler in the background uses the condition if correctAnswers > 6 then go to page “Passed” else go to page “Review Required”. Students who answer exactly 6 questions correctly — who should pass — are routed to “Review Required” because correctAnswers > 6 is false when correctAnswers = 6. The off-by-one boundary condition affects only students at exactly the passing threshold; students scoring 7 or more pass correctly, students scoring 5 or fewer fail correctly. The fix changes > 6 to >= 6. Boundary-condition students receiving wrong feedback page: 1 boundary case → 0. Work log: “goNextPage handler in background of Claims Compliance Quiz; if correctAnswers > 6 should be >= 6; students with exactly 6 correct answers routed to Review Required instead of Passed; fix: >= 6; boundary-case routing errors: 1 → 0; 1h.”

How HourTab tracks ToolBook developer retainer hours

ToolBook shared-file exclusive lock bugs are invisible by the same mechanism that makes them impossible to reproduce in single-user development testing: the FileOpen call succeeds every time when only one student session is running; the FilePrint writes the record correctly; the FileClose releases the file handle; the OpenScript handler completes without error; the .tbk book closes normally. The quiz result record appears in the results file. The developer confirms the feature works and moves on. The only evidence of the problem surfaces in post-training audits when group training sessions with 12 concurrent students produce 11 completion records out of 12 participants — with no error message in the ToolBook application, no visible indication to the affected student, and no ToolBook runtime error log entry (because ToolBook’s default error handler dismisses the error 2701 silently). Diagnosing the problem requires cross-referencing the Windows Event Log (application errors, SYSTEM errors for error 32 sharing violations), the ToolBook runtime error log (if configured), and the group training session roster against the results file record count. The diagnosis also requires understanding Windows file-sharing behavior — specifically that dwShareMode = 0 (exclusive access) means the file is completely inaccessible to other processes during the open window, regardless of how briefly the file is held open.

The work log must name the mechanism to be auditable: which book file (compliance_quiz.tbk), which OpenScript handler (closing-page closeBook handler in the Claims Compliance Quiz module), the FileOpen path (\\server\training\results\compliance_results.txt), the open mode (“a” append, exclusive Windows lock), the concurrent session count (12 simultaneous students), the collision window (1–2 seconds when two students complete within the same window), the result records lost per group training session before fix (1 silent loss), the result records lost after fix (0), and the fix (per-student files: compliance_results_sStudentID.txt; server-side batch consolidation). A log entry that says “fixed file issue in quiz, 2h” is not auditable. A log entry that names the book, the handler, the FileOpen path, the Windows error 32 sharing violation, the silent data loss mechanism, and the per-student-file fix is auditable and defensible to the insurance company compliance team. HourTab gives ToolBook developers a public retainer-hours URL they send to clients — insurance companies, financial services firms, healthcare organizations, utilities, and government agencies that built compliance and onboarding courseware in Asymetrix ToolBook II in the 1990s and 2000s, maintained today by the original ToolBook developer or a successor retainer consultant.

Comparative context: ToolBook shared-file exclusive lock bugs are structurally similar to exclusive-lock patterns in other legacy environments where the platform’s default file I/O acquires a lock wider than necessary. FileMaker retainers cover the $$global variable scope leakage pattern — a different class of invisible state bug, but both share the “tested solo, works correctly; fails with concurrent sessions” diagnostic pattern that makes them invisible in development. WinDev retainers cover the HLock file-system lock not released — the same OS file-system lock class as ToolBook’s exclusive FileOpen, where a held lock blocks concurrent sessions until the lock is explicitly released or the session terminates. Advantage Database retainers cover the AdsTable.Edit exclusive lock for single-user applications deployed multi-user — an exclusive lock acquired by default on record edit, blocking concurrent access in a deployment the developer designed for single-user and never tested with concurrent sessions.

FAQ: ToolBook developer retainers