ReadBuffer() action

The ReadBuffer() action returns the contents of the screen buffer.

Parameters

ReadBuffer() takes one or two optional parameters.

ascii: Return the buffer contents as text. This is the default.; Note that when ReadBuffer(ascii) is invoked from the HTTP server, the results are always in UTF-8, regardless of the workstation's local encoding.
ebcdic: Return the buffer contents in EBCDIC.
unicode: Return the buffer contents as Unicode code points. New in 4.0
field: Return only the contents of the current field. Another parameter can also be specified to control the output format. New in 4.0

Return value

The screen buffer contents, one row per line, with each buffer position separated by spaces.

Start Field positions in the buffer are represented by the string SF(attrs), where attrs is a comma-separated list of field attributes.

If an ordinary buffer position has additional attribute overrides, these are identified with the string SA(attrs), where attrs is a comma-separated list of field attributes. Note that an SA does not represent a buffer position -- it only gives the additional attributes for the current buffer position.

In EBCDIC mode, a buffer position containing a Graphic Escape character is identified with the string GE(nn), where nn is the character code in code page 310 in hexadecimal.

Ordinary characters are represented in one of three ways:

ASCII mode: An even number of hexadecimal digits, representing an EBCDIC character mapped to the local workstation's local encoding. There are two digits per encoded character. For example, if the character is EBCDIC X'C1' (A), the output would be 41. If the character is EBCDIC X'B4' and the host code page is cp037, that's a copyright symbol ©, and the output for a UTF-8 workstation would be c2a9.
EBCDIC mode: 2-digit hexadecimal number.
Unicode mode: 4-digit Unicode code point.

In ASCII and Unicode modes, DBCS characters (which take up two buffer positions) are handled specially. The first position is returned with the entire character either as text or as a code point, and the second position is returned as -.

Field mode

New in 4.0

In Field mode, the output begins with a four-line preamble describing the field:

Start1 row column: The 1-origin coordinates of the Start Field character.
StartOffset offset: The cursor offset of the Start Field character.
Cursor1 row column: The 1-origin coordinates of the cursor.
CursorOffset offset: The offset of the cursor.

In Field mode, after the preamble, the buffer output begins with the keyword Contents:.

Examples

Return the entire screen buffer, one row per line. This is only the beginning of the output. The first field on the screen starts at (1, 1), is protected, and begins with SVM02.

x3270> ReadBuffer()
SF(c0=e0) 53 56 4d 30 32 ...

The next three examples are from a screen with the cursor on an 8-character input field that was initially filled with underscores; an x was typed into the first position of the field, so its field attribute shows it as modified.

First, ASCII mode: New in 4.0

x3270> ReadBuffer(field)
Start1: 21 12
StartOffset: 1611
Cursor1: 21 14
CursorOffset: 1613
Contents: SF(c0=c1) 78 5f 5f 5f 5f 5f 5f 5f

Next, EBCDIC mode. New in 4.0

x3270> ReadBuffer(field,ebcdic)
Start1: 21 12
StartOffset: 1611
Cursor1: 21 14
CursorOffset: 1613
Contents: SF(c0=c1) a7 6d 6d 6d 6d 6d 6d 6d

Then Unicode mode: New in 4.0

x3270> ReadBuffer(field,unicode)
Start1: 21 12
StartOffset: 1611
Cursor1: 21 14
CursorOffset: 1613
Contents: SF(c0=c1) 0078 005f 005f 005f 005f 005f 005f 005f

The next three examples are from a screen with the cursor on an 73-character input field containing the Chinese character 中 and the rest blanks. The host code page is cp935 and the workstation encoding is UTF-8.

First, ASCII mode. Note that the DBCS character is bracketed by EBCDIC SO (X'0E') and SI (X'0F') characters, which are not remapped, that the 中 expands to its 3-byte UTF-8 encoding, and that the second byte of the 中 is output as -. New in 4.0

x3270> ReadBuffer(field)
Start1: 24 6
StartOffset: 1845
Cursor1: 24 7
CursorOffset: 1846
Contents: SF(c0=c0,fe=01) 0e e4b8ad - 0f 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20

Next, EBCDIC mode. Note that the DBCS character just looks like two bytes of EBCDIC; it is known to be DBCS only because of the SO (X'0E') and SI (X'0F'). 中 is X'5BCF' in host code page 935. New in 4.0

x3270> ReadBuffer(field,ebcdic)
Start1: 24 6
StartOffset: 1845
Cursor1: 24 7
CursorOffset: 1846
Contents: SF(c0=c0,fe=01) 0e 5b cf 0f 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40

Then, Unicode mode. SO (X'0E') and SI (X'0F') are untranslated, as in ASCII mode. 中 is U+4E2D. The second byte of the is output as -. New in 4.0

x3270> ReadBuffer(field,unicode) 
Start1: 24 6
StartOffset: 1845
Cursor1: 24 7
CursorOffset: 1846
Contents: SF(c0=c0,fe=01) 000e 4e2d - 000f 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020

The next three examples are from a screen with the cursor on an 73-character input field containing the text hello ⍺ there and the rest blanks. ⍺ is an APL character. The host code page is bracket and the workstation encoding is UTF-8.

First, ASCII mode. Note that the ⍺ expands to its 3-byte UTF-8 encoding. New in 4.0

x3270> ReadBuffer(field)
Start1: 23 80
StartOffset: 1839
Cursor1: 24 14
CursorOffset: 1853
Contents: SF(c0=c1,fe=01) 68 65 6c 6c 6f 20 e28dba 20 74 68 65 72 65 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20

Next, EBCDIC mode. Note that the ⍺ is output as GE(b0); X'B0' is ⍺ in host code page 310. New in 4.0

x3270> ReadBuffer(field,ebcdic)
Start1: 23 80
StartOffset: 1839
Cursor1: 24 14
CursorOffset: 1853
Contents: SF(c0=c1,fe=01) 88 85 93 93 96 40 GE(b0) 40 a3 88 85 99 85 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40

Then, Unicode mode. ⍺ is U+237A. New in 4.0

x3270> ReadBuffer(field,unicode)
Start1: 23 80
StartOffset: 1839
Cursor1: 24 14
CursorOffset: 1853
Contents: SF(c0=c1,fe=01) 0068 0065 006c 006c 006f 0020 237a 0020 0074 0068 0065 0072 0065 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020 0020