Subject: Proposal for FMH on TN3270E (2nd draft)

From: "Derek W. Bolton" <[email-masked]>
Date: Fri, 30 Jan 1998 17:29:17 +1100 (EST)

This revision corrects an error regarding the inbound FMH from
a DBCS printer and adds information regarding IPDS.
The key consequence of these two changes is that "silent FMH
support" becomes a viable proposition for IPDS.  Since DBCS
and IPDS are the front-runners in needing FMHs, this very
simple form of support is all that is needed at present.
If anyone is aware of other looming needs, please speak up.

Changes are flagged in column 74.

-----------------------------------------------------------

      FMH support for TN3270E
      -----------------------

1. Background
   ----------

1.1 Usage
    -----

Function Management Headers are used in some LUT0 and LUT1 SNA
applications, and in all LUT6.2 applications.  They are not permitted
in LUT2 or LUT3, and were not at first used in the 3274 LUT1 support.
Consequently, no provision was made for them in TN3270, TN3270
printing (RFC1646) or TN3270E (RFC1647).

Subsequently, support for FMHs over LUT1 has been added to 3x74,
as has support for LUT6.2.  In particular, FMHs are used on
3x74 LUT1 for DBCS (Kanji etc.) printers and IPDS printers.

1.2 FMHs in general
    ---------------

1.2.1 Relationship to RUs and chains

In the simplest usage:

- There is up to one FMH per chain.
- Only at the beginning of the chain.
- The FMH may be spread over multiple RUs if too long for one.
- The FI flag is 1 in the BC RU and 0 in the rest.

At the next level of complexity:

- There may be multiple FMHs, consecutively, at the start of the
  chain.
- The presence of an FMH following the current one is indicated
  by the concatenation flag at byte 1, bit 0 of the current.
- As with a single FMH, these FMHs may continue over several
  RUs, but only the first has the FI flag on.

(Note that an FMH other than the first may happen to be at the
start of an RU, but the FI flag in that RU would be 0.  The
concatenation flag in the preceding FMH is sufficient to
introduce it.)

So far so good.

However, the description of FMHs in [2] only requires a (concatenated
sequence of) FMH to start at the start of an RU, not necessarily at
the start of a chain.  It states clearly that any RU in the chain may
have the FI flag on and thus start with an FMH, though the preceding
RU ended with ordinary data.

This would be awkward for TN3270E, since the RU boundaries are not
visible to the clients.  Fortunately, it is awkward for higher-level
Host applications also, e.g. CICS and IMS applications.  These
generally do not see RU boundaries either.  Moreover, it is
contradicted by the description of sense code 400F in [2].  So it is
not surprising that the 3174 does not support this generality.

1.2.2 Usage of DSSEL in FMH1s

FMH1s describe the datastream of accompanying data.
The accompanying data can be in a single chain (BEDS) or
spread over multiple chains (BDS ... EDS).

It is also possible to abort the datastream (ADS instead of EDS),
suspend a datastream (SDS) and resume it later (RDS).
In practice SDS/RDS are only used to insert console output into
a longer transfer of data.

The entire datastream must be within a bracket.  If EB occurs
after BDS but before EDS then the datastream is implicitly aborted.

1.2.3 Response to FMH RU

The FI flag is not echoed in the SNA response.

There are many SNA sense codes associated with FMH errors.  Most of
these are at the application level and begin with 0x1008.

1.3 FMHs in 3x74 LUT1
    -----------------

On LUT1, the 3174 supports only FMH-1s.

By default, LUT1 sessions use SCS datastream.  These FMH1s are used
for introducing other datastreams.  For these purposes, the relevant
format is:

 byte   0  |      1      |      2       |     3     |   4  .. n
    .------------------------------------------------------------
    |length|concat| type |medium|subaddr|flags| DSP | DSSEL
    '------------------------------------------------------------
 bits    8     1      7      4      4      4     4      3
 value  n+1    0     01      0      0      0    B-D    xxx

 where
   concat is the concatenation flag
   medium = 0 (console)

1.3.1 Structured Field Datastream

(See [1].)                                                               |

This is used by DBCS and IPDS printers so that a Read Partition Query    |
exchange can be conducted with an LUT1 printer.

Usage: 0x0601000B6000

  BC RU
  length = 6
  concat = 0
  DSP = 0xB
  DSSEL = BEDS

Since the DSSEL = BEDS, the Structured Field datastream is from
the end of the FMH to the end of the chain.

The usage is bidirectional, but always as one from the Host
application and a reply from the secondary.

The inbound reply is slightly different.  It has the SRI flag on:        |

  0x0601008B6000                                                         |

1.3.2 Document Content Architecture (DCA-L2) Datastream

Usage:

DSP = 0xC

Anyone have any further information on this????

1.3.3 IPDS Datastream

(See [4].)                                                               |

Usage: 0x0601300D4000, 0x0601300D2000

  OIC RU
  length = 6
  concat = 0
  DSP = 0xD
  DSSEL = BDS, EDS
  No data following FMH in the same chain                                |

Although no ADS is sent, an EB before EDS implicitly aborts
the datastream.

1.3.4 FMH Error handling in 3174

SNA sense      Cause

0835 0006      Bind has byte 6 bit 1 set to 1 (FMHs will be used)
               but printer does not support FMHs

1008 xxxx      Invalid parameters in FMH

400F 0000      Incorrect use of FI (not BC RU, or Bind had byte 6
               bit 1 set to 0)

1.4 Existing support of FMHs in "TN3270"
    -----------------------------------

A crude de facto standard has arisen for handling Structured Field
Datastream FMHs in both RFC1646 and RFC1647 contexts: the FMHs are
merely forwarded, in both directions, as data.  The receiver must
recognize that the FMH is present by inspecting the first few bytes of
the Telnet record and determining that they do not look like valid
SCS.

This is workable because the only permitted FMH is a fixed 6-byte
string, and it only occurs at the start of a record.

This de facto standard is referred to below as "silent FMH support".

2. Proposal
   --------

2.1 Policy
    ------

There is a trade-off between making many data checks in the server,
thereby keeping the client interface simple, and minimizing the
server's knowledge of the datastream, thereby preserving flexibility.
This proposal takes the latter approach.  In particular, except for
silent FMH support, the server does not know which FMH types the
client supports.

Since TN3270E does not permit the client to reject the Bind,
the server must police the bind parameters as far as possible.

With regard to the 1008 xxxx sense codes, it is impractical to
perpetuate the TN3270E style of mapping these to new one-byte codes.
(Neither is that style of any benefit to customers or support
engineers, as it presents them with yet another table of codes that's
needed to understand the flows.)

Instead, the client has the option of providing the SNA codes or
letting the server map all errors to the less informative 1008 0000.

2.2 Phases                                                               |
    ------                                                               |

It turns out that the only two well-understood requirements (DBCS and    |
IPDS) will work perfectly well with "silent FMH support".  Therefore     |
this proposal is in three phases:                                        |

I)   Bless the de facto "silent FMH support".                            |

II)  Add the capability for sending SNA sense codes from the client.     |

III) Add an architected mechanism for transferring arbitrary FMHs        |
     through a server.                                                   |

     Note, however, that the client is unlikely to be able to use        |
     any except BEDS for inbound FMHs since the server will              |
     assume CD at the end of each chain.                                 |

The third phase can be deferred until a need is demonstrated.            |

2.3 New functions to be negotiated
    ------------------------------

2.3.1 FMH-FLAG function (Phase III)                                      |

This function has no effect unless TN3270E is also negotiated.

If this function is negotiated then the server and client may send
TN3270E headers with the FMH-PRESENT flag set to 1.

2.3.2 SNA-SENSE function (Phase II)                                      |

This function has no effect unless TN3270E and RESPONSES are also
negotiated.

If this function is negotiated then the client may send RESPONSE
messages with SNA-SENSE-PRESENT set to 1 in the RESPONSE-FLAG field.

Note that although the need comes from the welter of FMH sense codes,
the usage of this function is not restricted to responses to SCS-DATA.
Once this function has been negotiated, the server is committed to
accepting SNA-SENSE responses to 3270-DATA.

2.4 New flags in TN3270E header fields
    ----------------------------------

2.4.1 FMH-PRESENT flag in REQUEST-FLAG field (Phase III)                 |

The 0x08 bit is allocated in the REQUEST-FLAG field.

This is the first use of the REQUEST-FLAG field for data types           |
other than REQUEST.  By implication, this proposal renders               |
the REQUEST-FLAG field meaningful for data types SCS-DATA and            |
RESPONSE.  In each case, the REQUEST-FLAG field is considered            |
a set of bits.  In general, the meaning of the REQUEST-FLAG field        |
depends on the data type.  Although this proposal defines the            |
same bit in the REQUEST-FLAG field for both SCS-DATA and                 |
RESPONSE, it is not implied that the remaining bits will always          |
mean the same for both.                                                  |

When the DATA-TYPE is SCS-DATA, this bit indicates whether the record
starts with an FMH.  This applies both to and from the client.

When the DATA-TYPE is RESPONSE, this flag indicates whether it is a
response to an FMH.  This serves purely to assist in the
interpretation of negative responses.  Thus, although the flag is
defined for both negative and positive responses, it is only necessary
to set the flag when the client is rejecting an FMH without providing
the SNA sense code.  In particular, if the client is rejecting data
following the FMH it is not necessary to set this flag.

This flag is undefined for other DATA-TYPEs.

2.4.2 SNA-SENSE-PRESENT flag in RESPONSE-FLAG field (Phase II)

The 0x04 bit is allocated in the RESPONSE-FLAG field.  When the
DATA-TYPE is RESPONSE, this bit indicates whether the data portion of
the record consists of a single byte status code (SNA-SENSE-PRESENT =
0) or a 4 byte SNA sense code (SNA-SENSE-PRESENT = 1).

2.5 Server behavior
    ---------------

2.5.1 Bind processing

If the server receives an LUT1 Bind with byte 6 bit 1 set to 1 (FMHs
will be used), but the client has not negotiated FMH-FLAG, then the
server may choose to reject the Bind with sense 0835 0006.  This is
left optional (perhaps on customer configuration) in order to
accommodate silent FMH support.  However, when providing such support,   |
the server is recommended to perform additional checks on the data, as   |
outlined below.

Note that this policing can be implemented before Phase III.             |

2.5.2 LU-LU RU from Host application with FI = 1 and category = FMD

The server checks that the FMH is supported in principle:

      check that                  sense if wrong

      Bind said FMH               400F 0000
      BC = 1                      400F 0000

If the server is providing silent FMH support to the client,
the following additional checks, in this order:

      length = 6                  1008 2009 (optional)
      Type = 1                    1008 C000 (optional)
      DSP = B                     1008 6006 (optional)
      FMH is one of a known list, 1008 0000 (optional)                   |
      e.g.:                                                              |
            0x0601000B6000                                               |
            0x0601300D4000                                               |
            0x0601300D2000                                               |

(Note: If neither FMH-FLAG nor SNA-SENSE is negotiated then it is        |
recommended that the server only permit a specific list of               |
FMHs from the Host.)                                                     |

The server either sends a negative response to the Host application or
forwards the data to the client.

If FMH-FLAG has been negotiated, the server forwards the FMH data as
part of the record, just as for normal data, and sets the FMH-PRESENT
flag in the TN3270E header.

If FMH-FLAG was not negotiated then the server does the same with the
data but does not set FMH-PRESENT.

2.5.3 SCS-DATA from client

When the server receives an SCS-DATA record from the client that has
FMH-PRESENT, it forwards the record to the Host application with FI
set in the Begin Chain RU.

If the server receives FMH-PRESENT but FMH-FLAG was not negotiated,
the server may choose either of two actions:

- Terminate the LU-LU session.  It is suggested that, if BIND was
  negotiated, the UNBIND should carry a reason code of 0xFE.
  (If some future extension allows for SNA sense codes to flow to
  the client in the unbind image, the code to be used here should
  be 400F 0000.)

- Behave, for that message only, as though FMH-FLAG was negotiated.

The server is not required to validate FMHs received from the client
with FMH-PRESENT.

If the server has sent a silent FMH to the client, and the SCS-DATA
record does not have FMH-PRESENT, then the server must compare
the first 6 bytes of the data for being 0x0601008B6000.                  |
If so, it sets FI in the Begin Chain RU.

2.5.4 NEGATIVE-RESPONSE from client

When the server receives a NEGATIVE-RESPONSE from the client it checks
the SNA-SENSE-PRESENT flag (if negotiated).

If SNA-SENSE-PRESENT is set then the server takes the first four bytes
of data following the TN3270E header as an SNA sense code and sends
these, unchanged and unchecked, in the -rsp to the Host application.

If SNA-SENSE-PRESENT is not set, or not negotiated, but the LU session
can use FMHs, the server checks the FMH-PRESENT flag (if negotiated).
If it is set then the server sends -rsp 1008 0000 to the Host
application.

If the server is providing silent FMH support to the clients
and SNA-SENSE has not been negotiated then the server cannot             |
in general tell whether the client is objecting to the FMH or            |
to ensuing data.  However, of the three currently identified             |
FMHs requiring support, only 0x0601000B6000 can have data in             |
the same chain.  Even then, the cause of the rejection may               |
well be that this particular client does not expect FMHs at all.         |
Therefore it is recommended to interpret the rejection as                |
rejection of the FMH itself.  The server should send SNA -rsp 1008 0000  |
to the Host.                                                             |

2.5.5 EB from Host application

The existing function is to send EOJ to the client.  There is no
change required here.

2.6 Client behavior
    ---------------

2.6.1 Received FMH

A client that negotiates FMH-FLAG takes responsibility for checking
the received FMHs.  If an error is found in a received FMH, the client
must send a NEGATIVE-RESPONSE.

If SNA-SENSE has been negotiated then the NEGATIVE-RESPONSE should       |
carry SNA-SENSE = 1 and the appropriate 4 byte SNA sense code as the     |
four bytes of the data.

Otherwise, it carries SNA-SENSE = 0, FMH-PRESENT = 1, and a one byte     |
status code of 0 (Command Reject).

2.6.2 Sent FMH

A client that negotiates FMH-FLAG must set FMH-PRESENT on all records
it sends that start with an FMH.

2.6.3 Received EOJ

If a client receives EOJ after BDS and before EDS then the client
should infer ADS.

Appendix A. References
----------- ----------

[1] IBM's "3174 Functional Description", Bookshelf book CN7A7003,
    GA23-0218-11.
[2] IBM's "Systems Network Architecture Formats", GA27-3136-14.
[3] RFC1647
[4] IBM's "IPDS and SCS Technical Reference", S544-5312-00.              |

Appendix B. Abbreviations
-------------------------

-rsp    Negative response
+rsp    Positive response
ADS     Abort Destination Selection, value of DSSEL
BB      Begin Bracket, byte 2 bit 0 of RH of BC RU
BC      Begin chain, byte 0 bit 6 of RH
BC RU   An RU with BC = 1
BDS     Begin Destination Selection, value of DSSEL
BEDS    Begin and End Destination Selection, value of DSSEL
DCA     Document Content Architecture
DSP     Datastream Profile, byte 3 bits 4-7 of FMH
DSSEL   Destination Selection, byte 4 bits 0-2 of FMH
EB      End Bracket, byte 2 bit 1 of RH of BC RU
EC      End chain, byte 0 bit 7 of RH
EC RU   An RU with EC = 1
EDS     End Destination Selection, value of DSSEL
FI      Format Indicator, byte 0 bit 4 of RH
FIC     An RU with BC = 1 and EC = 0
FMD     Function Management Data (user data, not FMH)
FMH     Function Management Header, a SNA data header
IPDS    Intelligent Printer Data Stream
LIC     An RU with BC = 0 and EC = 1
LU      Logical Unit
LUTn    Logical Unit Type n, n = 0, ..
MIC     An RU with BC = 0 and EC = 0
OIC     An RU with BC = 1 and EC = 1
RDS     Resume Destination Selection, value of DSSEL
RH      Request Header, 3 byte header on SNA RU
RU      Request Unit, an SNA frame starting with an RH
SDS     Suspend Destination Selection, value of DSSEL
SNA     Systems Network Architecture

Appendix C. Conventions and Notation
------------------------------------

Byte order is big-endian, i.e. bit 0 is the most significant bit.