158 lines
8.1 KiB
Markdown
158 lines
8.1 KiB
Markdown
# a3270
|
||
|
||
[](https://git.hugfreevikings.wtf/rudi/a3270/actions)
|
||
[](https://developer.android.com)
|
||
[](LICENSE)
|
||
|
||
An **x3270-aligned IBM 3270 mainframe terminal emulator for Android**, written in Kotlin using **Jetpack Compose** and powered by the `lib3270j` protocol engine from [j3270](https://git.hugfreevikings.wtf/rudi/j3270). Designed for mobile access to IBM z/OS, z/VM, CMS, and TSO systems over TN3270 and TN3270E.
|
||
|
||
---
|
||
|
||
## 🔗 Repositories
|
||
|
||
- **a3270 (Android App)**: https://git.hugfreevikings.wtf/rudi/a3270
|
||
- **j3270 (Desktop App & `lib3270j` Core Library)**: https://git.hugfreevikings.wtf/rudi/j3270
|
||
|
||
`a3270` relies on the shared 3270 protocol library (`lib3270j`) provided by the `j3270` repository.
|
||
|
||
---
|
||
|
||
## 🚀 Quick Download & Install
|
||
|
||
### Latest Standalone APK
|
||
You can download ready-to-install Android APKs directly from releases or CI builds:
|
||
|
||
- **[Download Latest Tagged Release (`a3270.apk`)](https://git.hugfreevikings.wtf/rudi/a3270/releases)**
|
||
- **[Latest Nightly CI Artifacts](https://git.hugfreevikings.wtf/rudi/a3270/actions)** (Download under the latest successful workflow run)
|
||
|
||
### Installing `a3270`
|
||
To install the APK on a connected Android device or emulator via `adb`:
|
||
|
||
```bash
|
||
adb install -r a3270.apk
|
||
```
|
||
|
||
---
|
||
|
||
## 📱 Compatibility & System Requirements
|
||
|
||
- **Minimum Android Version**: Android 7.0 (Nougat) — **API Level 24** (`minSdk 24`)
|
||
- **Target Android Version**: Android 14 — **API Level 34** (`targetSdk 34`)
|
||
- **Compile SDK**: **API Level 34** (`compileSdk 34`)
|
||
- **Architecture**: Universal — pure Kotlin/Java running on ART, fully compatible with all CPU ABIs (`arm64-v8a`, `armeabi-v7a`, `x86`, `x86_64`)
|
||
- **Form Factors**: Adaptive UI scaling optimized for smartphones, foldables, tablets, and Chromebooks (Android runtime)
|
||
- **Input Devices**: Full touch-screen support, native virtual keyboards, and external physical/Bluetooth keyboards
|
||
|
||
---
|
||
|
||
## ✨ Features
|
||
|
||
### 🖥️ Terminal Emulation & Protocol
|
||
- **RFC 2355 TN3270 & TN3270E Engine**: Robust state machine, Option Negotiation, Device-Type Query, and LU name specification powered by `lib3270j`.
|
||
- **Standard & Dynamic Terminal Models**:
|
||
- Model 2 (24 × 80)
|
||
- Model 3 (32 × 80)
|
||
- Model 4 (43 × 80)
|
||
- Model 5 (27 × 132)
|
||
- **Dynamic Screen Dimensions**: Configurable custom geometry (rows & columns up to 255 × 255).
|
||
- **EBCDIC Code Pages**: Full character translation across international code pages (037, 1047, 500, etc.).
|
||
|
||
### 📊 Graphics & Peripherals
|
||
- **GDDM & GOCA Graphics**: Native rendering of Programmed Symbols (PS) and GOCA vector graphics directly in the Compose canvas.
|
||
- **Light Pen Simulation**: Interactive touch support to simulate light pen selection and graphic cursor pick correlation.
|
||
- **IBM 3287 Printer Emulation**: Integrated printer session support for spool/report capture (via associated display LU or dedicated printer LU) with direct printing through Android PrintManager (PDF export / system print).
|
||
|
||
### 📁 IND$FILE File Transfer
|
||
- Full mobile UI supporting both **CUT** and **DFT (DDM)** high-speed structured field transfers.
|
||
- Compatible with **TSO**, **VM/CMS**, and **CICS** environments.
|
||
- ASCII/binary translation, CRLF conversions, and configurable record format (`recfm`), record length (`lrecl`), and allocation units.
|
||
|
||
### 🔍 Developer & Productivity Tools
|
||
- **Field Inspector**: Live interactive inspector displaying start/end addresses, length, protection, numeric status, MDT (Modified Data Tag), display intensity, and extended highlighting/color, with one-tap "Jump to Field".
|
||
- **Screen Search / Find**: On-screen text search with case sensitivity, forward/backward navigation, and visual match highlighting.
|
||
- **Screen Exporter**: Export the current screen buffer to **Plain Text**, formatted **HTML**, or **PNG image**, with one-tap clipboard copy and Android system share sheet integration.
|
||
- **Script & Macro Automation**: Built-in script runner supporting automated keystroke and wait sequences (e.g. `[enter]`, `[wait]`, `[tab]`) for login macros and repetitive tasks.
|
||
|
||
### ✍️ Entry Assist & Typing Modes
|
||
- **Document (DOC) Mode**: Configurable left/right margins, custom tab stops, and end-of-line bell warning.
|
||
- **Word Wrap**: Automatic word wrapping across lines during input.
|
||
- **APL Mode**: Support for APL extended character sets and symbols.
|
||
- **Field Handling**: Automatic field skip (Auto-Skip), Numeric field lock, and Insert Mode auto-reset on AID transmission.
|
||
|
||
### 🎨 Display, Themes & Ergonomics
|
||
- **Jetpack Compose UI**: Smooth, hardware-accelerated 3270 terminal screen rendering with touch-to-position cursor.
|
||
- **Color Themes**: Light and Dark application themes, 3270 extended color support, and 4-color legacy override mode.
|
||
- **Cursor Customization**: Block and Underline cursor styles with toggleable blinking.
|
||
- **Crosshair Ruler**: Toggleable horizontal and vertical ruler lines following the cursor for easy data tracking.
|
||
- **Block Selection**: Rectangular text selection and copy mode.
|
||
- **OIA Status Line**: Real-time Operator Information Area displaying connection status, keyboard lock, insert mode, cursor row/col, LU name, and inhibit reason codes.
|
||
|
||
### 🔒 Security, Networking & Storage
|
||
- **SSL / TLS Encryption**: Secure encrypted mainframe sessions with TLS certificate verification.
|
||
- **Interactive Untrusted Certificate Prompt**: Inspect SSL certificates, view full certificate chain details, and accept/reject unverified connections.
|
||
- **Proxy Support**: Connect via HTTP CONNECT, SOCKS4, SOCKS5, and Telnet proxies with optional user/password authentication.
|
||
- **Background Session Persistence**: Android foreground service (`specialUse`) keeps your terminal TCP connection alive with status notifications when multitasking or screen is off.
|
||
- **Host Profile Manager & INI Export**: Save multiple mainframe profiles, configure auto-connect on launch, and export/import configuration in INI format (interoperable with desktop `j3270`).
|
||
|
||
### ⌨️ Input & Keyboards
|
||
- **On-Screen Function Key Bar**: Two-row responsive touch bar providing PF1–PF24, PA1–PA3, Enter, Clear, Reset, Attn, SysReq, Erase EOF, Erase Input, Tab, BackTab, and D-pad cursor controls with haptic feedback.
|
||
- **Termux-Style Native Input**: Low-latency native input connection with permanent number row and lock protection against soft-keyboard resets.
|
||
- **Hardware Keyboard Support**: Complete physical keyboard integration with F1–F12 (mapped to PF1–PF12 / PF13–PF24 with Shift/Alt), Ctrl shortcuts, dead keys, and international character input.
|
||
|
||
---
|
||
|
||
## 🛠️ Building from Source
|
||
|
||
### Prerequisites
|
||
- **Java Development Kit (JDK)**: JDK 17 or JDK 21
|
||
- **Android SDK**: API 34 platforms and build-tools (`ANDROID_HOME` or `ANDROID_SDK_ROOT` set)
|
||
- **Minimum Target Device**: Android 7.0+ (API 24+)
|
||
|
||
### 1. Clone Repositories Side-by-Side
|
||
For the easiest setup, clone both `j3270` and `a3270` into the same parent folder:
|
||
|
||
```bash
|
||
git clone https://git.hugfreevikings.wtf/rudi/j3270.git
|
||
git clone https://git.hugfreevikings.wtf/rudi/a3270.git
|
||
cd a3270
|
||
```
|
||
|
||
> **Note:** If `j3270` is located in another directory, specify its location via the `J3270_DIR` environment variable:
|
||
> ```bash
|
||
> export J3270_DIR=/path/to/j3270
|
||
> ```
|
||
> or via Gradle property:
|
||
> ```bash
|
||
> ./gradlew assembleDebug -Pj3270Dir=/path/to/j3270
|
||
> ```
|
||
|
||
### 2. Build the Debug APK
|
||
Using the helper script:
|
||
```bash
|
||
./build.sh
|
||
```
|
||
|
||
Or using Gradle Wrapper directly:
|
||
```bash
|
||
./gradlew assembleDebug
|
||
```
|
||
|
||
The compiled APK will be generated at:
|
||
```
|
||
build/outputs/apk/debug/a3270-debug.apk
|
||
```
|
||
|
||
---
|
||
|
||
## 📜 Acknowledgements
|
||
|
||
- [j3270](https://git.hugfreevikings.wtf/rudi/j3270) — Desktop emulator and `lib3270j` protocol engine
|
||
- [x3270](https://x3270.miraheze.org/wiki/Main_Page) — Reference C implementation and protocol specifications
|
||
- [Antigravity](https://antigravity.google)
|
||
- Claude Opus 4.6
|
||
- Gemini 3.1 Pro
|
||
- Gemini 3.7 Flash
|
||
- Gemma4 12B and 26B
|
||
- GPT-OSS 120B
|
||
- Qwen3 4B and 32B
|