Introduction
Background
Q3270 is a TN3270 terminal emulator for accessing IBM mainframe computers running MVS, z/OS, VM/CMS and related operating systems. It is built using the Qt framework and runs on Linux and macOS.
The name Q3270 reflects both its Qt heritage and its purpose: a Qt-based 3270 terminal emulator.
"Emulator" is an interesting term — some refer to programs like this as Emulators, Simulators, TN3270 Clients, or simply Clients. Q3270 uses the term Emulator.
Q3270 was inspired by x3270, with the goal of providing a more modern user experience. It has been used successfully with:
- MVS 3.8j and VM/370 running under the Hercules mainframe emulator
- IBM's Z xPlore environment running z/OS 3.1
- z/OS 3.2 running on z16
It is developed using QtCreator and QtDesigner.
This document does not describe what a 3270 terminal is, nor how to operate one. It is expected that the reader is familiar with IBM mainframe systems.
Colour Heritage
Q3270 supports the 7-colour field attribute model used on the later IBM 3278 type terminals. The standard palette — blue, red, pink, green, turquoise, yellow and white — is fully supported, and colour themes allow these to be customised to suit personal preference.
Platform Support
| Platform | Status |
|---|---|
| Linux (X11 and Wayland) | Primary development platform |
| macOS | Supported |
| Windows | Not tested |
Dependencies
Q3270 requires Qt 5.15 or later, including the QtSvg module.
Installation
Linux
Install Qt development libraries via your package manager, then build from source.
Ubuntu/Debian:
Fedora:
openSUSE:
Arch Linux:
Then build:
macOS
Q3270 is available via Homebrew:
Getting Started
When Q3270 is launched without any auto-start sessions configured, the main window appears with no active connection. From here you can open a saved session, create a new connection via the Session menu, or configure auto-start sessions for hosts you connect to regularly.
Sessions
In Q3270, a Session is a named configuration for a particular host. Each session stores the host address and port, terminal size and characteristics, font, colour theme, and keyboard mapping. This allows you to maintain separate configurations for different hosts — for example, one session for a local Hercules MVS system and another for IBM's Z xPlore environment.
Menu Reference
File Menu
The File menu handles session files.
New Window opens an additional Q3270 window, allowing you to connect to the same or a different host simultaneously.
Recent Sessions shows a list of recently used sessions for quick access.
Open Session opens a previously saved session, connecting to the host specified in that session's configuration.
Save Session saves the current session settings, overwriting the previously saved version. This option is only available once a session has been saved at least once.
Save Session As saves the current connection as a new session, or saves the current session under a new name.
Quit closes Q3270.
Open Session
Selecting a session from the list will apply its saved settings and connect to the configured host.
Save Session As
Enter a session name and description, or click an existing session to use it as a starting point, then click OK. If you use the name of an existing session, Q3270 will ask you to confirm before overwriting it.
Session Menu
The Session menu controls the connection to the host.
Connect attempts to connect to the host specified in the session preferences. If no host has been configured, the Preferences dialog is shown first.
Disconnect terminates the current connection.
Preferences opens the session preferences dialog. See the Preferences section below for full details.
Manage Menu
The Manage menu provides access to global application settings and session management features.
Sessions manages the list of saved sessions.
Auto Start Sessions configures sessions that launch automatically when Q3270 starts. This is useful if you regularly connect to one or more hosts — Q3270 can establish those connections without manual intervention each time it is launched. Multiple auto-start sessions are supported for users who need connections to several hosts on startup.
Keyboard Maps opens the keyboard mapping editor. Keyboard maps are global to the application; each session selects which map to use. See the Keyboard Mapping section for details.
Colour Themes opens the colour theme editor. Colour themes are global to the application; each session selects which theme to use. See the Colour Themes section for details.
View Menu
Show Toolbar toggles the toolbar on and off.
Preferences
The Preferences dialog configures settings for the current session. It is opened via Session → Preferences, and contains several tabs.
Connection Tab
The Connection tab specifies the host to connect to. The target can be a hostname or IP address. If the host uses a non-standard port (for example, Hercules with MVS 3.8j defaults to port 3270 rather than the standard TN3270 port 23), this can be overridden here. An optional LU name can be used to connect to a specific logical unit on the host, such as an MVS console.
Under the Security section, Secure Connection enables SSL/TLS for the connection. Verify Certificates controls whether Q3270 accepts only certificates forming a valid certificate chain. If you are connecting to a host using a self-signed certificate, leave this option unselected.
Note: Disabling certificate verification means your connection may be susceptible to interception. Only disable this when you are confident in the security of your network path.
Terminal Tab
The Terminal tab controls the characteristics of the terminal connection.
Terminal Model specifies the alternate screen size. The default screen size is 24×80. Larger models provide an alternate screen size that host applications can switch to. Note that not all applications make use of alternate screen sizes.
Q3270 supports the Query Partition 3270 structured field, which allows the host to interrogate the terminal's capabilities. The Dynamic terminal type allows you to specify custom dimensions for the alternate screen. Note that some applications impose their own limits — ISPF supports a maximum of 84×160, for example.
The terminal model can only be changed while disconnected, as the model is negotiated with the host when the connection is established.
Stretch screen to fit window (enabled by default) expands the terminal display to fill the window, ignoring aspect ratio. Disabling this option restores a 4:3 aspect ratio, which may leave a border around the terminal display.
Terminal Code Page controls how international EBCDIC characters are displayed. For example, code page 285 (United Kingdom) renders the dollar sign ($) as a pound sign (£).
Cursor Settings controls cursor appearance. By default the cursor inherits the colour of the underlying field, changing colour as it moves around the screen. Unticking Inherit uses a fixed grey cursor instead. Cursor blinking can be switched off or slowed using the adjacent options.
Ruler toggles the on-screen ruler, which is displayed as white lines. The ruler can be shown as crosshairs, or as vertical or horizontal lines only.
Tweaks modifies terminal behaviour relative to the original 3270 specification.
The Delete key option controls whether the Delete key (which removes the character under the cursor and shifts remaining characters back) operates across display lines when a field spans multiple lines. By default this is disabled, matching original 3270 behaviour.
The Backspace option controls whether the Backspace key can move the cursor back beyond the start of the current field. By default this is prevented, matching original 3270 behaviour.
Colour Tab
The Colour tab allows you to select which colour theme this session uses. Colour themes are configured globally via Manage → Colour Themes.
Keyboard Tab
The Keyboard tab allows you to select which keyboard map this session uses. Keyboard maps are configured globally via Manage → Keyboard Maps.
Colour Themes
Colour themes control how 3270 field attributes are rendered on screen. Q3270 supports the 7-colour palette of the IBM 3179 terminal — blue, red, pink, green, turquoise, yellow and white — and themes allow each of these to be mapped to any colour you choose.
Themes are global to the application and are selected per session. Multiple themes can be defined, allowing different visual styles for different sessions or hosts.
Keyboard Mapping
Q3270 allows the keyboard to be fully remapped to suit personal preference or to match the layout of other 3270 emulators you may be familiar with. Keyboard maps are global to the application and are selected per session.
Known Limitations
Q3270 is actively developed. The following features are not yet implemented:
- IND$FILE file transfer
- Macro and scripting support
- Codepage support is currently limited to IBM-037, IBM-1047 and IBM-285
- Printer session support
- Some less common 3270 field attributes (Field Mark, Dup, mandatory entry, trigger fields)
See the project backlog for the current development priorities.
Licence
Q3270 is released under the BSD 3-Clause licence. See the LICENSE file for full details.
