doc: Add RFC documents

1 files changed, 731 insertions, 0 deletions

diff --git a/doc/rfc/rfc1646.txt b/doc/rfc/rfc1646.txt
new file mode 100644
index 0000000..353e1ff
--- /dev/null
+++ b/doc/rfc/rfc1646.txt
@@ -0,0 +1,731 @@
+
+
+
+
+
+
+Network Working Group                                         C. Graves
+Request for Comments: 1646                                     T. Butts
+Category: Informational                                        M. Angel
+                                                   Open Connect Systems
+                                                              July 1994
+
+
+           TN3270 Extensions for LUname and Printer Selection
+
+Status of this Memo
+
+   This memo provides information for the Internet community.  This memo
+   does not specify an Internet standard of any kind.  Distribution of
+   this memo is unlimited.
+
+Abstract
+
+   This document describes protocol extensions to TN3270.  There are two
+   extensions outlined in this document.  The first defines a way by
+   which a TN3270 client can request a specific device (LUname) from a
+   TN3270 server.  The second extension specifies how a TN3270 printer
+   device can be requested by a TN3270 client and the manner in which
+   the 3270 printer status information can be sent to the TN3270 server.
+   Discussions and suggestions for improvements to these enhancements
+   should be sent to the TN3270E Working Group mailing list
+   TN3270E@list.nih.gov . These extensions will be called TN3287 in this
+   document.  This information is being provided to members of the
+   Internet community that want to support the 3287 data stream within
+   the TELNET protocol.
+
+1. INTRODUCTION
+
+   The need to communicate with IBM mainframe systems has a number of
+   unique requirements associated with it.  This document addresses
+   those needs in a TCP/IP communications network.
+
+   IBM terminals are generically referred to as 3270's which includes a
+   broad range of terminals and devices,not all of which actually begin
+   with the numbers 327x.
+
+   The 3270 family of terminals and the IBM mainframe applications
+   systems are VERY closely coupled and it is the nature of the way the
+   3270s and the applications interact which require that this document
+   be available to provide a consistent way for the TCP/IP environment
+   to interact effectively with the 3270 applications of the IBM
+   mainframe world.
+
+
+
+
+
+Graves, Butts & Angel                                           [Page 1]
+
+RFC 1646                   TN3270 Extensions                   July 1994
+
+
+   IBM mainframe applications systems have existed for almost two
+   decades now and are used to serve tens of thousands of users daily.
+   For this reason it is usually the need of a mainframe environment to
+   add TCP/IP network support WITHOUT writing new applications to run
+   with the TCP network.  The TN3270 series of documents addresses how
+   this can be done and maintain compatibility with those mainframe
+   application systems.
+
+   One of the unique characteristics of the 3270 terminals is their
+   ability to communicate status information in an out-of-band data
+   flow.  These status's are in turn used by the applications systems to
+   support error recovery, and conflict resolutions, examples of these
+   are printer out of paper, and terminal powered up.  The terminals are
+   also half duplex and block mode in their operations, which results in
+   the need to communicate when blocks are being sent, when they end,
+   and when they cannot be sent.  This document describes these
+   characteristics in IBM VTAM/SNA terms.  Some VM mainframe application
+   systems do not use VTAM, so for those systems these terms don't
+   apply.  For any systems which use VTAM these terms apply and are
+   dealt with in some way by the TCP/IP to VTAM interface.
+
+   VTAM/SNA is a hierarchical network and some of that hierarchy needs
+   to be addressed by the TCP network attaching to it if the
+   applications systems are to continue to provide the same applications
+   support that they have provided to the 3270 terminals.
+
+   The 3270 terminal environment consists of a terminal controller with
+   terminals attached to that controller.  In VTAM/SNA this controller
+   is called a PU (Physical Unit) and the terminals called LUs (Logical
+   Units).  The PU is used to communicate management information to the
+   VTAM/SNA system, and the LU is used by the application to communicate
+   with the terminal.  VTAM/SNA identifies each LU and PU in a network
+   by a unique name.  These names are referred to as LUnames and
+   PUnames, and is how the network is managed and the applications
+   identify what terminals are being communicated with in the network.
+   The actual connection between a terminal and the applications is
+   referred to as a session, and it is this session which has both in-
+   band and out-of-band information flows sent between the applications
+   and the terminals.
+
+   VTAM/SNA 3270 terminals actually have two sessions when communicating
+   with the applications.  One session is directly connected with the
+   application and the other session is connected directly to VTAM.  It
+   is the session with VTAM, also called the SSCP, that is used to
+   communicate the out-of-band information flows.  This session is
+   called the SSCP-LU session, and the session with the application is
+   called the LU-LU session (in VTAM an applications is just another
+   Logical Unit).
+
+
+
+Graves, Butts & Angel                                           [Page 2]
+
+RFC 1646                   TN3270 Extensions                   July 1994
+
+
+   One such out-of-band flow is the LUSTAT message which tells the
+   application that the status of the terminal has changed, and is how a
+   printer or screen tells the application that it is ready, or is not
+   ready to receive data.
+
+   There are also flows which must be able to flow in the LU-LU session
+   to help control the use of the terminal by applications.  The block
+   of information sent in a session is called an RU (Request Unit) and
+   it tells what type of data this block contains, how long it is and if
+   more data (RUs) is coming along.  This is a gross over simplification
+   of what RUs are and do, but it should help understand their use in
+   the TN3270 documents.  Some of the VTAM/SNA terms used to describe
+   what an RU is requesting are:  Chains/chaining which tell a session
+   partner that another RU is being sent or not being sent in this
+   transmission.  Brackets which are used to indicate that a unit of
+   work is complete, such as when a printout of a file is complete.
+
+   The determination of what part of the VTAM/SNA protocols such as
+   brackets and chaining are to be used are managed by VTAM tables
+   called LOGMODE tables.  These tables are selected when an LU-LU
+   session is started and set up such things as bracket, and/or chaining
+   protocols; and the type of terminal data contained in the RUs, such
+   as printer data without screen formatting data (LU type 1), 3270
+   screen formatted data (LU type 2) and 3270 screen formatted data for
+   a printer (LU type 3).  The LOGMODE tables also contain the size of
+   the RU to be sent and received.  These tables also communicate the
+   screen size of 3270 terminals such as 24X80 (Model 2), 27X132 (Model
+   5), etc.  Each LU has a LOGMODE table entry hard assigned to it as
+   part of the VTAM configuration (often called a GEN).  The selection
+   of these table entries can't be controlled by the terminal LU or PU.
+   They can only be selected by the user at connection/logon time or by
+   the application when the connection is established.  The actual
+   LOGMODE entries to be used during a session are sent at session logon
+   time, in a special type of RU called a BIND.  Once the bind has been
+   sent then the rules for the use of the session have been set, can't
+   be changed, and must be followed.
+
+   The purpose of the TN3287 protocol is to provide a general IBM 3270
+   host printer communications facility.  Its primary goal is to allow a
+   method of connecting printer devices and printer-oriented processes
+   to each other.  This protocol will allow a TN3270 Client to process
+   3287 print data streams.
+
+   This memo supplements and extends the STD 8, RFC 854, TELNET Protocol
+   Specification.  This memo also presents an example of the correct
+   implementation.
+
+
+
+
+
+Graves, Butts & Angel                                           [Page 3]
+
+RFC 1646                   TN3270 Extensions                   July 1994
+
+
+2. GENERAL CONSIDERATIONS
+
+   A TELNET connection is a Transmission Control Protocol (TCP)
+   connection used to transmit data with interspersed TELNET control
+   information.
+
+   The companion document, STD 8, RFC 854 -- "TELNET Protocol
+   Specification" should be consulted for further information about the
+   TELNET command, codes and code sequences referenced in this
+   specification.
+
+3. CLIENT-SERVER NEGOTIATION
+
+   The TN3270 Client and Server require a specific negotiation protocol.
+   After the negotiation is complete, all transmission between the
+   Client and Server is in TELNET Binary format with a TELNET "End-Of-
+   Record(EOR)" sequence at the end of each data stream.
+
+   Support for the TN3287 data stream requires that both sides:
+
+      A.  Are able to exchange binary data.
+
+      B. Can establish the agreement between client and server on the
+         terminal type that will be used.
+
+      C. Agree to use the TELNET IAC EOR as a delimiter for inbound
+         and outbound TN3287 data streams
+
+   This implementation requires the options: TERMINAL-TYPE and BINARY be
+   successfully negotiated between the Client and Server before
+   processing of any print data streams.
+
+   This implementation supports host applications that can mix LU 1 and
+   LU 3 type data in the data stream.
+
+3.1  TN3287 SERVER
+
+   The maximum Request Unit (RU) size is server specific, but should not
+   exceed 4 kilobytes.
+
+   The LU type is determined by the bind from the mainframe application.
+   The server, when bound, must remember LU 1 or LU 3 type.
+
+   The server will automatically unbind the session upon receipt of a
+   TELNET CLOSE command.  The printer will be reported to VTAM as
+   powered down until a new TELNET connection is established.
+
+
+
+
+
+Graves, Butts & Angel                                           [Page 4]
+
+RFC 1646                   TN3270 Extensions                   July 1994
+
+
+3.2  TN3287 CLIENT
+
+   The TN3287 Client is a TN3270 client created specifically to print
+   mainframe 3270 print data.  The client emulates the IBM device type
+   that it identifies itself to the TN3270 server as, in this case, an
+   IBM 3287 model 1 type printer.  The design of this printer protocol
+   is aligned with the way printing occurs in the IBM host and how 3270
+   printers function.  These printer extensions DO NOT support a 3270
+   printer client that cannot accept both types LU 1 and LU 3 printer
+   streams.  No IBM printer operates in this fashion, and as a result,
+   no TN3270 server could function properly with mainframe applications
+   if it didn't allow for a mixing of LU 1 and LU 3 data streams.  The
+   common way in which this can occur is printer sharing between
+   multiple IBM host applications, such as CICS and JES.  Since there is
+   no restriction, the JES can be configured to output LU 1 data
+   streams, and the CICS can be  configured for LU 3 data streams.
+   Therefore, the server will identify what LU type the current
+   application connected to the server is using.  If that type is LU 1,
+   ALL message records sent to the Client will be preceded by one byte
+   of binary zeros (0x00).  If the first byte is not zeros, then that
+   byte will be a valid LU type 3 Write-Command-Code(WCC), which can
+   NEVER be zeros.  Thus, the client can tell the LU type of data as
+   each record is received.
+
+   This protocol does allow for the client to shutdown if the client
+   does not wish to support both LU types.  This is accomplished by
+   detecting an invalid data type from the received record, and
+   notifying the user that the mainframe application has sent LU type x
+   print data and should be configured for LU type y printing.
+
+4.  COMMAND STRUCTURE
+
+      1. All TELNET commands consist of at least a two-byte sequence:
+         the "Interpret-as-Command(IAC)" escape character followed by
+         the code for the command.
+
+   NOTE:  Since the TELNET IAC character (255 decimal) is used as a
+   delimiter (together with EOR) in the inbound and outbound data
+   streams, a data byte within the data stream itself that has the same
+   value as the IAC command is sent as two bytes (255, 255) and one byte
+   is discarded.
+
+4.1  TELNET COMMANDS
+
+   Command meaning - WILL and DO commands are used to obtain and grant
+   permission for the subsequent subnegotiation.  Both sides must
+   exchange WILL TERM-TYPE and DO TERM-TYPE before subnegotiation.
+
+
+
+
+Graves, Butts & Angel                                           [Page 5]
+
+RFC 1646                   TN3270 Extensions                   July 1994
+
+
+   The actual exchange of information is done within the option
+   subcommand.
+
+   <IAC DO TERMINAL-TYPE>  Sender requests that the other party begin
+   terminal-type sub-negotiation.
+
+   <IAC WILL TERMINAL-TYPE>  Sender is willing to send terminal-type
+   information in a subsequent sub-negotiation.
+
+   <IAC SB TERMINAL-TYPE SEND IAC SE>  Sender requests the receiver to
+   transmit his terminal-type.
+
+   <IAC SB TERM TYPE IS IBM-3287-1 IAC SE>   Sender is stating the name
+   of his terminal-type.  The code for <IS> is 0.  Optionally, a
+   specific Logical Unit (LU) can be requested by using the TERMINAL-
+   TYPE string below.   If no LUname is specified, the first available
+   3287 LU is selected.
+
+      IAC SB TERM-TYPE IS IBM-3287-1 @ LUNAME IAC SE
+
+   <IAC DO BINARY>  Sender requests that sender of the data starts
+   transmitting or confirms that the sender of data is expected to
+   transmit characters that are to be interpreted as 8 bits of binary
+   data by the receiver.
+
+   <IAC WILL BINARY>   Sender requests permission to begin transmitting,
+   or confirms it will now begin transmitting binary data.
+
+   An <EOR> is sent at the end of each SNA Request Unit (RU) end of
+   chain, in either direction.   The first byte following the <EOR> is a
+   Write-Command-Code(WCC) for LU 3 data streams.
+
+   An <AO> is sent at the end of the SNA RU and end of bracket.  This
+   signifies the end of the print output or file by the IBM host
+   application and possibly a change of LU type.
+
+4.2   COMMAND VALUES
+
+
+                     TELNET COMMAND                     CODE
+                     IAC  Interpret as Command           255
+                     DO                                  253
+                     WILL                                251
+                     SB  SuBnegotiation option           250
+                     SE  Subnegotiation End              240
+                     TERMINAL-TYPE                        24
+                     SEND                                  1
+                     IS                                    0
+
+
+
+Graves, Butts & Angel                                           [Page 6]
+
+RFC 1646                   TN3270 Extensions                   July 1994
+
+
+                     EOR  End-Of-Record                   25
+                     BINARY                                0
+                     AO  Abort Output                    245
+                     IP  Interrupt Process               244
+                     AYT  Are You There                  246
+                     BREAK                               243
+
+   NOTE:  The above codes and code sequences have the indicated meaning
+   only when immediately preceded by an "Interpret as Command (IAC)".
+
+5.  TN3270 Printer Status Message
+
+   The status message can be sent at any time.  It must be sent every
+   time the TN3270 Server sends an End-of-Record(EOR) indicator to the
+   TN3270 Client, or when a printing error occurs at the Client.  The
+   Printer Status Message is only sent by the TN3270 Client. Once the
+   End-Of-Record IAC is processed, the TN3270 Client sends the status
+   message to the server when it is ready to receive more print data.
+
+      MESSAGE DESCRIPTION:      SOH  %  R  S1  S2  IAC  EOR
+
+
+                               SOH = 0X01
+                               % = 0X6C
+                               R = 0XD9
+                               S1 = Status/Sense Byte 0
+                               S2 = Status/Sense Byte 1
+                               IAC = Telnet IAC Character
+                               EOR = Telnet EOR Character
+
+5.1   Status/Sense Byte description
+
+5.1.1.  S/S Byte 0:
+
+        High Order                                          Low Order
+
+
+        _____________________________________________________________
+        |                                                           |
+        |   0      1      2      3      4      5      6      7      |
+        |___________________________________________________________|
+
+
+          Bit Number:       Bit Definition:
+
+                0           Always Zero
+
+                1           Always Zero
+
+
+
+Graves, Butts & Angel                                           [Page 7]
+
+RFC 1646                   TN3270 Extensions                   July 1994
+
+
+                2           Always Zero
+
+                3           Always Zero
+
+                4           Always Zero
+
+                5           Unit Specify - is set due to an error
+                            condition.  The reason for the error
+                            condition will be indicated in S/S Byte 1.
+                            See Note 1*.
+
+                6           Device End - when this bit sent in response
+                            to a data message it indicates the client
+                            has successfully processed the data message
+                            from the server and notifies the server to
+                            send a new data message to the client when
+                            available.   See Note 2*.
+
+                7           Always Zero
+
+
+   Note 1*:   A negative response to the Server's data message would be
+   S/S Byte 0 Bit 5 "Unit Specify condition".  The possible Unit Specify
+   conditions are listed below.  (See Section 3.2 for bit settings for
+   the Unit Specify conditions listed below.)
+
+                Unit Specify Condition:    SNA Sense Code sent to host:
+
+                Command Rejected                     0X10030000
+                Intervention Required                0X08020000
+                Data Check                           0X10010000
+                Operation Check                      0X10050000
+                Component Disconnected (LU)          0X08020000
+
+   Note 2*:   Device End -  A positive response to the Server's data
+   message would be the "Device End" bit (S/S Byte 0 Bit 6) to indicate
+   a ready to receive data from the host condition.  This will also be
+   sent after clearing a previous Unit Specify condition of
+   "Intervention Required".
+
+
+
+
+
+
+
+
+
+
+
+
+Graves, Butts & Angel                                           [Page 8]
+
+RFC 1646                   TN3270 Extensions                   July 1994
+
+
+5.1.2.  S/S Byte 1:
+
+         High Order                                           Low Order
+
+       ______________________________________________________________
+       |                                                            |
+       |    0      1      2      3      4      5      6      7      |
+       |____________________________________________________________|
+
+
+          Bit Number:       Bit Definition:
+
+
+               0            Always Zero
+
+               1            Always Zero
+
+               2            Command Rejected (CR) -- This bit
+                            indicates an invalid 3270 command
+                            generated.
+
+               3            Intervention Required - Printer Not Ready.
+                            See Note 3*.
+
+               4            Component Disconnected - Printer is powered
+                            off or printer cable not connected.  See
+                            Note 4*.
+
+               5            Data Check - Invalid print data
+
+               6            Always Zero
+
+               7            Operation Check - An illegal buffer address
+                            or incomplete order sequence
+
+   Note 3*:  The Intervention Required is cleared by sending an S/S
+   message with the "Device End" bit (Bit 6 of S/S byte  0).  The LUSTAT
+   sent to the host is 0X00010000.  The IBM host interprets this as a
+   "printer now ready" condition.
+
+   Note 4*:  The Component disconnected is cleared by sending an S/S
+   message with the "Device End" bit  (Bit 6 of S/S byte 0).  The LUSTAT
+   sent to the host is 0X082B0000.  The IBM host interprets this as a
+   "printer now ready -- presentation space integrity may be lost"
+   condition.
+
+
+
+
+
+
+Graves, Butts & Angel                                           [Page 9]
+
+RFC 1646                   TN3270 Extensions                   July 1994
+
+
+6.  The following is an example of the Client-Server negotiation
+    process.
+
+      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-3287-1 IAC SE
+
+      Note: To request a specific LU the TERMINAL-TYPE string would be:
+      IAC SB TERMINAL-TYPE IS IBM-3287-1 @ LUNAME IAC SE
+      (The client has specified its terminal type is an IBM-3287-1)
+
+
+      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 End-Of-Record
+      (EOR)).
+
+
+      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 use binary
+      transmission)
+
+
+      Server:   0x00 (3270 PRINT DATA)
+      Client:        (S/S with DEV END) IAC EOR
+      Server:   0x00 (3270 PRINT DATA) IAC EOR
+
+      NOTE:  LU 1 type data is prefaced with a 0x00 character. LU 3
+      type data is not prefaced with a special character.  This
+      character will precede print data in each chain, and should be
+      discarded before the print data is processed.   An <IAC EOR> must
+      be received before changing to LU 1 or LU 3 type data.
+
+      Client:        (S/S with IR) IAC EOR (This indicates a paper jam
+                    at printer.)
+      Client:        (S/S with DE) IAC EOR (This indicates the clearing
+                    of above condition.)
+      Server:  0x00 (3270 PRINT DATA) (This indicates start of LU 1
+               data)
+
+      Server:   (3270 PRINT DATA)
+
+
+
+Graves, Butts & Angel                                          [Page 10]
+
+RFC 1646                   TN3270 Extensions                   July 1994
+
+
+      Server:   (3270 PRINT DATA)
+      Server:   (3270 PRINT DATA) IAC EOR
+      Client:        (S/S with DE) IAC EOR
+      Server:   0x00 (LAST 3270 PRINT DATA) IAC EOR
+
+
+      Client:        (S/S with DE) IAC EOR
+      Server:   IAC AO
+      (The Abort Output <AO> signifies the end-of-bracket -- end of
+      print job)
+
+7.  SECURITY CONSIDERATIONS
+
+   This document does not specify a security methodology to insure that
+   the client requesting a printer LU name is authorized to access that
+   LU.  Currently, this is left up to individual server implementations.
+   The design of the protocols described in this document allow for the
+   future incorporation of the RFCs regarding encryptions and
+   authentication protocols and services.  However, before this may
+   occur, certain extensions may be required to the protocols defined in
+   this document or to the encryptions and authentication services and
+   protocols.
+
+8. ERROR CONDITIONS
+
+   After a client and server have successfully completed negotiation, a
+   number of potential error conditions may be detected by the server
+   which require notifying the client and aborting the connection.
+
+   When an error condition is detected by the server, the client must be
+   negotiated back into NVT mode by the server sending a "WONT/DONT
+   BINARY" TELNET sequence and the client responding with the
+   appropriate "DONT/WONT BINARY" TELNET sequence.
+
+   The server should immediately send the appropriate error message to
+   the client as an ASCII string and then close the connection. The
+   error message should be prefixed by a numeric identifier to precisely
+   notify the client of the specific error condition. The error message
+   sent to the client should be routed to the proper console or log for
+   corrective action.
+
+   Below is a list of error conditions identified by numeric value,
+   error text, meaning of the error and recovery procedure.
+
+      Message: "01 No LU's of the type configured"
+
+         Meaning: The configuration definition on the server
+                  does not include the LU type requested.
+
+
+
+Graves, Butts & Angel                                          [Page 11]
+
+RFC 1646                   TN3270 Extensions                   July 1994
+
+
+         Recovery: Notify your Systems Administrator as this
+                   is a permanent error condition.
+
+      Message: "02 Requested LU unavailable"
+
+         Meaning: The requested LU is not available at
+                  this time.
+
+         Recovery: This may be a temporary error and may
+                   be retried periodically.  If the condition
+                   persists contact your Systems Administrator.
+
+      Message: "03 Requested LU type is inconsistent with configuration"
+
+         Meaning: The LU requested does not match the terminal
+                  type in the server configuration.
+
+         Recovery: Notify your Systems Administrator as this
+                   is a permanent error condition.
+
+      Message: "04 Requested LU is not configured"
+
+         Meaning: The LU is not defined in server configuration.
+
+         Recovery: Notify your Systems Administrator as this
+                   is a permanent error condition.
+
+   When a client receives a message not defined in the above list, the
+   message should be displayed to a console or log and the connection to
+   the server should be closed.  No other recovery should be attempted
+   as this is most likely a fatal error condition.  (Notify your Systems
+   Administrator.)
+
+9. REFERENCES
+
+   [1] Postel, J., and J. Reynolds, "TELNET Protocol Specification", STD
+       8, RFC 854, USC/Information Services Institute, May 1983.
+
+   [2] VanBokkeln, J., "TELNET Terminal-Type Option" RFC 1091, FTP
+       Software Inc., February 1989.
+
+   [3] Postel, J., and J. Reynolds, "TELNET Binary Transmission", STD
+       27, RFC 856, USC/Information Services Institute, May 1983.
+
+
+
+
+
+
+
+
+Graves, Butts & Angel                                          [Page 12]
+
+RFC 1646                   TN3270 Extensions                   July 1994
+
+
+Authors' Addresses
+
+       Cleve Graves
+       2711 LBJ Freeway
+       Dallas, Texas  75234
+
+       Phone: (214) 484-5200
+       EMail: cvg@oc.com
+
+
+       Thomas Butts
+       2711 LBJ Freeway
+       Dallas, Texas  75234
+
+       Phone: (214) 484-5200
+       EMail: tom@oc.com
+
+
+       Michelle Angel
+       2711 LBJ Freeway
+       Dallas, Texas  75234
+
+       Phone: (214) 484-5200
+       EMail: angel@oc.com
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Graves, Butts & Angel                                          [Page 13]
+