An interactive, educational simulator for IBM System/370 & z/Architecture High Level Assembler (HLASM).
Built as a playful, visual retro-computing laboratory to sit alongside modern CS compiler projects.
Zero install required: Runs 100% in your browser on desktop & mobile with instant step-by-step execution.
πΉ High-definition video available at
docs/demo.webm.
The recorded demonstration shows:
- Selecting Mission 1: The Register Ledger and inspecting the briefing.
- Typing the HLASM solution in the editor (
LR,AR,SR). - Assembling the bytecode with real-time symbol resolution.
- Stepping through instructions with Time-Travel (Undo) support, observing
R15register updates and 2-bit Condition Code changes. - Verifying the solution against automated assertions with celebratory confetti.
- Switching to the IBM SYSPRINT Assembly Listing view and testing the Amber CRT theme and Architecture Deep Dive.
Over 70% of Fortune 500 financial transactions and banking core ledgers still process on IBM Z mainframes. Yet 99% of modern software engineers have never encountered:
- Base-Displacement Addressing (
D(X,B)) instead of flat 64-bit pointers - Hardware Packed Decimal (BCD) that eliminates floating-point rounding errors (
0.1 + 0.2 === 0.3) - Storage-to-Storage (SS) string moves that bypass CPU registers entirely
- EBCDIC character encoding and 2-bit Condition Codes
IBM Mainframe HLASM Lab turns this legendary, often intimidating architecture into an approachable, visual, browser-based playground with guided educational missions, step-by-step execution, and full time-travel (undo) debugging.
- Authentic Two-Pass Assembler:
- Generates real IBM bytecode from HLASM source statements.
- Location Counter (
LOC), Symbol Table resolution, and automatic Base Register binding (BALR R12,0+USING *,R12). - Emits full IBM
SYSPRINTAssembly Listings with Hex Object Code side-by-side with source code.
- Mainframe Virtual CPU & Memory:
- 16 General Purpose Registers (R0 - R15): 32-bit signed/unsigned registers with delta change highlights.
- Program Status Word (PSW): Real-time 2-bit Condition Code meter (
0=Equal,1=Low,2=High,3=Overflow). - 64 KB Big-Endian Storage: Hex dump viewer + live IBM Code Page 037 EBCDIC character translation.
- Memory Delta Tracking: Visual pulse animations showing exact read/write memory ranges per instruction.
- Time-Travel Step-Back Debugging:
- Step forward (
F10) or step backward in time with full CPU/register/memory undo snapshots.
- Step forward (
- 5 Progressive Educational Missions ("Mainframe Cadet"):
- The Register Ledger: Warmup with R0-R15 and Register-to-Register (
LR,AR,SR) math. - The Anchor: Understanding base-displacement addressing and the sacred
USING *,12. - The 1964 EBCDIC String Transfer: Storage-to-Storage (
MVC) memory manipulation. - The Banker's Penny: Eliminating financial rounding errors using
PACK,AP, andUNPK. - The Tape Audit Loop: Sequential batch processing with
LA, index offsets, and Branch on Count (BCT).
- The Register Ledger: Warmup with R0-R15 and Register-to-Register (
- IBM 3270 CRT Aesthetics:
- Authentic terminal look with selectable Green, Amber, or Cyan phosphor modes.
- Optional CRT horizontal scanline shader overlay.
- Live architecture explainer drawer breaking down instruction mechanics in plain English.
Mainframe instructions allocate only 12 bits for a displacement (
BALR R12,0 * Load PC into R12
USING *,R12 * Register 12 is base anchor
L R2,MYVAL * Load memory into R2
ST R2,RESULT * Store register to RAM
MYVAL DC F'100'
RESULT DS FIn JavaScript or Python, 0.1 + 0.2 produces 0.30000000000000004. In banking, this is illegal. Mainframes use Packed Decimal:
PACK P_BAL(3),Z_BAL(4) * Convert zoned EBCDIC to packed BCD
PACK P_DEP(3),Z_DEP(4) * 2 digits per byte + sign nibble
AP P_BAL(3),P_DEP(3) * Exact base-10 addition
UNPK Z_OUT(4),P_BAL(3) * Convert back to display stringBranching does not check disparate flags. The Program Status Word tracks a 2-bit CC:
0: Equal / Zero / No Overflow1: First operand Low / Negative2: First operand High / Positive3: Arithmetic Overflow
mainframe-assembly-lab/
βββ docs/
β βββ demo.webm # Recorded video demonstration
β βββ screenshots/ # High-resolution application screenshots
βββ src/
β βββ core/
β β βββ assembler.ts # 2-pass HLASM parser & bytecode generator
β β βββ cpu.ts # Virtual CPU (16 GPRs, PSW, 64KB memory)
β β βββ ebcdic.ts # IBM CP037 <-> ASCII translation tables
β β βββ packedDecimal.ts # Hardware BCD PACK, UNPK, AP, SP engine
β β βββ challenges.ts # 5 educational missions & test harness
β β βββ engine.test.ts # Core engine Vitest unit tests
β β βββ challenges.test.ts # Mission validation test suite
β βββ components/
β β βββ Header.tsx # Brand, mode toggle, phosphor CRT themes
β β βββ CodeEditor.tsx # HLASM editor with line numbers & active PC
β β βββ RegisterGrid.tsx # R0-R15 grid with hex/dec toggle
β β βββ PSWDisplay.tsx # Instruction Counter & 2-bit CC meter
β β βββ MemoryViewer.tsx # Hex dump + EBCDIC character viewer
β β βββ InstructionExplainer.tsx # Real-time architectural callout
β β βββ MissionPanel.tsx # Guided challenge runner with assertions
β β βββ ArchitectureModal.tsx # Interactive deep-dive guide
β βββ App.tsx # Main simulation workbench
β βββ index.css # CRT scanlines & phosphor themes
# Clone the repository
git clone https://github.com/assafbar2/mainframe-assembly-lab.git
cd mainframe-assembly-lab
# Install dependencies
bun install # or npm install
# Run development server
bun dev # or npm run dev# Run all 17 unit tests (Assembler, CPU, BCD, Missions)
bun test # or npm test# Generate optimized production bundle
bun run build # or npm run build| Type | Instruction | Name | Description |
|---|---|---|---|
| RR | LR, AR, SR, MR, DR, CR, XR, NR, OR |
Register Math | 32-bit register arithmetic, logic, and multiply/divide |
| RR | BCR, BR, BER, BNER, BLR, BHR, BALR |
Branch Register | Branch to register or call subroutine |
| RX | L, ST, A, S, C, LA, LH, STH, AH, SH |
Storage/Register | Memory access via Base-Displacement D(X,B) |
| RX | BC, B, BE, BNE, BL, BH, BNL, BNH, BZ, BCT |
Branch Storage | Conditional jump or loop counter decrement |
| SI | MVI, CLI, NI, OI, XI |
Storage Immediate | 1-byte immediate assignments and bitwise operations |
| SS | MVC, CLC |
Storage to Storage | Character copy and compare up to 256 bytes |
| SS | PACK, UNPK, AP, SP, CP |
Packed Decimal | Financial arithmetic with hardware decimal precision |
| Pseudo | CSECT, USING, DROP, DC, DS, EQU, END |
Directives | Symbols, memory definitions, base anchors |
MIT Β© Assaf Barnir







