3270 Programming Overview

Greg Price July 1992

With the increasing complexity, capacity and speed of electronic finite-state machines, the human interface to these machines becomes increasingly important. The days of the flashing lights on the front panel are gone and the enduring window into machine internal processing is the ubiquitous visual display unit, or more simply, "screen". Whether the technology is based on plasma, liquid crystal or that hardy perennial, the cathode ray tube, the function is the same. The human response to the machine is usually based on the information that is visible on the "screen".

For the extended family of System/370 and related processors, the vast majority of these "screens" are members of the 3270 family. This article will examine some of the issues involved in using some of the extended features of 3270 devices, including some coding specifics for the TSO platform.

Many readers will be familiar with 3270 devices. The family of devices incorporates monochrome and color printers and visual display units, all of which can produce character output, and some of which can produce graphics output. Display screens and printers and any other device which terminate the computer network hierarchy are collectively known as "terminals". In order to communicate at all with the host processor, a terminal device must be connected to a terminal control unit which in turn is usually connected to a host I/O channel or a communications control processor.

3270 terminals are "block mode" terminals. Characters typed by a user on the keyboard are not sent to the host as they are typed. Indeed, a real 3270 terminal cannot even echo what is typed unless it is connected to a control unit such as a 3274 or 3174. The terminal and control unit combine to buffer data outboard from the host, and trigger an inbound I/O when a special key generates an attention interrupt. Keys capable of generating such an attention include Enter, SysReq, Clear, the Program Function keys, the Program Access keys, and the Selector Pen.

When 3270 was first released, the 3270 data stream provided control codes, called "orders", which could be imbedded in the data stream sent to a terminal to utilize available features. See figure 1 for a list of the original 3270 orders.

3270 Order Name

EBCDIC

ASCII

Subsequent Bytes

Start Field (SF)

x'1D'

x'1D'

1 - Attribute Byte

Set Buffer Address (SBA)

x'11'

x'11'

2 - Buffer Address

Insert Cursor (IC)

x'13'

x'13'

0

Program Tab (PT)

x'05'

x'09'

0

Repeat to Address (RA)

x'3C'

x'14'

3 - Buffer Address and Repeat Byte

Erase Unprotected to Address (EUA)

x'12'

x'12'

2 - Buffer Address

   Figure 1.  Original 3270 orders.

For some functions, such as insert cursor (IC), the presence of the order is sufficient to produce the required operation. For other orders the bytes immediately following the order provide data necessary to complete the function. Hence, the byte following a start field (SF) order will specify the intensity, protection and so forth of the field being started. SF can be said to be a two-byte order. Orders RA, EUA and SBA require a buffer address while RA (repeat to address) also needs the character that is to be repeated.

It is worth reviewing at this stage the 3270 buffer addressing scheme, and explaining a facet of this which even many experienced programmers are at a loss to explain. Veteran terminal users will have noticed that most screens have more than 256 display character locations. This means that more than one 8-bit byte is needed to specify a screen buffer address. In the 3270 data stream, buffer addresses are specified in two consecutive bytes.

The top left corner of any screen is designated location zero (0). To illustrate further consider a screen with 24 lines and 80 columns. The screen buffer has 1,920 different locations. The second column on the first line is location 1, the top right corner is location 79, the first column on the second line is location 80, and the bottom right corner is location 1,919. Location 1,920 is an invalid address and will cause an I/O error if specified in an order sent to the screen in this example. In summary, 3270 assigns location addresses sequentially from zero, in contrast to other schemes which supply row and column coordinates.

When sent in 3270 orders, buffer addresses take on a rather strange, or at least non-obvious form. Location 0 is sent as x'4040', location 1 is x'40C1', location 79 is x'C14F', location 80 is x'C150', location 1,919 is x'5D7F', and so on. In fact, this seemingly peculiar addressing protocol does have the binary number of the address location encoded in the two-byte data stream sequence. The last six bits of each byte form a 12-bit binary number that is the exact screen buffer location. This 3270 addressing format is known as "12-bit addressing".

         TITLE ' ENCODE SCREEN LOCATION TO 3270 BUFFER ADDRESS '
*
*        ON ENTRY R0 HAS BINARY BUFFER ADDRESS.
*        ON EXIT R0 HAS DATA STREAM BUFFER ADDRESS.
*
*        IF THE BUFFER ADDRESS IS 4K OR MORE THEN 14-BIT ADDRESSING
*        IS OBVIOUSLY SUPPORTED.  12-BIT ADDRESSING IS ALWAYS
*        SUPPORTED SO IT IS USED IF THE BUFFER ADDRESS IS LESS THAN 4K.
*
CALCPOSI DS    0H                 GET CODE FOR 3270 BUFFER ADDRESS.
         CH    R0,=H'4095'        LOCATION GREATER THAN 4K (12 BITS)?
         BHR   R14                YES, NO CONVERSION TO BE DONE.
         STC   R0,WORK+1          NO, DO ORIGINAL 3270 ADDRESSING.
         NI    WORK+1,B'00111111' GET LOW-ORDER SIX-BIT NUMBER.
         SRL   R0,6
         STC   R0,WORK            GET HIGH-ORDER SIX-BIT NUMBER.
         TR    WORK(2),TABLE      CONVERT TO 3270 DATA STREAM CHARS.
         ICM   R0,X'3',WORK       SAVE IN BOTTOM TWO BYTES OF R0.
         BR    R14                RETURN TO MAINLINE.
         SPACE
TABLE    DC    X'40C1C2C3C4C5C6C7C8C94A4B4C4D4E4F'   ABCDEFGHI¢.<(+|
         DC    X'50D1D2D3D4D5D6D7D8D95A5B5C5D5E5F'  &JKLMNOPQR!$*);¬
         DC    X'6061E2E3E4E5E6E7E8E96A6B6C6D6E6F'  -/STUVWXYZ¦,%_>?
         DC    X'F0F1F2F3F4F5F6F7F8F97A7B7C7D7E7F'  0123456789:#@'="
         SPACE
WORK     DS    D

Figure 2.  Sample source to encode a buffer address in a 3270 data stream. 

Since only six bits of each byte are involved in carrying significant information, it follows that these bytes can have 64 different values. Figure 2 contains an example of assembler code to convert a binary location into 3270 address format. The label TABLE identifies the 64 possible characters in a 3270 address data stream order. Note that they all correspond to EBCDIC displayable characters, as shown in the comments to the right of the hexadecimal. Note also that the x'40' bit is on for each byte while the x'80' bit can be set on or off so that the whole byte corresponds to a convenient EBCDIC character. The x'80' bit functions as a "3270 parity bit". But why is it necessary that control codes consist of displayable characters? The answer is simple.

System/360 and descendant processors are character set independent. (The fact that instructions such as EDIT, PACK and UNPK are more useful when EBCDIC is used for text is beside the point.) I/O devices such as disks and tapes are also character set independent. The only devices that are character set dependent are those which produce a physical representation of a character for interpretation by another machine such as a card reader or a human being. When a card punch (remember them?) receives a x'40' it may leave the appropriate card column with no holes punched. When a card reader reads a card column with no holes punched it may send a x'40' down the line, but a card reader on a different system may send a x'20' instead. Humans may regard a card column without holes as representing a blank or space, but what is the bit pattern of such a character? In EBCDIC it is x'40' and in ASCII it is x'20'. In other character sets it is probably something else.

The 3270 family incorporates ASCII as well as EBCDIC terminals. Since IBM has chosen EBCDIC for its host-based character set, output data must be translated from EBCDIC to ASCII before being transmitted to ASCII terminals, and input data from ASCII terminals must be translated to EBCDIC after being received.

(An interesting piece of trivia is that System/360 was intended to use ASCII, but ASCII was not ready in time so it proceeded with the IBM-developed EBCDIC character set. In the expectation that ASCII would "soon" be ready, the System/360 PSW had an ASCII bit to allow the processors to switch the operation of some instructions slightly once the applications has switched to using ASCII. By the time System/370 was developed it was realised that converting existing system and application software to ASCII would be prohibitively expensive so the ASCII bit in the PSW was dispensed with.)

EBCDIC consists of 256 different characters with x'00' to x'3F' and x'FF' being designated undisplayable control codes and x'40' to x'FE' being designated displayable character code points. Actually, x'00', known as the "null" character, is displayable. Users of ISPF EDIT will be familiar with the NULLS ON and NULLS OFF commands. With NULLS ON, trailing blanks are translated to nulls thus leaving room for data to be inserted with the use of the "insert mode" key. If an input field on the screen has no null characters then no characters can be supplied in insert mode in that field.

It is a relatively simple matter to map fixed control codes from one character set to another. Figure 1 lists both the EBCDIC and ASCII bit patterns for the basic 3270 orders. However, a problem arises when translating random control codes. If two character sets have the same number of characters then it may be possible to have a one-to-one reversible translation algorithm, but because ASCII only had 128 different characters unambiguous translation of random bit patterns is impossible. This problem can be encountered when transporting a file, often on magnetic tape or with PC file transfer programs, between ASCII-based and EBCDIC-based computer systems when the file records contain both numeric and character data. With no translation any character text remains unintelligible, whereas with translation the numeric data is rendered useless.

The solution is to ensure that all variable control codes are made up of displayable characters which exist in both character sets. With this method it becomes a straight forward matter to determine the original bit pattern from the resultant ASCII character string.

Consider the data stream for "repeat asterisks to location 84". The host program would create the string x'3CC1D45C' which is the RA (repeat to address) 3270 order followed by the EBCDIC characters 'AM*'. This would be sent unchanged to an EBCDIC terminal, but for an ASCII terminal it would be sent as x'14414D2A' which is the ASCII code for the RA order followed by the ASCII characters 'AM*'. Even though the screen buffer location of 84 is no longer directly encoded in the bit pattern of the order sequence, the 3270 terminal controller can decode the exact location specified.

This "send six meaningful bits per byte" solution is used not only for numeric control data but also for bit-encoded control bytes such as the WCC (write control character) and the attribute byte following an SF order. The first two bits of these bytes are used to ensure an appropriate symbol, as listed in TABLE from figure 2, is formed with the first bit fulfilling the "3270 parity bit" function and the second bit always being a one (1).

May 2010 Update - Thanks to Tom Armstrong. I am now informed that the real reason for the complex 3270 addressing scheme is because of support for remote 3270 screens via 3271 controllers. Before the era of SNA there was BSC. BSC was an inherently non-transparent line protocol. Code points in the x'00' to x'3F' range were reserved for control characters for both BSC and start-stop terminals like the 2741.

A BSC block would start with STX (x'02') followed by the data and end with ETB (x'26'). The remote device would reply with an ACK0 (x'1070') for the first block and then alternate ACK1 (x'1061') with ACK0. The last block in the chain would end with an ETX (x'03'). These control characters were recognized by the 2701 or 2703 control unit and used to start and end the calculation of the CRC which was written down the line immediately following the ETB or ETX by the 2701/3 for checking at the remote 3271 or any other BSC terminal. There was a Transparency feature that allowed all binary characters to be transmitted which could be fitted to the 2701/3 and the terminals, but this was very expensive option and so rarely used by customers. This also required additional programming support to turn it on and off.

The designers of the 3270 system therefore faced a dilemma. Local 3270 traffic could, of course, use any binary characters because channels are transparent but then use of remotely attached  BSC 3270s would force use of the expensive transparency feature on all 2701/3 controllers and 3271 controllers. Or, alternatively the datastream would have to be different for local 3270s vs remote 3270s. The designers wisely made the decision to use a common datastream that did not demand the transparency feature by not using any character below x'40'. Hence we ended up with the buffer and order addressing scheme that looks a little crazy to some people who do not understand why it was required for remote 3270s.

Another solution to the lack of binary transparency in BSC protocol was to take each byte and convert it into two bytes for transmission ie x'FF' becomes x'4F7F'. This was the technique used for the IBM 3735 terminal, but doubling the transmission time on slow 1200bps lines was never an attractive proposition.

There is no architectural requirement that all 3270 screens have the same size in terms of rows and columns. In fact, the architecture allows practically any screen size within a certain range, but the sizes encountered in practice are limited to the few different models that have been manufactured over the years. A partial list of real 3270-family screens includes the 3277 (Models 1 and 2), 3278 (Models 2, 3, 4 and 5), 3279 (various models of 24-line and 32-line color screens, some 4-color, some 7-color - the Model S3G had graphics support with single-plane and triple-plane loadable symbols), 3290 (configurable gas plasma amber monochrome that could be set up as 1, 2, 3 or 4 partitions depending upon model selection), 3180 (configurable green monochrome that could be set up as a model 2, 3, 4 or 5), 3179 (C and G models - the G model supporting vector graphics and single-plane loadable symbols), 3192 (with D (monochrome), C (color) and G (graphics) models), and ending up with the 3472 InfoWindow range. Figure 3 lists the screen sizes associated with various models from Model-1 to Model-5, and for the 3290 plasma screen in single partition mode. Model-1 has vanished from the shop floor and need not be mentioned further.

3270 Screen

Columns

Rows

Buffer Size

3277 Model 1

40

12

480

3277 Model 2

80

24

1,920

3278 Model 3

80

32

2,560

3278 Model 4

80

43

3,440

3278 Model 5

132

27

3,564

3290

160

62

9,920

   Figure 3.  Buffer sizes of various 3270 screens.

Most applications assume the minimum screen size is that of the Model-2, the most popular, or at least populous, of the screen sizes widely available. In general, screens can have a primary and an alternate screen size. For Model-2 screens these sizes are the same. Other models can support their own screen size as well as that of the Model-2.

Looking at Figure 3, a problem arises that most Assembler programmers would be familiar with. With 12 bits, addressability is limited to 4,096 locations, but some screen buffers have more than 4,096 locations.

This problem can be overcome by "14-bit addressing" where the two bytes containing the address location contain 2 zero bits followed by a 14-bit number. Distinguishing between a 12-bit address and a 14-bit address is very easy. If the second bit of the sequence (ie. the x'40' bit of the first byte) is a one then it is a 12-bit address, whereas if it is a zero then it is a 14-bit address. From the preceding discussion it follows that ASCII terminals cannot have more than 4,096 locations because they can only support 12-bit addressing.

Because 14-bit addressing is an extension to the original 3270 design brought about by larger screen sizes, a further more general concern becomes apparent. How can a host application exploit 3270 extended features and still support the original 3270 equipment when the exact terminal capabilities are not known at compile-time? The simple answer is: "It can ask."

Asking is done with something called a "Read Partition (Query)", commonly referred to as a "Query". Since the Query function is itself an extension to the basic 3270 function set, a recursive argument develops. How does a host application know whether or not it can do a Query to the terminal? To answer this host/terminal connectivity will be examined further.

In practice, most terminal I/O is driven by VTAM. Applications which talk to these terminals are VTAM applications. Common examples under MVS include TSO, CICS and IMS. When a terminal is logged on to a VTAM application the "LOGMODE" between the terminal and application specifies the "session BIND" being used. The BIND can specify various characteristics such as the primary and alternate screen sizes and the "query bit" setting. The "query bit" indicates whether the 3270 equipment supports the Query function.

While an application can specify which LOGMODE is to be used, it is usual for the application to let this default so that the application can be network independent. It therefore falls to the Network Systems Programmer to nominate the default LOGMODE for each terminal in the network in the VTAM definitions of the network. As implied earlier, local knowledge of which screens have which screen sizes and which screens are queryable is needed if applications are to have access to 3270 extended features.

However, in practice the Query is a controller function and once all terminal controllers in a network have reached a requisite level of modernity the query bit can safely be set on for all terminals defined to VTAM, even if some controller ports are connected to terminals that date from that period in history when dual intensity caused near-fatal cases of future shock.

In the general case, since the VTAM application has access to the BIND the application can test the query bit and, if it is on, issue a Query to the terminal. If features such as color, highlighting and graphics are supported then they can be exploited by the application to make the information being presented more readable and understandable by the terminal user. It is widely accepted that judicious use of color, for example, can greatly reduce any visual overload caused by an otherwise excessively overcrowded screen, and can thus increase the volume of meaningful data that can be delivered. Also, it looks prettier.

Or, to put it another way, many corporations have spent many thousands of dollars investing in color screen equipment without getting their money's worth because their application software could not exploit it. To quote one example, one corporation replaced most of their old screens with their more modern counterparts not realizing that they were color terminals until a user-written full-screen TSO program suddenly appeared in all its seven-color glory.

Network definitions can be further generalized by the use of appropriate LOGMODEs. A LOGMODE used by a 3270 screen has traditionally specified the primary and alternate screen sizes. This has meant that if, for example, a Model-3 screen was swapped with a Model-5 screen from elsewhere in the network, the VTAM DLOGMODEs (Default LOGMODEs) for both terminal definitions would have to be updated to ensure correct functionality was maintained. ACF/VTAM Version 3 now provides the LOGMODEs D4B32XX3 (local non-SNA), D4A32XX3 (local SNA) and D4C32XX3 (remote SNA) as documented in SYS1.SAMPLIB(ISTINCLM). These LOGMODEs provide for a primary screen size of 24 by 80 (Model-2), and an alternate screen size to be set depending on the results of a Query. This means that assuming no back-level terminal controllers, a single LOGMODE can be used for a given communication protocol without regard to the particular model of screen installed. As a result, the user is free to change terminal attributes and capabilities, either by replacing the physical terminal or via SETUP mode, without having to liaise with Network Support for corresponding VTAM definition changes.

3270 I/O Command

CCW op-code
(EXCP)

EBCDIC
(SNA)

ASCII
(SNA)

Erase All Unprotected (EAU)

x'0F'

x'6F':c'?'

x'3F':c'?'

Erase/Write (EW)

x'05'

x'F5':c'5'

x'35':c'5'

Erase/Write Alternate (EWA)

x'0D'

x'7E':c'='

x'3D':c'='

Read Buffer (RB)

x'02'

x'F2':c'2'

x'32':c'2'

Read Modified (RM)

x'06'

x'F6':c'6'

x'36':c'6'

Read Modified All (RMA)

N/A

x'6E':c'>'

x'3E':c'>'

Write (W)

x'01'

x'F1':c'1'

x'31':c'1'

Write Structured Field (WSF)

x'11'

x'F3':c'3'

N/A

No Operation (NOP)

x'03'

N/A

N/A

Sense (SNS)

x'04'

N/A

N/A

Sense ID (SNSID)

x'E4'

N/A

N/A

Figure 4.  3270 I/O commands.

Now look at figure 4. This is a list of the VTAM read and write commands applicable to 3270 terminals. Both the ASCII and EBCDIC codes are listed as are the corresponding CCW op-codes. It should be remembered that from an Operating System viewpoint local non-SNA terminals are I/O devices in their own right and do not necessarily have to be driven by VTAM.

If, under MVS, such a terminal is varied inactive to VTAM it then becomes available to any other job under the rules of device allocation. A job could allocate the terminal and perform I/O to it writing and reading 3270 data streams using the EXCP access method with the appropriate CCWs independently of any network telecommunications access method.

This is just what the Communications Task in the CONSOLE address space does in every version of MVS/SP. If a system console is registered in the active CONSOLxx member of SYS1.PARMLIB with UNIT(3270-X) then the device is assumed to be queryable and CommTask can use a larger than normal screen size if present, and any colors and highlighting specified in the active MPFLSTxx member of SYS1.PARMLIB, depending on the Query results. A more problem-program oriented example of driving screens with EXCP is the Emergency TeleProcessing System (ETPS) in File 353 of the CBT free MVS software collection.

The data stream sent to query the terminal cannot be sent with a normal WRITE command, but must be sent with a Write Structured Field (WSF) command. The first byte sent to the terminal with a normal WRITE is known as the Write Control Character. It controls sounding the audible alarm (BELL), unlocking the keyboard, resetting the MDT bits and clearing the AID, as shown in figure 10. The data sent by a WSF is one or more structured fields. Each structured field begins with a 2-byte length indicator and identifiers to signify the type of structured field. Thus, the length of the data stream sent by a WSF equals the sum of the length indicators of all the structured fields sent. The length of a data stream passed by an application to VTAM is this length plus one because this data stream starts with the WSF command code.

WSF is used to send structured fields outbound. Structured fields can also be sent inbound to the host by 3270 equipment. The first byte in an inbound data stream is known as the attention identifier or AID. The AID indicates which key on the keyboard was depressed by the terminal operator to cause the attention interrupt. Examples of AID values are x'7D' for ENTER, x'F1' for PF1, x'C3' for PF15, x'6E' for PA2 and x'6D' for CLEAR. All such AIDs are characters from TABLE in figure 2, again for the ASCII support reasons discussed earlier.

When one or more structured fields is sent inbound the AID byte has a value of x'88'. The AID is immediately followed by the two-byte length indicator of the first structured field. The total length of the inbound data stream will be the sum of the lengths of all the structured fields sent plus one for the AID byte.

Structured fields are employed for several functions. These include communicating with partitions other than the default partition of multi-partition terminals, loading programmable symbols and transmitting vector graphics. However, the function of immediate interest is issuing the Read Partition (Query) command and processing the response that is generated.

To issue a Query the string x'F3000501FF02' is passed to VTAM. This is the WSF command code followed by a five-byte structured field. The first two bytes of the structured field form the length count. This in turn is followed by a x'01' to identify a Read Partition structured field. It is mandatory that the partition identifier byte has a value of x'FF'. The last byte is x'02' to indicate a Query.

 TSO 3270 VDU TEST  ('Z'|'END' = EXIT.  'HELP' = DISPLAY HELP SCREEN.)
                    ('SYMSET#' = SHOW SYMBOL SET # WHERE # IS FROM 0 TO 1.)

 UNMODIFIED-FIELD-ATTRIBUTE-BYTES:  ,-,D,U,H,Y,<,%,&,0,M,4,Q,8,*,@.
 _        -------- DDDDDDDD UUUUUUUU HHHHHHHH YYYYYYYY
 
&&&&&&&& 00000000 MMMMMMMM 44444444 QQQQQQQQ 88888888

  TSO-MACRO   WORD0/R0  WORD1/R1  RTCD/R15
  GTSIZE      00000020  00000050  00000000  32 LINES  80 COLUMNS
  GTTERM      18502050  00000001  00000000  EBCDIC TERMINAL  QUERY BIT ON
  STCOM    NO                     00000000  (CHAR. MATRIX:   9 WIDE  12 DEEP)
  STFSMODE ON,INITIAL+NOEDIT=YES  00000000  (BUF-ADDR: 12-BIT/14-BIT)
  STTMPMD  ON,KEYS=ALL            00000000  (3270DS STRUC. FIELD SUPPORTED)
  TERMTYPE     NON-MVS  MACRO     MSP ONLY
  TGET     ASIS,WAIT    00000076  00000018  AID=88(h)  CURSOR-POSITION=
  TPG      NOEDIT,WAIT            00000000  (QUERY LIST IS SUPPORTED)

 LENG Q-ID QUERY-REPLY-FIELD-DETAILS  (FIELD TEST PFKS: 10-12, 1-7, 8(GE))
 000C 8180 808185868788A690
 0017 8181 01000050002000000A02E50002006F090C0A00
 0013 8185 B000091060000000030000000100F1
 0016 8186 000800F4F1F1F2F2F3F3F4F4F5F5F6F6F7F7
 000D 8187 0400F0F1F1F2F2F4F4
 0007 8188 000102
 0011 81A6 00000B01000050001800500020
 0004 8190

Figure 5.  Initial panel of the TERMTEST program from CBT file 134.

In order to understand the nature of the Query response, it is helpful to consider figure 5. This is the initial screen of the TERMTEST program invoked as a TSO command on an IBM 3192-C set-up as a Model-3 screen. The TERMTEST program is available from file 134 of the CBT tape with a ready-to-use load module in file 135. The screen image represented in figure 5 has several areas.

The area of interest in figure 5 begins with the white heading line about halfway down the screen above the hexadecimal of the Query reply sub-fields. LENG identifies the length indicators.Q-ID identifies the sub-field identifiers. Note that the first byte is x'81' to denote a Query reply sub-field. The second byte of Q-ID indicates the specific sub-field. Under QUERY-REPLY-FIELD-DETAILS is the data that is unique to each sub-field.

Locate Q-ID '8186' in figure 5. This is the extended color sub-field. The data in this sub-field in figure 5 indicates the action taken by the terminal for eight (8) different color specifications. For color x'00', the default, color x'F4' will be used. For color specifications of x'F1' to x'F7' in the 3270 data stream, the terminal will display colors x'F1' to x'F7' respectively.

Color Code

Color

x'F0'

Neutral = Black for screen; White for printer.

x'F1'

Blue

x'F2'

Red

x'F3'

Pink

x'F4'

Green

x'F5'

Turquoise

x'F6'

Yellow

x'F7'

Neutral = White for screen; Black for printer.

x'F8'

Black

x'F9'

Deep blue

x'FA'

Orange

x'FB'

Purple

x'FC'

Pale green

x'FD'

Pale turquoise

x'FE'

Grey

x'FF'

White

Figure 6.  Color codes supported by 3270 data stream.
Note: Color terminals generally only support color codes 1 through 7 inclusive for alphameric text.
The last eight colours listed are for graphics use only.

Figure 6 contains the colors supported by 3270. While support for sixteen (16) colors exists in the data stream architecture, most terminals will not support more than seven (7) colors, as indicated in the example in figure 5. When coding orders for a seven-color display, if a programmer can remember that blue is color 1, red is color 2, and green is color 4, then the codes for secondary colors can be derived using arithmetic. So, for example, because Turquoise is made up of Blue and Green, it has a color code of 1 plus 4 which equals 5. Similarly, Pink is color code 3 (Blue and Red), Yellow is color code 6 (Green and Red), and White which requires all three electron guns to be firing can be displayed using color code 7 (Green and Red and Blue).

Extended Data Stream (EDS) terminals also support highlighting attributes. Support for this is indicated in the x'87' sub-field. Look for Q-ID '8187' in figure 5 to see an example of this. Valid highlighting codes in a 3270 data stream are x'00' for the default of no extended highlighting, x'F1' for Blinking, x'F2' for Reverse video, x'F4' for Underscore, and x'F8' for Intensify. One could be forgiven for expecting a x'F3' to produce Blinking Reverse video, but only one highlighting attribute is allowed at once. Extended highlighting can be performed by monochrome screens, and in fact Intensify can only be performed by monochrome screens because a dual intensity capability is required.

Looking at the example in figure 5 in more detail, it can be seen that the x'87' sub-field has returned four pairs of codes, as indicated by the x'04' following the x'87'. A request for default highlighting (x'00') will produce no highlighting (x'F0'). A request for Blinking, Reverse video and Underscoring (x'F1', x'F2' and x'F4' respectively) will successfully produce those effects. A request for any other sort of highlighting, including Intensify, will be rejected as a data stream error.

Before looking at how to use these colors and highlightings, the nature of field and character attributes must first be examined. Consider an arbitrary formatted screen with fields defined by various attribute bytes. Some of these fields are protected (that is, cannot be updated by the terminal user) and some are unprotected (that is, some are input fields). Some are high intensity and some are low intensity. If there is a password field, it should be made non-displayable for echo suppression. Some fields may have the numeric-only attribute to prevent the terminal operator from typing alphabetic characters into a field from which the application program requires numeric-only data. Each of these attributes holds currency throughout the entire field. Figure 7 shows the meanings of field attribute byte bit settings.

Bit

Description

0

3270 "parity" bit.

1

Always 1. (Part of 3270 "parity" setting.)

2

0 = Unprotected. 1 = Protected.

3

0 = Alphanumeric. 1 = Numeric.

2+3

11 = (Protected+Numeric functions as) Autoskip.

4+5

00 = Display/not selector-pen-detectable.
01 = Display/selector-pen-detectable.
10 = Intensified display/selector-pen-detectable.
11 = Nondisplay/not selector-pen-detectable.

6

Always 0. (Reserved.)

7

Modified Data Tag (MDT).
0 = Field has not been modified.
1 = Field will be sent during Read Modified command operations. This bit is set when the terminal operator modifies the field. It can also be sent already set by the host application program.

Figure 7.  3270 Attribute byte - bit settings.

The attributes specified in an attribute byte following the Start Field order are given to each byte on the screen in consecutive locations until the next attribute byte is encountered. It is therefore possible to update the attributes of all bytes in a given field simply by updating the attribute byte at the start of the field. Remember that a field attribute byte occupies a location on the display screen and is displayed as a blank, so a data stream can have an SBA order to position the current address to an attribute byte, and then overlay the current attribute byte with a new Start Field order.

3270 Order Name

Byte 1

Byte 2

Byte 3

Byte 4

Start Field Extended (SFE)

x'29'

Count of Type/Value pairs

Type

Value

Modify Field (MF)

x'2C'

Count of Type/Value pairs

Type

Value

Set Attribute (SA)

x'28'

Type

Value

 

Figure 8.  Extended 3270 orders (for EBCDIC terminals only).

Extensions to the 3270 data stream have added extended attributes together with new orders to specify them. These extended orders are listed in figure 8. The attributes they may specify are listed in figure 9. Note that the combination of counts and bit-encoded values in these data streams prohibits support of these functions being implemented for ASCII 3270 terminals.

Attribute Type

Allowed Values

x'00' - Character Attribute reset

x'00' - only use with SA:
x'280000' will reset all character attributes to default values

x'C0' - Field Attribute

Standard 3270 field attribute byte
- only use with SFE and MF orders
- values as per figure 7

x'41' - Extended Highlighting

x'00' - Default
x'F1' - Blink
x'F2' - Reverse video
x'F4' - Underscore
x'F8' - Intensify (monochrome only)

x'42' - Color

x'00' - Default
x'F?' - colors as per figure 6

x'43' - Symbol Set

x'00' - Default
x'F1' - APL - use only with SA order
x'40'-x'EF' - symbol sets loaded by host program

Figure 9.  Attribute types for extended orders (SFE, MF and SA)

Extended attributes are specified with a Start Field Extended (SFE) order. The byte immediately following the SFE order code is a count of the number of type+value pairs following the count byte. Thus, an SFE order with a count byte value of N has 2(N+1) bytes in the whole order sequence. SFE-created attributes still take up one display location on the display screen. Any attribute categories supported by the terminal but not specified in the SFE order will be assigned their default values. For example, a field with no color specification will not be pink merely because it may happen to follow a pink field.

The Modify Field order (MF) allows a program to alter one or more categories of attributes of a pre-existing display field without the requirement to specify or even know all of the field's attributes. Any attribute categories supported by the terminal but not specified in the MF order will be left unchanged. If an MF order is encountered when the current buffer address does not contain an attribute byte then a data stream error is recognized.

The Set Attribute order (SA) is a notable extension because it introduces the concept of character attributes (as opposed to the field attributes discussed to date). Character attributes provide a mechanism which enables two consecutive display locations to have different attributes without an intervening field attribute byte, and can thus override field attributes. Character attributes are inherited from the previous displayable character in the data stream unless updated by an intervening SA order sequence. IBM 3270 equipment treats the data stream from each write command as starting with all character attributes as default, while Fujitsu 668x equipment remembers the latest character attribute values across write commands. (Fujitsu terminal equipment will be discussed later.)

Before giving examples of these orders it is pertinent to discuss the DCS macro. The author first discovered this Assembler language macro as an in-stream macro of the public domain REVIEW TSO command processor written by Bill Godfrey. Its function is to facilitate the coding of 3270 data streams by allowing the use of mnemonics in the definitions rather than typing in straight hex. While most programmers who code data streams would eventually come to know the codes of the orders they use, a great feature of the DCS macro is the automatic generation of the code required for 12-bit addressing of screen locations based on row and column coordinates, and this is its real strength.

Now, armed with the means of depicting 3270 data stream code, we can look at some coding examples.  First of all, a "clear the screen" sequence which often appears in simple clear-screen TSO commands:
         DCS   SBA,(1,1),RA,(1,1),X'00',IC
This use of the DCS macro would generate x'1140403C40400013'. It translates to "set the current buffer address to row-1 column-1, repeat the null character to row-1 column-1 and then insert the cursor. The result of sending this data stream to a terminal is to reset all display locations to zeros and leave the cursor in the top left corner. Note that 3270 allows buffer wrap-around, so that if an RA order, for example, specifies an address less than or equal to the current address then the character repetition will proceed to the end of the screen and then resume from the start of the screen. A special case of this is where the final address equals the current address, whereupon the screen will be completely filled with the repetition character. Note that because row-1 column-1 was used the above example is screen size independent.

Now consider:
         DCS   SA,COLOR,PINK,SBA,(1,1),RA,(1,1),C'*',IC
Here, x'2842F31140403C40405C13' would be generated. Instead of clearing the screen (or filling the screen with nulls) the latest example will fill the screen with asterisks in a single soothing hue of pink (assuming a color screen). A point to mention is that in ten bytes of data stream (not counting the insert cursor) possibly thousands of display locations on the screen have been updated.

Compare the previous example with:
         DCS   SA,COLOR,PINK,SBA,(1,1),IC,1920C'*'
Assuming a model-2 screen, the same result is achieved but with a lot longer data stream. Every display character (asterisks in this case) is sent individually rather than being generated by a single RA order. Over a remote network connection the difference in screen update times could be very noticable, and when considered with many other terminals on the same network performance becomes an important issue. Not only is the total network capacity a vital factor in handling the traffic load, but inefficient data stream coding can adversely affect the response times of other terminals on the same link by causing I/O interference.

The comparison of the above two examples introduces the concept of 3270 data stream compression, where a buffer containing a 3270 data stream to be sent to a terminal can be parsed (in-place if desired) and optimized by reducing strings of repeating characters to a single RA order. Since an RA order is four bytes long, it is only used when a character is repeated more than four times. By doing this, 3270 data streams can be reduced substantially. The REVIEW TSO command uses a subroutine to perform this function.  Indeed, there are several successful products on the market which do this at the CICS or VTAM level, and can thereby transform a network into a viable transmission medium for an application where the capacity did not exist to handle the natively generated data stream. In fact, there have been cases where such a product circumvented application-generated data stream errors, but that is another story.

For those readers who consider that they have now mastered 3270 data stream optimization, consider this: What if we now want a screen full of asterisks, still pink but with every second asterisk now being yellow. Sure, we could use
         DCS   SBA,(1,1)
         DCS   SA,COLOR,PINK,C'*',SA,COLOR,YELLOW,C'*'
         DCS   SA,COLOR,PINK,C'*',SA,COLOR,YELLOW,C'*'
         DCS   SA,COLOR,PINK,C'*',SA,COLOR,YELLOW,C'*'
         DCS   SA,COLOR,PINK,C'*',SA,COLOR,YELLOW,C'*'
         ...   ad nauseum,
but could it be optimized?  Probably, but how?

To see how, first consider the same example but where only every fourth asterisk is to be yellow. Again, we could use
         DCS   SBA,(1,1)
         DCS   SA,COLOR,PINK,C'***',SA,COLOR,YELLOW,C'*'
         DCS   SA,COLOR,PINK,C'***',SA,COLOR,YELLOW,C'*'
         DCS   SA,COLOR,PINK,C'***',SA,COLOR,YELLOW,C'*'
         DCS   SA,COLOR,PINK,C'***',SA,COLOR,YELLOW,C'*'
         ...   ad nauseum
but now also consider
         DCS   SA,COLOR,PINK,SBA,(1,1),RA,(1,1),C'*',SA,COLOR,YELLOW
         DCS   SBA,(1,4),C'*',SBA,(1,8),C'*',SBA,(1,12),C'*'
         DCS   SBA,(1,16),C'*',SBA,(1,20),C'*',SBA,(1,24),C'*'
         DCS   SBA,(1,28),C'*',SBA,(1,32),C'*',SBA,(1,36),C'*'
         DCS   SBA,(1,28),C'*',SBA,(1,32),C'*',SBA,(1,36),C'*'
         ...   ad nauseum (but not quite as much).

Looking at the first attempt we see that each four bytes of display took 10 bytes of data stream. Assuming a model-2 screen and since a quarter of 1920 is 480, we see that the first attempt has a data stream length of 4803 bytes. The second attempt took 13 bytes plus 4 bytes for each yellow asterisk giving a total of 1933 bytes. This represents a substantial reduction data stream length of roughly 60%. Similarly, with the original objective of producing alternating pink and yellow asterisks, a roughly 50% (7683 bytes vs 3850 bytes) reduction of data stream length can be achieved using the method of the last-mentioned solution over the first proposed solution. What conclusions are to be reached from this?

A fullscreen application programmer should consider the response time implications of different possible screen-painting techniques. To refresh an entire screen image, sending the data in consecutive screen location order may involve the simplest programming, but may not give the fastest response even if RA orders are exploited for repeating characters with identical attributes. Of course, this depends on the nature of the screen data to be displayed. In the examples above character and not field attributes were used to supply the color specification. In fact no attribute byte was present on the screen, so these asterisks would have the default field attributes of low intensity and unprotected. Note that in the last example, even though each yellow character had a pink character before and after it on the screen, there was only one "set color to yellow" order and all the yellow characters were sent together after all the pink characters had already been sent. This demonstrates the fact that character attributes are decided by previous bytes in the data stream, not bytes in preceding locations in the screen buffer.

With the knowledge discussed so far, a programmer is almost ready to code a 3270 output data stream. But first a more detailed discussion of the Write Control Character is appropriate. The bit settings of the WCC are described in figure 10. The programmer should know whether the destination terminal is a screen or a printer. If it is a printer and the output is to be printed, then the "Start Printer" bit of the WCC should be on. If this bit is on for a data stream sent to a screen, then a hardcopy print operation is initiated as if the terminal operator had selected the hardcopy print button on the keyboard. The "Define Printout Format" bits of the WCC should be zero for a screen. 3270 printers operating as SCS (SNA Character String) printers (LU type 1) should not be sent 3270 orders, while LU type 3 printers can process appropriate 3270 orders such as Set Buffer Address.

Bit

Description

0

3270 "parity" bit.

1

Originally always 1 - must be 1 for ASCII terminals.
Now functions as a Reset bit when special Write (EW, EWA, WSF).

2+3

Define printout format:
00 = NL, EM and CR orders in data stream define print line length.
If no orders then 132-character line length.
01 = 40-character line length.
10 = 64-character line length.
11 = 80-character line length. 

4

Start printer bit.
1 = Start print after write has completed.

5

Sound alarm bit.
1 = Sound the "bell" after write has completed.

6

Keyboard restore bit.
1 = Unlock the keyboard (ie. allow input) and reset the AID
byte to the no-AID condition (x'60') at the end of the write.

7

Reset MDT bit.
1 = Reset all MDT bits in all field attribute bytes in the
buffer before processing the data stream of this write.

Figure 10.  3270 Write Control Character (WCC) - bit settings.

Programmers coding fullscreen 3270 applications to operate under the TSO platform have a couple of other considerations. While most of the orders mentioned so far (including the original 3270 orders and SA) can be processed by a TPUT with the FULLSCR operand, the SFE and MF orders cannot be. If SFE and/or MF are to be used in the data stream, then the NOEDIT form of TPUT must be used. For TSO/VTAM, NOEDIT TPUTs allow the TSO programmer direct access to VTAM SEND processing without any intermediate editing of the data stream by TSO. But now consider the seemingly simple question of restoring the keyboard. When a TGET is issued after any sort of TPUT other than NOEDIT, TSO unlocks the keyboard to allow the terminal operator access to input functions. After a NOEDIT TPUT this keyboard unlocking is not automatically performed, and the user would have to hit the RESET key before typing any input. This can be obviated by setting the "Keyboard Restore" bit in the WCC, but for FULLSCR TPUTs it may be advantageous to let "the system" perform this unlocking because if the user of a remote SNA screen hits ENTER (or a PF key) after the keyboard is unlocked but before the TGET is issued then "loss of function" (X - f) may be displayed in the terminal status line at the bottom of the screen.

Sufficient discussion has now taken place to allow a programmer to code a screen image of any (reasonable?) design, including efficient blanking of unused parts of the screen, directly addressing "remote" parts of the screen, and supplying various field and character attributes such as intensity, protection, colour and highlighting. But what do the characters displayed on the screen look like? For a given code point, the character to be displayed is taken from ASCII for ASCII screens and EBCDIC for EBCDIC screens.

As mentioned earlier, all code points from x'40' to x'FE' are considered displayable characters, giving a blank plus 190 non-blank characters. However, the characters available on a "standard" keyboard fall short of this number.  What characters occupy the code points unused by keyboard characters? That depends on the exact version of EBCDIC built-in to the terminal. A 3278 out of New York may have square brackets for x'41' and x'42', but a 3179-G with that laid-back LA-Hispanic "west coast" groove may have a "hook" (upside-down question mark) for x'41'