Summary

###########################################################################
    
	File:     itlibdos.icn
	
	Subject:  Procedures for MS-DOS termlib-type tools
	
	Author:   Richard L. Goerwitz

	Date:     August 14, 1996

###########################################################################

   This file is in the public domain.

###########################################################################

	Version:  1.15

###########################################################################

  The following library represents a series of rough functional
  equivalents to the standard UNIX low-level termcap routines.  They
  are not meant as exact termlib clones.  Nor are they enhanced to
  take care of magic cookie terminals, terminals that use \D in their
  termcap entries, or, in short, anything I felt would not affect my
  normal, day-to-day work with ANSI and vt100 terminals.  At this
  point I'd recommend trying iolib.icn instead of itlibdos.icn.  Iolib
  is largely DOS-UNIX interchangeable, and it does pretty much every-
  thing itlibdos.icn does.

###########################################################################

  Requires:  An MS-DOS platform & co-expressions.  The MS-DOS version
  is a port of the UNIX version.  Software you write for this library
  can be made to run under UNIX simply by substituting the UNIX ver-
  sion of this library.  See below for additional notes on how to use
  this MS-DOS port.

  setname(term)
	Use only if you wish to initialize itermlib for a terminal
  other than what your current environment specifies.  "Term" is the
  name of the termcap entry to use.  Normally this initialization is
  done automatically, and need not concern the user.

  getval(id)
	Works something like tgetnum, tgetflag, and tgetstr.  In the
  spirit of Icon, all three have been collapsed into one routine.
  Integer valued caps are returned as integers, strings as strings,
  and flags as records (if a flag is set, then type(flag) will return
  "true").  Absence of a given capability is signalled by procedure
  failure.

  igoto(cm,destcol,destline) - NB:  default 1 offset (*not* zero)!
	Analogous to tgoto.  "Cm" is the cursor movement command for
  the current terminal, as obtained via getval("cm").  Igoto()
  returns a string which, when output via iputs, will cause the
  cursor to move to column "destcol" and line "destline."  Column and
  line are always calculated using a *one* offset.  This is far more
  Iconish than the normal zero offset used by tgoto.  If you want to
  go to the first square on your screen, then include in your program
  "iputs(igoto(getval("cm"),1,1))."

  iputs(cp,affcnt)
	Equivalent to tputs.  "Cp" is a string obtained via getval(),
  or, in the case of "cm," via igoto(getval("cm"),x,y).  Affcnt is a
  count of affected lines.  It is only relevant for terminals which
  specify proportional (starred) delays in their termcap entries.

###########################################################################

  Notes on the MS-DOS version:
	There are two basic reasons for using the I/O routines
  contained in this package.  First, by using a set of generalized
  routines, your code will become much more readable.  Secondly, by
  using a high level interface, you can avoid the cardinal
  programming error of hard coding things like screen length and
  escape codes into your programs.
	To use this collection of programs, you must do two things.
  First, you must add the line "device=ansi.sys" (or the name of some
  other driver, like zansi.sys, nansi.sys, or nnansi.sys [=new
  nansi.sys]) to your config.sys file.  Secondly, you must add two
  lines to your autoexec.bat file:  1) "set TERM=ansi-mono" and 2)
  "set TERMCAP=\location\termcap."  The purpose of setting the TERM
  variable is to tell this program what driver you are using.  If you
  have a color system, use "ansi-color" instead of "ansi-mono," and
  if you are using nansi or zansi instead of vanilla ansi, use one of
  these names instead of the "ansi" (e.g. "zansi-mono").  The purpose
  of setting TERMCAP is to make it possible to determine where the
  termcap file is located.  The termcap file (which should have been
  packed with this library as termcap.dos) is a short database of all
  the escape sequences used by the various terminal drivers.  Set
  TERMCAP so that it reflects the location of this file (which should
  be renamed as termcap, for the sake of consistency with the UNIX
  version).  Naturally, you must change "\location\" above to reflect
  the correct path on your system.  With some distributions, a second
  termcap file may be included (termcap2.dos).  Certain games work a
  lot better using this alternate file.  To try it out, rename it to
  termcap, and set TERMCAP to its location.
	Although I make no pretense here of providing here a complete
  introduction to the format of the termcap database file, it will be
  useful, I think, to explain a few basic facts about how to use this
  program in conjunction with it.  If, say, you want to clear the
  screen, add the line,

	iputs(getval("cl"))

  to your program.  The function iputs() outputs screen control
  sequences.  Getval retrieves a specific sequence from the termcap
  file.  The string "cl" is the symbol used in the termcap file to
  mark the code used to clear the screen.  By executing the
  expression "iputs(getval("cl"))," you are 1) looking up the "cl"
  (clear) code in the termcap database entry for your terminal, and
  the 2) outputting that sequence to the screen.
	Some other useful termcap symbols are "ce" (clear to end of
  line), "ho" (go to the top left square on the screen), "so" (begin
  standout mode), and "se" (end standout mode).  To output a
  boldfaced string, str, to the screen, you would write -

	iputs(getval("so"))
	writes(str)
	iputs(getval("se"))

  You could write "writes(getval("so") || str || getval("se")), but
  this would only work for DOS.  Some UNIX terminals require padding,
  and iputs() handles them specially.  Normally you should not worry
  about UNIX quirks under DOS.  It is in general wise, though, to
  separate out screen control sequences, and output them via iputs().
	It is also heartily to be recommended that MS-DOS programmers
  try not to assume that everyone will be using a 25-line screen.
  Some terminals are 24-line.  Some 43.  Some have variable window
  sizes.  If you want to put a status line on, say, the 2nd-to-last
  line of the screen, then determine what that line is by executing
  "getval("li")."  The termcap database holds not only string-valued
  sequences, but numeric ones as well.  The value of "li" tells you
  how many lines the terminal has (compare "co," which will tell you
  how many columns).  To go to the beginning of the second-to-last
  line on the screen, type in:

	iputs(igoto(getval("cm"), 1, getval("li")-1))

  The "cm" capability is a special capability, and needs to be output
  via igoto(cm,x,y), where cm is the sequence telling your computer
  to move the cursor to a specified spot, x is the column, and y is
  the row.  The expression "getval("li")-1" will return the number of
  the second-to-last line on your screen.

###########################################################################

  Requires: MS-DOS, coexpressions

###########################################################################

  See also: iscreen.icn, iolib.icn, itlib.icn

###########################################################################

This file is part of the (main) package.

Decode(s)

check_features()

er(func, msg, errnum)

getentry(name, termcap_string)

getname()

getval(id)

igoto(cm, col, line)

iputs(cp, affcnt)

maketc_table(entry)

read_file(f)

setname(name)