perm filename VISTA.MAN[SIM,SYS] blob sn#460346 filedate 1979-07-20 generic text, type T, neo UTF8


SWEDISH NATIONAL DEFENSE RESEARCH INSTITUTE  FOA Report
S-104 50 Stockholm 80                        D10007-M3(E5)
SWEDEN                                       March    1976


VISTA - FOR FULL CONTROL OF TEXT DISPLAY TERMINALS

BY JACOB PALME


ABSTRACT

     VISTA is a program package for controlling the input
     and output to an alphanumeric display terminal from a
     SIMULA program on the DECsystem-10 computer.  VISTA
     allows full program control over the contents of the
     display screen.  The package can for example be used to
     produce "moving pictures" on part or whole of the
     display screen, or to allow the terminal user to move
     around the screen inputting data in various screen
     fields.  A special subpackage FORM allows data input by
     letting the user fill in fields in a "form" displayed
     on the screen.  Full validity check is done immediately
     for each field input from the user.


SEARCH KEY:  Computer, Terminal, Display terminal,
     Alphanumeric terminal, Conversational program, Dialogue
     program, Input, Output, Man-computer interaction,
     SIMULA programming language, Picture, Video, Graphic.


SWEDISH ABSTRACT

     VISTA {r ett programpaket f`r styrning av inmatning och
     utmatning till en alfanumerisk sk{rm fr⎇n ett
     SIMULA-program som k`rs p⎇ datorn DECsystem-10.  VISTA
     m`jligg`r full programkontroll `ver inneh⎇llet p⎇
     sk{rmen.  Man kan t.ex. anv{nda paketet f`r att
     producera "r`rliga bilder" p⎇ hela eller delar av
     sk{rmen, eller f`r att till⎇ta terminalanv{ndaren att
     flytta sig runt sk{rmen medan han matar in data i olika
     f{lt p⎇ sk{rmen.  Ett speciellt underpaket FORM
     till⎇ter datainmatning genom att en blankett visas p⎇
     sk{rmen och anv{ndaren fyller i f{lt i denna blankett.
     Fullst{ndig validitetskontroll kan d⎇ g`ras omedelbart
     efter varje inmatat f{ltv{rde fr⎇n anv{ndaren.
PALME: VISTA - FULL CONTROL OF TEXT DISPLAY TERMINALS Page 2


0. TABLE OF CONTENTS

     1. INTRODUCTION
     2. OUTPUT TO THE DISPLAY TERMINAL
     3. INPUT FROM THE DISPLAY TERMINAL
     4. DATA AVAILABLE TO THE USER
     5. PREAMBLE FOR PROGRAMS USING THE VISTA PACKAGE
     6. SWITCHING BETWEEN SEVERAL SCREEN CONTENTS
     7. CAT AND SHIP - EXAMPLES OF USE OF THE VISTA PACKAGE
     8. FORM - A SUBPACKAGE FOR FORM-FILL-IN DATA ENTRY
     9. FORMT AND TABLE - EXAMPLES OF USE OF THE FORM
        PACKAGE
     10. DEBUGGING PROGRAMS USING THE VISTA PACKAGE


1. INTRODUCTION

     An alphanumeric display terminal allows the cursor to
     be moved freely around the screen, and information to
     be input and output at arbitrary positions on the
     screen.

     This can be used to produce pictures or tables on the
     screen, where objects or figure change or move during
     the execution of a program.  Data can also be input at
     arbitrary positions on the screen as guided by the
     terminal user.

     A special application of this is the "form fill-in"
     method of data entry into a program, where a form is
     displayed on the screen, and the terminal user fills in
     empty fields in this form.

     The VISTA package makes it simple to write such
     programs in the SIMULA programming language on a
     DECsystem-10 computer.

     The package is written for use with VISTA INFOTON
     alpha-numeric display terminals, but the package can be
     modified for use with other display terminals.  (The
     cursor control commands are unfortunately not yet
     standardized for display terminals.)
PALME: VISTA - FULL CONTROL OF TEXT DISPLAY TERMINALS Page 3


2. OUTPUT TO THE DISPLAY TERMINAL

     WARNING:  If you do any output to the terminal not
     using these procedures, the screen may be garbled.  You
     can then restore the screen by calling the procedure
     "restore←the←whole←screen".


PROCEDURE move←the←cursor←to(horiz, vertic);
     INTEGER horiz, vertic;
     COMMENT This procedure will move the cursor to the
     indicated position on the display screen.  The screen
     is indexed with [0,0] equal to the upper left corner of
     the screen, and with "horiz" increasing leftwards and
     "vertic" increasing downwards from this origin.


PROCEDURE home←the←cursor;
     COMMENT This procedure will move the cursor to position
     [0,0], that is the upper left corner of the screen.


PROCEDURE outchar(setchar);
     CHARACTER setchar;
     COMMENT This procedure will output the character
     "setchar" onto the cursor position on the screen.  The
     cursor is moved past the outputted character.


PROCEDURE set←char←on←screen(setchar,horiz,vertic);
     CHARACTER setchar;  INTEGER horiz, vertic;
     COMMENT This procedure will output the character
     "setchar" in the position [horiz,vertic] on the screen.
     The cursor is left referring to the [horiz,vertic]
     position (not the next position).


PROCEDURE synchronize(horiz, vertic);
     INTEGER horiz, vertic;
     COMMENT This procedure is to be called if there is a
     risk that the correct cursor position on the screen,
     and the position where the program believes the cursor
     to be, is not the same.  The cursor is moved to the
     indicated position even if such was the case.  Such a
     risk is most often common after inputting data from the
     user terminal when "echoenabled" is TRUE.  In such
     cases, VISTA will usually automatically call
     synchronize.
PALME: VISTA - FULL CONTROL OF TEXT DISPLAY TERMINALS Page 4
2. OUTPUT TO THE DISPLAY TERMINAL


PROCEDURE outtext(t);
     VALUE t;  TEXT t;
     COMMENT This procedure will output the text t on the
     terminal beginning at the cursor position on the
     screen.  The programmer must ensure that there is
     enough space left on the current line of the screen for
     the entire length of the TEXT "t".


PROCEDURE outfix(a,i,j);
     REAL a;  INTEGER i, j;
     COMMENT Almost same as standard SIMULA outfix on the
     screen.  The programmer must ensure that there is space
     for j more characters on the current line of the
     screen.


PROCEDURE outreal(a,i,j);
     REAL a;  INTEGER i, j;
     COMMENT Almost same as standard SIMULA outreal on the
     screen.  The programmer must ensure that there is space
     for j more characters on the current line of the
     screen.


PROCEDURE outint(i,j);
     INTEGER i, j;
     COMMENT Almost the same as standard SIMULA outint on
     the screen.  The programmer must ensure that there is
     space for j more characters on the current line of the
     screen.


PROCEDURE outimage;
     COMMENT Will output any characters in the sysout.image
     and then move the cursor to the beginning of the next
     line on the screen.


PROCEDURE blank←line(vertic);
     INTEGER vertic;
     COMMENT Will make line "vertic" on the screen fully
     blank.  The cursor is left at the first position of the
     blanked line.
PALME: VISTA - FULL CONTROL OF TEXT DISPLAY TERMINALS Page 5
2. OUTPUT TO THE DISPLAY TERMINAL


PROCEDURE blank←the←screen;
     COMMENT Will make the entire screen blank.  This is
     done automatically when a new VISTA object is created.




PROCEDURE restore←the←whole←screen;
     COMMENT If there is any risk that the data on the
     screen does not agree with what the program belives to
     be there, this procedure will restore the screen to
     what the program belives to be there.  This risk can
     happen if you have input or output data with procedures
     not part of the VISTA package, or if "echoenabled" is
     TRUE and the terminal user has done "type ahead" on the
     terminal keyboard.  "restore←the←whole←screen" is
     called by the VISTA package if the terminal user pushes
     the ALTMODE (ESCAPE) key on his terminal keyboard.


PROCEDURE restore←one←char(horiz, vertic);
     INTEGER horiz, vertic;
     COMMENT Will restore the character in the position
     horiz, vertic on the terminal to what the program
     believes to be there.


PROCEDURE cause←real←time←delay(number←of←fillers);
     INTEGER number←of←fillers;
     COMMENT this procedure will transmit
     "number←of←fillers" fill characters to the screen.
     These characters are not output to the screen.  This
     procedure can be used to delay moving pictures from
     moving too fast on the screen.  The number of fillers
     transmitted depends on the speed of the terminal line -
     more characters for faster terminal lines.  Example:
     With a 2400 baude terminal line, 120 fillers will cause
     a half-second delay.  Warning:  This procedure, and not
     the SLEEP procedure, is recommended if you want
     smoothly moving pictures on the screen.  This procedure
     is however rather CPU-time-consuming.
PALME: VISTA - FULL CONTROL OF TEXT DISPLAY TERMINALS Page 6
2. OUTPUT TO THE DISPLAY TERMINAL


PROCEDURE cancel←display;
     COMMENT The screen will be blanked.  Further calls on
     the output procedures in the VISTA package will only
     change the internal copy of the screen, nothing will be
     output to the terminal.

     This procedure can be used if you want to display
     another VISTA picture or if you want to talk to the
     terminal not using the VISTA package.

     WARNING:  The input procedures in the VISTA package may
     not be used on cancelled VISTA pictures.


PROCEDURE resume←display;
     COMMENT The screen is restored to the internal copy of
     the screen, and further output procedures in the VISTA
     package will affect both the terminal and the internal
     copy of the screen.

     Note that if you have used the VISTA output procedures
     on a cancelled picture, then the internal version of
     that picture is changed.  Thus, when you call
     resume←display, the modified picture is shown.

     WARNING:  If you are keeping several VISTA objects to
     switch between pictures, then  a l w a y s  cancel the
     previous display before resuming the next.  More than
     one VISTA object should never be resumed at the same
     time.


HOW TO CREATE BLINKING TEXT ON THE SCREEN:

     Put the character STARTBLINK in front of the blinking
     text and the character STOPBLINK after the blinking
     text.  Both STARTBLINK and STOPBLINK will show on the
     screen as blanks.

     Example:
     outchar(startblink);  outtext("BLINKING TEXT");
     outchar(stopblink);
PALME: VISTA - FULL CONTROL OF TEXT DISPLAY TERMINALS Page 7


3. INPUT FROM THE DISPLAY TERMINAL

     WARNING:  If you do any INPUT from the terminal not
     using these procedures, then the screen contents may be
     garbled.  In that case, the screen can be restored by
     calling the procedure "restore←the←whole←screen".

     If the terminal user pushes the ALTMODE (ESCAPE) or
     FORMFEED button on his terminal, then the procedure
     restore←the←whole←screen will be called from the
     program, the next time the program tries to make input
     from the terminal through the routines described below.


PROCEDURE echon;
     COMMENT will make echoenabled TRUE, which means that
     characters input from the terminal are echoed by the
     terminal control handler of the computer and not by the
     vista package.
     Advantage:  Faster echoing when the computer is heavily
     loaded.
     Disadvantage:  Risk that the screen contents do not
     agree with what the program believes to be there,
     especially if the terminal user has done "type ahead".
     Another disadvantage is that the terminal keys for
     moving the cursor up, down, left and right are echoed
     incorrectly.


PROCEDURE echoff;
     COMMENT will make "echoenabled" FALSE.  See "echon"
     above.


CHARACTER PROCEDURE insingle(echo);
     BOOLEAN echo;
     COMMENT will input one character directly from the
     terminal keyboard, bypassing sysin.image entirely.  The
     user need not push carriage return on his terminal, the
     program will get direct control every time the user
     pushes a terminal key.
     "echo" has effect only if "echoenabled" is FALSE.  In
     that case, if "echo" is FALSE, the input character is
     not echoed at all on the terminal screen.  The
     programmer must thus ensure that user input characters
     are echoed correctly.
     If "echo" is TRUE, but "echoenabled" FALSE, then the
     VISTA package will try to echo input characters.
     Terminal keys like the four keys for moving the cursor
     up, down, left and right, the carriage return, line
     feed, home and rub out(delete) keys are all echoed
     correctly.
PALME: VISTA - FULL CONTROL OF TEXT DISPLAY TERMINALS Page 8
3. INPUT FROM THE DISPLAY TERMINAL


PROCEDURE inimage;
     COMMENT inimage will input a line of text from the
     terminal into the buffer sysin.image.  IF "echoeanbled"
     is TRUE, inimage works just like the ordinary SIMULA
     inimage.  If "echoenabled" is FALSE, inimage is
     different in that every character with RANK less than
     32 will act as a "break" characters, that is signifying
     end of the data input with this call to the inimage
     procedure.


INTEGER PROCEDURE inint;
     COMMENT will search for and read an integer from the
     terminal.  If the data input from the terminal is not
     readable as an integer, then the input field is filled
     with question marks.


REAL PROCEDURE inreal;
     COMMENT will search for and read a real item from the
     terminal.  If the data input from the terminal is not
     readable as a real, the the input field is filled with
     question marks.


TEXT PROCEDURE inword;
     COMMENT will search for and read a word from the
     terminal.  A word is any sequence of non-blank
     characters.


BOOLEAN PROCEDURE inyes;
     COMMENT will search for either "yes" or "no" from the
     terminal, and will return TRUE if "yes" is found.


4. DATA AVAILABLE TO THE USER

     WARNING:  Never change these variables directly.  Always use
     the procedures described above.
PALME: VISTA - FULL CONTROL OF TEXT DISPLAY TERMINALS        Page 9
4. DATA AVAILABLE TO THE USER


SCREEN CONTENTS:


INTEGER PROCEDURE horizontalpos;
     COMMENT Position of the cursor on the screen.


INTEGER PROCEDURE verticalpos;
     COMMENT Position of the cursor on the screen.


TEXT ARRAY screen[0:height-1];
     COMMENT contents of the display screen;


CHARACTER PROCEDURE get←char←from←screen(horiz, vertic);
     INTEGER horiz, vertic;
     COMMENT will return the character in the indicated screen
     position.  Will return CHAR(0) if [horiz,vertic] is outside
     the available screen.


TERMINAL INTERFACE MODES:


BOOLEAN echoeanbled;
     COMMENT if TRUE, input characters are echoed by the monitor,
     if FALSE by the VISTA package or by you.  See further the
     description of the procedure "echon" above.


USEFUL CHARACTER VARIABLES:

     up = what is input when user pushes the key with an upward
          pointing arrow (usually indicating wish to move the
          cursor upwards on the screen).
     down = same for downward pointing arrow.
     left = same for left-pointing arrow.
     right = same for right-pointing arrow.
     home = what is input when user pushes the home key on the
          terminal, (usually indicating wish to move the cursor to
          a "home" position on the screen).
     formfeed, carriagereturn, altmode, linefeed, verttab, null,
          fill, tab, startblink, stopblink = what is input when the
          user pushes these respective terminal keys.
PALME: VISTA - FULL CONTROL OF TEXT DISPLAY TERMINALS       Page 10
4. DATA AVAILABLE TO THE USER


DISPLAYING ON OTHER TERMINALS THAN THE CONTROLLING TTY

     It is possible to use the VISTA package to display pictures on
     other terminals than the controlling TTY.

     Important:  Ensure that you always make outimage on every
     picture displayed on different terminals, before any input
     break in your program.  Otherwise you may get half-finished
     pictures on some TTY:s.  Note that the procedure "outimage"
     built into the VISTA package should be used.

     Output to other TTY:s is no problem.

     Input from other TTY:s through the VISTA package causes some
     problems.  The echo parameter must be TRUE when creating VISTA
     objects, and insinglechar cannot be used.

     VISTA can be combined with the REALTIME package to allow
     simultaneous dialouge on more than one terminal.


5. PREAMBLE FOR PROGRAMS USING THE VISTA PACKAGE

     The following example of a very short complete program using
     the VISTA package shows what you have to do:

     OPTIONS(/s:"libsim[106,346]");
     BEGIN
       EXTERNAL CHARACTER PROCEDURE getch;
       EXTERNAL INTEGER PROCEDURE trmop, checkreal,
       checkint;
       EXTERNAL PROCEDURE echo, abort, outchr;
       EXTERNAL CLASS vista;
       INSPECT NEW vista(78, 19, sysin, sysout, FALSE, 1) DO
       BEGIN
         INTEGER h, v, sign;
         blank←the←screen;
         FOR sign:= rank('A') STEP 1 UNTIL rank('Z') DO
         FOR h:= 1 STEP 1 UNTIL 10 DO
         FOR v:= 1 STEP 1 UNTIL 10 DO
         set←char←on←screen(char(sign),h,v);
       END;
     END;

     The parameters in the "NEW vista" statement are:

   > Width of the screen.  Subtract 1 or 2 from the real width.

   > Height of the screen.  Subtract 1 from the real height.

   > Sysin = the infile connected to the terminal.

   > Sysout = the outfile connected to the terminal.  (The package
     will probably only work if sysout is the controlling
PALME: VISTA - FULL CONTROL OF TEXT DISPLAY TERMINALS       Page 11
5. PREAMBLE FOR PROGRAMS USING THE VISTA PACKAGE


     terminal.)

   > TRUE if you want automatic echoing of characters by the
     monitor, FALSE if you want echoing by the VISTA package.
     FALSE is usually safer.  If you only use the VISTA package for
     output to the terminal, not for input from the terminal, then
     TRUE has certain advantages.

   > The last parameter indicates terminal type.  Should always be
     1, since the VISTA package does not yet accept any other kind
     of terminal than the INFOTON VISTA STANDARD terminal.  If this
     parameter is 0, the user at the terminal will be asked what
     kind of terminal he is using.

     All the source programs of the VISTA package are at the QZ
     data center available on the H40I48 DEC tape.  VISTA.ATR,
     VISTA.REL, FORM.ATR and FORM.REL will at the QZ data center be
     available in LIBSIM on either SYS: or [106,346].


6. SWITCHING BETWEEN SEVERAL SCREEN CONTENTS

     It is easy with the VISTA package to have several pictures,
     and switch between them.  You just allocate one object of the
     CLASS vista for each picture.  You can then have a reference
     variable referring to each picture.  Suppose that you have

          REF (vista) first←picture, second←picture;

     You can then switch from displaying the first to displaying
     the second picture on the screen by simply executing the
     statements:

          first←picture.cancel←display;
          second←picture.resume←display;

     Note:  More than one picture may never be active at the same
     time.  Therefore always cancel the previous picture before
     resuming the next.  VISTA objects just generated with NEW are
     always active, and if you do not want them active you should
     cancel them before generating the next picture.

     It is however legal to have no picture active.  This is what
     you do if you want to talk to the terminal without using the
     VISTA package.

     It is legal to use all the procedures in the VISTA package
     except the input procedures even on a cancelled picture.  The
     VISTA output procedures on a cancelled picture will then
     change an internal copy of the terminal screen, and this
     internal copy will be shown to the user again when the program
     calls the procedure "resume←display" on that picture.

     Example of a complete, executable program using two pictures
PALME: VISTA - FULL CONTROL OF TEXT DISPLAY TERMINALS       Page 12
6. SWITCHING BETWEEN SEVERAL SCREEN CONTENTS


     to switch between:

     OPTIONS(/s:"libsim[106,346]");
     BEGIN
       EXTERNAL CHARACTER PROCEDURE getch;
       EXTERNAL INTEGER PROCEDURE trmop, checkreal,
       checkint;
       EXTERNAL PROCEDURE echo, abort, outchr;
       EXTERNAL CLASS vista;
       REF (vista) first←picture, second←picture;
       INTEGER h, v, sign, casedifference;
       casedifference:= rank('a') - rank('A');
       second←picture:- NEW vista
       (78, 19, sysin, sysout, FALSE, 1);
       second←picture.cancel←display;
       first←picture:- NEW vista
       (78, 19, sysin, sysout, FALSE, 1);
       first←picture.blank←the←screen;
       second←picture.blank←the←screen;
       FOR sign:= rank('A') STEP 1 UNTIL rank('Z') DO
       BEGIN
         IF mod(sign,3) = 0 THEN
         BEGIN
           IF mod(sign,2) = 0 THEN
           BEGIN
             second←picture.cancel←display;
             first←picture.resume←display;
           END ELSE
           BEGIN
             first←picture.cancel←display;
             second←picture.resume←display;
           END;
         END;
         FOR h:= 1 STEP 1 UNTIL 10 DO
         FOR v:= 1 STEP 1 UNTIL 10 DO
         BEGIN
           first←picture.set←char←on←screen
           (char(sign),h,v);
           second←picture.set←char←on←screen
           (char(sign+casedifference),h+20,v);
         END;
       END;
     END;
PALME: VISTA - FULL CONTROL OF TEXT DISPLAY TERMINALS       Page 13


7. CAT AND SHIP - EXAMPLES OF USE OF THE VISTA PACKAGE

     CAT and SHIP are two demonstration examples to illustrate how
     the VISTA package can be used.

     CAT is a program in which a cat tries to catch a number of
     rats in a square cage.  The cage and the two animals are shown
     in a map of the cage on the terminal screen, where the user
     can see how they move about the cage.  The user at the
     terminal can guide the movement of the cat with four buttons
     for up, down, left and right.  The program makes the rat more
     intelligent if the terminal user catches many rats.  A score
     of escaped and caught rats is caught on the screen.

     SHIP is a simplified simulation program.  A number of ships
     try to move soldiers from one side of a lake to the other
     side.  A number of destroyers hunt the ships.  The user can
     see at the terminal how the ships move across the lake, how
     the destroyers move, how troups accumulate on the other side
     of the lake, how ships and destroyers fight.  A portion of the
     screen shows the number of ships in various states:  Loading,
     unloading, moving, killed etc.

     CAT and SHIP are at the QZ computing center available on
     [106,346] and if you have a VISTA terminal, you can run the
     programs by the command

     .RUN CAT[106,346] or

     .RUN SHIP[106,346]

     The source programs CAT.SIM and SHIP.SIM are at the QZ
     computing center available on DEC-tape H40I48.


8. FORM - A SUBPACKAGE FOR FORM-FILL-IN DATA ENTRY

     FORM is a subclass to VISTA to allow the writing of programs
     in which the terminal screen is made to look like a form with
     various empty fields.  The terminal user then inputs data by
     filling in the fields of the form.

     You define your form by generating an object of the CLASS
     FIELD for each field in the form.  For each field you indicate
     its position on the screen and the header in front of the
     input part of the field.  The order in which you generate the
     NEW FIELD objects is important.  They must be generated
     according to their position on the screen, left to right, top
     to bottom.

     You can also use any of the VISTA procedures on parts of the
     screen where you are not using the FORM package, e.g. you can
     use OUTTEXT to print a header on top of the form.

     When you have generated all the objects, you can call the
PALME: VISTA - FULL CONTROL OF TEXT DISPLAY TERMINALS       Page 14
8. FORM - A SUBPACKAGE FOR FORM-FILL-IN DATA ENTRY


     procedure SHOW←PAGE which will display all the headers on the
     screen.  You can then call the procedure ASK←PAGE which will
     ask the terminal user input for each field in the form.

     If you want to allow the user a chance to change his form
     entries after completing the answer, you can write
     "RESUME(FIRST←FIELD);"

     If you want to put in extra data collection, reliability test
     etc. then you define subclasses to the class field.

     Four such useful subclasses are already available in the FORM
     package.  They are INTFIELD, REALFIELD, CHOICEFIELD,
     ALPHAFIELD.  INTFIELD is for collecting integer input,
     REALFIELD for collection floating point input, CHOICEFIELD for
     inputting data which can only have a limited set of values,
     ALPHAFIELD for inputting alphabetic data.



CLASS field(h, v, header);
     VALUE header;
     INTEGER h, v;  TEXT header;
     COMMENT H and V are the horizontal and vertical position on
     the screen for this field.  HEADER is the text to be displayed
     on the screen in front of the field.
     BEGIN   TEXT answer;  COMMENT what the user inputs comes here;


     PROCEDURE change←answer(new←answer);
          VALUE new←answer;  TEXT new←answer;
          COMMENT will change both the internal and
          screen-displayed answer.  Can be used for automatic
          correction of input values.


     PROCEDURE error(errmess);
          VALUE errmess;  TEXT errmess;
          COMMENT will write a blinking error message on line 18 of
          the screen;

     END of field;
PALME: VISTA - FULL CONTROL OF TEXT DISPLAY TERMINALS       Page 15
8. FORM - A SUBPACKAGE FOR FORM-FILL-IN DATA ENTRY


field CLASS int←field(min, max, rangerror);
     VALUE rangeerror;
     INTEGER min, max;  TEXT rangeerror;
     COMMENT if the data input by the user is not an integer, then
     he is given an error message.  If the data is not between min
     and max, then the error message RANGERROR is given to him.
     BEGIN INTEGER intvalue;
     COMMENT INTVALUE will contain the data input by the user;
     END of intfield;


field CLASS realfield(min,max,rangerror);
     VALUE rangerror;
     REAL min, max;  TEXT rangerror;
     COMMENT same as INTFIELD for floating point input;
     BEGIN REAL realvalue;
     COMMENT realvalue will contain the data input by the user;
     END of realfield;


field CLASS choicefield(nonemessage);
     VALUE nonemessage;  TEXT nonemessage;
     COMMENT Will allow the user to chose between a limited number
     of alternatives;
     BEGIN
     CLASS choice(choicetext);
     VALUE choicetext;  TEXT choicetext;
     COMMENT you must yourself generate an object of the class
     choice for each alternative, e.g. "NEW choice("first
     alternative");  NEW choice("Second alternative");" etc.
     END of choicefield;


field CLASS alphafield;  COMMENT will only accept input containing
     nothing but letters and blanks;


PROCEDURE show←page;
     COMMENT All answers in all the fields will be erased and the
     form will be displayed on the terminal;
PALME: VISTA - FULL CONTROL OF TEXT DISPLAY TERMINALS       Page 16
8. FORM - A SUBPACKAGE FOR FORM-FILL-IN DATA ENTRY


PROCEDURE ask←page;
     COMMENT the terminal user is asked to fill in the form on his
     terminal;


PROCEDURE stopasking;
     COMMENT this procedure causes the procedure ASK←PAGE to return
     from where it was called.  Can be used if you under certain
     conditions wish to allow partly filled-in forms;


     A complete example of a simple program using the FORM package:

     OPTIONS(/l);
     OPTIONS(/s:"libsim[106,346]");
     BEGIN
       EXTERNAL CHARACTER PROCEDURE getch;
       EXTERNAL INTEGER PROCEDURE trmop, checkreal,
       checkint;
       EXTERNAL PROCEDURE echo, abort, outchr;
       EXTERNAL CLASS vista;
       EXTERNAL CLASS form;
       form(79,19,sysin,sysout,FALSE,1) BEGIN
         REF (field) givenname, surname, nationality,
         birthyear, eyes;
         REF (intfield) height;
         givenname:- NEW alphafield(0,6,"given names:");
         surname:- NEW alphafield(0,8,"surname:");
         nationality:- NEW alphafield(35,8,
         "nationality:");
         birthyear:- NEW intfield(0,10,"birthyear:",1800,
         1975,
         "Birthyear should be between 1800 and 1975.");
         INSPECT NEW choicefield(35,10,"eyecolour:",
         "Accepted eyecolours: brown, blue and grey.") DO
         BEGIN
           eyes:- THIS choicefield;
           NEW choice("brown"); NEW choice("blue");
           NEW choice("grey");
         END;
         blank←the←screen;
         outtext("INPUT OF PERSONAL DATA:");
         outimage;
         show←page;
         ask←page;
       END;
     END;
PALME: VISTA - FULL CONTROL OF TEXT DISPLAY TERMINALS       Page 17
8. FORM - A SUBPACKAGE FOR FORM-FILL-IN DATA ENTRY


WRITING YOUR OWN SUBCLASSES TO FIELD:

     If you want to do your own validity checking of data input
     from the user, or your own automatic correction of data input
     from the user, then you write your own subclasses to FIELD.
     Include in the body of the subclass the error corrections you
     want.  If you want to display an error message to the user,
     then call the procedure "ERROR".  If you want to change the
     data input from the user, then call the procedure
     "CHANGE←ANSWER".


Example of how you can write your own subclass to field:

     intfield CLASS evenmod10;
     COMMENT will give errors for odd numbers and
     take any input number modulo 10;
     BEGIN
       IF mod(intvalue,
       2) NE 0 THEN error("Odd number illegal.");
       answer.setpos(1);
       answer.putint(mod(intvalue,2),1);
       change←answer(answer.sub(1,1));
     END;

     FORM is available at the QZ computing center on DEC-tape
     H40I48 in the packed file "FORM.PAC".  Unpac with

     ./filpac U,form

     FORM.ATR and FORM.REL are part of LIBSIM on either SYS: or
     [106,346].


9. FORMT AND TABLE - EXAMPLES OF USE OF THE FORM PACKAGE

     FORMT and TABLE are two simple demonstration programs.  FORMT
     shows the use of FORM for input of a simple form from a
     terminal.  TABLE shows how a table of values can be input from
     a terminal in a similar manner.

     FORMT.SAV and TABLE.SAV are available for running at the QZ
     computing center on [106,346] and you can test it by writing

     .RUN FORMT[106,346] or

     .RUN TABLE[106,346]

     FORMT.SIM and TABLE.SIM are available at the QZ computing
     center on DEC-tape H40I48 in the packed file FORM.PAC.  Unpac
     with:
     ./filpac U,FORM
PALME: VISTA - FULL CONTROL OF TEXT DISPLAY TERMINALS       Page 18


10. DEBUGGING PROGRAMS USING THE VISTA PACKAGE

     VISTA programs are difficult to debug for two reasons:

   > DEBUG output will destroy the picture on the screen.

   > VISTA usually stops echoing characters from the terminal,
     which means that characters input to SIMDDT will not be
     echoed.

     Here are some ways to overcome these problems:

     You can direct the debugging output to another device than the
     terminal, for example to another terminal or to a disk file.

     After a debugging session, you can restore the screen by
     calling the procedure restore←the←whole←screen.  There are two
     ways to get the VISTA package to call this procedure.  One way
     is to write the SIMDDT statement "INPUT BADSCREEN:= TRUE".
     The next time a call is made on the procedure
     "MOVE←THE←CURSOR←TO" the screen will be restored.

     Another way is push the ALTMODE(ESCAPE) or FORMFEED character
     on your terminal, the next time when your program tries to
     make input from the terminal using the input procedures within
     VISTA.  This will also cause the screen to be restored.

     The problem that SIMDDT does not echo its input can be
     overcome by changing the switch on your terminal to local
     echo.  Do not forget to th set it back to no local echo before
     typing the SIMDDT "PROCEED" command.

     Another way to know what you have typed to SIMDDT is to push
     the CTRL-R combination on your terminal.

     COMMON CAUSES OF ERROR:

     The most common cause of bad picture on the screen is that
     your program tries to make some kind of input from or output
     to the terminal screen without using the input and output
     procedures which are part of the VISTA package.  Your program
     may for example contain statements like "INSPECT SYSOUT DO" or
     "SYSOUT.SETPOS(0)" or "SYSOUT.OUTIMAGE".

     Another common trouble is that you are accepting input from
     the user on the last line of the screen.  This may in certain
     cases cause the picture on the terminal screen to roll.