/*    
	Release Notes for the Sam76 Language dated September 6, 1988

This is still an experimental version, s76m.EXE for MSDOS.
The unix version is called S76, both are identical except for graphics
support in the MSDOS version.  At this time the graphics support
for the UNIX version depends on the use of a PC as the terminal,
and on the use of "ctrm" as the software to connect to the UNIX
system. This also requires that there be a corresponding "ctrm"
installation in the UNIX system.

Decision was made for the sake of portability of user scripts that
the "\" and "/" used respectively by DOS and UNIX in directory
pathing strings are equivalent. That is to say that the user
may use either character: \sam4\globe... is same as /sam4/globe...
A useful byproduct of this decision is that in UNIX systems the
user may prefer using the antislash "\" character which does not
have any syntactic significance, otherwise the user has to
protect strings containing the slash "/" as follows:

	%bf,(/sam4/globe/test.sam)/=
	%dt,procedure,!<%bf,/sam4/globe/test.sam>//=

Look at the *.FUN files for lists of available primitive functions.

There are a number of *.sam files which are sam language scripts.  To
invoke and possibly execute them use the "s76 name" syntax at the command
level, be it UNIX or DOS. "name" is the "name" part of "name.sam".

A Benchmarking script called bm40x.sam may be used to measure time of
execution of functions and compare successive versions of this mess.

COMMAND LINE and PIPES
  Command line invocation of s76(m) may include a variety of flags
  which consist of a - followed by a single character, eg: -a -b ...
  Following these optional flags may be the name of a file which implicitly
  has an extension, or file type, of .sam, eg: bm401 (for bm401.sam).
  Should such a file exist, and should it contain sam76 language scripts
  the name of one of these being an upper case "A"., then execution starts
  by invoking that script - eg: %A/ and the file is executed.

  In addition one can use s76(m) as a filter by piping standard input
  to the language, and either displaying the standard output or redirecting
  it to another program or file. For instance:

	echo %ad,5,6/%ex/= | s76m -p > xxx.jnk

  will put in xxx.jnk the evaluation of the material after echo. Likewise

	type h.txt | s76m -p -b			(blanking input text) 

  will display the evaluation of the sam76 language scripts in the file
  h.txt. Note the use of the -p flag to signify piping. This may be
  optional, but its use is recommended at this time.

  -?	gives the user a list of currently available flags.
  -b	do not return input to standard output.
  -p	set up system to function from stamdard input.
  -x	display the restart expression when starting up.

ISSUES to be RESOLVED
  Should %rot,/ and %rot/ return 0 or a null string???
  Should trig table provide 1/2 degree steps when in drifting point mode???
  Should trig functions return 5 rather than 4 places???

Note that functions %qdu/ and %sdu,x/ are not relevant to UNIX systems
because in UNIX systems disks and other similar devices are viewed as
files - eg: /dev/dsk/xxx - perhaps the sdu should be a mount command?

INTERACTION WITH OPERATING SYSTEM
Interaction with UNIX is via the %sys,xxx/ command where xxx is a string
which is fed into the UNIX shell. This command will return value string
which is generated as a result of the execution of the shell command.

Interaction with DOS is via the %sys,xxx/ command where xxx is a string
which is operated upon by COMMAND.COM. This is a null valued function.
if the user desires the value of some particular xxx command to be fed
back it is necessary to redirect the output to some user defined file
and then use the %rf,file/ command to get it back. For example:

	%sys,(dir > file.tmp)/&rf,file.tmp/=

Note that the user can do %sys/=  and then be in dos, and use
the dos "exit" command to get back to the sam76 interpreter.

ANOMALIES and SHORTCOMINGS to be CORRECTED:
  %soc,pun/ & %sic,rdr/	not functional.
  In Dos systems, control C exit must be disabled.
  In Unix systems, SAMEXIT=^C, export SAMEXIT may be required.

CORRECTIONS (since previous versions):
  In UNIX version the "del" key does not break out, returns 0x7F.
  Subtle error in handling of getenv() fixed.
  Subtle bug in the ZQ, ZS functions corrected.
  Some subtle bugs in function name decoding fixed.
  A subtle bug in %wf,.../ was exterminated.
  %uns,.../, %pcc,dos,.../ replaced by %sys,.../
  %xu,xtb,.../ is now implemented.
  Subtle bug in the LW function corrected.

ADDITIONS and ENHANCEMENTS (since previous versions):
  Full string capability for all arithmetic functions working.
  %cwc,string/	   	Change Warning Characters is implemented
  %pi,d/	   	Pi to d decimal places (0 to 500).
  %dpm/ &dpm/	   	Disable/enable drifting point mode.
  %rot,../%sh,../  	Have been enhanced to work in bases 2,4,8,16,and 32.
  %sy,pid/		Returns the process ID number.
  &sy,gen,XXX/		Gets the environment value of XXX.
  %sy,pen,XXX,YYY/	Is supposed to put environment XXX=YYY, but doesn't.
  %sy,cec,C/		Change Exit Character (in lieu of ^C if disabled)
  %xrf,filn,s0/		X base read file, value is hex contents of file.
  %xwf,filn,x1,x2,.../	X base write file of arguments x1,x2,x3,...
  &wf,filn/		Write File with an EOF (controlZ) at end of file.
  %xlx,x1,x2,.../	Xper. List Xbase.
  %pl,udm,d/		Plot Unix Display Mode (0-ctrm, d-other unix)

Plot icons family has been added, see "icon76.c" for details
  %pl,pic,X,Y,ico,X1,Y1,ico1,../Put Icons (&pl,pic,.../) inverts image.
  %pl,wic,X,Y,x1,x2,../		Write Icon (&pl,wic,.../) inverts image.
  %pl,ric,X,Y,dx,dy,s0/		Read Icon
  %pl,cic,X,Y,dx,dy,d/		Clear Icon

Graphic screen save and restore are implemented using the runlength encoded
format in use by PaintBrush and other similar software. File type PCX is
used to identify image files. Functions to create, retrieve and question are:
  %pcc,std,name,...../		Screen To Disk
  %pcc,dts,name,...../		Disk To Screen
  %pcc,pcx,name/		PCX header information

Additional pcc family functions to modify printer control are:
  %pcc,ppd,d/		Print Direction - 0landscape, 1portrait.
  %pcc,pnc,d/		Print "d" copies.
  %pcc,plm,d/		Print Left Margin "d" dots from left edge.
  %pcc,ptm,d/		Print Top Margin "d" dots from top of page.
  %pcc,pps,d/		Print Picture Size Code (See ESI specs. for scrndump)
			Note that d=3 is added to mode 6 for icon printing.
		See PCCA76.FUN for full list of pcc functions.

Selecting graphic modes is through the use of the %pl,dis,mode,XMAX,YMAX/
   function. If mode is equal to one of the supported modes in the table
   below, XMAX, and YMAX need not be provided, eg: %pl,dis,13/ will select
   the EGA mode, and turn - on the screen. Alternatively the user may
   specify XMAX, and YMAX and thus simulate a screen equal to or smaller
   than one actually available in a particular machine, for example
   %pl,dis,64,640,350/ will simulate mode 16 EGA in an AT&T machine which
   would have selected a 640 x 400 screen.

Graphics modes supported under DOS are:
  case 4  : 
  case 5  : mode = 4;  break;		/* CGA		320 x 200	*/
  case 6  : mode = 6;  break;		/* CGA		640 x 200	*/
/*case 7  : mode = 6;  break;	*/	/* HERCULES	 25 x  80    M	*/
  case 7  : mode = 64;  break;		/* AT&T		640 x 400    M	*/
  case 8  : mode = 72;  break;		/* AT&T	tiny	640 x 400    M	*/
  case 13 : mode = 4;  break;		/* EGA		320 x 200   16c	*/
  case 14 : mode = 14; break;		/* EGA		640 x 200   16c	*/
  case 15 : 				/* EGA		640 x 350    M	*/
  case 16 : mode = 15; break;		/* EGA		640 x 350   16c	*/
  case 17 : mode = 25; break;		/* VGA, MCGA	640 x 480   2c	*/
  case 18 : mode = 25; break;		/* VGA		640 x 480   16c	*/
  case 19 : mode = 4;  break;		/* MCGA		320 x 200   16c	*/
  case 20 : mode = 20; break;		/* HERCULES	720 x 348    2c	*/
  case 25 : mode = 25; break;		/* PGA		640 x 480  256c	*/
  case 30 : mode = 4;  break; 		/* Tecmar	320 x 200   16c	*/
  case 31 : mode = 14; break;		/* Tecmar	640 x 200   16c	*/
  case 32 : mode = 32; break;		/* Tecmar	640 x 400   16c	*/
  case 40 : mode = 25; break;		/* Vega		640 x 480   16c	*/
  case 64 : mode = 32; break;		/* AT&T		640 x 400    M	*/
  case 65 : mode = 14; break;		/* DEB		640 x 200   16c	*/
  case 66 : mode = 32; break;		/* DEB		640 x 400   16c	*/
  case 72 : mode = 32; break;		/* AT&T		640 x 400    M	*/
  case 80 : mode = 25; break;		/* Paradise	640 x 480   16c	*/


DOS USERS:

Packaging of the sam76 system has been changed so that s76(m) contains only
sam76 language functions. Miscellaneous drivers for printers and graphics
drivers are contained in other files:

	s76esd.exe		printer support, epson, oki and laserjetII
	s76pcx.exe		pcx file saves and restores
	s76scr.exe		binary screen saves and restores

It is important that s76(m).exe and these files be placed in a directory
which is in the search path, typically \bin, or \sys, or whatever.

Users who have source code should also have s76esi.lib so that they can
rebuild these external files.

Interaction is in pcca76.c, and the user can examine that program to see how
to add other drivers or external programs as they may wish.

Compilation should use Microsoft 5.1, sample makefiles to recompile the sam76
language or other drivers. Note that the drivers are compiled as a small model.
At this time s76(m) is compiled as a medium model.

Compilation has been made using Microsoft 6.00A (upgraded) using ms76x1.bat,
also note that at this time the 5.1 "make.exe" is being used, "nmake.exe"
provided with 6.00 does not work. In addition a large number of warning
messages are issued suggesting that functions in question must return
a value?????. (April 1991)

Additional entries have been made to the graphics board switch table
in plt76.c to provide for the 1024 x 768 and 256 color modes of the
Tseng Labs video graphics card. (April 1991)

July 1992 - Code slightly modified to remove all of the warning
messages generated by the Microsoft compiler. These messages
related to the fact that most subroutines never return values
they were written in such a way that a value might have been
expected, thence the warning messages.

August 1992 - Modified the %sy,cec,x/ function which normally
when used as shown here will change the "Exit Character" from
that denoted by "x", usually a CONTROL-C to the character specified.
The modification consists of using the neutral form &sy,cec,x/ to
disable the exit from taking place. Active use of the function is
used to re-enable the exit function.

*/