# a3270

[![Build & Test](https://git.hugfreevikings.wtf/rudi/a3270/actions/workflows/build.yaml/badge.svg)](https://git.hugfreevikings.wtf/rudi/a3270/actions)
[![Android](https://img.shields.io/badge/Android-API%2024%2B%20%7C%20Compose-green.svg)](https://developer.android.com)
[![License: Unlicense](https://img.shields.io/badge/License-Unlicense-blue.svg)](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