ibm5250 0.1.0.dev8__tar.gz → 0.1.0.dev9__tar.gz

{ibm5250-0.1.0.dev8 → ibm5250-0.1.0.dev9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ibm5250
-Version: 0.1.0.dev8
+Version: 0.1.0.dev9
 Summary: IBM 5250 terminal automation library
 License-File: LICENSE
 Requires-Python: >=3.11

{ibm5250-0.1.0.dev8 → ibm5250-0.1.0.dev9}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ibm5250"
-version = "0.1.0.dev8"
+version = "0.1.0.dev9"
 description = "IBM 5250 terminal automation library"
 requires-python = ">=3.11"
 

{ibm5250-0.1.0.dev8 → ibm5250-0.1.0.dev9}/src/ibm5250/__init__.py

@@ -35,6 +35,9 @@ from .datastream import (
     DSEventType,
     FieldResponse,
     build_aid_response,
+    build_save_screen_response,
+    decode_save_screen_fields,
+    decode_save_screen_image,
     ebcdic_decode,
     ebcdic_decode_stripped,
     ebcdic_encode,
@@ -81,6 +84,9 @@ __all__ = [
     "DSEventType",
     "FieldResponse",
     "build_aid_response",
+    "build_save_screen_response",
+    "decode_save_screen_image",
+    "decode_save_screen_fields",
     # EBCDIC helpers
     "ebcdic_encode",
     "ebcdic_decode",

{ibm5250-0.1.0.dev8 → ibm5250-0.1.0.dev9}/src/ibm5250/connection.py

@@ -26,7 +26,6 @@ from dataclasses import dataclass
 
 from .constants import (
     AID,
-    Command,
     TelnetCmd,
     TelnetOpt,
     TN5250EDataType,
@@ -62,6 +61,9 @@ _TN5250E_ATTN_FLAG = 0x40
 # host will run its Attention program (e.g. the System Request / Assist menu).
 _TN5250E_OP_CANCEL_INVITE = 0x0A
 
+# Byte 9 operation code for the Save Screen response record (RFC 2877 §4.3).
+_TN5250E_OP_SAVE_SCREEN_RESPONSE = 0x04
+
 _MAX_NEG_PASSES = 40  # Maximum Telnet option exchange iterations during negotiation
 
 
@@ -71,19 +73,14 @@ _MAX_NEG_PASSES = 40  # Maximum Telnet option exchange iterations during negotia
 
 _TN5250E_HEADER_LEN = 10
 
-# The header splits into a 6-byte fixed part (length, GDS id, flow type) and a
-# variable-length part whose length is given by byte 6 -- so the 5250 payload
-# begins at ``6 + header[6]`` (normally 6 + 4 = 10).
+# The 5250 payload starts after the fixed ten-byte TN5250E header. Byte 9 is
+# the per-direction sequence number, not a variable-header length.
 _TN5250E_FIXED_HEADER_LEN = 6
 
 
 def _payload_offset(frame: bytes) -> int:
     """Return the offset of the 5250 payload within a TN5250E *frame*."""
-    offset = _TN5250E_FIXED_HEADER_LEN + frame[_TN5250E_FIXED_HEADER_LEN]
-    if not _TN5250E_HEADER_LEN <= offset <= len(frame):
-        # Malformed variable-header length; fall back to the standard 10 bytes.
-        return _TN5250E_HEADER_LEN
-    return offset
+    return _TN5250E_HEADER_LEN
 
 
 @dataclass
@@ -113,7 +110,7 @@ class TN5250EHeader:
                     self.data_type,  # 6: data type
                     0x00,  # 7: request/response
                     self.err_flag,  # 8: error recovery
-                    var_len,  # 9: variable header length
+                    var_len,  # 9: operation code (var-header length; 3 = Put/Get)
                 ]
             )
             + var_hdr
@@ -337,21 +334,28 @@ class TN5250Connection:
         frame = _build_tn5250e_frame(req_resp=0x00, opcode=_TN5250E_OP_CANCEL_INVITE)
         self._send_frame(frame, description="Sending Cancel-Invite response")
 
-    def send_save_screen_response(self, save_id: bytes) -> None:
+    def send_save_screen_response(self, screen_data: bytes) -> None:
         """Send the TN5250E-level Save Screen acknowledgment.
 
         When the server issues an ESC+SAVE_SCREEN (0x04 0x02) command the
-        terminal must reply with a matching TN5250E frame whose variable header
-        encodes ESC + RESTORE_SCREEN + a two-byte identifier for the screen it
-        just saved.  The host stores that identifier and echoes it back in the
-        Restore Screen command when it wants that particular screen displayed
-        again, so every save must use a distinct *save_id*.
+        terminal replies with a complete, serialized presentation space. The
+        host stores this opaque regeneration buffer and returns it in a later
+        Restore Screen command.
+
+        Parameters
+        ----------
+        screen_data:
+            A complete length-prefixed Restore Screen response produced by the
+            datastream encoder.
         """
         if not self._tn5250e_active:
             return  # save/restore handshake only occurs in TN5250E mode
 
-        var_hdr = bytes([Command.ESC, Command.RESTORE_SCREEN]) + bytes(save_id)
-        frame = _build_tn5250e_frame(req_resp=0x00, opcode=len(var_hdr), var_hdr=var_hdr)
+        frame = _build_tn5250e_frame(
+            req_resp=0x00,
+            opcode=_TN5250E_OP_SAVE_SCREEN_RESPONSE,
+            var_hdr=screen_data,
+        )
         self._send_frame(frame, description="Sending Save Screen response")
 
     def recv_record(self) -> bytes:
@@ -772,7 +776,7 @@ def _iac_escape(data: bytes) -> bytes:
 
 
 def _build_tn5250e_frame(*, req_resp: int, opcode: int, var_hdr: bytes = b"") -> bytes:
-    """Build an IAC-EOR-terminated TN5250E frame with no 5250 payload.
+    """Build an IAC-EOR-terminated TN5250E frame with an optional 5250 payload.
 
     Produces the fixed 10-byte header (RFC 2877 §3.3) followed by an optional
     variable header, IAC-escapes it, and appends the IAC-EOR record terminator.
@@ -784,7 +788,7 @@ def _build_tn5250e_frame(*, req_resp: int, opcode: int, var_hdr: bytes = b"") ->
     req_resp:
         Byte 7 (request/response flags) — e.g. the Attn flag.
     opcode:
-        Byte 9 (operation code / variable-header length).
+        Byte 9 operation code (RFC 2877 §4.3) — how the host identifies the record.
     var_hdr:
         Optional variable-header bytes appended after the fixed header.
     """
@@ -800,7 +804,7 @@ def _build_tn5250e_frame(*, req_resp: int, opcode: int, var_hdr: bytes = b"") ->
             TN5250EDataType.INPUT,  # 6: data type (workstation → host)
             req_resp,  # 7: request/response flags
             0x00,  # 8: error recovery
-            opcode,  # 9: opcode / variable-header length
+            opcode,  # 9: operation code
         ]
     )
     return _iac_escape(header + var_hdr) + bytes(

{ibm5250-0.1.0.dev8 → ibm5250-0.1.0.dev9}/src/ibm5250/data-stream-logic.md

@@ -38,11 +38,13 @@ The **TN5250Connection** manages the TCP socket to the IBM i (AS/400) host.
 ### Save Screen Response (`send_save_screen_response`)
 
 When the server issues a SAVE_SCREEN command, the terminal must reply with a
-TN5250E-framed acknowledgment carrying `ESC + RESTORE_SCREEN + a two-byte
-identifier`. This tells the server "I've saved the screen under this name; you
-can now overlay it." **Every save must use a distinct identifier** — the server
-stores it and echoes it back later to say _which_ saved screen it wants
-restored. See [Save/Restore Screen Flow](#saverestore-screen-flow).
+TN5250E-framed record carrying `ESC + RESTORE_SCREEN + a two-byte length + the
+current presentation space`. The image is freshly serialized from the current
+screen model: geometry, cursor/home positions, the complete character/attribute
+plane, and the field table. Host-to-terminal WTD, Clear Unit, and Read commands
+are never replayed. The host stores this opaque regeneration buffer and returns
+it in a later Restore Screen command. See
+[Save/Restore Screen Flow](#saverestore-screen-flow).
 
 ---
 
@@ -130,12 +132,19 @@ terminator for the variable-length part of an SF order.
   after SF is then the attribute.
 - The **FFW** (Field Format Word) defines field behaviour — bypass/input,
   keyboard shift, mandatory entry, and so on. Byte 0 always has bit `0x40` set,
-  which is how it is told apart from an attribute byte.
+  which is how it is told apart from an attribute byte. Byte 1 bit `0x80` is
+  **Auto-Enter**: the host expects an Enter AID to be sent automatically the
+  moment the field is completely filled (`Field.auto_enter`). On the wire this
+  looks like e.g. `1D 40 A0 26 00 01` — FFW `40 A0`, attribute `26`, length `1`
+  — which is a plain auto-enter field, _not_ an FCW pair.
 - Zero or more **FCW** (Field Control Word) pairs may follow; the chain ends at
   the first attribute byte, _not_ at a continuation bit.
 - The attribute byte is written at the field's start position, and the field's
   length is the **two bytes after it** — it is not derived from an FCW and it is
   not inferred from where the next field begins.
+- A **Start of Header (SOH)** begins a new format table. Applying it discards
+  existing field definitions without clearing display characters; subsequent
+  SF orders rebuild the table for the current write.
 
 ### Write Structured Field (WSF / Query)
 
@@ -170,6 +179,8 @@ The **Screen** holds the actual state that represents what you'd see on a physic
 - **Field list** — all SF/MF-defined fields with their position, length, format word, and modified-data-tag.
 - **Cursor position** — where the blinking cursor sits.
 - **Keyboard locked flag** — when True, the terminal won't send AID keys.
+- **Last AID** — the most recent AID successfully sent to the host; included
+  in Save Screen device state.
 
 ### Applying Events
 
@@ -210,8 +221,8 @@ This is the central method — it:
 2. Feeds it through `parser.parse()` to get a list of `DSEvent` objects.
 3. Iterates through events looking for special commands:
    - **QUERY** → sends back a Query Reply with terminal capabilities
-   - **SAVE_SCREEN** → deep-copies the current `Screen`, files it under a fresh identifier, and returns that identifier in the save-screen acknowledgment
-   - **RESTORE_SCREEN** → looks the identifier the server sent up among the saved screens, makes it current (dropping any newer saves), resizes the parser to its dimensions, then applies any remaining events from the same record on top
+   - **SAVE_SCREEN** → deep-copies the current `Screen` onto a stack, serializes one complete regeneration buffer from that model, and returns it in the save-screen response
+   - **RESTORE_SCREEN** → pops the most recently saved `Screen`; the host-returned regeneration buffer is opaque because the local copy is authoritative, then any remaining events from the same record are applied on top
    - **RESIZE_SCREEN** → re-creates the parser and screen at the new dimensions
 4. If no RESTORE occurred, applies all events to the screen normally.
 5. **Post-RESTORE keyboard drain**: After restoring a screen, the keyboard is locked (because it was locked when saved). The server sends a follow-up record to unlock it. The terminal tries one more `_recv_and_apply()` to consume that unlock record. If nothing comes (RecvTimeout), it moves on.
@@ -224,6 +235,16 @@ This is the central method — it:
 4. Sets `keyboard_locked = True` (the server will unlock it when it replies).
 5. Calls `_recv_and_apply()` to wait for and process the server's response.
 
+### Auto-Enter fields
+
+When `type_into()` fills a field whose FFW has the Auto-Enter bit set, it
+submits `AID.ENTER` itself (via the normal `send_key` path) rather than waiting
+for the caller — mirroring a physical 5250. The cursor is placed on the
+auto-enter field first, because `set_field_text` otherwise advances it to the
+next field once the current one is full. Only the modified-data tags are cleared
+locally; the resulting screen (often a Save/Restore popup handshake) is driven
+entirely by the host and handled by `_recv_and_apply()`.
+
 ### Waiting: `wait_for_text(text)`
 
 1. Checks if the text already appears on screen (from events already applied).

{ibm5250-0.1.0.dev8 → ibm5250-0.1.0.dev9}/src/ibm5250/datastream.py

@@ -34,6 +34,10 @@ import struct
 from collections.abc import Iterator
 from dataclasses import dataclass, field
 from enum import Enum, auto
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .screen import Screen
 
 from .constants import (
     AID,
@@ -41,7 +45,6 @@ from .constants import (
     EBCDIC_SPACE,
     FFW,
     KNOWN_ORDERS,
-    SAVE_SCREEN_ID_LEN,
     SCREEN_COLS,
     SCREEN_COLS_132,
     SCREEN_ROWS,
@@ -82,6 +85,7 @@ class DSEventType(Enum):
     SET_ATTRIBUTE = auto()  # Set a display/character attribute (SA)
     COMMAND = auto()  # Raw command code (WTD, read, etc.)
     QUERY = auto()  # Server requests terminal capability query reply
+    START_OF_HEADER = auto()  # SOH order carrying the current format header
 
 
 @dataclass
@@ -219,25 +223,20 @@ class DataStreamParser:
                     yield from self._parse_wsf(data_view, byte_offset, total_bytes)
                     return
                 elif sub_command in (Command.SAVE_SCREEN, Command.RESTORE_SCREEN):
-                    # The server is issuing a save/restore command with an ESC
-                    # prefix.  A Restore Screen carries the two-byte screen
-                    # identifier that the workstation returned when the host
-                    # asked it to save that screen.
                     byte_offset += 1
-                    save_id = b""
-                    if (
-                        sub_command == Command.RESTORE_SCREEN
-                        and total_bytes - byte_offset == SAVE_SCREEN_ID_LEN
-                    ):
-                        save_id = bytes(data_view[byte_offset:total_bytes])
+                    restore_data = b""
+                    if sub_command == Command.RESTORE_SCREEN:
+                        restore_data = bytes(data_view[byte_offset:total_bytes])
                         byte_offset = total_bytes
                     log.debug(
-                        "ESC + command 0x%02X (screen id %s) — emitting COMMAND event",
+                        "ESC + command 0x%02X (%d restore bytes) — emitting COMMAND event",
                         sub_command,
-                        save_id.hex() or "-",
+                        len(restore_data),
                     )
                     yield DSEvent(
-                        type=DSEventType.COMMAND, command=sub_command, data=save_id
+                        type=DSEventType.COMMAND,
+                        command=sub_command,
+                        data=restore_data,
                     )
                     return
                 else:
@@ -301,10 +300,13 @@ class DataStreamParser:
                                 current_buffer_position + len(data_chunk)
                             ) % self._size
                     else:
+                        soh_start = byte_offset  # at the length byte
                         byte_offset += 1
-                        byte_offset += max(
-                            0, start_of_header_length
-                        )  # skip past the rest of the header
+                        byte_offset += max(0, start_of_header_length)
+                        yield DSEvent(
+                            type=DSEventType.START_OF_HEADER,
+                            data=bytes(data_view[soh_start:byte_offset]),
+                        )
 
                 case Order.TRANSPARENT_DATA:
                     byte_offset += 1
@@ -618,6 +620,228 @@ class DataStreamParser:
 # ---------------------------------------------------------------------------
 
 
+# Fixed segments of the Save/Restore Screen (04 12) structured field, taken
+# from a known-good "nikkie 6.1" reply. Unlike a Write To Display (04 11)
+# packet, this structured field is a self-describing snapshot: order bytes in
+# the buffer are shift-escaped with 0x10, and the buffer is preceded by a
+# device identity/capability header and a device/keyboard state block.
+_SAVE_SCREEN_SHIFT = 0x10
+_SAVE_SCREEN_DEVICE_ID = b"\x10\x01\x0bnikkie 6.1\x00"
+_SAVE_SCREEN_CAPS = bytes.fromhex("08 20 08 1f 1a 07 7f")  # 24x80 device capabilities
+_SAVE_SCREEN_MARKER = b"\x18\x50"  # begin 80-column display snapshot
+_SAVE_SCREEN_BUFFER_INTRO = 0x04  # 10 04 <len> <dims> <character plane>
+_SAVE_SCREEN_DEVICE_STATE = b"\x01\x01"
+_SAVE_SCREEN_PLANE_STATE = b"\x01\x00\x00"
+_SAVE_SCREEN_CURSOR_TAG = 0x02
+# Active-field pointer: 00 00 <field id> 00. The field id is screen-dependent
+# (the format-table index the cursor sits in); pinned until derivation is
+# verified against more capture frames. Never read back on our restore path.
+_SAVE_SCREEN_ACTIVE_FIELD_POINTER = b"\x00\x00\x01\x00"
+# Constant keyboard/shift/insert mode flags that follow the field pointer.
+_SAVE_SCREEN_INPUT_MODE_FLAGS = b"\x00\x01\x01\x00\x01\x00"
+# The AID byte (screen.last_aid) is emitted here, between the mode flags and
+# the trailer — it is dynamic, not part of either constant.
+_SAVE_SCREEN_INPUT_STATE_TRAILER = bytes.fromhex("00 0b 00 00 00 03 00 00")
+# Two full presentation-space window definitions are derived from geometry.
+# Neutral format header used when no host SOH has been received.
+_SAVE_SCREEN_DEFAULT_SOH = b"\x07" + bytes(7)
+# Per-field descriptor flag: 0xC5 for input-attribute (0x24) fields, 0xC7 otherwise.
+_SAVE_SCREEN_INPUT_ATTR = 0x24
+_SAVE_SCREEN_FIELD_FLAG_INPUT = 0xC5
+_SAVE_SCREEN_FIELD_FLAG_OTHER = 0xC7
+_SAVE_SCREEN_FIELD_ENTRY_LEN = 9  # flag(3) + data_pos(2) + len(1) + ffw(2) + attr(1)
+
+
+def build_save_screen_response(screen: Screen) -> bytes:
+    """Serialize the current screen as a Save/Restore Screen (04 12) reply.
+
+    The reply mirrors a "nikkie 6.1" save: device identity, two window
+    descriptors, a device-state block, the run-length-compressed image
+    (``10 04``), and the trailing window (``10 05`` / ``10 06``) and
+    field-format (``10 08``) sections. The two-byte length after
+    ``ESC RESTORE_SCREEN`` includes itself.
+    """
+    size = screen.rows * screen.cols
+    image = _compress_save_screen_plane(bytes(screen._chars[:size]))
+
+    body = bytearray()
+    body += _SAVE_SCREEN_DEVICE_ID
+    body += b"\x10\x02" + _SAVE_SCREEN_CAPS
+    body += _SAVE_SCREEN_MARKER
+    body += _SAVE_SCREEN_CAPS  # second window descriptor (bare, no 10 02)
+    body += _SAVE_SCREEN_MARKER
+    body += _save_screen_state_block(screen)
+    body += bytes([_SAVE_SCREEN_SHIFT, _SAVE_SCREEN_BUFFER_INTRO])
+    body += struct.pack(">H", 4 + len(image))  # length counts LL LL + SS SS + image
+    body += struct.pack(">H", size)
+    body += image
+    body += _save_screen_windows(size)
+    body += _save_screen_format_table(screen)
+
+    return (
+        bytes([Command.ESC, Command.RESTORE_SCREEN])
+        + struct.pack(">H", 2 + len(body))
+        + bytes(body)
+    )
+
+
+def _dims_for_size(size: int) -> tuple[int, int]:
+    """Map a plane size back to (rows, cols) for the two supported geometries."""
+    if size == SCREEN_ROWS_27 * SCREEN_COLS_132:
+        return SCREEN_ROWS_27, SCREEN_COLS_132
+    return SCREEN_ROWS, SCREEN_COLS
+
+
+def decode_save_screen_image(buffer: bytes) -> tuple[int, int, bytes] | None:
+    """Extract ``(rows, cols, character_plane)`` from a Save/Restore buffer.
+
+    The inverse of the ``10 04`` image built by
+    :func:`build_save_screen_response`: locate the section, read its declared
+    length and dimensions, and run-length-decode the plane. Returns ``None``
+    when no image section is present.
+    """
+    marker = buffer.find(bytes([_SAVE_SCREEN_SHIFT, _SAVE_SCREEN_BUFFER_INTRO]))
+    if marker == -1 or marker + 6 > len(buffer):
+        return None
+    declared_len = int.from_bytes(buffer[marker + 2 : marker + 4], "big")
+    size = int.from_bytes(buffer[marker + 4 : marker + 6], "big")
+    image = buffer[marker + 6 : marker + 6 + declared_len - 4]
+    plane = bytearray()
+    index = 0
+    total = len(image)
+    while index < total and len(plane) < size:
+        if (
+            image[index] == _SAVE_SCREEN_SHIFT
+            and index + 3 < total
+            and image[index + 1] == Order.SET_BUFFER_ADDRESS
+        ):
+            count = image[index + 2]
+            plane += bytes([image[index + 3]]) * count
+            index += 4
+        else:
+            plane.append(image[index])
+            index += 1
+    if len(plane) < size:
+        plane += bytes([EBCDIC_SPACE]) * (size - len(plane))
+    rows, cols = _dims_for_size(size)
+    return rows, cols, bytes(plane[:size])
+
+
+def _save_screen_state_block(screen: Screen) -> bytes:
+    """Return the device-state block with live cursor and screen geometry."""
+    cursor_pos = screen.cursor_pos
+    rows = screen.rows
+    cols = screen.cols
+    size = rows * cols
+    last_row_start = size - cols
+    last_cell = size - 1
+    pos_hi, pos_lo = (cursor_pos >> 8) & 0xFF, cursor_pos & 0xFF
+    row, col = encode_addr(cursor_pos, cols)
+
+    block = bytearray(9)  # no format-area pointers
+    block += struct.pack(">HBB", cursor_pos, row, col)
+    block += _SAVE_SCREEN_DEVICE_STATE
+    block += bytes(7)
+    block += struct.pack(">BHHB", rows, last_row_start, last_cell, 0)
+    block += struct.pack(">BBHH", rows, rows, last_row_start, last_cell)
+    block += bytes(5)
+    block += struct.pack(
+        ">BHHHH", rows, last_row_start, last_cell, last_row_start + 1, last_cell - 1
+    )
+    block += struct.pack(">BHH", rows + 1, size, size + cols - 1)
+    block += struct.pack(">BHH", rows + 2, size + cols, size + 2 * cols - 1)
+    block += _SAVE_SCREEN_PLANE_STATE
+    block += bytes([_SAVE_SCREEN_CURSOR_TAG, pos_hi, pos_lo])
+    block += _SAVE_SCREEN_ACTIVE_FIELD_POINTER
+    block += _SAVE_SCREEN_INPUT_MODE_FLAGS
+    block += bytes([screen.last_aid])  # dynamic: the last AID key sent
+    block += _SAVE_SCREEN_INPUT_STATE_TRAILER
+    return bytes(block)
+
+
+def _save_screen_windows(size: int) -> bytes:
+    """Build the 10 05 / 10 06 window definitions sized to the screen."""
+    geometry = struct.pack(">H", size)
+    section = b"\x00\x09" + geometry + b"\x10\x12" + geometry + b"\xc0"
+    return b"\x10\x05" + section + b"\x10\x06" + section
+
+
+def _save_screen_format_table(screen: Screen) -> bytes:
+    """Build the 10 08 field-format table from the host SOH and input fields.
+
+    Each field is a fixed 9-byte descriptor: a 3-byte flag prefix, a 2-byte
+    data position, a length byte, the 2-byte FFW, and the attribute byte.
+    """
+    header = screen.last_start_of_header or _SAVE_SCREEN_DEFAULT_SOH
+    entries = bytearray()
+    for input_field in screen.input_fields:
+        flag = (
+            _SAVE_SCREEN_FIELD_FLAG_INPUT
+            if input_field.attribute == _SAVE_SCREEN_INPUT_ATTR
+            else _SAVE_SCREEN_FIELD_FLAG_OTHER
+        )
+        entries += bytes([flag, 0x00, 0x00])
+        entries += struct.pack(">H", input_field.data_pos)
+        entries += bytes([input_field.length & 0xFF])
+        entries += input_field.field_format_word[:2].ljust(2, b"\x00")
+        entries += bytes([input_field.attribute])
+    payload = header + bytes([len(screen.input_fields) & 0xFF]) + bytes(entries)
+    return b"\x10\x08" + struct.pack(">H", 2 + len(payload)) + bytes(payload)
+
+
+def decode_save_screen_fields(buffer: bytes) -> list[tuple[int, int, bytes, int]]:
+    """Extract field specs from a Save/Restore 10 08 table.
+
+    The inverse of :func:`_save_screen_format_table`: each field is a fixed
+    9-byte descriptor. Returns ``(start_pos, length, ffw, attribute)`` tuples,
+    or an empty list when no format table is present.
+    """
+    marker = buffer.find(b"\x10\x08")
+    if marker == -1 or marker + 4 > len(buffer):
+        return []
+    declared_len = int.from_bytes(buffer[marker + 2 : marker + 4], "big")
+    payload = buffer[marker + 4 : marker + 4 + declared_len - 2]
+    if not payload:
+        return []
+    soh_len = payload[0]
+    index = 1 + soh_len
+    if index >= len(payload):
+        return []
+    count = payload[index]
+    index += 1
+    specs: list[tuple[int, int, bytes, int]] = []
+    for _ in range(count):
+        entry = payload[index : index + _SAVE_SCREEN_FIELD_ENTRY_LEN]
+        if len(entry) < _SAVE_SCREEN_FIELD_ENTRY_LEN:
+            break
+        data_pos = int.from_bytes(entry[3:5], "big")
+        specs.append((max(0, data_pos - 1), entry[5], bytes(entry[6:8]), entry[8]))
+        index += _SAVE_SCREEN_FIELD_ENTRY_LEN
+    return specs
+
+
+def _compress_save_screen_plane(plane: bytes) -> bytes:
+    """Run-length compress a linear cell plane for a Save Screen image.
+
+    Runs of four or more identical bytes become ``10 11 <count> <byte>``;
+    shorter runs are emitted literally. Counts are capped at 255 per order.
+    """
+    out = bytearray()
+    index = 0
+    length = len(plane)
+    while index < length:
+        byte = plane[index]
+        run = 1
+        while index + run < length and plane[index + run] == byte and run < 0xFF:
+            run += 1
+        if run >= 4:
+            out += bytes([_SAVE_SCREEN_SHIFT, Order.SET_BUFFER_ADDRESS, run, byte])
+        else:
+            out += bytes([byte]) * run
+        index += run
+    return bytes(out)
+
+
 @dataclass
 class FieldResponse:
     """One field's contribution to an AID response."""

{ibm5250-0.1.0.dev8 → ibm5250-0.1.0.dev9}/src/ibm5250/screen.py

@@ -19,6 +19,7 @@ from collections.abc import Sequence
 from dataclasses import dataclass, field
 
 from .constants import (
+    AID,
     CC2,
     EBCDIC_NULL,
     EBCDIC_SPACE,
@@ -26,10 +27,18 @@ from .constants import (
     SCREEN_COLS,
     SCREEN_ROWS,
     Attr,
+    Command,
     pos_to_rowcol,
     rowcol_to_pos,
 )
-from .datastream import DSEvent, DSEventType, ebcdic_decode, ebcdic_encode
+from .datastream import (
+    DSEvent,
+    DSEventType,
+    decode_save_screen_fields,
+    decode_save_screen_image,
+    ebcdic_decode,
+    ebcdic_encode,
+)
 from .exceptions import FieldNotFound
 
 log = logging.getLogger(__name__)
@@ -108,6 +117,28 @@ class Field:
         """True when the field's display attribute is 'non-display' (password)."""
         return self.attribute & Attr.NON_DISPLAY_MASK == Attr.NON_DISPLAY_MASK
 
+    @property
+    def auto_enter(self) -> bool:
+        """True when the FFW Auto-Enter bit is set.
+
+        The host submits an Enter AID automatically as soon as such a field is
+        completely filled.
+        """
+        return len(self.field_format_word) >= 2 and bool(
+            self.field_format_word[1] & FFW.AUTO_ENTER
+        )
+
+    @property
+    def writable_length(self) -> int:
+        """Number of positions writable on the field's first row.
+
+        A field's formal area can span to the next field, but data is only
+        written up to the end of the row holding the first data byte (see
+        :meth:`Screen.set_field_text`), so auto-enter fills at this boundary.
+        """
+        row_remaining = self._screen_cols - (self.data_pos % self._screen_cols)
+        return max(0, min(self.length, row_remaining))
+
     @property
     def mdt(self) -> bool:
         """True if the Modified Data Tag is set (field was touched)."""
@@ -164,22 +195,39 @@ class Screen:
         self._keyboard_locked: bool = True
         self._write_lengths: dict[int, int] = {}  # pos → length of last write
         self._pending_scroll_clear: bool = False
+        self._last_start_of_header: bytes = b""  # SOH header from the last WTD
+        self._last_aid: int = AID.NO_AID
 
-    def copy(self) -> Screen:
-        """Return a deep copy of this screen (for save/restore)."""
-        import copy as _copy
-        new = Screen.__new__(Screen)
-        new.rows = self.rows
-        new.cols = self.cols
-        new._size = self._size
-        new._chars = bytearray(self._chars)
-        new._attrs = bytearray(self._attrs)
-        new._fields = _copy.deepcopy(self._fields)
-        new._cursor = self._cursor
-        new._keyboard_locked = self._keyboard_locked
-        new._write_lengths = dict(self._write_lengths)
-        new._pending_scroll_clear = False
-        return new
+    @classmethod
+    def from_save_buffer(cls, buffer: bytes) -> Screen | None:
+        """Reconstruct a screen from a host Save/Restore Screen buffer.
+
+        The 04 12 buffer is self-contained: the character plane comes from its
+        10 04 image and every field from its 10 08 format table. Returns None
+        when the buffer has no image section.
+        """
+        decoded = decode_save_screen_image(buffer)
+        if decoded is None:
+            return None
+        rows, cols, plane = decoded
+        screen = cls(rows=rows, cols=cols)
+        screen._chars[: len(plane)] = plane
+        for start_pos, length, ffw, attribute in decode_save_screen_fields(buffer):
+            if not 0 <= start_pos < screen._size:
+                continue
+            screen._fields.append(
+                Field(
+                    start_pos=start_pos,
+                    length=length,
+                    field_format_word=ffw,
+                    attribute=attribute or Attr.NORMAL,
+                    _explicit_length=length,
+                    _screen_cols=cols,
+                )
+            )
+            screen._attrs[start_pos] = attribute
+        screen._fields.sort(key=lambda f: f.start_pos)
+        return screen
 
     # ------------------------------------------------------------------
     # Event application
@@ -204,6 +252,9 @@ class Screen:
             log.debug("Screen resized to %d rows × %d cols", self.rows, self.cols)
 
         elif event_type == DSEventType.COMMAND:
+            if event.command == Command.CLEAR_FORMAT_TABLE:
+                self._fields.clear()
+                self._write_lengths.clear()
             cc2 = event.control_char_2
             if cc2 & CC2.RESET_MDT:
                 for screen_field in self._fields:
@@ -231,6 +282,11 @@ class Screen:
         elif event_type == DSEventType.SET_ATTRIBUTE and 0 <= event.position < self._size:
             self._attrs[event.position] = event.attribute_value
 
+        elif event_type == DSEventType.START_OF_HEADER:
+            self._fields.clear()
+            self._write_lengths.clear()
+            self._last_start_of_header = event.data
+
     def apply_all(self, events: Sequence[DSEvent]) -> None:
         """Apply a sequence of events, then recalculate field lengths."""
         deferred_unlock = False
@@ -284,6 +340,10 @@ class Screen:
     def cursor_pos(self) -> int:
         return self._cursor
 
+    @property
+    def last_aid(self) -> int:
+        return self._last_aid
+
     @property
     def cursor_row(self) -> int:
         return pos_to_rowcol(self._cursor, self.cols)[0]
@@ -296,6 +356,11 @@ class Screen:
     def keyboard_locked(self) -> bool:
         return self._keyboard_locked
 
+    @property
+    def last_start_of_header(self) -> bytes:
+        """SOH header bytes (length + data) from the most recent WTD."""
+        return self._last_start_of_header
+
     @property
     def fields(self) -> list[Field]:
         """All fields (protected and input) on the current screen."""
@@ -305,7 +370,6 @@ class Screen:
     def input_fields(self) -> list[Field]:
         """Only unprotected (input) fields."""
         return [f for f in self._fields if not f.is_protected]
-
     # ---- text extraction ----
 
     def get_text(self, row: int, col: int, length: int) -> str:
@@ -568,11 +632,9 @@ class Screen:
         return [f for f in self._fields if f.mdt and not f.is_protected]
 
     def clear_modified_fields(self) -> None:
-        """Restore original data in fields modified by user input."""
+        """Clear field modification bookkeeping without changing screen data."""
         for f in self._fields:
-            if f.mdt and f._saved_data:
-                pos = f.data_pos
-                self._chars[pos : pos + len(f._saved_data)] = f._saved_data
+            if f.mdt:
                 f._saved_data = b""
                 f.mdt = False
 

{ibm5250-0.1.0.dev8 → ibm5250-0.1.0.dev9}/src/ibm5250/terminal.py

@@ -40,6 +40,7 @@ from .datastream import (
     FieldResponse,
     build_aid_response,
     build_query_reply,
+    build_save_screen_response,
 )
 from .exceptions import (
     ConnectionError,
@@ -78,8 +79,12 @@ class FieldProxy:
 
     @value.setter
     def value(self, text: str) -> None:
-        """Write *text* into the field (marks MDT)."""
-        self._term.screen.set_field_text(self._field, text)
+        """Write *text* into the field (marks MDT).
+
+        Routed through :meth:`Terminal.type_into`, so filling a field whose FFW
+        has the Auto-Enter bit set submits the host's Enter AID automatically.
+        """
+        self._term.type_into(self._field, text)
 
     @property
     def field(self) -> Field:
@@ -154,8 +159,6 @@ class Terminal:
         self._poll_interval = poll_interval
         self._rows = rows
         self._cols = cols
-        self._saved_screens: list[tuple[bytes, Screen]] = []
-        self._next_save_id: int = 1
 
     # ------------------------------------------------------------------
     # Connection management
@@ -250,13 +253,27 @@ class Terminal:
             The text to enter.
         clear_first:
             If *True*, clear any existing content first.
+
+        Notes
+        -----
+        If *field* has the FFW Auto-Enter bit set and this call fills it, the
+        host's Enter AID is sent automatically (blocking for the response), just
+        as a physical 5250 terminal would.  Do not follow such a call with an
+        explicit ``send_key(AID.ENTER)``.
         """
         f = field.field if isinstance(field, FieldProxy) else field
         if clear_first:
-            self._screen.set_field_text(f, text)
+            content = text
         else:
-            existing = self._screen.get_field_text(f).rstrip()
-            self._screen.set_field_text(f, existing + text)
+            content = self._screen.get_field_text(f).rstrip() + text
+        self._screen.set_field_text(f, content)
+        # An auto-enter field makes the host submit Enter the instant it fills.
+        # set_field_text advances the cursor to the next field once a field is
+        # full, so restore it to this field before submitting to match the AID
+        # a real 5250 emulator sends.
+        if f.auto_enter and f.writable_length and len(content) >= f.writable_length:
+            self._screen._cursor = f.data_pos
+            self.send_key(AID.ENTER)
 
     def move_cursor(self, row: int, col: int) -> None:
         """Move the cursor to 1-based *(row, col)* without sending a key."""
@@ -536,6 +553,7 @@ class Terminal:
             cursor_pos=self._screen.cursor_pos,
             cols=self._screen.cols,
         )
+        self._screen._last_aid = aid
         self._screen.clear_modified_fields()
         self._screen._keyboard_locked = True
         if aid in (AID.PAGE_DOWN, AID.PAGE_UP):
@@ -585,6 +603,7 @@ class Terminal:
         else:
             self._screen.apply_all(parsed_events)
 
+
     def _resize(self, rows: int, cols: int) -> None:
         """Track a screen-size change and re-create the parser to match."""
         self._rows = rows
@@ -593,49 +612,29 @@ class Terminal:
         log.debug("Parser resized to %d rows × %d cols", rows, cols)
 
     def _save_screen(self) -> None:
-        """Snapshot the current screen and acknowledge the host's Save Screen.
+        """Acknowledge the host's Save Screen with a serialized presentation space.
 
-        The acknowledgment carries a distinct two-byte identifier; the host
-        stores it and echoes it back in the Restore Screen command to say which
-        of the saved screens it wants displayed again.
-        """
-        save_id = bytes([self._next_save_id, self._next_save_id + 1])
-        # Identifiers are a byte wide, so wrap before either byte overflows.
-        self._next_save_id = self._next_save_id % 254 + 1
-        self._saved_screens.append((save_id, self._screen.copy()))
-        log.debug("Saved screen as id %s", save_id.hex())
-        self._conn.send_save_screen_response(save_id)
-
-    def _restore_screen(self, save_id: bytes) -> bool:
-        """Restore the screen the host identifies by *save_id*.
-
-        Returns ``True`` if a saved screen was restored.  Screens saved after
-        the restored one are discarded — the host has unwound past them.
+        The response is a self-contained snapshot; the host stores it and echoes
+        it back verbatim on Restore, so no local copy is retained.
         """
-        if not self._saved_screens:
-            log.debug("Restore Screen with no saved screens — ignoring")
-            return False
+        response = build_save_screen_response(self._screen)
+        log.debug("Saved screen (%d response bytes)", len(response))
+        self._conn.send_save_screen_response(response)
 
-        index = next(
-            (
-                i
-                for i in range(len(self._saved_screens) - 1, -1, -1)
-                if self._saved_screens[i][0] == save_id
-            ),
-            None,
-        )
-        if index is None:
-            # Unknown identifier: fall back to the most recently saved screen.
-            log.debug(
-                "Restore Screen id %s not found; using most recent save",
-                save_id.hex() or "-",
-            )
-            index = len(self._saved_screens) - 1
+    def _restore_screen(self, restore_data: bytes) -> bool:
+        """Restore the screen entirely from the host-returned buffer.
 
-        self._screen = self._saved_screens[index][1]
-        del self._saved_screens[index:]
+        The 04 12 buffer is a self-contained snapshot: its 10 04 image is the
+        character plane and its 10 08 table defines every field. No local
+        presentation state is consulted.
+        """
+        restored = Screen.from_save_buffer(restore_data)
+        if restored is None:
+            log.debug("Restore Screen buffer had no image — ignoring")
+            return False
+        self._screen = restored
         self._screen.clear_modified_fields()
-        # The saved screen carries its own dimensions; the parser must follow it.
+        # The restored screen carries its own dimensions; the parser must follow it.
         self._resize(self._screen.rows, self._screen.cols)
         return True
 

{ibm5250-0.1.0.dev8 → ibm5250-0.1.0.dev9}/uv.lock

@@ -13,7 +13,7 @@ wheels = [
 
 [[package]]
 name = "ibm5250"
-version = "0.1.0.dev8"
+version = "0.1.0.dev9"
 source = { editable = "." }
 
 [package.dev-dependencies]