TIC - Talk is Cheap

Copyright 1987
By Donald Elton
Carolina System Software


Documentation:
--------------

This is an abbreviated documentation file intended to give you enough
information about TIC to let you try it out while you decide if you
want to buy the full package that includes the complete 40 page user's
guide.  It is not all inclusive and the package you downloaded isn't
all inclusive either but is there to let you 'try before you buy'.


Features:
---------

TIC is a ProDOS based terminal program for the Apple //e and Apple //c
personal computers with an Apple Super Serial card or equivalent in
slot 2 and an optional printer attached to slot 1.

TIC also supports the new Apple IIgs with either an Apple Super Serial
card plugged into slot 2 or using the built-in IIgs serial port.

This program supports a standard TTY terminal mode along with several
terminal emulations and file transfer protocols:
xmodem, xmodem crc, ymodem, ymodem crc, turbo xmodem/ymodem and
Ascii Express (tm USII) protocol for ProDOS file transfers.  Ascii
text uploads are also supported using x-on/x-off protocol with user
selectable prompt, character, and line delays.

A copy buffer can be used to record an online session or to download
a file where protocol modes are not available.  The copy buffer may
be saved to disk either automatically when the buffer fills or manually.


Getting Online:
---------------
TIC automatically places you right in terminal mode as soon as you leave
the title screen.  You can dial your modem either manually by typing in
the commands that your modem recognizes (see your modem manual) or under
the control of command/macro files (described below).  It's usually best
to get comfortable with the manual method before venturing to use the
command files.  For Hayes compatible modems you can dial the phone by
typing ATD followed by the phone number and then hit the RETURN key.


Hardware Set-up:
----------------
Note that in order to use this program with the Apple Super Serial card
you must have switch 6, block 2 turned to the ON position thus enabling
interrupts.

If you are using this program with the Apple IIgs port then you need to
set your Control panel to select MODEM PORT for slot 2.  Depending on your
cable you may need to set the modem port to DCD HANDSHAKE OFF.  The other
options on the modem port screen should be left at their default values
as TIC will control them directly.


About Shareware:
----------------

This is a Shareware program.  This means that it is distributed primarily
electronically via bulletin board programs and information systems.  You
may distribute this program freely with the stipulation that users of the
program are advised of the shareware nature of this product.  I ask that
if you use this program that you send me $30 to help support me in writing
programs like this.  Given that competitive products for the Apple
generally sell for twice this amount I think this is a fair thing to ask.
In return for the $30 you get a nice manual, technical support, update
notices, and a good feeling inside for helping to keep down the high
cost of quality apple software.  If this product gets good user support
via the shareware agreement then it will continue to be updated with
new features, largely at the suggestions of users.  Shareware distribution
has the potential of being a great way to distribute great apple software
at minimal prices because of the minimal distribution costs.  Help keep
a good thing going and send your check today to:

Don Elton
3207 Berkeley Forest Drive
Columbia, SC  29209-4111

803 776 3936 (300-2400 baud)

If you'd like to make any comments or suggestions concerning TIC please
feel free to send them to me at the above address.

Commisions:
-----------

Oh yeah, new idea.  The copy of TIC that you are using has a Serial number
affixed to the title screen.  This is the serial number of the user who
registered the copy you are using.  If this serial number is 0 then you
got this copy directly from me.  When you register TIC you should list
the serial number of the copy of TIC you were using so I can send a $5
finder's fee to the person who actually registered the copy you first tried
out.  This will work the same for you too... This means that if you give
10 copies of TIC away to friends and all 10 of them register the program
by paying the $30 shareware fee then I'll mail you a check for $50.

If you upload the program to a bulletin board and 100 people register
and give your serial number with their order then I mail you $500.  Just
another incentive for you to register the program yourself and to encourage
others to do the same.  Thanks for your support.


Terminal Emulation:
-------------------

     TIC can now do screen emulation of many popular terminals.  This
is accomplished by the loading of special termcap definition files
which contain the necessary translation tables to do the particular
emulation.  The default is TTY (no emulation).  You may specify the
termcap definition file you want to use from the OA-M menu.  From this
entry (9) you enter the pathname required to reach the termcap file
assuming that the prefix is set to the root directory.  You may 
optionally use a full pathname at this entry.  You may also specify a
termcap file using the EMULATE statement from a command file.  Note that
ZOOM mode is only available from TTY mode.

     You may use the supplied DEFTERM basic program to define your own
terminals.  You need to have some idea of what makes up a terminal 
emulation to use this program so do so at your own risk.

     Note that TIC can only emulate terminals that are based on binary
codes.  This leaves out the VT-100/VT-200 series since they are based
on ascii codes.  They may be supported in a future version of TIC.


Command File Documentation:
--------------------------

     Talk is Cheap (TIC) versions 0.27 and above support a powerful Command
file feature that allows a user to automate most functions internal to TIC.
This document is a supplemental user's guide to describe how the Command file
feature works and to specify the language of statements used within Command
files.  There are also several new features, not related to Command files that
have been added to TIC as a result of user suggestions.


Note:  OA-X refers to the Open Apple plus "X" key combination.  CA-X refers to
       the Closed Apple plus "X" key combination.  Note that the newer Apple
       IIgs and //e keyboards substitute "OPTION" for the Closed Apple key.

     TIC now supports powerful Command files.  These Command files, if properly
named, are automatically executed when you press the Closed Apple key together
with a letter key or they may be specified manually using the OA-X command
described above.  If the user presses the CA-A combination then TIC will look
for a file named "TIC.KEY.A" to execute as a command file.  Command files that
are executed as keyboard Macros are called Macro Command Files.  In order for
TIC to find its Command files, TIC keeps up with the concept of a Root
directory.  The Root directory is the directory that TIC resides in when it is
run.  All Macro Command Files must reside in the Root directory.

     At startup time, if a file named "TIC.STARTUP" is found in the Root
directory then TIC will execute it as a Command file automatically.  If you are
using a program selector such as the Extended Command Processor (ECP) then you
may specify an alternate startup Command file at run-time by specifying the
alternate file name after the TIC file name:

:tic <file>

The above would start TIC and force TIC to execute <file> as the startup
Command file.

In order to invoke Macro Command files, you must have a text file named
TIC.MACROS in TIC's Root directory.  Each line of this file should begin
with the letter of a valid Macro key.  i.e. if you start a line in
TIC.MACROS with "A" then you should have a file named "TIC.KEY.A" in the
same Root directory with TIC.  The remainder of the line should start
immediately after the letter identifier and should be the name of the
service associated with the particular Macro key.  An example TIC.MACROS file
might contain:

aApple BBS
bRadio Shack BBS
cMy BBS
fYour BBS


Most Command file operations can be aborted by pressing the ESC key.  There may
be a short delay in aborting certain Command file functions.


TIC Command file Syntax:

     TIC Command files are text files created by any text editor.  They consist
of lines of text with a single command per line.  Blank lines are ignored as
are leading and trailing spaces which may be included in the file to improve
readability.  Upper and lower case characters are allowed and will not affect
parsing.  TIC does not check the file type of Command files.



Command List:


#
     This is the comment character.  It is a command that is ignored.  One or
          more blank characters must follow the # symbol.  Labels are defined
          as the first word following the # symbol.  Thus to encode the label
          'start' in a Command file you would use the following:

# start  <-- this is a label.. "Start"


BUFFER ON

     Turns on the recording buffer.


BUFFER OFF

     Turns off the recording buffer.


BUFFER CLEAR

     Erases the recording buffer.


BUFFER SAVE

     Saves the recording buffer to the autosave file.


BUFFER WRITE <file>

     Saves the recording buffer to <file>.


DISPLAY <string>

     The <string> is displayed to the CRT.  <string> may contain imbedded
          control characters or you may encode them by prefixing a letter key
          with the "^" symbol.  Thus, "^C" is Control-C.  Use "^^" to encode a
          single "^" character literally.  Note that the characters displayed
          are sent to the CRT using the communications console driver so
          carriage returns and line feeds must be encoded separately as "^M^J".
          Either single or double quotes are required if <string> contains
          imbedded blanks.


DO <label>

     Calls a subroutine that begins with the line following <label>.  See also,
          RETURN.  Note that only one DO procedure may be active at one time.


EMULATE <pathname>

     Emulate the terminal defined in the termcap file found at <pathname>.
Specify TTY for no emulation.


GOTO <label>

     Transfers control to the statement following <label>.


HANGUP

     Hangs up the telephone connection.


IF EXISTS <path> <statement>

     If <path> exists then exeucte <statement>.  Otherwise, execution continues
          with the statements that follow this statement.


IF FAILED <statement>

     If the previous statement failed (i.e. a WAITFOR statement didn't find its
          target before the time limit expired) then <statement> is executed.
          Otherwise, control passes to the next statement and <statement> is
          ignored.


IF KEYBOARD <CHAR> <LABEL>

     If the most recently pressed keyboard character matches <CHAR> then
          continue execution with the statement following <LABEL>.


PAUSE <seconds>

     Execution pauses for the duration specified in <seconds>.  If <seconds> is
          omitted then execution will pause for approximately one second.


PRINT INIT <string>

     Sets the printer initialization string as specified.  Control characters
          can be encoded just like DISPLAY.


PRINT OFF

     Turns off online printing.


PRINT ON

     Turns on online printing.


PRINT SCREEN

     Prints the current screen.


QUIT

     The ProDOS QUIT MLI call will cause TIC to shutdown and exit to the
          selector program.


RECEIVE <file>

     Receives <file> from a host computer using Xmodem, Ymodem, or ProDOS
          xmodem protocol.


RETURN

     This statement returns control back to the next line following the last
          executed DO statement.


SEND <file> PRODOS

     Transmits <file> to a host computer using ProDOS Xmodem protocol.


SEND <file> TEXT

     Transmits <file> to a host computer using Ascii protocol using the
          previously defined prompt, line delay, and character delay.


SEND <file> XMODEM

     Transmits <file> to a host computer using Xmodem protocol.


SEND <file> YMODEM

     Transmits <file> to a host computer using Ymodem protocol.


SET APPEND ON
SET APPEND OFF

     This determines whether automatic buffer saves are appended to the
          original autosave file.  The default is SET APPEND OFF which
          means that when each buffer save is done, a new autosave file
          is created with a higher number appended to the end of the
          file name.  This limits you to 10 autosave files of about 16K each.
          If you SET APPEND ON then all buffer saves will be appended to the
          end of the current autosave file creating a single large file.


SET AUTOSAVE <file>

     This sets a new autosave file.  The <file> name should be at least 3
          characters in length.


SET BAUD 300
SET BAUD 1200
SET BAUD 2400
SET BAUD 4800
SET BAUD 9600
SET BAUD 19200

     Sets the Baud rate as indicated.


SET BINARY2 AUTO
SET BINARY2 MANUAL

     AUTO is the default.  This determines whether TIC will automatically
unpack Binary II files as they are downloaded.


SET BUFFER AUTO
SET BUFFER MANUAL

     AUTO is the default.  This determines whether TIC will automatically turn
its copy buffer on and off upon receipt of the Control-R and Control-T signals
from the host.  To disable this feature, use the SET BUFFER MANUAL statement
within a command file.


SET CDELAY <0-9>
SET LDELAY <0-9>

     Sets the Character or Line delay timer for Text file uploads.  These
          settings default to 0 if you do not set them and remain set until you
          reset them or re-run TIC.

SET DFORMAT 8N1
SET DFORMAT 7E1
SET DFORMAT 7O1
SET DFORMAT 7E2
SET DFORMAT 7O2

     Sets the data bits, parity, and stop bits for the serial port.


SET DUPLEX FULL
SET DUPLEX HALF
SET DUPLEX CHAT

     Sets Duplex to full, half, or chat for terminal mode.


SET ECHO ON
SET ECHO OFF

     Enables or disables the display of Command file statements as they
          execute.  These statements are used primarily to debug Command files.


SET PADCR ON
SET PADCR OFF

     Enables or disables TIC adding a space character to blank lines during
          text mode uploads.  The default value is ON.


SET PORT SSC
SET PORT IIGS

     Sets the communications driver to Super Serial Card or IIgs internal port.
          This command overrides the initial card identification routine in
          TIC.


SET PREFIX <path>

     Sets the ProDOS prefix.


SET PROMPT <character>

     Sets the handshaking prompt for text uploads.


SET SLOT <1,2,4,5,6,7>

    Tells TIC where to find your Super Serial card (or clone) that you with to
use for the communications port.  Has no effect when used with an internal
port on the Apple IIgs since its port is fixed at slot 2.


SET TIMER <seconds>

     Sets the time limit for WAITFOR searches.


STOP

     The Command file is terminated if this command is encountered.   No error
          message is displayed.


VIEW <file>

     <file> is displayed to the CRT.


WAITFOR KEYBOARD

     Execution will pause until a key is pressed at the keyboard or until the
          time limit expires.  If time expires then FAILED becomes true and can
          be tested by the IF statement.


WAITFOR STRING <string>

     Execution will pause until <string> is received over the serial port or
          until the time limit expires.  If <string> is omitted then execution
          pauses until any character is received over the serial port.  Note
          that <string> may contain imbedded control characters just like the
          DISPLAY command.


WAITFOR TIME '00:00'

     Execution will pause until the specified time matches the ProDOS system
          time.  You should not use this command if you do not have a ProDOS
          compatible clock installed.  Note that the time string must be
          exactly 5 characters long and must be encoded in 24 hour format.


XMIT <string>

     The <string> is transmitted out the serial port.  Note that imbedded
          control characters may be encoded in <string> just like with the
          DISPLAY command.


Turbo Xmodem:
-------------

     Turbo Xmodem is a means of speeding up xmodem or ymodem downloads.
It works by pre-acknowledging incoming blocks of data to eliminate the
delay that slows down xmodem transfers between blocks of data.  On the
down side, a single data error will result in an aborted transfer.
In addition, you can only use this mode when downloading to a ram disk.
This file transfer protocol can speed up xmodem downloads by as much as
100% but has limited utility because of the limitations noted above.  It
is included by popular demand.
