🖥️ TN3270 Terminal for VS Code

Connect to mainframe TN3270 systems directly from your editor. Open secure, independent TN3270 terminal sessions in VS Code tabs with full EBCDIC support, customizable key sequences, and persistent connection settings.

✨ Features

📑 Multiple Terminal Tabs – Open unlimited independent TN3270 sessions as editor tabs
🔐 Secure Connections – TLS encryption for mainframe communications (configurable TN3270 or encrypted modes)
⚡ High-Performance Rendering – Canvas-based 3270 screen drawing with responsive updates
🎛️ Full TN3270 Protocol Support – EBCDIC character encoding, TN3270E, screen sizes from 24×80 to 62×160+
⌨️ Customizable Key Sequences – Define macro sequences for PF keys and key combinations
💾 Persistent Settings – Save connection defaults (host, port, security) in VS Code settings
🔧 Easy Configuration – Guided terminal creation with optional host/port prompts

🚀 Quick Start

1. Install the Extension

Search for "TN3270 Terminal" in VS Code Extensions (or use ID: tomasdanek.tn3270-terminal)
Click Install

2. Start Your First Connection

Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
Run TN3270: New Terminal
A new TN3270 tab opens with connection settings
Enter your mainframe host, port, and security level
Click Connect

3. Quick Connect with Prompts

Open the Command Palette
Run TN3270: New Terminal to Host...
You'll be prompted for:
- Host: Mainframe IP or hostname
- Port: TN3270 port (default: 23)
- Security: Choose "Encrypted (TLS)" or "Unencrypted (TN3270)"
Terminal opens pre-configured with your settings

⌨️ Commands

Command	Shortcut	Description
`TN3270: New Terminal`	—	Open a terminal tab with default settings
`TN3270: New Terminal to Host...`	—	Open a terminal with prompted host/port/security

⚙️ Configuration

Configure defaults in VS Code Settings or settings.json:

Available Settings

Setting	Type	Default	Description
`tn3270.defaultHost`	string	`localhost`	Default mainframe host (use in non-prompted mode)
`tn3270.defaultPort`	number	`23`	Default mainframe port
`tn3270.defaultSecurity`	enum	`tls`	Security mode: `tls` (encrypted) or `telnet` (unencrypted)
`tn3270.defaultCodepage`	string	`870`	EBCDIC codepage (e.g., 870, 280, 500)
`tn3270.defaultRows`	number	`62`	Terminal rows for dynamic sizing
`tn3270.defaultColumns`	number	`160`	Terminal columns for dynamic sizing
`tn3270.proxyUrl`	string	`ws://localhost:8080/ws`	WebSocket proxy endpoint URL
`tn3270.autoSpawnProxy`	boolean	`false`	Auto-start proxy (requires manual setup)

Example settings.json

{
  "tn3270.defaultHost": "my.mainframe.com",
  "tn3270.defaultPort": 992,
  "tn3270.defaultSecurity": "tls",
  "tn3270.defaultCodepage": "870",
  "tn3270.proxyUrl": "ws://localhost:8080/ws"
}

🏗️ Architecture

The extension uses a WebSocket-to-TCP proxy to bridge your browser-based terminal to the mainframe:

VS Code Editor
    ↓
TN3270 Extension (webview)
    ↓
WebSocket Connection
    ↓
Proxy Server (Node.js)
    ↓
TCP/TLS Connection
    ↓
TN3270 Mainframe Server

🖇️ WebSocket Proxy Setup

The extension requires a WebSocket proxy server. Choose one of these options:

Option A: Manual Proxy (Development)

Start the proxy before opening terminals:

cd path/to/tn3270-ng2/proxy
npm install
node server.js
# Proxy listens on ws://localhost:8080/ws

Option B: Docker (Production Recommended)

cd path/to/tn3270-ng2
docker build -t tn3270-server .
docker run -d -p 8080:8080 tn3270-server

Option C: Remote Proxy

Configure tn3270.proxyUrl to point to a remote proxy:

{
  "tn3270.proxyUrl": "wss://proxy.company.com/tn3270"
}

This supports secure WebSocket (WSS) connections for production environments.

📋 Requirements

VS Code ≥ 1.84.0
WebSocket Proxy Server running at your configured proxyUrl
- Default: ws://localhost:8080/ws
- Or remote: wss://your-proxy.com/path
Node.js ≥ 18.0.0 (only if running proxy locally)

🔍 Troubleshooting

"WebSocket connection failed"

Verify your proxy server is running on the configured URL
Check tn3270.proxyUrl in settings
Ensure firewall allows WebSocket connections

"Connection refused"

Confirm mainframe host and port are correct
Check that TLS/telnet mode matches your mainframe setup
Verify network connectivity to the mainframe

"EBCDIC decoding errors"

Check tn3270.defaultCodepage matches your mainframe
Common codepages: 870 (Czech), 280 (Italian), 500 (International)

📖 Usage

New Terminal – Run TN3270: New Terminal to open a tab with your default settings
Terminal Menu – Click the Connection panel to adjust host/port/security/model
Connect – Click the connect button to initiate the connection
Interact – Type commands; use PF keys displayed in the toolbar
New Tab – Each terminal is independent—open as many as needed

💡 Tip: Use TN3270: New Terminal to Host... for quick connections without editing settings.

📝 License

Eclipse Public License v2.0 (EPL-2.0) — Same as upstream Zowe project

📂 Source And Attribution

The full source code for this extension is available at https://github.com/settti/tn3270.

This extension is derived in part from the Zowe tn3270-ng2 project and redistributes EPL-2.0 licensed code and modifications under the same license. Upstream notices for included EPL-2.0 code are preserved.

🤝 Contributing

Contributions welcome! Report issues or submit PRs on GitHub.

🔗 Resources

Zowe Project: https://www.zowe.org/
TN3270 Protocol: https://en.wikipedia.org/wiki/3270_Emulator
GitHub Repository: https://github.com/settti/tn3270

TN3270 Terminal

Tomas Danek