Diagnosing and Recovering Dyalog APL Component File Corruption

Recognizable Condition

When working with Dyalog APL component files, operations such as ⎕FIX, ⎕READ, or ⎕REPLACE may return error codes ¯1 (file not found), ¯2 (damaged file), or trigger a WS FULL or FILE ERROR. These symptoms indicate that the file’s internal structure may be compromised.

Common Causes

Cause	Typical Indicator
Abrupt session termination while file open	File left with an open handle; subsequent ⎕FIX returns ¯2
Power loss or unexpected shutdown	Corruption visible in file header; ⎕FIX 'info' shows mismatched component count
Network filesystem latency	Intermittent ¯1 errors despite file present
Concurrent access without locking	Silent data loss; ⎕READ returns unexpected values
Using an outdated component format with a newer Dyalog version	⎕FIX 'upgrade' needed; header version lower than expected

Ordered Diagnostic Checks

1. Verify file existence and permissions – run from the host OS (e.g., ls -l /path/to/file.dyalog) or via Dyalog: ⎕NA 'fileexists' 'path/to/file.dyalog'. Ensure the process has read/write access.
2. Attempt a quiet load – in a Dyalog session: ⎕FIX 'quiet' 'path/to/file.dyalog'. If the call returns 0, the file can be opened; any non‑zero code indicates a problem.
3. Inspect the file header – ⎕FIX 'info' 'path/to/file.dyalog'. Note the component count, version stamp, and any reported errors.
4. Check for concurrent locks – OS tools (e.g., lsof /path/to/file.dyalog on Unix) or Dyalog’s sharing query: ⎕FX 'share' 'path/to/file.dyalog'. A non‑zero result means another process holds the file.
5. Test a small read/write cycle on a copy – create a temporary copy: ⎕COPY 'path/to/file.dyalog' 'temp.dyalog'. Then try ⎕READ temp.dyalog 1 followed by ⎕REPLACE temp.dyalog 1 ⎕NULL. Success suggests the original corruption is isolated; failure points to deeper damage.

Fixes Tied to Findings

• File merely locked – Close all Dyalog sessions that may have the file open (use ⎕OFF or OS task manager). Retry the ⎕FIX operation.
• Version mismatch in header – Run an upgrade: ⎕FIX 'upgrade' 'path/to/file.dyalog'. Keep a backup of the original file before upgrading, as the change is irreversible.
• Detected damaged components – Extract undamaged parts: ⎕READ 'path/to/file.dyalog' ⍳n where n is the highest good component number from the info output. Create a new file with ⎕CREATE 'new.dyalog' and write each good component back via ⎕REPLACE.
• File beyond repair – Restore from the most recent backup or re‑generate components from source code. If no backup exists, consider the data lost.

Escalation Criteria

Contact Dyalog support when:

• ⎕FIX continues to return error codes after applying the above recovery steps.
• Multiple component files exhibit similar corruption patterns.
• OS logs show I/O errors, filesystem checksum failures, or hardware alerts coinciding with the corruption.

When opening a support ticket, provide the file’s SHA‑256 checksum, the exact Dyalog version (⎕VER), and a minimal script that reproduces the failure.