ibm5250 0.1.0.dev7__tar.gz → 0.1.0.dev9__tar.gz

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

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

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

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

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

@@ -19,6 +19,7 @@ from .constants import (
     FFW,
     SCREEN_COLS,
     SCREEN_ROWS,
+    Attr,
     Command,
     Order,
     TelnetCmd,
@@ -34,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,
@@ -65,6 +69,7 @@ __all__ = [
     "TelnetCmd",
     "TelnetOpt",
     "FFW",
+    "Attr",
     "SCREEN_ROWS",
     "SCREEN_COLS",
     # Address helpers
@@ -79,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.dev7 → ibm5250-0.1.0.dev9}/src/ibm5250/connection.py

@@ -26,8 +26,6 @@ from dataclasses import dataclass
 
 from .constants import (
     AID,
-    CC2,
-    Command,
     TelnetCmd,
     TelnetOpt,
     TN5250EDataType,
@@ -49,7 +47,6 @@ _TELNET_OPT_CMD_LEN = 3  # bytes: IAC + command + option (WILL/WONT/DO/DONT)
 # SNA / TN5250E wire-format framing constants
 _GDS_RECORD_ID_HI = 0x12  # SNA GDS record-type identifier, high byte
 _GDS_RECORD_ID_LO = 0xA0  # SNA GDS record-type identifier, low byte
-_SAVE_SCREEN_RESP_CC1 = 0x01  # CC1 value in the Save Screen response variable header
 
 # TN5250E header byte 7 (request/response flags). Real emulators set bit 0x40
 # here to signal the Attention (Attn) key -- a header-only INPUT record with no
@@ -64,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
 
 
@@ -73,6 +73,15 @@ _MAX_NEG_PASSES = 40  # Maximum Telnet option exchange iterations during negotia
 
 _TN5250E_HEADER_LEN = 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*."""
+    return _TN5250E_HEADER_LEN
+
 
 @dataclass
 class TN5250EHeader:
@@ -101,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
@@ -325,24 +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) -> 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+CC1+CC2 (mirroring what working emulators
-        send).  This is a protocol-level exchange with no 5250 data stream
-        payload.
+        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
 
-        # 4-byte variable header: [ESC, RESTORE_SCREEN, CC1, CC2.RESET_MDT].
-        # byte 9 of the fixed header carries the variable-header length.
-        var_hdr = bytes(
-            [Command.ESC, Command.RESTORE_SCREEN, _SAVE_SCREEN_RESP_CC1, CC2.RESET_MDT]
+        frame = _build_tn5250e_frame(
+            req_resp=0x00,
+            opcode=_TN5250E_OP_SAVE_SCREEN_RESPONSE,
+            var_hdr=screen_data,
         )
-        frame = _build_tn5250e_frame(req_resp=0x00, opcode=len(var_hdr), var_hdr=var_hdr)
         self._send_frame(frame, description="Sending Save Screen response")
 
     def recv_record(self) -> bytes:
@@ -354,8 +367,8 @@ class TN5250Connection:
                     log.debug("Short TN5250E frame (%d bytes), skipping", len(frame))
                     continue
                 hdr = TN5250EHeader.from_bytes(frame)
-                self._last_recv_opcode = frame[9]  # byte 9: opcode / var_len
-                payload = bytes(frame[_TN5250E_HEADER_LEN:])
+                self._last_recv_opcode = frame[9]  # byte 9: opcode
+                payload = bytes(frame[_payload_offset(frame) :])
                 log.debug(
                     "← TN5250E type=%02X data_type=%02X payload=%d bytes",
                     hdr.record_type,
@@ -365,20 +378,16 @@ class TN5250Connection:
             else:
                 frame_bytes = bytes(frame)
                 # IBM i sends TN5250E-formatted records even when TN5250E was
-                # not formally negotiated.  The 10-byte fixed header begins
-                # with a big-endian 16-bit record length that equals the total
-                # frame size.  Byte 9 of the header is the variable-header
-                # length — that many additional bytes follow before the real
-                # 5250 payload.
+                # not formally negotiated.  The header begins with a big-endian
+                # 16-bit record length that equals the total frame size, and
+                # byte 6 holds the length of the variable header that follows
+                # it — the real 5250 payload starts after that.
                 if len(frame_bytes) >= _TN5250E_HEADER_LEN and int.from_bytes(
                     frame_bytes[:2], "big"
                 ) == len(frame_bytes):
                     hdr = TN5250EHeader.from_bytes(frame_bytes)
                     self._last_recv_opcode = frame_bytes[9]  # byte 9: opcode
-                    var_hdr_len = frame_bytes[
-                        9
-                    ]  # RFC 2877 variable-header length field
-                    skip = _TN5250E_HEADER_LEN + var_hdr_len
+                    skip = _payload_offset(frame_bytes)
                     payload = frame_bytes[skip:]
                     # Server is speaking TN5250E — our responses must include the header too
                     if not self._tn5250e_active:
@@ -387,9 +396,8 @@ class TN5250Connection:
                         )
                         self._tn5250e_active = True
                     log.debug(
-                        "← implicit TN5250E header stripped (fixed=%d var=%d) data_type=%02X payload=%d bytes",
-                        _TN5250E_HEADER_LEN,
-                        var_hdr_len,
+                        "← implicit TN5250E header stripped (%d bytes) data_type=%02X payload=%d bytes",
+                        skip,
                         hdr.data_type,
                         len(payload),
                     )
@@ -768,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.
@@ -780,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.
     """
@@ -796,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.dev7 → ibm5250-0.1.0.dev9}/src/ibm5250/constants.py

@@ -83,11 +83,12 @@ class TN5250ESubNeg:
 
 
 class Command:
-    INLINE_WRITE_STRUCTURED_FIELD = (
-        0x02  # Introduces an inline WSF record within a WTD stream
+    ESC = 0x04  # precedes every 5250 command in a record
+    CLEAR_UNIT = 0x40  # erase the display, reset it to the primary size (24×80)
+    CLEAR_UNIT_ALTERNATE = (
+        0x20  # erase the display, switch to the alternate size (27×132);
+        # followed by a one-byte parameter (0x00 or 0x80)
     )
-    ESC = 0x04  # precedes Write Structured Field inline
-    CLEAR_UNIT = 0x40  # erase the display and format table
     WRITE_TO_DISPLAY = (
         0x11  # main screen update command; followed by CC1/CC2 and orders
     )
@@ -105,16 +106,16 @@ class Command:
 
 # Write to Display control characters (CC1 / CC2)
 class CC1:
-    """Control Character 1 — first byte after WTD command.
+    """Control Character 1 — first byte after the WTD command.
 
-    Only bits 0-2 are defined by the IBM 5250 spec; bits 3-7 are reserved.
-    Keyboard lock/unlock is controlled exclusively by CC2, not CC1.
+    CC1 selects which Modified Data Tags and input-field buffers the host wants
+    reset before the write is applied.  It does **not** erase the screen and it
+    does **not** change the screen dimensions — those are driven exclusively by
+    the Clear Unit (:data:`Command.CLEAR_UNIT`) and Clear Unit Alternate
+    (:data:`Command.CLEAR_UNIT_ALTERNATE`) commands.
     """
 
     RESET = 0x00
-    CLEAR_UNIT = 0x20  # Erase entire screen before write
-    CLEAR_UNIT_ALT = 0x40  # Erase screen using alternate screen dimensions
-    CLEAR_FORMAT_TABLE = 0x60  # Discard field definitions only; no screen erase
     SOUND_ALARM = 0x80  # Audible alarm
 
 
@@ -133,22 +134,32 @@ class CC2:
 # ---------------------------------------------------------------------------
 
 class Order:
+    """5250 orders embedded in a Write to Display data stream.
+
+    Note these are *5250* order codes -- they differ from the 3270 codes of the
+    same name (e.g. 5250 Repeat to Address is 0x02, not 0x3C).
+    """
+
     START_OF_HEADER = 0x01  # Start of Header (variable-length; skip past it)
+    REPEAT_TO_ADDRESS = 0x02  # Repeat to Address  — 2 address bytes + 1 fill char
+    ERASE_TO_ADDRESS = (
+        0x03  # Erase to Address   — 2 address bytes + length + attribute types
+    )
     TRANSPARENT_DATA = 0x10  # Transparent Data   — 2-byte length + raw EBCDIC
     SET_BUFFER_ADDRESS = 0x11  # Set Buffer Address — 2 address bytes
-    ERASE_TO_ADDRESS = (
-        0x12  # Erase to Address        — 2 address bytes (fill with nulls)
+    WRITE_EXTENDED_ATTRIBUTE = (
+        0x12  # Write Extended Attribute — 2 bytes; not emulated
     )
     INSERT_CURSOR = 0x13  # Insert Cursor            — 2 address bytes; marks cursor pos
     MOVE_CURSOR = 0x14  # Move Cursor              — 2 address bytes
-    GROUP_ERASE_TO_ADDRESS = 0x16  # Group Erase to Address   — 2 address bytes (fill with nulls, within field group)
+    WRITE_DISPLAY_STRUCTURED_FIELD = (
+        0x15  # Write to Display Structured Field — 2-byte length + payload
+    )
     START_FIELD = 0x1D  # Start Field        — 2-byte FFW [+ 2-byte FCW pairs]
-    SET_ATTRIBUTE = 0x28  # Set Attribute      — 1 attribute type + 1 value byte
-    MODIFY_FIELD = 0x2C  # Modify Field       — like SF but doesn't clear data
-    REPEAT_TO_ADDRESS = 0x3C  # Repeat to Address  — 2 address bytes + 1 fill char
 
-_KNOWN_ORDERS = frozenset(
-    v for k, v in vars(Order).items() if not k.startswith("_")
+
+KNOWN_ORDERS = frozenset(
+    v for k, v in vars(Order).items() if isinstance(v, int) and not k.startswith("_")
 )
 
 # ---------------------------------------------------------------------------
@@ -218,36 +229,56 @@ class AID:
 
 
 class FFW:
-    """Field Format Word bits (byte 0 and byte 1 of the 2-byte FFW)."""
+    """Field Format Word bits (byte 0 and byte 1 of the 2-byte FFW).
 
-    # Byte 0
+    Note the FFW carries *behaviour* only.  A field's visual appearance comes
+    from the separate attribute byte that follows the FFW/FCWs in the SF order
+    (see :class:`Attr`).
+    """
+
+    # Byte 0 — bit 0x40 is the "this is an FFW" identifier and is always set.
+    IDENTIFIER = 0x40  # Marks the byte as a Field Format Word rather than an attribute
     BYPASS = 0x20  # Protected field — no input allowed (read-only)
     DUP_ENABLE = 0x10  # Dup key enabled — user can duplicate the previous field's value
-    MDT = 0x01  # Modified Data Tag — set when the field has been touched
-    AUTO_ENTER = 0x08  # Auto Enter — automatically submit when the field is filled
-    FER = 0x04  # Field Exit Required — user must press Field Exit before leaving
-
-    # Byte 1 (keyboard shift / display attribute)
+    MDT = 0x08  # Modified Data Tag — set when the field has been touched
+    # Byte 0, low 3 bits — field type (keyboard shift)
     ALPHA_SHIFT = 0x00  # Alphabetic shift — accepts any character
-    ALPHA_ONLY = 0x04  # Alphabetic only — rejects digits and special characters
-    NUM_SHIFT = 0x08  # Numeric shift — defaults keyboard to numeric mode
-    NUM_ONLY = 0x18  # Numeric only — rejects non-numeric input
-    KATA_SHIFT = 0x0C  # Katakana shift — Japanese katakana character entry
-    DIGITS_ONLY = 0x1C  # Digits only — accepts 0–9 with no sign
-    IO_ONLY = 0x10  # Inhibit Output only — field is write-protected from the keyboard
-    SIGNED_NUM = 0x14  # Signed numeric — accepts digits plus a trailing sign character
-    # Display attribute (high nibble of byte 1)
-    DISP_NORM = 0x00  # Normal — green on black
-    DISP_HIGH = 0x20  # High intensity — bright green on black
-    DISP_RI = 0x40  # Reverse image — black on green
-    DISP_RI_HIGH = 0x60  # Reverse image high intensity — bright black on green
-    DISP_UNDER = 0x80  # Underline — green with underline
-    DISP_UNDER_HI = 0xA0  # Underline high intensity — bright green with underline
-    DISP_BLINK = 0xC0  # Blink — flashing field
-    NON_DISPLAY = 0xE0  # Non-display — invisible; used for password entry
-    DISPLAY_ATTR_MASK = (
-        0xE0  # Bitmask for the display attribute field (high 3 bits of byte 1)
-    )
+    ALPHA_ONLY = 0x01  # Alphabetic only — rejects digits and special characters
+    NUM_SHIFT = 0x02  # Numeric shift — defaults keyboard to numeric mode
+    NUM_ONLY = 0x03  # Numeric only — rejects non-numeric input
+    KATA_SHIFT = 0x04  # Katakana shift — Japanese katakana character entry
+    DIGITS_ONLY = 0x05  # Digits only — accepts 0–9 with no sign
+    MAG_READER = 0x06  # Magnetic stripe reader input only
+    SIGNED_NUM = 0x07  # Signed numeric — accepts digits plus a trailing sign character
+    FIELD_TYPE_MASK = 0x07  # Bitmask for the field type bits of byte 0
+
+    # Byte 1
+    AUTO_ENTER = 0x80  # Auto Enter — automatically submit when the field is filled
+    FER = 0x40  # Field Exit Required — user must press Field Exit before leaving
+    MONOCASE = 0x20  # Monocase — lower-case input is folded to upper case
+    MANDATORY = 0x08  # Mandatory entry — the field may not be left empty
+    RIGHT_ZERO = 0x05  # Right-adjust, zero fill
+    RIGHT_BLANK = 0x06  # Right-adjust, blank fill
+    MANDATORY_FILL = 0x07  # Mandatory fill — the field must be filled completely
+    MANDATORY_FILL_MASK = 0x07  # Bitmask for the adjust/fill bits of byte 1
+
+
+class Attr:
+    """5250 display attribute byte values (0x20-0x3F).
+
+    Every attribute occupies one display position and governs the appearance of
+    the characters that follow it until the next attribute byte.
+    """
+
+    NORMAL = 0x20  # Green
+    REVERSE = 0x21  # Green, reverse image
+    HIGH_INTENSITY = 0x22  # White
+    UNDERLINE = 0x24  # Green, underlined
+    NON_DISPLAY = 0x27  # Invisible — used for passwords and command strings
+    RED = 0x28  # Red
+    BASE = 0x20  # All attribute bytes have this bit pattern in their high bits
+    MASK = 0xE0  # ``byte & MASK == BASE`` identifies an attribute byte
+    NON_DISPLAY_MASK = 0x07  # ``byte & MASK == 0x07`` means non-display
 
 
 # ---------------------------------------------------------------------------
@@ -436,6 +467,10 @@ SCREEN_COLS = 80
 SCREEN_ROWS_27 = 27  # 27×132 model
 SCREEN_COLS_132 = 132
 
+# Length of the screen identifier the workstation returns in its Save Screen
+# acknowledgment and that the host echoes back in a Restore Screen command.
+SAVE_SCREEN_ID_LEN = 2
+
 EBCDIC_SPACE = 0x40
 EBCDIC_NULL = 0x00
 

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

@@ -19,7 +19,11 @@ The **TN5250Connection** manages the TCP socket to the IBM i (AS/400) host.
 1. Reads bytes from the socket into a buffer.
 2. Scans for the IAC-EOR (Interpret As Command — End Of Record) sequence (0xFF 0xEF) which marks the end of a logical record.
 3. Un-escapes any doubled IAC bytes (0xFF 0xFF → 0xFF).
-4. If TN5250E is active, strips the 10-byte header + variable header → returns the raw 5250 payload.
+4. If TN5250E is active, strips the header → returns the raw 5250 payload. The
+   header is six fixed bytes followed by a variable part whose **length is byte 6**
+   (normally 4, giving the familiar 10-byte total), so the payload starts at
+   `6 + frame[6]`. Byte 9 is the _opcode_, not the header length — confusing the
+   two silently truncates the first bytes of the payload.
 5. If the socket has no data within the timeout, raises **RecvTimeout**.
 
 ### Sending (`send_record`)
@@ -33,7 +37,14 @@ 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 special TN5250E-framed acknowledgment (no 5250 payload — just a variable header encoding ESC + RESTORE_SCREEN + CC1 + CC2). This tells the server "I've saved the screen; you can now overlay it."
+When the server issues a SAVE_SCREEN command, the terminal must reply with a
+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).
 
 ---
 
@@ -43,28 +54,37 @@ The **DataStreamParser** takes a raw 5250 payload (one record from the connectio
 
 ### Record Structure
 
-Every 5250 record starts with a **command byte**:
-
-| Command                         | Meaning                                                                             |
-| ------------------------------- | ----------------------------------------------------------------------------------- |
-| `0x11` (Write to Display)       | Main screen update — followed by CC1, CC2, then orders/data                         |
-| `0x40` (Clear Unit)             | Clears the display and field definitions                                            |
-| `0x02` (Save Screen)            | Server wants to save the current screen (same format as WTD)                        |
-| `0x12` (Restore Screen)         | Server wants to restore a previously saved screen                                   |
-| `0x04` (ESC)                    | Escape prefix — next byte is the real command (Clear Unit, WTD, WSF, Save, Restore) |
-| `0xF3` (Write Structured Field) | Carries structured data like Query commands                                         |
-| `0x42/0x52/0x72/0x62`           | Read commands — server asks client to send back screen/field data                   |
-| `0x21` (Write Error Code)       | Display error on status line                                                        |
-| `0x50` (Clear Format Table)     | Discard field definitions                                                           |
+Every command in a record is introduced by **ESC (`0x04`)**, and one record may
+carry several commands back to back:
+
+| Command                         | Meaning                                                                                  |
+| ------------------------------- | ---------------------------------------------------------------------------------------- |
+| `0x11` (Write to Display)       | Main screen update — followed by CC1, CC2, then orders/data                              |
+| `0x40` (Clear Unit)             | Erases the display and field definitions and selects the **primary** size (24×80)        |
+| `0x20` (Clear Unit Alternate)   | Erases the display and selects the **alternate** size (27×132); takes one parameter byte |
+| `0x02` (Save Screen)            | Server wants the client to save the current screen                                       |
+| `0x12` (Restore Screen)         | Server wants a previously saved screen restored; followed by its two-byte identifier     |
+| `0xF3` (Write Structured Field) | Carries structured data like Query commands                                              |
+| `0x42/0x52/0x72/0x62`           | Read commands — server asks client to send back screen/field data                        |
+| `0x21` (Write Error Code)       | Display error on status line                                                             |
+| `0x50` (Clear Format Table)     | Discard field definitions                                                                |
+
+### Screen size
+
+The display size is **absolute and set only by the clear commands**: Clear Unit
+selects 24×80, Clear Unit Alternate selects 27×132. It is never a toggle, and it
+is never inferred from out-of-range buffer addresses. Getting this wrong is what
+made a screen returning from a 132-column layout keep rendering as 27×132 with
+stale content bleeding through.
 
 ### Control Characters (CC1 / CC2)
 
-After a WTD or Save Screen command, two bytes control screen-level behavior:
+Write to Display is followed by two control bytes:
 
-- **CC1** — Screen clear mode:
-  - `0x20`: Clear the entire screen before writing new data
-  - `0x40`: Clear and switch to alternate screen size (24×80 ↔ 27×132)
-  - `0x00`: Don't clear — overlay on existing content
+- **CC1** — Lock/reset flags. Notably CC1 **neither erases the screen nor
+  changes its dimensions**; only the clear commands above do that.
+  - `0x01`/`0x02`: Reset pending AIDs / unlock after the write
+  - `0x04`: Sound the alarm
 
 - **CC2** — Keyboard and field flags:
   - `0x08`: Unlock the keyboard (let the user type)
@@ -75,24 +95,56 @@ After a WTD or Save Screen command, two bytes control screen-level behavior:
 
 After the command + CC bytes, the rest of the record is a stream of **orders** intermixed with **data bytes**:
 
-| Order                                                  | What it does                                                                                                                                                                                                                                                        |
-| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **SBA** — Set Buffer Address (`0x11`) + row + col      | Move the write position to a specific screen cell                                                                                                                                                                                                                   |
-| **SF** — Start Field (`0x1D`) + FFW [+ FCWs]           | Define a new input/output field at the current position. The FFW (Field Format Word, 2 bytes) defines field type — bypass/input, numeric, non-display, etc. Optional FCW (Field Control Word) pairs add behaviours like mandatory entry, right-adjust, or monocase. |
-| **MF** — Modify Field (`0x2C`) + FFW [+ FCWs]          | Modify an existing field's attributes                                                                                                                                                                                                                               |
-| **IC** — Insert Cursor (`0x13`)                        | Place the cursor at the 2-byte address that follows (falls back to the current position only when no address bytes remain)                                                                                                                                          |
-| **MC** — Move Cursor (`0x14`) + row + col              | Move the cursor to a specific position                                                                                                                                                                                                                              |
-| **RA** — Repeat to Address (`0x3C`) + row + col + char | Repeat a character from current position up to the target                                                                                                                                                                                                           |
-| **EA** — Erase to Address (`0x12`) + row + col         | Erase (fill with nulls) from current position to target                                                                                                                                                                                                             |
-| **TD** — Transparent Data (`0x10`) + length + data     | Write raw bytes (transparent, no order interpretation)                                                                                                                                                                                                              |
-| **SA** — Set Attribute (`0x28`) + type + value         | Set a display attribute (colour, underline, etc.)                                                                                                                                                                                                                   |
-| **SOH** — Start of Header (`0x01`) + length + data     | Metadata block, skipped                                                                                                                                                                                                                                             |
+These are the **5250** order codes; several share a name with a 3270 order but
+use a different byte value (5250 Repeat to Address is `0x02`, not `0x3C`).
+
+| Order                                                        | What it does                                                                                                                                 |
+| ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| **SOH** — Start of Header (`0x01`) + length + data           | Metadata block, skipped                                                                                                                      |
+| **RA** — Repeat to Address (`0x02`) + row + col + char       | Repeat a character from the current position up to **and including** the target                                                              |
+| **EA** — Erase to Address (`0x03`) + row + col + len + types | Erase (fill with nulls) from the current position through the target. `len` counts itself plus the extended-attribute type bytes that follow |
+| **TD** — Transparent Data (`0x10`) + length + data           | Write raw bytes (transparent, no order interpretation)                                                                                       |
+| **SBA** — Set Buffer Address (`0x11`) + row + col            | Move the write position to a specific screen cell                                                                                            |
+| **WEA** — Write Extended Attribute (`0x12`) + type + value   | Extended character buffer attribute; not emulated, operands are consumed                                                                     |
+| **IC** — Insert Cursor (`0x13`)                              | Place the cursor at the 2-byte address that follows (falls back to the current position only when no address bytes remain)                   |
+| **MC** — Move Cursor (`0x14`) + row + col                    | Move the cursor to a specific position                                                                                                       |
+| **WDSF** — Write to Display Structured Field (`0x15`)        | GUI constructs (windows, scrollbars); not emulated, the payload is skipped                                                                   |
+| **SF** — Start Field (`0x1D`)                                | Define a field at the current position — see below                                                                                           |
 
 Anything that isn't a recognized order byte is treated as **EBCDIC (Extended Binary Coded Decimal Interchange Code)** character data and written sequentially into the screen buffer.
 
-### Inline Structured Fields (0x02 / 0x04 in the order stream)
-
-IBM i sometimes embeds 3–4 byte attribute markers (`0x02 XX YY` or `0x04 XX YY ZZ`) inline within the data stream to carry extended colour/highlight info. The parser identifies these and skips over them without writing them as screen text.
+### Attribute bytes
+
+Bytes in the range **`0x20`–`0x3F`** are display attributes. They are _data_:
+each one occupies a screen position (rendered as a blank) and governs the
+appearance of everything after it until the next attribute. `0x27` — more
+precisely any attribute whose low three bits are all set — means _non-display_,
+which is how password fields and hidden command strings are rendered blank.
+
+Because attributes are the only bytes with that bit pattern, they double as the
+terminator for the variable-length part of an SF order.
+
+### Start Field (SF)
+
+    SF (0x1D) [FFW1 FFW2 [FCW1 FCW2]...] ATTR LEN_HI LEN_LO
+
+- An **output-only** field omits the FFW and FCWs entirely: the byte straight
+  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. 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)
 
@@ -127,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
 
@@ -167,8 +221,9 @@ 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` onto a stack, sends the save-screen acknowledgment to the server
-   - **RESTORE_SCREEN** → pops the saved screen off the stack, replaces the current screen with it, 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.
 
@@ -180,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).
@@ -194,12 +259,30 @@ This is the central method — it:
 This is how the server does "popup" screens (like overlaying a detail view on a list):
 
 1. Server sends **SAVE_SCREEN** → terminal saves a copy of the current screen
+   under a fresh two-byte identifier and returns that identifier in the Save
+   Screen response
 2. Server sends a normal WTD with new content → terminal shows the popup
 3. User interacts with the popup (sends keys, gets responses)
-4. Server sends **RESTORE_SCREEN** → terminal swaps back to the saved screen
+4. Server sends **RESTORE_SCREEN + identifier** → terminal swaps back to _that_
+   saved screen and discards any screens saved after it
 5. Server sends a follow-up WTD to unlock the keyboard on the restored screen
 
-The tricky part: after step 4, the restored screen has `keyboard_locked = True` (it was saved right after the client sent an AID key). The terminal must consume the unlock record (step 5) before attempting the next `send_key`, otherwise the server rejects the input.
+Saves nest, so this is **not** a stack the terminal may simply pop: the server
+decides how far to unwind and names the screen it wants. Unwinding two levels
+in one go — restore `04 05`, Clear Unit, restore `03 04` — is normal, and
+popping blindly restores the wrong screen.
+
+A restored screen brings its own dimensions with it, so the parser must be
+re-created to match whenever one is restored.
+
+The other tricky part: after step 4, the restored screen has
+`keyboard_locked = True` (it was saved right after the client sent an AID key).
+The terminal must consume the unlock record (step 5) before attempting the next
+`send_key`, otherwise the server rejects the input.
+
+Screens restored this way are usually followed by _partial_ updates that repaint
+only the parts of the screen that changed, so the restored snapshot has to be
+byte-accurate — any error in it survives into the final display.
 
 ---