crtsty.39

-*-TEXT-*-

File: CRTSTY,  Node: Top,  Up: (DIR),  Next: Introduction

	CRTSTY is a program that supports various display terminals
not directly supported by ITS.  If you have problems with CRTSTY use
:BUG CRTSTY to report them.

* Menu:

* Introduction::	Introduction to CRTSTY
* Options::		Command line options
* Terminals::		Specific terminal types & features
* Unsupported::		What to do if your terminal is unsupported
* LOGIN Inits::		How to use CRTSTY from a LOGIN init

* New Terminals: (TERMS)TOP	Info for people planning on buying terminals
			

File: CRTSTY,  Node: Introduction,  Up: Top,  Previous: Top,  Next: Options

	CRTSTY is a program which attempts to function as an invisible
intermediary between ITS and a "strange" display terminal.  A "strange"
terminal is anything not supported by ITS itself.  To see what support is
available for your terminal, if any, see [*Note Terminals: (INFO;TERMS)Top.]
For a variety of reasons, a terminal might not be suitable for direct ITS
support.  For example, it may have no command corresponding to one that
is required, or may need a non-standard escape sequence, or whatever.
In general these terminals are not numerous enough to justify putting
the support code directly into the system, and so CRTSTY exists.

In the usual case, all that is necessary is to furnish CRTSTY with the
terminal name:
		:CRTSTY <name>
For example, one might say ":CRTSTY FOX" or ":CRTSTY H1500".  The system
will now understand your terminal.  This is not actually what goes on; a
full explanation will be given later.

File: CRTSTY,  Node: Options, Up: Top, Previous: Introduction, Next: Terminals

	There are many options that can be specified while invoking
CRTSTY, so as to better match the particular terminal or user.  For
example, some particular models of a certain terminal may have
unusual features or options, which CRTSTY can take advantage of if it
is told about them, or they may lack some features which CRTSTY assumes
are standard, and CRTSTY must be prevented from using them.

Options are specified on the JCL line just like a terminal ID is,
separated by spaces or commas:

		:CRTSTY <terminal> <option1> <option2>...

Some options may take an argument, which must immediately follow the
option name; for example, ":CRTSTY FOX SPEED 300 NO TAB" has an
option named "SPEED", with an argument of 300, as well as an option
named "NO TAB", with no argument.

The following list of options is organized functionally, although there
is some overlapping; the categories used are:

* Menu:

* Terminal capabilities and parameters::
	speed, ispeed, ospeed, height, width, no abs, no tabs,
	no bell, no cleol, no cleos, no lid, no cid, scrlcount

* ITS options::
	glass, sail, scroll

* startup options::
	no warn, softok, no login, login

* user choice options::
	[no] inverse, visbel, wholine, alarm, [no] smeol, steos,
	no sii, no attach, tty, slave, debug, tpcbs, buffer, simulate

File: CRTSTY,  Node: Terminal capabilities and parameters,  Up: Options,
Next: ITS options,  Previous: Options

You can override CRTSTY's default assumptions about terminal
capabilities and parameters with these options.  For example,
if you had a cheap model of the HP2645 that lacked line insert
and delete, you could use ":CRTSTY HP2645 NO LID".


SPEED, ISPEED, OSPEED
	Are each followed by a decimal number, indicating the
actual speed of the terminal in bits per second.  This is
primarily meant for terminals connected in such a manner that ITS
cannot determine the speed of their communications line, for
example, most terminals connected through the ARPANET.  The speed
should be one of the following:
	110, 150, 300, 600, 1200, 1800, 2400, 4800, 9600.
The input speed is currently unimportant as far as CRTSTY is
concerned.  The output speed, however, is used for two things:
  [1]  Padding.  Terminals require a certain amount of time to execute
	their functions; in some cases so much that pad characters must
	be sent.  The number of pads is a function of output speed.
  [2]  Output buffer size.  CRTSTY attempts to buffer one second worth of 
	output at a time.  If this buffer is too large, it will take a long 
	time to stop any output when the user wants to (by a ^S 
	for example).  If this buffer is too small, output will be slowed down 
	and come in small bursts, especially when the system is loaded.

HEIGHT, PAGEL
	Followed by a decimal number.  This should only be used
to specify the actual number of lines on a terminal's screen, for
cases when CRTSTY's default size is wrong.  Do not use it to
force display into an area  smaller than the actual screen size;
instead use ":TCTYP PAGEL N" after invoking CRTSTY.  It is
important that CRTSTY know the actual hardware screen size, even
if ITS is told not to use all of it.

WIDTH, LINEL
	Followed by a decimal number.  The number of columns on
the terminals screen.  Same cautions for HEIGHT hold here; it is
OK to use ":TCTYP WIDTH N-1" to shorten effective screen width,
but CRTSTY must always know the actual hardware size.  Note that
TCTYP uses width specifications that are the number of columns
minus one.  Thus ":CRTSTY FOO WIDTH 80" and ":TCTYP FOO WIDTH 79"
are equivalent.
	Note that some terminals may do unexpected things in the
last column of a line.  If the terminal is skipping an extra
blank line whenever the system prints a continued line (one with
an ! at the end), you can probably fix that by giving a :TCTYP to
set the line length to one less than the actual screen width.
Some terminals have "auto-linefeed" switches which cause a
character written in the last column to generate a CRLF; in
general CRTSTY and ITS will provide better support if such
switches are turned off.  Send mail to BUG-CRTSTY@MC if any of
these problems evidence themselves, so that permanent fixes can
be made.

SCRLCOUNT N
     Tells CRTSTY that the terminal creates N blank lines on each
scroll (LF from last line of screen).

     The following enable the user to disable the use of various
features that CRTSTY might normally believe a terminal capable
of.  Meant for use in case the terminal is not properly executing
the feature for some reason, or use of the feature is causing
lossage (perhaps due to improper implementation in CRTSTY).
Since these are features that usually can be done in some other
(though usually slower) way, these options might enable
successful use of the terminal.

NO BELL - Tells CRTSTY that the terminal lacks a bell.

NO ABS - Tells CRTSTY that the terminal lacks absolute cursor
positioning.

NO TABS - Tells CRTSTY that the terminal lacks a tab command.

NO CLEOL - Tells CRTSTY that the terminal lacks a clear to end of
line command.

NO CLEOS - Tells CRTSTY that the terminal lacks a clear to end of
screen command.

NO LID - Tells CRTSTY that the terminal lacks line insert/delete
commands.

NO CID - Tells CRTSTY that the terminal lacks character
insert/delete commands.

File: CRTSTY,  Node: ITS options,    Up: Options,	
Previous: Terminal capabilities and parameters,   Next: startup options

GLASS - Same as :TCTYP GLASS.

SAIL - Same as :TCTYP SAIL.  Tells ITS to display characters 0-37
and 177 directly.

SCROLL - Same as :TCTYP SCROLL.  Tells ITS to scroll instead of
wrap when typeout reaches the bottom of the screen.

File: CRTSTY,  Node: startup options,   Up: Options,   Previous: ITS options,
Next: user choice options

NO LOGIN - CRTSTY ^Z's a new HACTRN, but does not log the
	user in automatically as it usually does.

LOGIN <name> - CRTSTY ^Z's a new HACTRN, and logs it in
	automatically as <name>.

NO WARN - Suppress warning messages on startup, such as "interchanged keys"
	messages.  This can be useful when CRTSTY is invoked from a
	DDT INIT file, and the user is sick and tired of seeing the same
	warning again and again.

SOFTOK - Suppresses error check that complains if CRTSTY user
	current terminal type is "software".

File: CRTSTY,  Node: user choice options,  Up: Options,
Previous: startup options

The user can control various random options.

			[no] inverse, visbel, wholine, alarm,
			[no] smeol, steos,
			no sii, no attach, tty, slave, debug,
			tpcbs, buffer, simulate

BUFFER N
	Followed by a decimal number.  Can be used to
specifically override the output buffer size.  See the
description of the OSPEED option for the implications of this.
In general, using this option isn't recommended.

VISBEL - Send a visible printing sequence in addition to (or instead of, if
	NO BELL is specified) all hardware bells, usually using
	the standout mode of the terminal.

INVERSE - "Inverse Video".  Reverses the sense of the entire
	screen.  Characters will be black-on-white.

ALARM <# mins> - If this option is given, CRTSTY will send a bell
	whenever terminal output happens after being idle for the specified
	number of minutes.  The idea is that you may want to be alerted
	from your book/desk/dinner by an unsolicited typeout of any form.
	Typein resets the "timer", as does typeout, so echo alone won't feep.

NO ATTACH - CRTSTY runs like any other job, under the user's HACTRN; it does
	not :ATTACH itself and become top-level.  ^Z will
	bring the user back to his original HACTRN, stopping the CRTSTY.

SLAVE - To "slave" a STY; suppresses the ^Z of a new HACTRN, and naturally
	doesn't log the user in either.  Also, logging out will not
	kill the STY or CRTSTY; it can be ^Z'd again manually.  Note that
	if NO ATTACH is not also given, there is no way to flush the CRTSTY
	short of gunning it down.  This can be useful for semi-permanent
	setups.


TPCBS - A temporary debugging switch which turns off CRTSTY's use of
	%TPCBS (intelligent terminal ptcl) so as to produce weird errors
	with SCPOS for the edification of unbelieving ITS TTY hackers.
	Don't use it.

File: CRTSTY,  Node: Terminals,  Up: Top, Previous: Options, Next: Unsupported

	This node may eventually have a menu pointing at each possible
terminal type that CRTSTY will understand, with each subnode documenting
various relevant features which CRTSTY furnishes for that terminal and
the like.  In the meantime, [*Note Terminals: (INFO;TERMS)Terminals.]
lists most supported terminals and gives technical information about them,
mostly aimed toward a potential buyer.

For the time being, the VT52 is the only one described here owing to its
usefulness (and complexity for the unknowing crtsty user).
Basically CRTSTY's VT52 implementation turns on the "alternate keypad"
mode in the following ways:
Key			Function
Left blank (blue)	META		These 3 apply to next real char typed;
Center blank (red)	TOP		any combination may be used.  If you
Right blank (black)	CONTROL		make a mistake, then hit the following
Down arrow		Cancel previous keys	which does what it says.
Up arrow		CALL		As opposed to plain Control-Z
Left arrow		BACK-NEXT	(^_ for com-links etc.)
ENTER			CRTSTY-Escape   Tell CRTSTY to do something
Right arrow		BREAK		escape for SUPDUP, TELNET, and PTY
0-9			META-0 to META-9	Very handy as args in EMACS.

Note that Escape (altmode) followed by a capital A, B, C, or D very quickly
has a small but non-zero chance of being interpreted as CALL, Cancel-previous,
BREAK, or BACK-NEXT.  If you don't use CAPS LOCK you'll probably never see
this, but if you do, the solution is (unfortunately) to not type with lightning
speed.

The ENTER key is a key that signals CRTSTY that you want to tell it something.
It saves the bottom line of your screen, and prompts with a "CRTSTY-->"
and waits for a single character.  It understands the following commands on
any terminal:
D -- Dump the screen image into the file .TEMP.;<uname> SCREEN
H -- Send a HELP character to the program
F -- Toggle FEEP mode (the ALARM option in JCL) whereby a BEEP is sent if you
     get output after being idle for both input and output for more than a
     JCL-specified amount of time.

In addition, individual terminals may specify additional operations.


File: CRTSTY,  Node: Unsupported,  Up: Top,  Previous: Terminals,
Next: LOGIN Inits

	It is generally a simple matter to add support for a new
terminal to CRTSTY.  This section will attempt to describe certain
minimum requirements the terminal must satisfy in order to be
supportable.  It then gives the procedure for requesting CRTSTY support
for your terminal.

	The first step is to check to see if your terminal is already
supported.  The most up to date information can be gained by typing
:CRTSTY ?, which will cause CRTSTY to list the terminals it knows
about.  However, sometimes the 6 letter names can be difficult to
recognize, therefore one might want to look over the menu in 
[*Note Terminals: (INFO;TERMS)Terminals.]

	In order for a terminal to be usable as an ITS display terminal
it must be able to selectively erase portions of the screen and to move
its cursor to any position on the screen.  While these requirements are
satisfied by most display terminals there are some which do not.  For
example a storage scope terminal (e.g. the Tektronix 4010 series
terminals) cannot selectively erase - only the whole screen can be
cleared.  Some terminals cannot move the cursor anywhere on the screen,
(e.g. the ADM-3) and so do not qualify.  This is not to say that these
terminals are unusable as ITS terminals, but that they cannot be used
as display terminals (e.g. for real-time editing in EMACS).  Use
":TCTYP TEK" for the 4010 series, and ":TCTYP GLASS" for those CRT
terminals which cannot move their cursor. (*Note (INFO;TCTYP)Top.)

	If the terminal satisfies the above two requirements then it is
possible for CRTSTY to support it.  However some terminals which meet
these requirements are painful to use as display terminals because they
lack features which must be simulated.  For example some terminals lack
any easy means of erasing to the end of a line or to the end of the
screen; to simulate these basic erasure commands CRTSTY must erase
character by character to the end of line/screen.  This is often
unbearable, especially at slow speeds.  Such terminals are better used
as "glass teletypes" rather than display terminals.  If you have such a
terminal (e.g. the ADM-3A) we highly recomend that you use it as a glass
TTY instead of trying to use CRTSTY.  If you do use CRTSTY, be content
that it works as well as it does; suggestions for display optimization
on such terminals are given the very lowest priority and will probably
never be done.

	At slow speeds even terminals with the basic erasure commands can
be painful to use as editing terminals unless they have the ability to
insert a new line on the screen (moving subsequent lines down), delete a
line from the screen (moving subsequent lines up), insert a character in a
line, and delete a character from a line.

	If your terminal has all the necessary features (selective erase
and cursor positioning), and is not supported by ITS or CRTSTY, you are
welcome to request CRTSTY support for it.  To do so send a message to
BUG-CRTSTY, that is do
	:BUG CRTSTY
and give a detailed description of the terminal.  If you simply ask for
support without giving a description we will at best ask for the details,
or at worst ignore you.  To support a terminal we need to know the
following things:

(Please do not specify commands in hex, or use obscure ASCII names for
control characters.)

[1] The size of the screen, i.e. the no. of characters per line and
	the no. of lines on the screen.
[2] The commands which should be sent to perform each of the following
	functions:
  a. Move cursor up one line
  b. Move cursor down one line - usually this is LF (^J, 012)
  c. Move cursor back one character position - usually this is BS (^H, 010)
  d. Move cursor forward one character position
  e. Move cursor to "home" position - For our purposes, this better be the
				upper left corner.
  f. Move cursor to beginning of line - usually CR (^M, 015)
  g. Move cursor to arbitrary position on screen ("absolute move")
  h. Erase to end of line - say whether it erases the complete line the
	cursor is on (bad) or just everything to the right of cursor (good).
  i. Erase to end of screen - similarly, will this clobber chars to the
	left of the cursor?  (It shouldn't)
  j. Erase whole screen - does it also move the cursor?  (should home)
  k. Insert line
  l. Delete line
  m. Insert character (or enter/exit insert character mode)
  n. Delete character
  o. Ring bell - usually BEL (^G, 007)
  p. Set tab stops - If tabs are not settable, or defaults are furnished,
	specify tab size (usually this is 8)
  q. Tab - usually HT (^I, 011)
[3] What the terminal does when a character is typed when the cursor
	is on the last column of a line.  Some terminals remain in the
	last column after the character is typed, others automatically
	CRLF.  If there is a choice (e.g. a switch) the former
	(remaining in the last column) is preferred.
[4] What the terminal does if you attempt to move down off the edges of the
	the screen
	a. by LineFeed off bottom
	b. by cursor position command off the bottom
	c. move off the bottom by an auotmatic CRLF off the last line
	d. cursor position off the right, left and top of the screen.
[5] A list of functions which might require padding at some speeds
	and the amount of padding required (this is best expressed as
	the amount of time required to perform the operation, but can
	also be given as the no. of pad characters required at each
	speed).
[6] Also any other features which might be useful.  If in doubt as to
	"usefulness", describe them anyway; who knows?
[7] Any misfeatures which CRTSTY should try to correct for.  For
	example many terminals have poor keyboard layouts which CRTSTY
	can correct for by exchanging certain keys.  The most common
	such switch is done for terminals where RUBOUT can only be typed
	with the SHIFT key down.  RUBOUT and the unshifted character are
	then usually exchanged.  Other common misfeatures include LF
	being ignored or interpreted specially after CR.

It isn't necessary that a terminal be able to do everything listed above
(in fact, much of CRTSTY's benefit comes from simulating those which
the terminal can't do), however, be sure to furnish some answer for
all of the items; otherwise we'll probably have to ask you about it
anyway.

File: CRTSTY,  Node: LOGIN Inits,  Up: Top,  Previous: Unsupported

If one simply puts :CRTSTY ... in one's init file, when one logs in, CRTSTY
will be started up, and will log in the user on the CRTSTY's STY.  However,
this second login will also attempt to run CRTSTY and encounter an error unless
precautions are taken to prevent such recursion.

The way to prevent the recursion is as follows:

:DDTSYM TCTYP/
:IF N Q-%TNSFW
(:CRTSTY <the JCL you would use to run it by hand>
)

Note that all 's in the above are ALTMODE's, not Dollar-signs

This should be placed near the beginning of your init before anything real
is done.  The first time through, you won't be on a STY so it will simply
run the CRTSTY, which will flush the DDT that was running the init, so no
further processing will be done on that run of the init.  The second time
through, you will be on a STY, and the :IF conditional will fail and the
part between the ( and the ) will not be done.  It also will not try to
run it if you are on a PTY, or using SUPDUP.

If you wish to have it ask you if you want to run CRTSTY, you can do the
following:

:DDTSYM TCTYP/
:IF N Q-%TNSFW
(:--CRTSTY--IF MORE 0
(:CRTSTY <the JCL you would use to run it by hand>
))

To prevent it from asking if you're on a TV, another layer is necessary:

:DDTSYM TCTYP/
:IF N Q-%TNSFW
(:IF N Q-%TNTV
(:--CRTSTY--IF MORE 0
(:CRTSTY <the JCL you would use to run it by hand>
)))

Another aproach is to only run it if you are on a dialup or coming in from the
net:

:DDTSYM TCTYP/
:IF N -%TNSFW
(:DDTSYM TTYTYP/
:IF N Q&<%TYDIL^_%TYSTY>
(:--CRTSTY--IF MORE 0
:CRTSTY <the JCL you would use to run it by hand>
)))

For more info on DDT see *note DDT: (DDT)TOP.
For more info on INIT files, and DDT conditionals,
see *note INITS: (DDT)XFILE.