Diagnosing Dyalog APL Component File I/O Errors (⎕FREAD/⎕FWRITE)

Recognizable condition

When you call ⎕FREAD or ⎕FWRITE on a Dyalog component file and the function returns error 11 (FILE ACCESS ERROR) or error 13 (INVALID COMPONENT NUMBER), the file appears to exist and the operating‑system permissions look correct.

Cause / diagnostic table

Symptom	Likely cause	What to look for
Error 11 on any component number	File locked by another process	OS shows an open handle; ⎕FIBS returns a non‑zero lock count
Error 11 with file size 0 bytes	Corrupted or zero‑length file	⎕FINFO reports size 0 or header checksum mismatch
Error 13 for a specific number	Component number out of range or missing	Requested number not in ⎕FNUMS list
Error 11 after a large read/write	Insufficient workspace memory	⎕WA shows low available bytes before the call

Ordered checks

1. Check for a file lock
   1. Run the OS tool that lists open handles (e.g., Process Explorer on Windows or lsof on Linux/macOS) and look for the component file path.
   2. Alternatively, from a Dyalog session execute ⎕FIBS '/path/to/file.cmp'; a non‑zero result indicates another Dyalog process holds the file.
2. Inspect file size and header
   1. Execute ⎕FINFO '/path/to/file.cmp'. The result is a nested vector where the first element is the file size in bytes.
   2. If the size is 0, the file is likely corrupted or truncated.
3. Validate the component number
   1. List existing components with ⎕FNUMS '/path/to/file.cmp'. This returns a simple integer vector of all component numbers present.
   2. Confirm that the number you intend to read or write appears in that vector.
4. Verify workspace memory availability
   1. Before a large ⎕FREAD/⎕FWRITE, call ⎕WA to see the available workspace in bytes.
   2. Compare the required size (approximate component size from ⎕FINFO) with the free workspace.

Fixes tied to findings

• File lock – If another process holds the file, either terminate that process (if safe) or wait until it releases the lock, then retry the operation. For a Dyalog lock shown by ⎕FIBS, you can issue ⎕FERASE '/path/to/file.cmp' from the holding session to release, or simply close that session.
• Corruption – Restore the file from a known good backup. If no backup exists, attempt to salvage readable components with ⎕FCOPY '/path/to/file.cmp' '/path/to/salvaged.cmp'; ⎕FCOPY skips components that cannot be read.
• Wrong component number – Adjust the number to one returned by ⎕FNUMS. For example, if you wanted component 5 but ⎕FNUMS shows 1 2 3 4, use 4 or create a new component with ⎕FAPPEND.
• Low workspace – Free unused objects with ⎕CLEAR or ⎕EX 'name', increase the maximum workspace limit via ⎕MAXWS ← new_limit (subject to OS limits), or split the component into smaller parts using multiple ⎕FWRITE calls.

Escalation criteria

If after performing the checks above the error persists:

• Repeat the lock check with a different OS tool to rule out a hidden handle.
• Run a file‑system integrity check (e.g., chkdsk on Windows or fsck on Linux) on the volume containing the component file.
• Collect a Dyalog trace (⎕TRACE ← '⎕FREAD' '⎕FWRITE') and reproduce the failure; forward the trace to Dyalog support with the exact component file (if it can be shared) and the OS version.
• Consider testing the operation on a different machine or with a freshly created component file to isolate whether the problem is environment‑specific.

Verification

After applying a fix, rerun the original ⎕FREAD or ⎕FWRITE call. A successful ⎕FREAD returns the component data; a successful ⎕FWRITE returns a shy result of 0. Confirm that:

• ⎕FINFO reports a non‑zero file size.
• ⎕FNUMS lists the component number you used.
• ⎕WA shows sufficient free workspace during the operation.