COMTRAN Language Definition

A structured definition of IBM Commercial Translator (COMTRAN) as it existed historically, prepared for compiler construction.

This document is the working language reference for this repository's compiler project. It defines the source language only: it deliberately contains no compiler architecture, intermediate representations, grammars, or implementation strategy. It is a living reference: correct it against the manuals, never against modern expectations.

This is a reading copy. ../comtran-language-definition.md is canon. That file is larger than the 512 KB limit for Markdown rendering on GitHub, so a browser cannot show it as a document. This directory holds the same text in parts, and each part renders. A generator writes these files. Do not edit them: correct canon, then run dart run tool/generate_definition_mirror.dart.

Sources and authority

Everything here is extracted from the two surviving IBM manuals, converted to Markdown in comtran-manuals/:

Conventions inherited from the conversions: 1960s spellings ("alphameric", "imbedded") and genuine typos are preserved verbatim in quotations; the 1960s literal-delimiting quotation mark (card code 4-8) is rendered as a straight apostrophe '; overpunched digits are rendered by zone: minus with a combining overline (9̅), plus with a superscript plus (9⁺). Paths like images/page-050.png refer to the 150-dpi page scans inside each manual's directory, the ground truth for any disputed reading.

The F/J rule. F28-8043 describes the full language as designed; J28-6169 describes what the January 1962 field-test processor actually accepted, and explicitly defers, restricts, or corrects many F features. Divergences are flagged F/J divergence where they arise and are catalogued in §8. A compiler writer must decide early which language is being implemented: the 1960 design (F) or the 1962 processor language (J); this document treats J as definitive and presents F material as design context and as the base text that J amends.

Where to look

• Ambiguity catalog with resolutions, 69 entries: §8.5, lines 3960–4060.
• Severity codes and message-implied rules: §8.4, lines 3736–3959.
• F28-8043 vs J28-6169 conflicts: §8.3, lines 3598–3735.
• Deferred and removed features (F→J digest): §8.2, lines 3482–3597.
• Questions the manuals do not answer: Open questions, lines 4281–4521.

Contents

1. Character set and lexical conventions
   • 1.1 Character set
   • 1.2 The literal-delimiting quotation mark
   • 1.3 Words and name formation
   • 1.4 Kinds of names
   • 1.5 Compound names (qualification)
   • 1.6 Reserved words: the fixed vocabulary
   • 1.7 Constants and literals
   • 1.8 Operators, punctuation characters, and spacing
   • 1.9 Coding forms, card columns, and continuation
   • 1.10 Summary table of lexical limits
   • 1.11 Conversion caveats relevant to this section
2. Overall program structure and procedure organisation
   • 2.1 The three descriptions (divisions) of a complete program
   • 2.2 Source deck structure: how a program reaches the compiler
   • 2.3 The structural hierarchy: expressions → clauses → sentences → sections → divisions
   • 2.4 Procedure-names: how statements are labeled
   • 2.5 Sections: BEGIN SECTION … END
   • 2.6 Default flow of control and program termination
   • 2.7 Verbs: program verbs vs processor verbs, and the complete inventory
   • 2.8 How procedures connect to the data and environment descriptions
   • 2.9 Program size and structural limits (7090 implementation)
   • 2.10 Ambiguities affecting this section (summary)
3. Data description and storage model
   • 3.1 Files, records, and fields — the data hierarchy
   • 3.2 The *DATA division and the data description card
   • 3.3 Type codes in detail
   • 3.4 The Description field in detail
   • 3.5 Signed-number representation and overpunch
   • 3.6 Mode, justification, and the machine storage model
   • 3.7 Lists, tables, and subscripts (declaration side)
   • 3.8 Record length: fixed vs. variable (storage view)
   • 3.9 Storage areas
   • 3.10 Numeric limits and defaults — summary
   • 3.11 F/J divergences in data description — summary
4. Arithmetic and data-manipulation statements
   • 4.1 Arithmetic expressions
   • 4.2 Modes, precision, and mixed-mode evaluation (709/7090)
   • 4.3 The SET command — arithmetic assignment
   • 4.4 SET used with condition-names
   • 4.5 The ADD command
   • 4.6 The ADD CORRESPONDING command
   • 4.7 The MOVE command
   • 4.8 The MOVE CORRESPONDING command and CORRESPONDING matching rules
   • 4.9 Functions in arithmetic and data-manipulation statements
   • 4.10 Restrictions and limits affecting this section (consolidated)
   • 4.11 Cross-references
5. Control-flow statements
   • 5.1 Default sequential flow and sentence boundaries
   • 5.2 The conditional statement (IF ... THEN ... OTHERWISE)
   • 5.3 Conditional expressions
   • 5.4 The GO TO command
   • 5.5 The DO command
   • 5.6 The STOP command; STOP RUN
   • 5.7 Sections, procedure-names, and structural constraints on transfer targets
   • 5.8 Numeric limits and restrictions bearing on control flow (J)
   • 5.9 Flagged ambiguities (summary)
6. Input/output and report-generation facilities
   • 6.1 The file model: record, file, block, buffer
   • 6.2 Locate and Transmit modes
   • 6.3 Record types and variable-length record options
   • 6.4 The OPEN command
   • 6.5 The GET command
   • 6.6 The FILE command
   • 6.7 The CLOSE command and CLOSE ALL FILES
   • 6.8 Labels and non-standard label processing
   • 6.9 The DISPLAY command
   • 6.10 The LOAD command (and OVERLAP) — deferred
   • 6.11 The worked examples of J 02.07.F
   • 6.12 Report generation: what exists and what does not
   • 6.13 Environment-card summary for I/O (cross-reference to §7)
   • 6.14 Ambiguities flagged in this section
7. Special facilities and library conventions
   • 7.1 The Environment Description (J 02.06)
   • 7.2 Compiler control cards ($CMPLE, *FINISH) (J 02.01)
   • 7.3 The library system — COPY, LIBRARY, INCLUDE (F design; deferred in J)
   • 7.4 Program segmentation — OVERLAP and LOAD (F design; deferred in J)
   • 7.5 Renaming and linkage — CALL, ENTER, CONTRL
   • 7.6 Commentary conventions — NOTE and the period-blank rule
   • 7.7 The CRYPT facility — 709/7090 machine symbolic language (J 02.08)
   • 7.8 F/J divergence summary for this section
8. Known ambiguities, underspecified behaviour, and plausible resolutions
   • 8.1 Status of the sources
   • 8.2 The F→J delta: complete digest of J Appendix 90.01 (deferred features, restrictions, limitations)
   • 8.3 F28-8043 vs J28-6169: contradictions and divergences
   • 8.4 The severity-code system and rules implied by the diagnostics (J Appendix 90.04)
   • 8.5 Consolidated ambiguity catalog, with plausible resolutions
9. Sample-program observations that illuminate the language
   • 9.1 Program-level structure as practiced
   • 9.2 Coding-form usage in practice
   • 9.3 Data description in practice
   • 9.4 Environment description as actually written (J only)
   • 9.5 Procedure idioms, verb by verb
   • 9.6 What the compilation listing reveals about the source language
   • 9.7 What the execution output reveals
   • 9.8 Consolidated F-sample vs J-sample divergence table
   • 9.9 Flagged ambiguities (details in §8.5)

• Open questions
  • Lexical
  • Program structure and control cards
  • Data description and storage model
  • Arithmetic and data manipulation
  • Control flow
  • Input/output
  • Environment, library, and system
  • Sample-program loose ends