Squeezing The Last Drop Out Of SCRFT
			  Eric P. Scott
		    Jet Propulsion Laboratory

The terminal-independent screen handling procedures provide a
means by which user programs can perform basic display functions
on a scope terminal, or simulated output on a hardcopy device.
In addition to the devices supported by Digital, up to eight
site-dependent "foreign terminals" may be defined.

Images that reference the terminal-independent screen handling
procedures link against the shareable image SCRSHR.  If called
upon to service a "foreign terminal" SCRSHR merges the customer-
supplied image SCRFT into P0 space and calls its entry point for
each request (except SCREEN_INFO, which SCRSHR always handles).

SCRFT must be PIC (Position Independent Code) and reentrant.  In
order to work with images installed with elevated privileges
(MAIL, MONITOR, PHONE, SHOW) it must itself be INSTALLed.  While
it can (and should) be installed /SHARED, don't specify /HEADER--
wrong things happen.

A "template SCRFT" is provided in SYS$SYSROOT:[SYSHLP.EXAMPLES].
It documents the call interface between SCRSHR and SCRFT, but the
other comments are not entirely accurate and as a model for a
practical SCRFT it leaves much to be desired.  I found it
advantageous to discard it entirely.  SCRFT has to handle an NxM
problem--N function calls that can be applied to M terminals.
The DEC-supplied template cases first on function code.  As I'm
more likely to want to add support for additional terminal types
than DEC is about to add new screen procedures in a minor release
it makes more sense to case first on terminal type.  Other than a
small amount of common preprocessing, each terminal gets its own
separately maintainable chunk of code.

Internal to SCRSHR is a structure called the Terminal Control
Block that preserves context for each channel across calls to the
procedures.  An undocumented feature of the SCRSHR-SCRFT
interface is that its address can be found in R6.  I use this
fact to good advantage; if I have a terminal that lacks the
"reverse index" function but can move its cursor up and insert a
blank line at an arbitrary screen row, then I can implement
UP_SCROLL \if I know what line the cursor is on./  Assuming that
all output is routed through the procedures (or at the very
least that the cursor position is not "lost" between a procedure
that establishes it and one that takes it as an implicit input),
then my bookkeeping will agree with the external cursor position.

The sample SCRFT accompanying this article contains support for
three terminals.  They are not necessarily representative of the
terminals most sites have, nor is any endorsement of a particular
manufacturer or model intended.  This code is published solely to
illustrate the techniques used.  No guarantees are made that it
will work in all cases; some of the DEC-supplied utilities call
the procedures with illegal arguments or take advantage of known
features of DEC terminals.  SCRFTDBG is a SCRFT surrogate that
traces the procedure calls.  Use it to find out why your SCRFT
didn't work or why PHONE is unbearably slow at 300 baud.

Certain minimum requirements are expected of candidates for
support.  The screen must be no smaller than 24x80.  The terminal
must not wrap at column 80 (if this is selectable the proper
selection is off).  The terminal must have the ability to move
its cursor and clear to the end of the current line.  If the
terminal has "standout modes" (I'm deliberately avoiding the word
"attributes") they must not consume screen positions.  Support
for deficient or "braindamaged" terminals is by no means
impossible; I do, however, actively discourage their use.

My hope is that in some future release of VMS it will be possible
to support foreign terminals with the same ease as Digital
terminals; either by extending the Terminal Control Block to
include at least a "user context longword" and pass its address
to SCRFT as a formal parameter along with the addresses of
LIB$GET_VM and LIB$FREE_VM and provide initialization and rundown
hooks called for each channel or by dispensing with SCRFT
entirely and allowing customers to tinker with SCRSHR directly.
While I'm on the subject, the terminal driver tracks cursor
position as well; it should be possible for SCRSHR to "advise"
it.  Until then, this is the best we have.