ibm5250 0.1.0.dev6__tar.gz → 0.1.0.dev8__tar.gz

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

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

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

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

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

@@ -19,6 +19,7 @@ from .constants import (
     FFW,
     SCREEN_COLS,
     SCREEN_ROWS,
+    Attr,
     Command,
     Order,
     TelnetCmd,
@@ -65,6 +66,7 @@ __all__ = [
     "TelnetCmd",
     "TelnetOpt",
     "FFW",
+    "Attr",
     "SCREEN_ROWS",
     "SCREEN_COLS",
     # Address helpers

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

@@ -26,13 +26,13 @@ from dataclasses import dataclass
 
 from .constants import (
     AID,
-    CC2,
     Command,
     TelnetCmd,
     TelnetOpt,
     TN5250EDataType,
     TN5250ERecordType,
     TN5250ESubNeg,
+    encode_addr,
 )
 from .exceptions import ConnectionError, ProtocolError, RecvTimeout
 
@@ -48,9 +48,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
-_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
@@ -74,6 +71,20 @@ _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).
+_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
+
 
 @dataclass
 class TN5250EHeader:
@@ -82,10 +93,12 @@ class TN5250EHeader:
     err_flag: int = 0x00
 
     aid: int = AID.NO_AID  # AID byte placed in the variable header (default: no-AID)
+    cursor_row: int = 0x00
+    cursor_col: int = 0x00
 
     def to_bytes(self, payload_len: int) -> bytes:
-        # 3-byte variable header: _VAR_HDR_OP_HI _VAR_HDR_OP_LO <AID>
-        var_hdr = bytes([_VAR_HDR_OP_HI, _VAR_HDR_OP_LO, self.aid])
+        # 3-byte variable header: cursor row, cursor column, AID.
+        var_hdr = bytes([self.cursor_row, self.cursor_col, self.aid])
         var_len = len(var_hdr)
         total = payload_len + _TN5250E_HEADER_LEN + var_len
         return (
@@ -238,6 +251,8 @@ class TN5250Connection:
         *,
         data_type: int = TN5250EDataType.INPUT,
         aid: int = AID.NO_AID,
+        cursor_pos: int | None = None,
+        cols: int = 80,
     ) -> None:
         """Send a 5250 data record to the host.
 
@@ -248,16 +263,21 @@ class TN5250Connection:
             raise ConnectionError("Not connected")
 
         escaped = _iac_escape(data)
+        cursor_row, cursor_col = (
+            encode_addr(cursor_pos, cols) if cursor_pos is not None else (0, 0)
+        )
 
         if self._tn5250e_active:
             hdr = TN5250EHeader(
                 data_type=data_type,
                 aid=aid,
+                cursor_row=cursor_row,
+                cursor_col=cursor_col,
             ).to_bytes(len(escaped))
             frame = hdr + escaped
         else:
-            # Basic TN5250: AID byte is the first byte of the payload
-            frame = bytes([aid]) + escaped
+            # Basic TN5250 carries AID and cursor address in the data stream.
+            frame = bytes([aid, cursor_row, cursor_col]) + escaped
 
         frame += bytes([TelnetCmd.INTERPRET_AS_COMMAND, TelnetCmd.END_OF_RECORD])
 
@@ -317,23 +337,20 @@ 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, save_id: 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.
+        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*.
         """
         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]
-        )
+        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)
         self._send_frame(frame, description="Sending Save Screen response")
 
@@ -346,8 +363,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,
@@ -357,20 +374,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:
@@ -379,9 +392,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),
                     )

{ibm5250-0.1.0.dev6 → ibm5250-0.1.0.dev8}/src/ibm5250/constants.py

@@ -83,10 +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
     WRITE_TO_DISPLAY = (
         0x11  # main screen update command; followed by CC1/CC2 and orders
     )
@@ -104,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
 
 
@@ -121,11 +123,10 @@ class CC2:
     """Control Character 2 — second byte after WTD command."""
 
     RESET = 0x00
-    UNLOCK_KEYBOARD = 0x01
-    RESET_MDT = 0x02  # Clear all MDT bits
-    RESET_MDT_UNLOCK = 0x03
+    UNLOCK_KEYBOARD = 0x08
+    RESET_MDT = 0x10  # Clear all MDT bits
+    RESET_MDT_UNLOCK = 0x18
     SET_MDT = 0x04  # Set MDT on all input fields
-    MOVE_CURSOR = 0x08  # IC order sets cursor, not default position
 
 
 # ---------------------------------------------------------------------------
@@ -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).
+
+    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
+    # 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
 
@@ -541,10 +576,17 @@ def decode_addr(hi: int, lo: int, cols: int = SCREEN_COLS) -> int:
 
 
 def pos_to_rowcol(pos: int, cols: int = SCREEN_COLS) -> tuple[int, int]:
-    """Convert a linear position to (row, col), both 0-based."""
-    return divmod(pos, cols)
+    """Convert a zero-based linear position to a 1-based ``(row, col)``."""
+    if pos < 0:
+        raise ValueError("Buffer position must be non-negative")
+    row, col = divmod(pos, cols)
+    return row + 1, col + 1
 
 
 def rowcol_to_pos(row: int, col: int, cols: int = SCREEN_COLS) -> int:
-    """Convert (row, col) to a linear position (both 0-based)."""
-    return row * cols + col
+    """Convert a 1-based ``(row, col)`` to a zero-based linear position."""
+    if row < 1 or col < 1:
+        raise ValueError("Screen coordinates start at (1, 1)")
+    if col > cols:
+        raise ValueError(f"Column must be between 1 and {cols}")
+    return (row - 1) * cols + col - 1