tnz
TN3270 terminal class.
Low level APIs for telnet-3270 for Z tool and library.
Usage
from tnz import tnz
Environment variables used
SESSION_PS_SIZE SESSION_SECLEVEL SESSION_SSL_VERIFY TNZ_COLORS TNZ_LOGGING ZTI_SECLEVEL
Copyright 2021, 2025 IBM Inc. All Rights Reserved.
SPDX-License-Identifier: Apache-2.0
Classes
One instance for each terminal and the connection.
Methods for actions taken at the terminal
attn ATTN enter ENTER clear CLEAR key_backspace Backspace key_backtab Backtab key_curdown Down key_curleft Left key_curright Right key_curup Up key_data characters/string key_delete Delete key_end (End) key_eraseeof Erase EOF key_eraseinput ERASE INPUT key_home Home key_insdata insert characters/string key_newline NL key_tab Tab key_wordl (Word Left) key_wordr (Word Right) pa2, pa2, pa3 PAx pfX (pf1, pf2, … pf24) PFxx
Additional methods to enhance the terminal experience
paste_data multiline characters/string
Characters in the terminal
scrstr Method to get characters/string
Attributes in the terminal
plane_fa Field attributes plane_eh Extended highlighting plane_fg Forground color plane_bg Background color
Various methods perform actions taken by the remote application. Use the wait method to wait for the remote application to request actions and for the instance to process them.
The data in the 3270 terminal is located by an address. This may be different from other applications that use a row and column or an x position and a y position. In addition, vectors described using addresses typically wrap - for instance from address 2 to address 1 produces a vector start at address 2, continues to the end of the terminal, continues at the beginning of the terminal, and terminates at address 1.
The send method and the send_* methods send data to the remote host.
Attributes
instance-attribute
addr16bit = False
instance-attribute
aid = 96
instance-attribute
alt = 0
instance-attribute
amaxcol = 80
instance-attribute
amaxrow = 24
instance-attribute
bufadd = 0
instance-attribute
buffer_size = maxrow * maxcol
instance-attribute
bytes_received = 0
instance-attribute
bytes_sent = 0
instance-attribute
capable_color = False
property
cert_verified
Bool indicating if secure and cert was verified as trusted.
instance-attribute
codec_info = {}
instance-attribute
colors = int(getenv('TNZ_COLORS', '768'))
instance-attribute
curadd = 0
instance-attribute
ddmdata = None
instance-attribute
ddmdict = {}
instance-attribute
ddmrecv = False
instance-attribute
ddmsend = False
instance-attribute
dmaxcol = 80
instance-attribute
dmaxrow = 24
property
writable
encoding
Name of encoding.
instance-attribute
file_appends = None
property
host_verified
Bool indicating if secure and host was verified.
instance-attribute
inop = 6
instance-attribute
inpid = 0
instance-attribute
lastcmd = None
instance-attribute
local_do = []
instance-attribute
local_dont = []
instance-attribute
local_will = []
instance-attribute
local_wont = []
instance-attribute
lu_name = None
instance-attribute
maxcol = dmaxcol
instance-attribute
maxrow = dmaxrow
instance-attribute
name = name
instance-attribute
plane_bg = bytearray(buffer_size)
instance-attribute
plane_cs = bytearray(buffer_size)
instance-attribute
plane_dc = bytearray(buffer_size)
instance-attribute
plane_eh = bytearray(buffer_size)
instance-attribute
plane_fa = bytearray(buffer_size)
instance-attribute
plane_fg = bytearray(buffer_size)
instance-attribute
pwait = False
instance-attribute
read_state = NORMAL
instance-attribute
readlines = None
instance-attribute
readlines_pa2 = True
instance-attribute
remote_do = []
instance-attribute
remote_dont = []
instance-attribute
remote_will = []
instance-attribute
remote_wont = []
property
secure
Bool indicating if connection is secure.
instance-attribute
seslost = False
property
start_tls_completed
Bool indicating if start_tls completed.
instance-attribute
system_lock_wait = True
instance-attribute
terminal_type = 'IBM-DYNAMIC'
property
tn3270
Bool indicating if NOT NVT mode.
property
tn3270e
Bool indicating if using TN3270E.
instance-attribute
updated = False
instance-attribute
use_tn3270e = False
Functions
address(address_bytes)
Return an integer buffer address for the input encoded byte string address.
address_bytes(address)
Return an encoded byte string for the input integer buffer address.
attn()
Send 3270 ATTN
char_addrs(saddr=None, eaddr=None)
A generator of character data address ranges.
clear(zti=None)
Send CLEAR
close()
Close the connection.
connect(host=None, port=None, secure=False, verifycert=True, *, event=None)
Connect to the host.
ddm_in_progress()
Return bool indicating if ddm is in progress.
download()
Return current Download (or None).
enter(text=None, zti=None)
Send ENTER
extended_color_mode()
Return bool indicating if screen using extended colors.
staticmethod
fav_repr(fav)
Return string representation of field attribute value.
field(address)
Return field address and attribute value as tuple.
Get the field address and attribute value associated with the input address.
fields(saddr=None, eaddr=None)
A generator of all fields as (address, attribute).
get_file(parms, filename, assist=True)
Get host file into local file.
Would be nice, when the local system is Z, to transfer in binary. However, when transfer is done in binary, no information about the record format comes across. So, there is no knowledge if the host records were fixed-80 or variable length - so there is no indication as to where the line breaks should be.
Transfering using the ASCII CRLF options seems to cause the host to convert between cp037 and iso8859-1. If something other than cp037 is expected/needed, support must be added to translate back from iso8859-1 to cp037. Then using the desired code page (e.g. cp1047) to translate to Unicode.
getpeername()
Return remote address to which socket is connected.
getsockettype()
Return type of socket.
group_addrs(saddr, eaddr)
A generator of character data address range groups.
A generator function that iterates through groups of characters. The characters in each group have all the same attributes. Each iteration returns a tuple with the start and end addresses.
It is assumed that the input address(es) are valid for the current buffer size. They are in the range from 0 to buffer_size-1, inclusive.
staticmethod
is_detectable_attr(attr)
Return whether or not the input field attribute is for a selector-pen-detectable field.
staticmethod
is_displayable_attr(attr)
Return whether or not the input field attribute is for a displayable field.
staticmethod
is_intensified_attr(attr)
Return whether or not the input field attribute is for an intensified field.
staticmethod
is_modified_attr(attr)
Return whether or not the input field attribute is for a modified field.
staticmethod
is_normal_attr(attr)
Return whether or not the input field attribute is for a normal field.
staticmethod
is_numeric_attr(attr)
Return whether or not the input field attribute is for a numeric field.
is_pen_detectable(address)
Return True or False to indicate if the address is selector-pen detectable
is_protected(address)
Return True or False to indicate if the address is protected
staticmethod
is_protected_attr(attr)
Return whether or not the input field attribute is for a protected field.
is_unprotected()
Return True or False to indicate if all fields are unprotected
iterow(saddr, eaddr)
Iterate through rows of bytes in the input bytearray.
Note that the inputs are addresses and the outputs are positions. In other words, the outputs for each iteration will always have the start less than the end and buffer_size is used when the vector goes to the end of the bytearray.
key_aid(aid)
Process an aid key.
key_backspace(zti=None)
Process backspace key, which behaves like a cursor left followed by a delete as long as cursor is not on a field attribute nor is there a field attribute to the left.
key_backtab(zti=None)
Process backtab key.
key_curdown(zti=None)
Process cursor down key.
key_curleft(zti=None)
Process cursor left key.
key_curright(zti=None)
Process cursor right key.
key_curup(zti=None)
Process cursor up key.
key_data(text, onerow=False, zti=None)
Process keyboard character data.
key_delete(zti=None)
Process delete key.
key_end()
Process End key - go to end of text in field.
End is not a 3270 key, but common on modern keyboard.
Cursor will move onto a null character in the current field where the character to the left is not a null character and all characters to the right are null characters.
If cursor is in an unprotected field and the field does not end in a null character, the cursor will be put on the last character in the field.
If cursor is in a protected field and the field does not end in a null character, the cursor will be put on the field attribute of the next field.
key_eraseeof(zti=None)
Process eraseeof key.
key_eraseinput(zti=None)
Process ERASE INPUT key.
key_home(zti=None)
Process home key.
key_ins_data(text, zti=None)
Process keyboard character data in insert mode.
key_newline(zti=None)
Process newline key.
key_tab(zti=None)
Process tab key.
key_word_left()
Move cursor left to the previous word.
key_word_right()
Move cursor right to the next word.
classmethod
logging()
Initialize logging
next_data(saddr, eaddr=None)
Get the address range of the next field data.
next_field(saddr, eaddr=None, offset=1)
Get the address and attribute value of the next field.
Get the address and attribute value associated with the next field relative to the input field address. The first location for searching is the address AFTER the input saddr. If eaddr is specified.
pa1()
Send PA1
pa2()
Send PA2
pa3()
Send PA3
paste_data(data, zti=None)
Process pasted character data.
pf1()
Send PF1
pf10()
Send PF10
pf11()
Send PF11
pf12()
Send PF12
pf13()
Send PF13
pf14()
Send PF14
pf15()
Send PF15
pf16()
Send PF16
pf17()
Send PF17
pf18()
Send PF18
pf19()
Send PF19
pf2()
Send PF2
pf20()
Send PF20
pf21()
Send PF21
pf22()
Send PF22
pf23()
Send PF23
pf24()
Send PF24
pf3()
Send PF3
pf4()
Send PF4
pf5()
Send PF5
pf6()
Send PF6
pf7()
Send PF7
pf8()
Send PF8
pf9()
Send PF9
put_file(filename, parms, assist=True)
Put host file from local file.
staticmethod
rcba(value, start, stop)
read circular byte array
value: byte array start: first index into byte array stop: last index into byte array returns copy of data from array
scrstr(saddr=0, eaddr=0, rstrip=None)
Return a string representation of the character buffer.
selector_pen(address, zti=None)
send(data=None)
Send input byte array as data to the host. This method will escape IAC bytes.
send_3270_data(value)
Send input byte array as a 3270-DATA record to the host. This method will escape IAC bytes and send EOR after the data.
send_aid(aid, short=None)
Process the sending of an AID (enter command). Used by methods with the name of the AID (e.g. enter).
send_command(code)
Send telnet command to the host.
Send a single-byte telnet command to the remote.
Supported commands
NAME CODE MEANING NOP 241 No operation. Data Mark 242 The data stream portion of a Synch. Break 243 NVT character BRK. Interrupt Process 244 The function IP. Abort output 245 The function AO. Are You There 246 The function AYT. Erase character 247 The function EC. Erase Line 248 The function EL. Go ahead 249 The GA signal.
See other methods for other commands
NAME METHOD EOR send_rec() SE send_sub() SB send_sub() WILL send_will() WON'T send_wont() DO send_do() DON'T send_dont()
send_do(opt, buffer=False)
Send DO to the host.
send_dont(opt, buffer=False)
Send DON'T to the host.
send_rec(value)
Send input byte array as a record to the host. This method will escape IAC bytes and send EOR after the data.
send_sub(value, buffer=False)
Send input subcommand data to the host. This method will bookend the data with IAC SB adn IAC SE.
send_terminal_type(buffer=False)
Send the terminal type to the host.
send_will(opt, buffer=False)
Send WILL to the host.
send_wont(opt, buffer=False)
Send WON'T to the host.
set_cursor_address(address)
Set the cursor address to the input address.
set_cursor_position(row, col)
Set the cursor address from the input row and column.
First (row, col) is (1, 1).
shutdown()
Shut down the connection.
start_readlines()
Initialize readlines.
staticmethod
ucba(dst, start, src, begidx=0, endidx=None)
update circular byte array
dst: target circular byte array start: first index into target byte array src: data to copy to array begidx: start index in data to copy (default is 0) endidx: end index in data to copy (default is len(src))
upload(file)
Upload data from file-like object to remote server.
uploading()
Return bool indicating if currently uploading.
wait(timeout=None, zti=None, key=None)
Wait for event.
Returns after timeout seconds or when data is received.
word_at(address)
Return the word at the input address.
Bases: Exception
General Tnz error.
Bases: TnzError
May be related to terminal characteristics.
Bases: TnzError
Error processing file transfer.
Functions
bit6(control_int)
Translate 6-bit control characters to printable characters. This is used for bytes that have bits 0 and 1 reserved in order to make the byte a printable character. See figure D-1 in Data Stream Programmers Reference.
connect(host=None, port=None, secure=None, verifycert=None, name=None, *, event=None)
Create a new Tnz object and connect to the host.
secure = False if do not care about security secure = True for encrypted connection verifycert only has meaning when secure is True