

				     SESSION
				  By Eric Tauck
				 October 2, 1990

     Session is	a simple yet capable communications program.  Some of the
     features of Session include text and binary file transfers, a DOS
     shell, ANSI terminal emulation, and a macro language.  Session works
     well for connecting to online services and	BBS's.

     Session is	primarily configured with command line parameters.  The
     idea is to	have a batch file or menu system run Session with the
     proper parameters and log-on macro.

			      Command Line Options
			      --------------------

     All command line parameters must be separated by one or more spaces.
     Configuration options consist of a	slash, a letter, and a number.	If
     the name of a macro file is present on the	command	line, the macro
     will automatically	be compiled and	executed.

     /Bnnnn  Baud rate (actually bits per second).  Most modems	work at
	     300, 1200,	or 2400	bps.  I	think the maximum reliable speed
	     using this	software is 19200 bps.	On some	hardware I have	had
	     some trouble with a direct	serial link using this software	at
	     above 2400	bps.  The default is /B2400.

     /Cn     Color.  This option forces	Session	to use the color or black
	     and white attribute sets.	Use /C0	to let Session choose, /C1
	     to	force the color	attribute set, or /C2 to force the b/w
	     attribute set.  The default is /C0.

     /Dn     Serial port data bits.  Use /D7 for 7 data	bits or	or /D8 for
	     8 data bits.  The default is /D8.

     /Nn     Noise.  This option will silence Session if you don't like
	     any noise.	 Use /N0 for no	noises or /N1 to enable	noises.

     /Onnnn  Options.  The values below	must be	added together to enable
	     the desired features.  For	instance, /O33 will enable local
	     echo and high bit stripping (1 + 32).  If the /O parameter	is
	     used, any option not explicitly enabled is	disabled.  For
	     instance, though ANSI is enabled by default, specifying /O33
	     will turn ANSI support off.  If you set any /O option, you
	     must set ALL the /O options you want enabled.

		  1  Local echo.  All characters typed locally will be
		     echoed to the display.  GEnie needs this option.

		  2  Split screen.  The	screen will be divided in in two.
		     All incoming characters will be displayed in the upper
		     half and all characters typed locally will	be
		     displayed in the lower half.

		 16  Append LF to CR.  A linefeed will be displayed after
		     every incoming carriage return.  This is particularly
		     useful for	direct micro-to-micro chatting in split
		     screen mode.


		 32  Strip high	bit.  The upper	bit of all incoming bytes
		     is	cleared.  This should clear up the scrambled prompt
		     you might get just	before logging on to Compuserve	or
		     GEnie.

		 64  Fast xmodem.  Use this option when	connecting directly
		     to	other micros or	BBS's.	Do not use this	option when
		     connecting	to timesharing systems (like GEnie and
		     Compuserve).  This	option is on by	default.

		128  1K	xmodem.	 Allows	data to	be sent	and received using
		     1024 byte xmodem blocks.  This protocol is	usually	a
		     little faster than	regular	xmodem but not all systems
		     support it.

		256  Enable ANSI.  Allows the remote system to control the
		     screen using ANSI sequences.  It usually doesn't hurt
		     to	have ANSI enabled, even	if the remote system
		     doesn't use ANSI sequences.  This option is on by
		     default.

		512  Detect loss of carrier.  Session will beep	and display
		     a message whenever	the carrier is lost.  Losing the
		     carrier usually means the remote system is	no longer
		     connected.

	       2048  Filter control characters.	 Unsupported incoming
		     control characters	will not be displayed.	This
		     sometimes cuts down on the	garbage	displayed on the
		     screen when connecting or disconnecting at	2400 bps.
		     This option is on by default.

	       8192  Enable macro debugging.  When enabled, every time a
		     macro is started or a BREAK or QUIT is encountered
		     within a macro, the current location in the macro is
		     displayed and the top three items on the stack and
		     return stack are displayed.  You may then press ALT-B
		     to	disable	debugging or ALT-A to abort the	macro.	Any
		     other key allows the macro	to continue running with
		     debugging on.

     /Pn     Serial port number.  Use /P1 for serial port one or /P2 for
	     serial port two.  The default is /P1.

     /Rn     Serial parity.  Use /P0 for no parity, /P1	for odd	parity,	or
	     /P2 for even parity.  The default is /P0.

     /Sn     Serial stop bits.	Use /S1	for one	stop bit or /S2	for two
	     stop bits.	 The default is	/S1.

     /Tnn    Text pacing.  This	option slows the rate at which text files
	     are sent by pausing at the	end of each line.  This	is
	     sometimes necessary when connecting to slow systems.  The time
	     is	specified in "ticks," which occur about	18.2 times a
	     second. The default is /T9	(about 1/2 second).

     /Vnn    Video mode.  Use the numbers below	to specify which text video
	     mode you wish to use.  The	mode descriptions list the number


	     of	columns	by the number of rows.	Note that the non-standard
	     modes (all	the modes except 80 x 25) require specific video
	     adapters.	The default mode is /V8025.

		8  80 x	12; VGA	color
		9  80 x	14; VGA	color
	       10  80 x	21; VGA
	       11  80 x	25; all	adapters
	       12  80 x	28; VGA
	       13  80 x	43; EGA, VGA
	       14  80 x	50; VGA

			     Terminal Mode Commands
			     ----------------------

     Session enters terminal mode upon execution.  All commands	are
     immediately available.

     F1	    Help screen.  This command displays	a one page summary of all
	    the	terminal commands.

     PgUp   Upload a binary file.  This	command	sends a	file using the
	    xmodem protocol.  The protocol can be adjusted from	the command
	    line when Session is started.

     PgDn   Download a binary file.  This command receives a file using	the
	    xmodem protocol.  The protocol can be adjusted from	the command
	    line when Session is started.

     ALT-A  Abort file transfer.  This command aborts (in order): a binary
	    file transfer, a text upload, or a text download.  Only one
	    thing is aborted at	a time,	but repeatedly pressing	this key
	    twill abort	all these things.

     ALT-B  Toggle macro debugging.  This command turns	debugging on if
	    it's off, or turns it off if it's on.  Macro debugging can also
	    be turned on or off	from the command line when Session is
	    started.

     ALT-C  Clear screen.  This	command	clears the screen.  In split screen
	    mode, both halves of the screen are	cleared.

     ALT-D  Download a text file.  This	command	captures incoming text to a
	    file.  If the file you specify already exists, the new text	is
	    appended to	its end.  You can stop downloading text	by pressing
	    ALT-A.

     ALT-E  Toggle echo.  This command turns echo on if	it's off, or turns
	    it off if it's on.	Echo can also be turned	on or off from the
	    command line when Session is started.

     ALT-M  Run	macro.	This command compiles and runs a macro.	 If the
	    file you specify doesn't exist in the current directory and	DOS
	    3.0	or higher is running, Session will look	in the directory
	    where SESSION.COM resides.

     ALT-R  Reset screen.  Use this command to clear and reset the colors
	    of the screen when a remote	system has left	the screen in an


	    odd	state (by setting the colors with ANSI sequences).

     ALT-S  Toggle split screen.  This command splits the screen if it's
	    whole, or merges the screen	if it's	split.	Split screen mode
	    can	also be	turned on or off from the command line when Session
	    is started.

     ALT-U  Upload a text file.	 This command sends a text file	to the
	    serial port.  The text is sent just	as if you had typed it.

     ALT-X  Exit program.  This	command	leaves the Session program.

     ALT-Z  System shell.  This	command	runs a DOS shell.  Running a DOS
	    shell doesn't affect the serial connection.

				 Macro Language
				 --------------

     The macro language	comes from the WASM library and	is described in	the
     Language Description section of the file MACRO.DOC.  The following	is a
     description of the	Session	specific keywords added	to this	macro
     language:

     CGET    - 0 | byte	-1

       Get a communications byte.  Return false	if no byte or true and a
       byte if available.

     CLEAR

       Clear the screen.  The screen is	cleared	just like the clear screen
       terminal	command	ALT-C.

     CPUT    byte -

       Send a communications byte.  The	byte is	sent directly, not through
       the terminal.

     CREP    byte -

       Replace a communications	byte.  Simulates receiving a byte.  Can
       only replace one	byte at	a time.

     DLOAD   file -

       Download	a file using xmodem.  The user is not prompted for a file
       name, however overwrites	will be	verified as usual.

     ERROR   message -

       Display an error	message.  The error is displayed at the	top of the
       screen, the speaker is beeped, and ESC must be pressed.

     INPUT   buffer prompt - 0 | -1

       Input a string to the buffer.  False is returned	if there is no
       input.



     KGET    - 0 | key -1

       Get a keystroke.	 Return	false an no byte or true and a byte if
       available.

     KREP    key -

       Replace a keystroke.  Simulates pressing	a key.	Can only replace
       one keystroke at	a time.

     MESS    message -

       Type a string to	the terminal screen.  The string is displayed in
       the color of system messages and	an CR/LF is appended to	the end.

     RESET

       Reset the timer.	 This keyword resets the timer used by the TICKS
       keyword.

     TERM    byte -

       Send a byte through the terminal.  The byte is subject to being
       echoed or otherwise processed by	the terminal.

     TICKS   - ticks

       Return time passed.  The	time since the last RESET is returned in
       ticks.  Ticks occur about 18.2 times a second.

     TYPE    character -

       Type a character	to the terminal	screen.	 The character is displayed
       in the color of system terminal messages.

     ULOAD   file -

       Upload a	file using xmodem.  The	user is	not prompted for a file
       name.

     VERIFY  message - 0 | -1

       Verify something.  The verify prompt is displayed and the user must
       press Y for yes or N for	no.  False is returned if the result is	no.

     Macro debugging can be toggled on or off with the terminal	command
     ALT-B or turned on	or off from the	command	line.  When macro debugging
     is	on, the	state of the macro is displayed	whenever a macro starts, a
     BREAK is encountered, or a	QUIT is	encountered.  The information
     displayed is: the current location	in the macro, the number of items
     on	the stack, the number of items on the return stack (from CALL's),
     the top three items on the	stack, and the top three items on the
     return stack.  The	stack items are	displayed three	different ways:	as
     a signed decimal number, a	hexadecimal number, and	the nearest
     previous symbol to	that address.  The nearest previous symbol is also
     displayed for the current macro location.

     When a macro is interrupted and its state information displayed, the


     debugger waits for	a keystroke.  You can press ALT-A to abort the
     macro, ALT-B to disable debugging and continue, or	any other key to
     continue with debugging still on.

     By	placing	BREAK statements at key	locations, you can determine
     exactly what the macro is doing.  The best	way to write a macro is	to
     write and test small parts	of it at at time.
