User Guide

1. Getting Started

IM3270 is a modern 3270 terminal emulator for connecting to IBM mainframes. It provides a feature-rich experience with split screen, macros, file transfer, and more.

Launching IM3270

• Windows: Launch from Start Menu or desktop shortcut
• Linux: Run im3270 or find in application launcher

Main Interface

• Menu Bar: Access all features (File, Edit, Connection, Transfer, View, Help)
• Tab Bar: Manage multiple terminal sessions
• Terminal Area: Main 3270 display
• Status Bar: Connection status, cursor position, keyboard state
• PF Key Toolbar: Clickable function key buttons (optional)

2. Connecting to a Mainframe

Quick Connect

1. Press Ctrl+N or select File → New Connection
2. Enter the mainframe hostname or IP address
3. Enter the port (default: 23, or 992 for SSL)
4. Optionally enter an LU name
5. Check "Use SSL/TLS" for secure connections
6. Click Connect

Terminal Models

Terminal Types

3. Keyboard Shortcuts

Function Keys

Editing & Navigation

Application

Clipboard & Selection

Paste to Data Area

Use Ctrl+Shift+V to paste multi-line text into the ISPF editor data area, automatically skipping protected line command fields. This is ideal for pasting code or JCL directly into the editor without overwriting line numbers.

4. Connection Profiles

Save your connection settings for quick access.

Creating a Profile

1. Press Ctrl+P to open Profile Manager
2. Click New Profile
3. Enter a profile name and connection details
4. Click Save

Profile Settings

• Host, port, and SSL/TLS settings
• Terminal model (2, 3, 4, or 5)
• Terminal type (IBM-3278 monochrome or IBM-3279 color)
• LU name for console connections

Terminal Type

Choose the terminal type based on your mainframe system:

• IBM-3278 (Monochrome) - Better compatibility with older systems like MVS 3.8j, Hercules, and legacy VTAM configurations
• IBM-3279 (Color) - Modern color terminal, works with most z/OS systems

Tip: If you see a blank/idle screen after connecting, try switching to IBM-3278.

5. Multiple Sessions (Tabs)

Work with multiple mainframe connections simultaneously using tabs.

6. Split Screen PRO

View two sessions side-by-side or stacked. (Requires licensed version)

Clicking on a non-active pane now properly activates it, moving the cursor and keyboard focus to that pane.

Enable Split Screen

1. Right-click a tab
2. Select Split Horizontal or Split Vertical
3. Drag the divider to resize panes

7. File Transfer

Transfer files between your computer and the mainframe using IND$FILE.

Download from Mainframe

1. Select Transfer → Download (or Ctrl+Shift+R)
2. Enter the mainframe dataset name
3. Choose local save location
4. Select transfer mode (Text or Binary)
5. Click Download

Upload to Mainframe

1. Select Transfer → Upload (or Ctrl+Shift+U)
2. Choose local file to upload
3. Enter mainframe dataset name
4. Select transfer mode and options
5. Click Upload

8. Retro CRT Mode

Experience a nostalgic look with classic CRT monitor effects.

Enable CRT Mode

Select View → Retro Terminal and choose Green Phosphor or Amber Phosphor

CRT Effects

• Scanlines simulation
• Screen curvature
• Phosphor glow
• Subtle flicker
• Green or amber phosphor colors

9. Macros

Record and replay sequences of keystrokes for repetitive tasks.

Recording a Macro

1. Press Ctrl+M to start recording
2. Perform the actions you want to record
3. Press Ctrl+M again to stop
4. Enter a name for the macro

Playing a Macro

Press Ctrl+Shift+M and select the macro to play, or assign a keyboard shortcut.

10. JavaScript Scripting

Automate mainframe workflows with JavaScript scripts. IM3270 includes a full-featured script editor with syntax highlighting, autocomplete, and a step-through debugger.

Opening the Script Editor

Press Ctrl+Shift+J to toggle the script editor panel alongside the terminal.

Writing Scripts

The CodeMirror editor provides JavaScript syntax highlighting, bracket matching, and search (Ctrl+F). Type screen., session., script., stats., or console. to get autocomplete suggestions with descriptions.

Available APIs

• screen - getText(), getLine(row), getCursorPosition(), waitForText(text, timeout), waitForKeyboard(timeout)
• session - type(text), send(key), moveTo(row, col), typeAndSend(text, key)
• script - sleep(ms), log(msg), stop(), readFile(path), writeFile(path, content), checkpoint(label)
• stats - get(), reset(), tick(label)
• console - log(msg), warn(msg), error(msg)

Running Scripts

• Ctrl+Enter - Run the current script
• Ctrl+S - Save the current script
• Ctrl+Space - Trigger autocomplete
• Step button - Execute one line at a time
• Pause button - Pause at next checkpoint() call

File Storage

Scripts are saved as .im3270.js files in ~/.im3270/scripts/. You can also import/export scripts and drag-and-drop .js files onto the editor panel.

File I/O

Scripts can read and write text files using script.readFile(path) and script.writeFile(path, content). By default, file access is sandboxed to the scripts folder. You can disable sandboxing in Preferences > Scripting.

Example

await session.type('TSO IBMUSER');
await session.send('ENTER');
await screen.waitForKeyboard();
script.log('Screen: ' + screen.getLine(0));

See the Scripting Guide for full documentation.

11. AI Agent Mode PRO

New in v0.47.0. REXX Driver (IMDRV) new in v0.48.0.

Agent Mode lets you describe what you want in plain English. The AI generates and runs a script on your mainframe session, then explains the results. Requires a Pro license and an active connection.

Opening Agent Mode

Click the robot icon in the toolbar or use View → Agent Mode.

How It Works

1. Type your request in plain English (e.g. "List all datasets starting with CARMI")
2. The AI generates a script and shows its plan
3. Optionally review and approve the script before it runs
4. The script executes on your terminal session
5. The AI explains the results

Configuration

Open Preferences → Agent to set your LLM provider, model, and API key.

Supported Providers

Provider	Default Model	API Key
Anthropic (recommended)	claude-sonnet-4-6	sk-ant-... - console.anthropic.com
OpenAI	gpt-4o	sk-... - platform.openai.com
Google Gemini	gemini-2.0-flash	AIza... - aistudio.google.com
Ollama / local	llama3.1:8b (or any model)	None required; set Base URL to your server

Anthropic (Claude) Models

• claude-haiku-4-5-20251001 - fastest, good quality, lowest cost
• claude-sonnet-4-6 - default, best balance of speed and quality
• claude-opus-4-7 - highest quality for complex tasks

Local / OpenAI-compatible (Ollama, LM Studio, vLLM)

Set Provider to ollama, enter your server's Base URL (default: http://localhost:11434), and enter the model name. No API key needed unless your server requires one.

API Key Setup

Three ways to configure (first non-empty wins):

1. Preferences → Agent - enter interactively; stored in app preferences
2. ~/.config/im3270/setup.json - write before first launch; applied once at startup:

   {"agentApiKey": "sk-ant-...", "agentProvider": "anthropic", "agentModel": "claude-sonnet-4-6"}

3. IM3270_AGENT_API_KEY env var - for enterprise/OEM builds embedded at build time

Agent REXX Driver (IMDRV)

On z/OS systems, the agent can use IMDRV - a REXX dispatcher installed in a PDS on the mainframe. IMDRV provides structured results without screen-scraping ISPF panels, making agent operations faster and more reliable.

Installing IMDRV

Run IMINST.rexx from ISPF option 6. It allocates userid.IM3270.EXEC and installs IMDRV there. Installation takes a few seconds. The installer also writes your API key to ~/.config/im3270/setup.json on your workstation.

IMDRV Functions

LISTDS	List datasets matching a pattern
LISTMBR	List members of a PDS
READFILE	Read a dataset or PDS member
CHECKJOB	Check job status in the output queue
SYSINFO	Return z/OS version and system ID
CLEANUP	Delete temporary work files from the session

The agent detects whether IMDRV is installed and uses it automatically when available, falling back to ISPF panel navigation otherwise.

Stop Button

Click ■ Stop or press ESC in the agent panel to cancel a running agent at any time.

12. Presentation Tools

IM3270 includes features designed for teaching, demos, and screen sharing.

Keystroke Display

Show pressed keys in a corner overlay - perfect for demos and training videos.

• Toggle Display: Ctrl+Shift+Y or View → Show Keystrokes
• Password Mode: Ctrl+Alt+Y - masks keystrokes as "•••" for password fields
• Shows PF keys, PA keys, Enter, Tab, and typed characters
• Combines quick typing into words
• Configure history size (3-10 items) in Preferences

Crosshair Cursor

Full-screen crosshair helps viewers follow cursor position.

• Toggle: Ctrl+Shift+X or View → Crosshair
• Customize color in Preferences

Magnifier

Zoom into any area of the screen for detailed viewing.

• Toggle: Ctrl+G or View → Magnifier
• Hover to magnify, click to lock position
• Configure size (small/medium/large) in Preferences

Pointer Sonar

Find your cursor with animated circles.

• Trigger: Ctrl+Shift+F
• Displays expanding circles around pointer

Pointer Highlight

Persistent glowing ring around pointer for screen sharing.

• Toggle: Ctrl+H
• Ring follows cursor movements

14. Preferences

Customize IM3270 to your liking via Edit → Preferences.

15. Licensing

IM3270 offers a 60-day free trial with most features. After the trial, a license key is required for continued use.

Edition Comparison

Feature	Trial	Personal	Team
Duration	60 days	Perpetual	Perpetual
Price	Free	See pricing	See pricing
Users	1	1	Up to 10
Support	No	Email	Priority
Updates	No	✓	✓
Core Features
Terminal Emulation (3278/3279)	✓	✓	✓
Multiple Sessions (Tabs)	✓	✓	✓
Connection Profiles	✓	✓	✓
File Transfer (IND$FILE)	✓	✓	✓
Macro Recording	✓	✓	✓
Custom Key Mappings	✓	✓	✓
CRT Retro Effects	✓	✓	✓
Pro Features PRO
Split Screen (Side-by-Side)	No	✓	✓
Crosshair Cursor Tracking	No	✓	✓
Magnifier (Zoomed View)	No	✓	✓
Keystroke Display (Presentations)	No	✓	✓

Activating Your License

1. Purchase a license from im3270.infomanta.com
2. You will receive a license key via email
3. In IM3270, go to Help → About
4. Click on the license status area and enter your key
5. Your license is now active

Session Logging

Record all screen output to a file via View → Session Logging. Choose Text or HTML format.

Application Log

IM3270 writes a diagnostic log to ~/.im3270/im3270.log which captures platform info, s3270 version checks, connection events, SSL errors, and backend status. This log is useful for troubleshooting startup and connection issues.

• Help → View Application Log - opens the log file in your default text editor
• Help → Open Log Folder - opens the ~/.im3270/ directory in your file manager

13. Console Output Log

The Console Output Log panel provides real-time monitoring of connection events, errors, warnings, and transfer results. Open it via View → Toggle Console Output Log or press Ctrl+`.

Console Commands

The panel includes a command bar at the bottom. Type a command and press Enter:

help	List all available commands
diagnose	Run log diagnostics (analyzes application log for issues)
status	Show connection status, backend port, keyboard state
tabs	List all open tabs with IP:port and SSL status
port	Show backend listening port
version	Show application version
history	Show recent file transfer history
clear	Clear console output

Use Arrow Up/Down to navigate command history. Press Escape to clear input.

Log Diagnostics

Run diagnostics from Tools → Run Log Diagnostics or type diagnose in the console. The diagnostic checks for: connection timeouts, suspicious IP addresses, unreachable hosts, startup failures, missing s3270, port conflicts, SSL errors, and WebSocket errors. Results are color-coded and also written to the application log.