"VT" :  Routines to drive the VT100 Terminal
============================================

Abstract
--------

"VT" is a Macro subroutine which generates the escape codes to enable most
of the VT100 terminal functions to be controlled by a call from a Fortran
program. Unimplemented functions can easily be added by copying and editing
the appropriate region of the source and re-assembling. This can be done with
only a minimal knowledge of the Macro language. "ANSI" escape sequences are
used throughout. The routines occupy 748. bytes of memory, and thus add only
about 1.5 blocks to the run-time program size.


                 David A. Tindall,
                 Department of Physics,
                 Dalhousie University,
                 Halifax, Nova Scotia, B3H 3J5,
                 Canada.


Format of subroutine calls
--------------------------

Each of the names in the following index may be called from a Fortran program.
e.g.   CALL CLRBEG      to CLeaR the BEGinning of the line
       CALL RM(2)       to Reset Mode 2; i.e. to put the VT100 in VT52 mode
       CALL CUP(23,56)  to Position the CUrsor to line 23, column 56

The routines which take arguments fall into three categories:
a) LL(n) RM(n) & SM(n)            n is taken modulo 10
b) CUB(n) CUD(n) CUF(n) & CUU(n)  n is converted to two Ascii digits
c) CUP(m,n) STBM(m,n)             m & n are each converted to two Ascii digits

In all cases an argument defaulted, missing, or less than 1 will be assigned 
the value 1. This means that it is necessary to use CALL LL(10), rather than
CALL LL(0), to turn off the programmable LED's on the VT100. 
An argument greater than 80 will be assigned the value 80.
Please note that this does NOT ensure that all calls will be in a range that
the VT100 can meaningfully accept. For example it does not ensure that STBM
will be in range, which requires m =< n-2 and n =< 24. However, it appears
that the VT100 ignores out-of-range commands like CALL STBM(80,80).

The index shows which of the calls take arguments and their function.





















Alphabetical Index of subroutine calls
======================================----------------------------------------
 Name      *   Escape code      Function performed (refer to VT100 User Guide)
------------------------------------------------------------------------------
ALIGND    [G]   <ESC> #8        ALIGN Display (fill screen with E's)
ANSI      [5]   <ESC>  <        set ANSI mode
BIGBOT    [I]   <ESC> #4        BIG BOTtom (of double height line)
BIGTOP    [H]   <ESC> #3        BIG TOP (of double height line)
CLRALL    [N]   <ESC> [2J       CLeaR ALL of the screen
CLRBEG    [S]   <ESC> [1K       CleaR BEGinning of line
CLRBOT    [P]   <ESC> [0J       CLeaR the BOTtom of the screen
CLREND    [T]   <ESC> [0K       CLeaR END of the line
CLRLIN    [R]   <ESC> [2K       CLeaR LINe
CLRTOP    [O]   <ESC> [1J       CLeaR the TOP of the screen
CRLF      [6]   <CR><LF>        Carriage Return,Line Feed 
CUB(n)    [4]   <ESC> [~~D      CUrsor Backward n characters
CUD(n)    [2]   <ESC> [~~B      CUrsor Down     n lines
CUF(n)    [3]   <ESC> [~~C      CUrsor Forward  n characters
CUP(m,n)  [Y]   <ESC> [~~;~~H   CUrsor Position to line m, column n
CUU(n)    [1]   <ESC> [~~A      CUrsor Up       n lines
DGS       [M]   <ESC> (B        Deselect Graphics Set
DWL       [J]   <ESC> #6        Double Width Line
IND       [\]   <ESC>  D        INDex (move down)
KPAM      [C]   <ESC>  =        KeyPad Application Mode
KPNM      [D]   <ESC>  >        KeyPad Numeric Mode
LL(n)     [Q]   <ESC> [~q       Light Led n (on keyboard); n=10 for all off
NEGVID    [U]   <ESC> [7m       NEGative VIDeo for next characters
NEL       [[]   <ESC>  E        NEw Line
POSVID    [V]   <ESC> [0m       POSitive VIDeo for next characters
RESCUR    [B]   <ESC>  8        REStore CURsor & attributes
RI        [F]   <ESC>  M        Reverse Index (move up)
RIS       [E]   <ESC>  c        Reset to Initial State
RM(n)     [X]   <ESC> [?~l      Reset Mode n
SAVCUR    [A]   <ESC>  7        SAVe CURsor & attributes
SGS       [L]   <ESC> (0        Select Graphics Set
SM(n)     [W]   <ESC> [?~h      Set   Mode n
STBM(m,n) [Z]   <ESC> [~~;~~r   Set Top(m) and Bottom(n) Margins
SWL       [K]   <ESC> #5        Single Width Line
    
Notes
-----
*) The second column shows the characters which are used by the test programs
   TST100 and TST101 --  see those programs for further details.
2) The symbol ~~ represents the two Ascii digits corresponding to the
   integer argument in the subroutine call.    





















Editing VT.MAC 
--------------

The following notes should help you to edit VT.MAC to add additional features
not supported in the released version of "VT".

1) The symbol MSGn identifies an n-character escape sequence
e.g. MSG5, initialised to  <ESC> [?3l, is used by all the "VT" functions
which require a five-character escape sequence viz:

SM      <ESC> [?~h
RM      <ESC> [?~l
CUU     <ESC> [~~A
CUD     <ESC> [~~B
CUF     <ESC> [~~C
CUB     <ESC> [~~D

(where ~ denotes an Ascii digit)


2) Register allocation:

R0   First  character of argument
R1   Second character of argument
R2   Address of current MSG string
R3   Argument storage in "GETARG" subroutine
R4   Number of arguments still to be processed in call to "GETARG"
R5   Fortran argument pointer


3) Note that any Fortran-callable routine added to "VT" must be
appended to the list of .GLOBL symbols at the head of VT.MAC


































GENERAL HINTS ON USING "VT"
===========================

1) Use CALL ANSI at the start of your Fortran program in case the VT100
   terminal has been left in the VT52 mode by a previous job.

2) Issue the RT-11 monitor command  SET TT NOCRLF  to prevent the operating
   system from adding spurious newlines in your output. This may be most
   conveniently included in your startup file.

3) The program can be tested to see if the correct escape sequences are
   being sent to the terminal in at least two ways:
   a) Set the VT100 into VT52 mode (either manually or by the use of CALL 
      RM(2) ) and then the character part of the escape sequence will be
      seen on the VT100.
   b) Run the program with a terminal device which does not respond to the
      escape sequences (e.g. an LA36 DecWriter).

4) In order to test that any additional functions you have added to "VT"
   produce the correct escape sequences you can run TST100 (from a VT100
   terminal) or TST101 (from an LA36 DecWriter). Documentation
   on these test programs is enclosed as comments in the respective source
   files. 

5) When mixing "VT" calls with Format-controlled output, use '+' at the 
   beginning and $ at the end of the Format statement to suppress the
   <LF>.....<CR> combination ordinarily generated by PDP-11 Fortran.

6) Refer to the "VT100 User guide"  part no. EK-VT-UG-002 for the detailed
   description of the operation of the various functions.

7) Source files supplied with "VT":

   VT    .TXT   this document
   VT    .MAC   MACRO source of the "VT" routine
   VTDEMO.FOR   FORTRAN demonstration program to show capabilities of "VT"
   TIME  .FOR   Another FORTRAN demonstration program
   TST100.FOR   FORTRAN test program for use on VT100 video terminal.
   TST101.FOR   Similar to TST100, except used on LA36 DecWriter



























Index of subroutine calls, by Escape Code
=========================================-------------------------------------
 Name      *   Escape code      Function performed (refer to VT100 User Guide)
------------------------------------------------------------------------------
CRLF      [6]   <CR><LF>        Carriage Return,Line Feed 
SAVCUR    [A]   <ESC>  7        SAVe CURsor & attributes
RESCUR    [B]   <ESC>  8        REStore CURsor & attributes
ANSI      [5]   <ESC>  <        set ANSI mode
KPAM      [C]   <ESC>  =        KeyPad Application Mode
KPNM      [D]   <ESC>  >        KeyPad Numeric Mode
IND       [\]   <ESC>  D        INDex (move down)
NEL       [[]   <ESC>  E        NEw Line
RI        [F]   <ESC>  M        Reverse Index (move up)
RIS       [E]   <ESC>  c        Reset to Initial State
BIGTOP    [H]   <ESC> #3        BIG TOP (of double height line)
BIGBOT    [I]   <ESC> #4        BIG BOTtom (of double height line)
SWL       [K]   <ESC> #5        Single Width Line
DWL       [J]   <ESC> #6        Double Width Line
ALIGND    [G]   <ESC> #8        ALIGN Display (fill screen with E's)
SGS       [L]   <ESC> (0        Select Graphics Set
DGS       [M]   <ESC> (B        Deselect Graphics Set
CLRBOT    [P]   <ESC> [0J       CLeaR the BOTtom of the screen
CLREND    [T]   <ESC> [0K       CLeaR END of the line
POSVID    [V]   <ESC> [0m       POSitive VIDeo for next characters
CLRBEG    [S]   <ESC> [1K       CleaR BEGinning of line
CLRTOP    [O]   <ESC> [1J       CLeaR the TOP of the screen
CLRALL    [N]   <ESC> [2J       CLeaR ALL of the screen
CLRLIN    [R]   <ESC> [2K       CLeaR LINe
NEGVID    [U]   <ESC> [7m       NEGative VIDeo for next characters
RM(n)     [X]   <ESC> [?~l      Reset Mode n
SM(n)     [W]   <ESC> [?~h      Set   Mode n
CUB(n)    [4]   <ESC> [~~D      CUrsor Backward n characters
CUD(n)    [2]   <ESC> [~~B      CUrsor Down     n lines
CUF(n)    [3]   <ESC> [~~C      CUrsor Forward  n characters
CUP(m,n)  [Y]   <ESC> [~~;~~H   CUrsor Position to line m, column n
CUU(n)    [1]   <ESC> [~~A      CUrsor Up       n lines
LL(n)     [Q]   <ESC> [~q       Light Led n (on keyboard); n=10 for all off
STBM(m,n) [Z]   <ESC> [~~;~~r   Set Top(m) and Bottom(n) Margins
    
Notes
-----
*) The second column shows the characters which are used by the test programs
   TST100 and TST101 --  see those programs for further details.
2) The symbol ~~ represents the two Ascii digits corresponding to the
   integer argument in the subroutine call.    





















Index of subroutine calls, by character used in TST100/TST101 programs
======================================================================--------
 Name      *   Escape code      Function performed (refer to VT100 User Guide)
------------------------------------------------------------------------------
CUU(n)    [1]   <ESC> [~~A      CUrsor Up       n lines
CUD(n)    [2]   <ESC> [~~B      CUrsor Down     n lines
CUF(n)    [3]   <ESC> [~~C      CUrsor Forward  n characters
CUB(n)    [4]   <ESC> [~~D      CUrsor Backward n characters
ANSI      [5]   <ESC>  <        set ANSI mode
CRLF      [6]   <CR><LF>        Carriage Return,Line Feed 
SAVCUR    [A]   <ESC>  7        SAVe CURsor & attributes
RESCUR    [B]   <ESC>  8        REStore CURsor & attributes
KPAM      [C]   <ESC>  =        KeyPad Application Mode
KPNM      [D]   <ESC>  >        KeyPad Numeric Mode
RIS       [E]   <ESC>  c        Reset to Initial State
RI        [F]   <ESC>  M        Reverse Index (move up)
ALIGND    [G]   <ESC> #8        ALIGN Display (fill screen with E's)
BIGTOP    [H]   <ESC> #3        BIG TOP (of double height line)
BIGBOT    [I]   <ESC> #4        BIG BOTtom (of double height line)
DWL       [J]   <ESC> #6        Double Width Line
SWL       [K]   <ESC> #5        Single Width Line
SGS       [L]   <ESC> (0        Select Graphics Set
DGS       [M]   <ESC> (B        Deselect Graphics Set
CLRALL    [N]   <ESC> [2J       CLeaR ALL of the screen
CLRTOP    [O]   <ESC> [1J       CLeaR the TOP of the screen
CLRBOT    [P]   <ESC> [0J       CLeaR the BOTtom of the screen
LL(n)     [Q]   <ESC> [~q       Light Led n (on keyboard); n=10 for all off
CLRLIN    [R]   <ESC> [2K       CLeaR LINe
CLRBEG    [S]   <ESC> [1K       CleaR BEGinning of line
CLREND    [T]   <ESC> [0K       CLeaR END of the line
NEGVID    [U]   <ESC> [7m       NEGative VIDeo for next characters
POSVID    [V]   <ESC> [0m       POSitive VIDeo for next characters
SM(n)     [W]   <ESC> [?~h      Set   Mode n
RM(n)     [X]   <ESC> [?~l      Reset Mode n
CUP(m,n)  [Y]   <ESC> [~~;~~H   CUrsor Position to line m, column n
STBM(m,n) [Z]   <ESC> [~~;~~r   Set Top(m) and Bottom(n) Margins
NEL       [[]   <ESC>  E        NEw Line
IND       [\]   <ESC>  D        INDex (move down)
    
Notes
-----
*) The second column shows the characters which are used by the test programs
   TST100 and TST101 --  see those programs for further details. This index is
   ordered by these characters (in order of Ascii value).
2) The symbol ~~ represents the two Ascii digits corresponding to the
   integer argument in the subroutine call.    






















                                                                       