RFC 1205
5250 Telnet interface
RFC 1205: 5250 Telnet Interface 🦋
Okay bestie, let's start with the basics 💅 This is RFC 1205, called 5250 Telnet Interface. It was written by P. Chmielewski at IBM Corporation in February 1991 🌸 It's an info memo, not a standard, since it does not specify any standard. The title block doesn't list anything it obsoletes or updates ✨
Status of this Memo 📜
The status section is giving legal-but-make-it-cute 😭 It's being distributed to document the interface to the IBM 5250 Telnet implementation, for hosts on the Internet that want to support the 5250 work station data stream inside Telnet. It provides information for the Internet community and doesn't specify any standard. Distribution is unlimited 🎀
1. Introduction ✨
This RFC explains the interface to the IBM 5250 Telnet implementation 🦋 The whole point is that someone who wants to build a client Telnet that emulates an IBM 5250 work station can actually do it 💖 It does not go through every 5250 command, aid code, and other 5250 data stream goodie, though. All of that lives in the IBM 5250 Information Display System, Functions Reference Manual, IBM publication number SA21-9247 📚 Corrections and additions to that manual get written up right here in this RFC, in section 5 🫶
2. Telnet Options 🎀
No new Telnet options are defined for 5250 mode, so there's nothing new to memorize there 🙈 But to turn 5250 mode on, the client and server MUST agree to at least support the Binary, End-Of-Record (EOR), and Terminal-Type Telnet options. The full list of 5250 terminal types is kept in the Assigned Numbers RFC, and it includes the following:
IBM-5555-C01 24 x 80 Double-Byte Character Set color display
IBM-5555-B01 24 x 80 Double-Byte Character Set (DBCS)
IBM-3477-FC 27 x 132 color display
IBM-3477-FG 27 x 132 monochrome display
IBM-3180-2 27 x 132 monochrome display
IBM-3179-2 24 x 80 color display
IBM-3196-A1 24 x 80 monochrome display
IBM-5292-2 24 x 80 color display
IBM-5291-1 24 x 80 monochrome display
IBM-5251-11 24 x 80 monochrome displayHere's a typical negotiation to get into 5250 mode 👑 The server starts it off by sending the DO TERMINAL-TYPE request:
Server: IAC DO TERMINAL-TYPE
Client: IAC WILL TERMINAL-TYPE
Server: IAC SB TERMINAL-TYPE SEND IAC SE
Client: IAC SB TERMINAL-TYPE IS IBM-5251-11 IAC SE
(The client has specified its terminal-type is an IBM-5251-11)
Server: IAC DO END-OF-RECORD
Client: IAC WILL END-OF-RECORD
Server: IAC WILL END-OF-RECORD
Client: IAC DO END-OF-RECORD
(The server and client have both agreed to transmit EORs)
Server: IAC DO TRANSMIT-BINARY
Client: IAC WILL TRANSMIT-BINARY
Server: IAC WILL TRANSMIT-BINARY
Client: IAC DO TRANSMIT-BINARY
(The server and client have both agreed to binary transmission)3. Data Stream Format 🧚
The actual data stream exchanged between the client and server is a header followed by the 5250 work station data stream 💜 For details on that second part, check out the IBM 5250 Information Display System, Functions Reference Manual (SA21-9247). The header that goes in front of the 5250 data stream was originally designed for the 5250 Display Station Pass-Through (DSPT) application. 5250 DSPT is kind of like Telnet and runs on the IBM AS/400, System/36, and System/38 over an SNA network 🌈
The header is designed to be variable in length and has two parts. The first part is fixed and is always 6 octets long, formatted like this:
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Logical Record Length | Record Type |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Reserved |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Logical Record Length: 16 bits
This field gives the length, in octets, of this logical record, including the header length. The length is calculated BEFORE doubling any IAC characters in the data stream. It does not include the <IAC><EOR> that gets tacked onto the end of the data stream to mark the end of this logical record. The length is sent with the most significant octet first. For example, a length of 36 (decimal) would be specified as '0024'X.
Record Type: 16 bits
This field gives the SNA record type. It SHOULD always be set to '12A0'X to indicate the General Data Stream (GDS) record type.
Reserved: 16 bits
This field is currently not used 🙃
The second part of the header is also variable in length. Its length is specified in the first octet. Right now this part is always 4 octets long, and it looks like this:
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| |E|A| | | |S|T|H| | |
| Var Hdr Len |R|T| | | |R|R|L| | Opcode |
| |R|N| | | |Q|Q|P| | |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Var Hdr Len: 8 bits
The length, in octets, of the variable portion of the header. Right now this is always '04'X.
Flags: 16 bits
Bit 0(ERR): This bit is set to indicate a data stream output error. The negative response code is sent as data following the opcode field.Bit 1(ATN): This bit is set to indicate that the 5250 attention key was pressed.Bits 2-4(*): These bits are reserved (set to zero).Bit 5(SRQ): This bit is set to indicate that the 5250 System Request key was pressed.Bit 6(TRQ): This bit is set to indicate that the 5250 Test Request key was pressed.Bit 7(HLP): This bit is set to indicate the Help in Error State function. The error code is sent as data following the header and is a four digit packed decimal number. For example, an error code of'0005'Xindicates the operator attempted to type in an area of the display that is not enabled for input.Bits 8-15(*): These bits are reserved (set to zero).
Opcode: 8 bits
This field holds the operation code, which tells you what kind of operation the sender is asking for. These are the valid values:
'00'X: No Operation
'01'X: Invite Operation
'02'X: Output Only
'03'X: Put/Get Operation
'04'X: Save Screen Operation
'05'X: Restore Screen Operation
'06'X: Read Immediate Operation
'07'X: Reserved
'08'X: Read Screen Operation
'09'X: Reserved
'0A'X: Cancel Invite Operation
'0B'X: Turn On Message Light
'0C'X: Turn Off Message LightThe actual 5250 work station data stream comes right after the opcode field in the header, and it ends with the <IAC><EOR> pair. Some operations skip the data stream entirely, so the header is followed straight away by an <IAC><EOR> 🙈 For example, the server could send this request to turn on the message light:
000A 12A0 0000 0400 000B FFEF
| | | | | | |
| | | | | | End Of Record marker
| | | | | |
| | | | | Opcode = Turn On Message Light ('0B'X)
| | | | |
| | | | Flags = '0000'X
| | | |
| | | Variable Header Length = '04'X
| | |
| | Reserved - Set to '0000'X
| |
| Record Type = General Data Stream ('12A0'X)
|
Logical Record Length = '000A'X for this recordIn this example, the opcode tells you what's being requested, and there's no work station data stream attached 💅
4. Data Flow Examples 🌸
These examples show the flow of data between the client and server for some of the more common operations 💖 They're meant to show the order the logical records get sent in and what's inside each one. The hex for the records exchanged between client and server is shown. How a client carries out each operation depends on the implementation, and those details aren't covered here. In these examples, whenever a field's value depends on the length of the screen data in a particular logical record, it's shown as 'LLLL' ✨
4.1. Query Device Example 🔍
The server can send a Query command to figure out what kind of device it's talking to. When a client gets a Query command, it MUST send the Query Reply back to the server. Check out section 5 for the full format of the Query command and Query Reply 🫶
Server: Sends Write Structured 001112A0 00000400 000304F3 0005D970
Field Query command. 00FFEF
Client: Responds with a Query 004712A0 00000400 00000000 88003AD9
Reply, in this case, 70800600 01030000 00000000 00000000
for a 3180-2. 00000000 00000001 F3F1F8F0 F0F0F202
00000061 50000100 00000018 11000000
00000000 000000FF EF4.2. Cancel Invite Example 🦋
The server sends a Cancel Invite when it needs to flip the normal flow direction 🔄 When a client gets a Cancel Invite, it SHOULD reply with a Cancel Invite and not send any user data until the server has "invited" the work station again. A work station counts as "invited" once the server has sent a read command to the client. Here's how the Cancel Invite flow goes:
Server: Sends header with the 000A12A0 00000400 000AFFEF
Opcode = Cancel Invite.
Client: Sends header with the 000A12A0 00000400 000AFFEF
Opcode = Cancel Invite
to indicate that the
work station is no
longer invited.4.3 System Request Example ✨
okay so the 5250 System Request operation is what happens when a client wants to interrupt the server job to do some function 💅 like, a user hits the system request key (or whatever key is mapped to it), and the client Telnet kicks off this flow:
Client: Sends header with the 000A12A0 00000404 0000FFEF
System Request bit set.Note: side quest 🙈 the client is allowed to tuck user data into this record right after the header. the server reads that data as an option picked from the system request menu, so the server wouldn't send the menu and the flow would just keep going based on whatever option got selected. for this example though, the client sends no user data, so the flow goes like this:
Server: Sends header with the 000A12A0 00000400 000AFFEF
Opcode = Cancel Invite.
Client: Sends header with the 000A12A0 00000400 000AFFEF
Opcode = Cancel Invite
to indicate that the
work station is no
longer invited.
Server: Sends Save (Immediate) 000C12A0 00000400 00040402 FFEF
command with
Opcode = Save Screen.
Client: Sends the screen image LLLL12A0 00000400 00040412
to be saved. <Screen Image> FFEF
Server: Sends System Request LLLL12A0 00000400 0003
menu with <System Request Menu> FFEF
Opcode = Put/Get.
Client: Sends User Input to LLLL12A0 00000400 0000
the Sys Req menu. <User Input> FFEFNote: what happens next is totally up to whichever System Request option the user picked 🎀 once all that System Request processing is done, the server carries on with the restore operation:
Server: Sends the saved LLLL12A0 00000400 00050412
screen to be restored, <Saved Screen> FFEF
Opcode = Restore Screen.(No reply is necessary from the client)
Server: Sends Read Modified 000E12A0 00000400 00010452 0000FFEF
Data Tag (MDT) command,
opcode = Invite.And then the client gets "invited" again 🦋 and jumps right back into the state it was in before the System Request key got hit. iconic recovery arc, honestly 👑
5. 5250 Data Stream Enhancements 🌈
okay so this section is basically an addendum to the IBM 5250 Information Display System, Functions Reference Manual 📖 it covers enhancements to the 5250 data stream that aren't documented yet in that manual. the current version of that manual (when this was written) has the IBM publication number SA21-9247-6. this section also fixes some wrong info in SA21-9247-6, and the corrections and enhancements are listed below, each with an approximate page number reference to that manual 🍓
5.1 Errors or Inconsistencies in SA21-9247-6 🙈
the Insert Cursor (IC) order on pages 2-136 and 2-137 is listed with a value of Hex 03, which is wrong. the correct value is Hex 13 💀
on page 2-137, the listed "Restrictions" for the Insert Cursor, Repeat to Address, and Set Buffer Address orders should be updated to describe how Row and Column values must be valid for the current display screen size (either 24 x 80 or 27 x 132) 🫶
5.2 Enhancements to Existing 5250 Data Stream Commands/Orders ✨
a new flag is added to the second byte of the Control Character on page 2-40 🎀 this flag controls whether the cursor should be moved or not moved at the end of the Write to Display processing. bit 1 of the second byte was previously reserved, and now it's the one used for this flag. if bit 1 is a 0, the cursor keeps moving to the system IC address on a Lock-to-Unlock keyboard transition. if bit 1 is a 1, the cursor doesn't move 💅
a new Field Control Word (FCW) gets added on page 2-65 to show that an entry field has transparent data 🦋 basically the entry field contents go straight from the display screen to the host at read time with zero formatting, so an entry field can hold any values (Hex 00 to Hex FF). a transparent field is marked with a Hex 84xx FCW, where xx can be any value. Note: unpredictable results will happen if a field is defined as both signed numeric and a transparent field 😭
the Read Immediate, Read Input Fields, and Read MDT Fields commands got upgraded to support transparent fields (page 2-5) ⭐ if a transparent FCW shows up for an input field, the field data isn't formatted at all (for example, nulls don't get converted to blanks) 🧚
the restriction on the column address being zero for the Set Buffer Address (SBA) order (page 2-138) isn't always true anymore 🌸 so a reference to Start of Field (SF) row 1/column 1 field support should be made, and a note should be added in SF to describe Row 1/Column 1 field support. a Row 1/Column 1 field is defined by an SBA of row 1/column 0, followed by an SF. for a Row 1/Column 1 input field, the first input-capable position is row 1/column 1. if the SF defines an input field, the screen attribute is not allowed to be nondisplay. and writing the screen attribute gets suppressed for a Row 1/Column 1 field, so the attribute gets discarded 👑
5.3. New 5250 Data Stream Commands/Orders ✨
okay bestie, this is where the 5250 data stream gets some brand new goodies 🎀 First up, the Read MDT Fields Alternate input command. It's basically the same as Read MDT Fields, with two differences:
- The command is indicated by a
X'82' - Leading and embedded nulls within the field remain as nulls
Then there's the Read MDT Fields Immediate Alternate input command 🦋 It's the same as Read MDT Fields Alternate, except:
- The command is indicated by a
X'83' - The command is an immediate read command like Read Immediate. So no control characters follow the command byte, field data comes back right away, and the aid code is
X'00'💀
Next, the Move Cursor order (MC) has been added (page 2-137) 🧚 The MC order moves the cursor to the location given by the two bytes after the order. Byte 1 is the row address and byte 2 is the column address. It's super handy when you want to move the cursor without messing with the system IC address. The MC order doesn't care about the Write to Display control character values, including the "Leave Cursor" flag (CC1 bit 1). And if there's more than one MC or IC in the data stream, the cursor ends up at the address from the last MC or IC 🫶
Heads up: a parameter error gets posted when any of these happen.
- There are fewer then two bytes following the order.
- The row address is zero or greater than the number of rows on the display screen.
- The column address is zero or greater than the number of columns on the display screen.
Here's the format:
Move Cursor Order Byte 1 Byte 2
X'14' Row Address Column AddressAnd the result? The address from the MC order is used to move the cursor once the Write to Display is done 💜
Now for the Transparent Data order (TD), also added on page 2-137 🌈 The TD order is followed by two length bytes and then the transparent data. That transparent data gets written to the display screen starting at the current display address. Any values from Hex 00 to Hex FF are allowed, and all length values are valid as long as you don't overwrite the end of the display screen. Iconic, honestly ✨
Restrictions, because there are always restrictions 🙈 A parameter error gets posted when:
- There are fewer then two bytes following the order.
- There are fewer bytes in the data stream than specified in the length field.
- Attempting to write beyond the end of the display screen.
Format:
TD Order Bytes 1 and 2 Bytes 3 to ?
X'10' Length of transparent Transparent data
data (not counting
length bytes)Result: the transparent data is written to the display 🍓
Last but definitely not least, the Query command 👑 It's a brand new input command (page 2-5) that the server uses to find out what the client 5250 display can actually do. When the client gets a Query command, it sends back a Query Reply describing its capabilities. Main character energy, fr fr.
The Query command must follow an Escape ('04'X) and a Write Structured Field command ('F3'X). Here's what it looks like:
Byte Value Description
====== ======= ========================
0-1 X'0005' Length of command
2 X'D9' Command Class
3 X'70' Command Type - Query
4 X'00' Flag Byte
Bit 0: B'0' - Query Command
Bit 1-7: - Reserved (set to zero)And the Query Reply is laid out like this 💅
Byte Value Description
===== ======== ===================================
0-1 X'0000' Cursor Row/Column (set to zero)
2 X'88' Inbound Write Structured Field Aid
3-4 X'003A' Length of Query Reply
5 X'D9' Command Class
6 X'70' Command Type - Query
7 X'80' Flag Byte
Bit 0: B'1' - Query Reply
Bit 1-7: - Reserved (set to zero)
8-9 Controller Hardware Class
X'0001' - Local Twinax Controller
X'0061' - Local ASCII Controller
X'0101' - SDLC/X.21/X.25 Twinax Controller
(5394 emulating a 5294)
X'0103' - SDLC/X.21/X.25 Twinax Controller (5394)
X'0200' - PC DOS non-DBCS WSF
X'0300' - OS/2 non-DBCS WSF
X'0400' - PC DOS DBCS WSF
X'0500' - OS/2 DBCS WSF
X'0600' - Other WSF or any other 5250 Emulator
10-12 Controller Code Level
X'010300' - For example, Version 1 Rel 3.0
13-28 X'00' Reserved (set to zero)
29 Device Type
X'01' - 5250 Display or 5250 Emulation
30-33 C'cccc' Device Type (e.g. 3180 for 3180 Mod 2)
34-36 C'ccc' Device Model (e.g. 002 for 3180 Mod 2)
37 Keyboard ID
X'02' - Standard Keyboard
X'82' - G Keyboard
38 X'00' Extended Keyboard ID
39 X'00' Reserved
40-43 X'xxxxxxxx' Display Serial Number
44-45 Maximum number of input fields
X'0100' - Typically = 256 input fields
46-48 X'00' Reserved (set to zero)
49-53 Controller/Display Capability
Bit 0-1: B'00' - No Row 1/Col 1 support
B'01' - Row 1/Col 1 support
Bit 2: B'0' - No Read MDT Alternate Command support
B'1' - Read MDT Alternate Command support
Bit 3: B'0' - Display does not have PA1/PA2 support
B'1' - Display does have PA1/PA2 support
Bit 4: B'0' - Display does not have PA3 support
B'1' - Display does have PA3 support
Bit 5: B'0' - Display does not have Cursor Select support
B'1' - Display does have Cursor Select support
Bit 6: B'0' - Display does not have Move Cursor Order support
B'1' - Display does have Move Cursor Order support
Bit 7: B'0' - No Read MDT Immediate Alt Command support
B'1' - Read MDT Immediate Alt Command support
50
Bit 0-3: B'0001' - 24 x 80 Screen Size
B'0011' - Capable of 24 x 80 and 27 x 132
Bit 4: B'0' - No light pen support
B'1' - Light pen support
Bit 5: B'0' - No Mag Stripe Reader support
B'1' - Mag Stripe Reader support
Bit 6-7: B'00' - Mono display
B'01' - 5292/3179 style color, including color PCs
51 X'00' - Reserved
52
Bit 0-2: B'000' - No Double Byte Character Set (DBCS)
capability
B'001' - Presentation screen DBCS capability only
Bit 3-7: B'00000' - Reserved
53
Bit 0-2: B'000' - No graphics capability
B'001' - 5292-2 style graphics
Bit 3-7: B'00000' - Reserved
54-60 X'00' Reserved (set to zero)6. References 📚
- IBM, "IBM 5250 Information Display System, Functions Reference Manual", SA21-9247-6, March 1987.
- Postel, J. and J. Reynolds, "Telnet Protocol Specification", RFC 854, USC/Information Sciences Institute, May 1983.
- Postel, J. and J. Reynolds, "Telnet Option Specifications", RFC 855, USC/Information Sciences Institute, May 1983.
- Postel, J. and J. Reynolds, "Telnet Binary Transmission", RFC 856, USC/Information Sciences Institute, May 1983.
- VanBokkeln, J., "Telnet Terminal-Type Option", RFC 1091, FTP Software, Inc., February 1989.
- Postel, J. and J. Reynolds, "Telnet End of Record Option", RFC 885, USC/Information Sciences Institute, December 1983.
Security Considerations 🔒
Security issues are not discussed in this memo. Nothing to see here, bestie 🙈
Author's Address 🖋️
Paul Chmielewski
IBM Corporation
Highway 52 and 37 Street North West
Rochester, Minnesota 55901
Phone: (507) 253-6315
EMail: paulc@rchland.iinus1.ibm.com
📦 where this page comes from
- ietf: rfc1205 1991-02
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms