ibm5250 0.1.0.dev1__tar.gz → 0.1.0.dev3__tar.gz

{ibm5250-0.1.0.dev1 → ibm5250-0.1.0.dev3}/PKG-INFO

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

{ibm5250-0.1.0.dev1 → ibm5250-0.1.0.dev3}/pyproject.toml

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

{ibm5250-0.1.0.dev1 → ibm5250-0.1.0.dev3}/src/ibm5250/connection.py

@@ -52,6 +52,19 @@ _VAR_HDR_OP_HI = 0x08  # TN5250E variable-header opcode byte 0
 _VAR_HDR_OP_LO = 0x2C  # TN5250E variable-header opcode byte 1
 _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
+# AID and no variable header. Observed on the wire when the PC "Esc" key (mapped
+# to Attn) is pressed: 00 0a 12 a0 00 00 04 40 00 00.
+_TN5250E_ATTN_FLAG = 0x40
+
+# TN5250E header byte 9 operation code (RFC 2877 §4.3). After the workstation
+# sends Attn, the host cancels its outstanding read invite by sending a
+# header-only Cancel-Invite record (opcode 0x0A, no payload). The workstation
+# must acknowledge it by echoing the same Cancel-Invite record back before the
+# host will run its Attention program (e.g. the System Request / Assist menu).
+_TN5250E_OP_CANCEL_INVITE = 0x0A
+
 _MAX_NEG_PASSES = 40  # Maximum Telnet option exchange iterations during negotiation
 
 
@@ -184,6 +197,10 @@ class TN5250Connection:
         self._ttype_will_sent = False
         self._negotiated_ttype = "IBM-3477-FG"  # screen model reported to IBM i
 
+        # Byte 9 (opcode/var-header length) of the last received TN5250E record.
+        # Used to detect header-only Cancel-Invite records (opcode 0x0A).
+        self._last_recv_opcode: int = 0x03
+
         # TLS
         if use_tls and tls_context is None:
             tls_context = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
@@ -244,13 +261,61 @@ class TN5250Connection:
 
         frame += bytes([TelnetCmd.INTERPRET_AS_COMMAND, TelnetCmd.END_OF_RECORD])
 
+        self._send_frame(frame, description=f"→ {len(data)} payload bytes: {data.hex()}")
+
+    def _send_frame(self, frame: bytes, *, description: str) -> None:
+        """Send a fully-framed (IAC-EOR terminated) record under the send lock."""
+        if self._sock is None:
+            raise ConnectionError("Not connected")
+        log.debug(description)
         with self._lock:
             try:
                 self._sock.sendall(frame)
             except OSError as exc:
                 raise ConnectionError(f"Send failed: {exc}") from exc
 
-        log.debug("→ %d payload bytes: %s", len(data), data.hex())
+    def send_attn(self) -> None:
+        """Send the Attention (Attn) signal to the host.
+
+        Attn is *not* an AID key. In TN5250E it is a header-only INPUT record
+        whose byte 7 carries the Attn flag (``0x40``) with no variable header
+        and no payload -- exactly what emulators emit when the PC "Esc" key
+        (mapped to Attn) is pressed. On the AS/400 this typically raises the
+        System Request / Assist menu. In basic (non-TN5250E) mode the Attn key
+        is signalled with a Telnet BREAK (RFC 1205).
+        """
+        if not self._tn5250e_active:
+            # Basic TN5250: the Attn key is signalled with a Telnet BREAK.
+            frame = bytes(
+                [
+                    TelnetCmd.INTERPRET_AS_COMMAND,
+                    TelnetCmd.BREAK,
+                    TelnetCmd.INTERPRET_AS_COMMAND,
+                    TelnetCmd.END_OF_RECORD,
+                ]
+            )
+        else:
+            # Header-only INPUT record: byte 7 carries the Attn flag.
+            frame = _build_tn5250e_frame(req_resp=_TN5250E_ATTN_FLAG, opcode=0x00)
+
+        self._send_frame(frame, description="Sending Attn signal")
+
+    def send_cancel_invite_response(self) -> None:
+        """Acknowledge a host Cancel-Invite by echoing it back.
+
+        After the workstation sends Attn, the host replies with a header-only
+        Cancel-Invite record (opcode ``0x0A``, no payload) to cancel its
+        outstanding read invite. The workstation must echo the identical record
+        back; only then does the host run its Attention program (which raises,
+        for example, the System Request / Assist menu). Without this ack the
+        host stalls and never sends the follow-up screen.
+        """
+        if not self._tn5250e_active:
+            return  # cancel-invite handshake only occurs in TN5250E mode
+
+        # Header-only INPUT record: byte 9 opcode = Cancel-Invite, no payload.
+        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:
         """Send the TN5250E-level Save Screen acknowledgment.
@@ -261,42 +326,16 @@ class TN5250Connection:
         send).  This is a protocol-level exchange with no 5250 data stream
         payload.
         """
-        if self._sock is None:
-            raise ConnectionError("Not connected")
         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]
+        # 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]
         )
-        total = _TN5250E_HEADER_LEN + len(var_hdr)  # 14
-        frame = (
-            bytes(
-                [
-                    (total >> 8) & 0xFF,
-                    total & 0xFF,  # record length
-                    _GDS_RECORD_ID_HI,
-                    _GDS_RECORD_ID_LO,  # GDS identifier
-                    0x00,
-                    0x00,  # flags
-                    TN5250EDataType.INPUT,  # data type (matches request)
-                    0x00,
-                    0x00,  # seq / asap-exit
-                    len(var_hdr),  # variable header length = 4
-                ]
-            )
-            + var_hdr
-        )
-        frame = _iac_escape(frame) + bytes(
-            [TelnetCmd.INTERPRET_AS_COMMAND, TelnetCmd.END_OF_RECORD]
-        )
-        log.debug("Sending Save Screen response")
-        with self._lock:
-            try:
-                self._sock.sendall(frame)
-            except OSError as exc:
-                raise ConnectionError(f"Send failed: {exc}") from exc
+        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:
         """Block until a complete record arrives; return the raw 5250 payload."""
@@ -307,6 +346,7 @@ 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:])
                 log.debug(
                     "← TN5250E type=%02X data_type=%02X payload=%d bytes",
@@ -326,6 +366,7 @@ class TN5250Connection:
                     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
@@ -369,6 +410,24 @@ class TN5250Connection:
         """True if TN5250E enhanced mode was successfully negotiated."""
         return self._tn5250e_active
 
+    @property
+    def last_recv_opcode(self) -> int:
+        """Return byte 9 (opcode/var_len) from the last received TN5250E frame.
+
+        Read-poll responses must echo this value back to the server.
+        """
+        return self._last_recv_opcode
+
+    @property
+    def last_recv_was_cancel_invite(self) -> bool:
+        """True if the last received TN5250E record was a Cancel-Invite.
+
+        The host sends a header-only Cancel-Invite (opcode ``0x0A``, no 5250
+        payload) after the workstation presses Attn. It must be acknowledged
+        via :meth:`send_cancel_invite_response`.
+        """
+        return self._last_recv_opcode == _TN5250E_OP_CANCEL_INVITE
+
     # ------------------------------------------------------------------
     # Internal — Telnet negotiation
     # ------------------------------------------------------------------
@@ -698,3 +757,40 @@ class TN5250Connection:
 def _iac_escape(data: bytes) -> bytes:
     """Double any IAC (0xFF) bytes in *data* for safe Telnet transmission."""
     return data.replace(b"\xff", b"\xff\xff")
+
+
+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.
+
+    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.
+    Used for the header-only control records: Attn, Cancel-Invite response and
+    Save Screen response.
+
+    Parameters
+    ----------
+    req_resp:
+        Byte 7 (request/response flags) — e.g. the Attn flag.
+    opcode:
+        Byte 9 (operation code / variable-header length).
+    var_hdr:
+        Optional variable-header bytes appended after the fixed header.
+    """
+    total = _TN5250E_HEADER_LEN + len(var_hdr)
+    header = bytes(
+        [
+            (total >> 8) & 0xFF,
+            total & 0xFF,  # 0-1: logical record length
+            _GDS_RECORD_ID_HI,
+            _GDS_RECORD_ID_LO,  # 2-3: GDS identifier
+            0x00,
+            0x00,  # 4-5: reserved
+            TN5250EDataType.INPUT,  # 6: data type (workstation → host)
+            req_resp,  # 7: request/response flags
+            0x00,  # 8: error recovery
+            opcode,  # 9: opcode / variable-header length
+        ]
+    )
+    return _iac_escape(header + var_hdr) + bytes(
+        [TelnetCmd.INTERPRET_AS_COMMAND, TelnetCmd.END_OF_RECORD]
+    )

{ibm5250-0.1.0.dev1 → ibm5250-0.1.0.dev3}/src/ibm5250/terminal.py

@@ -217,6 +217,20 @@ class Terminal:
         """Send an AID key by name, e.g. ``"Enter"``, ``"F3"``, ``"Clear"``."""
         self.send_key(AID.from_name(name), wait=wait)
 
+    def send_attn(self, *, wait: bool = True) -> None:
+        """Send the Attention (Attn) signal to the host.
+
+        Attn is a protocol-level attention indication -- *not* an AID key -- and
+        is what 5250 emulators send for the PC "Esc" key. On the AS/400 it
+        typically raises the System Request / Assist menu. By default this
+        blocks until the host responds; pass ``wait=False`` to return
+        immediately after sending.
+        """
+        self._conn.send_attn()
+        self._screen._keyboard_locked = True
+        if wait:
+            self._recv_and_apply()
+
     def type_into(
         self,
         field: Field | FieldProxy,
@@ -517,6 +531,14 @@ class Terminal:
 
     def _recv_and_apply(self) -> None:
         received_payload = self._conn.recv_record()
+        # A header-only Cancel-Invite (no 5250 payload) is the host's reply to
+        # our Attn: it cancels the outstanding read invite. We must echo it back
+        # to let the host run its Attention program (e.g. the Assist menu);
+        # otherwise the host stalls and never sends the follow-up screen.
+        if not received_payload and self._conn.last_recv_was_cancel_invite:
+            log.debug("Received Cancel-Invite; echoing acknowledgment")
+            self._conn.send_cancel_invite_response()
+            return
         parsed_events = list(self._parser.parse(received_payload))
         # If this record has screen content, the pending save is no longer back-to-back
         for ev in parsed_events:

{ibm5250-0.1.0.dev1 → ibm5250-0.1.0.dev3}/uv.lock

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