Z308 3270 Full Screen I/O Routines

OBSOLETE

Please note that this routine has been obsoleted in CNL 219. Users are advised not to use it any longer and to replace it in older programs. No maintenance for it will take place and it will eventually disappear.
Suggested replacement: None

These routines write a character string anywhere on a full screen 3270 terminal, or any VT100 compatible terminal attached to a 7171 or Series/1. The screen may also be formatted into fields preceded by attributes, to intensify (highlight), protect, or hide the field (like in the password entry screen of CP). The extended attributes (colors on the 3278) are not supported, in this case the four default colors discriminate protected/unprotected and normal/highlighted fields.

Structure:

FUNCTION subprograms
User Entry Names: IOSWRT, IOSRD, IOSDIM

Usage:

The variable IRC and the functions IOSWRT, IOSRD and IOSFLD are of type INTEGER.

    IRC = IOSWRT()
    IRC = IOSWRT('CLEAR')

    IRC = IOSWRT(LINE,LENGTH,LINENO,NCOL)
    IRC = IOSWRT(LINE,LENGTH,LINENO,NCOL,IATTR)
    IRC = IOSWRT(LINE,LENGTH,LINENO,NCOL,IATTR,0)
    IRC = IOSWRT(LINE,LENGTH,LINENO,NCOL,IATTR,IBUF)

IRC

Indicates whether the operation was successful or not.
$=\; 0:$ Operation successful;
$=\; -1:$ The screen is under CP control, must clear and rewrite it;
$=\; -2:$ Invalid line number;
$=\; -3:$ Invalid column number;
$=\; -4:$ Buffer full;
$=\; -5:$ No space for attribute;
$=\; -6:$ String length not specified;
$=\; -7,...,-12:$ Non-fatal I/0 errors, retry.

LINE

A character string to be displayed. This string may consist of a string in quotes, a character variable or array, or any array containing Hollerith constants.

LENGTH

( INTEGER) Contains the length of the character string (or the number of bytes in the hollerith array). It has a different meaning according to its value:
$>\; 0:$

Maximum limit is the end of the buffer. A string can occupy the whole screen, wrapping from the end to the beginning of the screen. The last 8 positions at the bottom right corner are not visible, being overwritten by CP with 'CERNVM '.
$=\; 0:$

A field is started empty if the attribute is present. An empty (unprotected) field may be used for input.

The cursor is positioned on the screen as indicated by the following parameters.

LINENO

( INTEGER) Defines the line in which the start of the string should be positioned; the top line is line 1, the bottom line is line 24 on 3270 Model 2, line 35, 43 or 27 on 3270 Models 3, 4, or 5.

NCOL

( INTEGER) Defines the column in which the start of the string should be positioned; the leftmost column is column 1, the rightmost is 80 in Models 2-4, and 132 in Model 5.

IATTR

( INTEGER) Contains the attributes of the field. If this parameter is present, the string is also the beginning of a field, which inherits the properties of the attribute, and extends across the screen to the next field. The attribute is located in the position at the left of the first character of the string, it is hidden (dark) and protected from overwriting by the keyboard. The rightmost 6 bits of IATTR define the attribute as follows:
$=\; 32:$ ( PROTECT) The field will not be overwritten by the keyboard;
$=\; 16:$ ( NUMERIC) The field will accept only numeric input;
$=\; 12:$

(HIDE) The field will not be displayed, like the password input field in the CP LOGON screen;
$=\; 8:$ ( HIGHLIGHT) The field will be intensified and selector pen detectable;
$=\; 4:$ ( SELPEN) The field will be selector pen detectable only;
$=\; 2:$ ( Reserved) Should be set to zero;
$=\; 1:$

( MDT) Modified Data Tag, when set the field will be included in the next READ MODIFIED command executed. This bit is set when something is put in the field by the keyboard, but can be set under program control to include default responses which will be displayed on the screen, and read back even if the content has not been modified by the keyboard.
The attribute is the logical OR of all the values.

IBUF

( INTEGER) Array used to prepare a mask for the screen which can be used several times. The first value must be initialized by the user to the length in bytes of the N-2 remaining words of the array, while the second value must be initialized to zero. Every time this routine is called with all parameters this value is updated, so that the user knows the amount used, and can clear the buffer by resetting to zero the second element of the array.

If IBUF (or the first element of the array) is zero, an internal array is used (around 3000 bytes, the rest of the 4K memory page). If this parameter is missing altogether, an immediate write to screen is performed, useful to fill up the voids of the already displayed mask with variable information, defaults in input fields, or old inputs which may be modified later; in this case the internal buffer is used, destroying its contents; so the internal buffer must be used before an immediate write is performed.

    IRC = IOSWRT(IBUF)
    IRC = IOSWRT(0)
    IRC = IOSWRT('WRITE')

    IRC = IOSRD(ECB)

ECB

( INTEGER) Receives a non-zero value upon Attention Interrupt (actually the lower part of CSW, with status bits). This variable should be set to zero before the call, so that the program may periodically inspect, and continue processing while it is zero, or go to retrieve full-screen input if not.

    IRC = IOSRD(BUFF,LENGTH,LINENO,NCOL)

IRC

Indicates whether the operation was successful or not.
$>\; 0:$ Operation successfull, IRC = Number of the PF-key pressed;
$=\; 0:$ Operation successfull, ENTER pressed;
$=\; -1:$ Screen under CP control ( PA1 key pressed before);
$=\; -2:$ PA2 key pressed (Clear Output in CMS);
$=\; -3:$ CLEAR key pressed, the screen is now empty;
$=\; -4:$ No input available;
$=\; -5:$ Incorrect parameters number;
$=\; -6,...,-12:$ I/O errors, retry.

BUFF

Array of convenient length to receive the modified fields. This buffer is useful if the input has to be saved, otherwise it is not required, the internal buffer is used instead.

LENGTH

( INTEGER) This variable contains, on entry, the length of BUFF. On exit, it contains the actual length used of this array. The length of the buffer should be the sum of the field lengths, three bytes per field, plus four bytes for the cursor coordinates. If this parameter is zero, then the internal buffer is used.

LINENO

( INTEGER) Gives the number of the line where the cursor is located at the moment of the full-screen read.

NCOL

( INTEGER) Gives the number of the column where the cursor is located at the moment of the full-screen read.

    CALL IOSFLD(LINE,LENGTH,LINENO,NCOL)

LINE

Array of convenient length to receive the modified field.

LENGTH

( INTEGER) This variable contains, on entry, the length of LINE. On exit, it contains the actual length used of the field. When it becomes negative then there are no more fields left in the buffer.

LINENO

( INTEGER) Gives the number of the line where the first character of the field is located.

NCOL

( INTEGER) Gives the number of the column where the first character of the field is located.

Z309