# a3270

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

---

## ✨ Features

- **Modern Jetpack Compose UI**: Responsive, touch-optimized 3270 terminal screen rendering.
- **TN3270 & TN3270E Protocol Support**: RFC 2355 compliant state machine, negotiation, Device-Type query, and SSL/TLS encryption via `lib3270j`.
- **On-Screen Function Key Bar**: Quick-access touch bar for PF1–PF24, PA1–PA3, Enter, Clear, Reset, and Attn keys.
- **IND$FILE File Transfer**: Full mobile UI for **CUT** and **DFT (DDM)** high-speed structured field file transfers with ASCII/binary translation, CRLF handling, and recfm/lrecl formatting for TSO, VM/CMS, and CICS.
- **OIA Status Line**: Real-time Operator Information Area displaying connection state, keyboard lock, insert mode, cursor row/col, and LU name.
- **Host Profile Storage**: Save and manage multiple mainframe connection profiles with custom ports, models, and SSL/TLS options.
- **Background Session Persistence**: Android foreground service keeps your terminal session alive when multitasking.
- **Terminal Models**:
  - Model 2 (24x80)
  - Model 3 (32x80)
  - Model 4 (43x80)
  - Model 5 (27x132)

---

## 🛠️ 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)

### 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
```

---

## 🏷️ How to Tag & Publish (Beta) Releases

Releases can be published automatically to Gitea via Git tags:

```bash
# 1. Create a version tag (stable or beta)
git tag -a v0.1.0-beta.1 -m "Release v0.1.0-beta.1"

# Or a stable release:
git tag -a v0.1.0 -m "Release v0.1.0"

# 2. Push the tag to Gitea
git push origin v0.1.0-beta.1
```

Pushing any `v*` tag triggers the automated release workflow (`.gitea/workflows/release.yaml`), which:
1. Automatically detects pre-releases (tags containing `beta`, `alpha`, `rc`, `pre`, `preview`, or `dev`) and marks them as **Pre-release** on Gitea.
2. Builds the APK and packages it.
3. Publishes a new Gitea Release with `a3270.apk` attached automatically.

---

## 🔍 Topics & Discoverability

Suggested keywords/topics for repository indexing:
`tn3270` · `tn3270e` · `ibm-3270` · `mainframe` · `terminal-emulator` · `android` · `android-app` · `jetpack-compose` · `kotlin` · `x3270` · `j3270` · `ind-file` · `file-transfer` · `ebcdic` · `z-vm` · `z-os` · `cms` · `tso` · `cics`

---

## 🤝 Contributing

Contributions are welcome! Please feel free to open a bug report or feature request via the Gitea issue tracker.

I have contributed no code to this project, it was entirely written by LLMs with my guidance only.

---

## 📜 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