Club Amiga de Montreal - CAM/CAM_CD_1.iso/files/602b.lha/Necromancer_v3.0/necromancer.doc

Text File | 1992-01-17 | 22KB | 588 lines

Necromancer V0.3  - Initial Beta Docs

iii    - Introduction and Copyright Notices

1.0    - Required files and libraries
  1.1     - Required Libraries and Devices
  1.2     - XPR Protocol Libraries
  1.3     - ReqTools Library

2.0    - Screen Display
  2.1     - The Status Line
  2.1     - The Status Box Icons

3.0    - Editing the Setup
  3.1     - Setting Default Directories
  3.2     - Setting the BREAK Character
  3.3     - Setting the Serial Port Parameters
  3.4     - Loading and Saving the Setup

4.0    - Macros
  4.1     - Editing a Macro List
    4.1.1  - Special Sequences
  4.2     - Loading and Saving Macros

5.0    - Colors

6.0    - Capturing Text

7.0    - The Review Buffer
  7.1     - Viewing the Review Buffer
  7.2     - Clearing the Review Buffer
  7.3     - Saving the Review Buffer

8.0    - File Transfers
  8.1     - Selecting a Protocol
  8.2     - Configuring a Protocol
  8.3     - Downloading Files
    8.3.1  - Auto-starting a Download
    8.3.2  - Aborting a Download
  8.4     - Uploading Files
    8.4.1  - Aborting an Upload

9.0    - The Phonebook
  9.1     - Editing the Phonebook
    9.1.1  - Moving Around in the Phonebook
    9.1.2  - Deleting Entries
    9.1.3  - Saving a PhoneBook
    9.1.4  - Loading a PhoneBook
    9.1.5  - Leaving Edit Mode
  9.2    - Auto-Dialing


Introduction and Copyright Notices

The programs and files in this distribution are freely distributable, but
are also Copyright (c) 1992 William Coleman except as noted below.  The
original archived file (unmodified) may be freely distributed as long as no
more than a nominal fee is charged to cover time and copying costs.

ReqTools is Copyrighted (C) 1991 Nico Francois.

The XPR format is Copyrighted (C) 1989 by W.G.J. Langeveld

Additional copyrights may be found in the XPR Libraries that are located in
the xpr directory of this distribution.


1.0  Required files and libraries

The only absolutly required file is Necromancer itself.  Some of the files
that are generated by Necromancer are:

    Necro.conf     (default setup info)
    Necro.macs     (default macros)
    Necro.fone     (default phonebook)

If these files exist in the current directory they will be loaded when
Necromancer loads.


1.1 Required Libraries and Devices

Any required Library must be in either Libs:, RAM:, or the startup directory.
The required libraries are:

    reqtools.library
    xpr???.library  (see below)

All devices must be in your DEVS: directory.  The required devices are:

    serial.device


1.2  XPR Protocol Libraries

The XPR protocol allows the user (that's you) to add new transfer protocols
to a program by simply placing an XPR library where the program can find it.
It also allows the programmer (that's me) from having to write the stupid
things.  There are currently XPR libraries for most of the popular protocols.

Any of the various XPR libraries can be used.  Necromancer must be able to
locate the XPR libraries at startup.  Some of the XPR libraries available are:

    xprascii.library
    xprkermit.library
    xprxmodem.library
    xprzmodem.library

DO NOT rename these libraries!!!  They must be in the standard name format
(xpr???.library) or Necromancer will not be able to recognize them. See
section 8 for more information.

A couple of the more popular XPR libraries can be found in the xpr directory
of this distribution.  The install script will copy these files to your LIBS:
directory for you or you can copy them over by hand if you wish.


1.3  ReqTools Library

The ReqTools Library is a set of Requester functions that Necromancer uses
display all of it's fileboxes, pallete requester, information boxes.  The
install script included in this distrubution will copy the proper file to
your LIBS: directory.  If you like to do things by hand simply copy
reqtools/rom20/reqtools.library or reqtools/rom13/reqtools.library (the
former if you have V2.0 ROMs and the latter for V1.3) to your LIBS:
directory.



2.0  Screen Display

The Necromancer screen is divided up into up to four areas:

 _______________________________________
| Necromancer Vx.x           [][] | <- Menu Bar
|---------------------------------------|
|                    |
|   Terminal Screen            |
|                    |
|    In chat mode 16 x 80        |
|        else 20 x 80        |
|                    |
|  (Necromancer always forces           |
|             the TOPAZ80 font). |
|                    |
|---------------------------------------|
| In chat mode this 3 x 80 area is used |
| for keyboard input.            |
|   _________________________________    |
|  |[ ] [ ] [ ] [ ]  [][][][][][][][]|    |
|  |          Status Box         |    |
|  |_________________________________|    |
-----------------------------------------


2.1  The Status Line

A typical status line looks like this:

 Local     8N1@2400  1234567 Free  .....................     Sun 08 Dec 16:24:00
  ^     ^^^^ ^     ^          ^              time/date
  |     |||| |     |          |
  |     |||| |     |          |__ Filename of open capture file.
  |     |||| |     |
  |     |||| |     |___ Amount of    free memory (total).
  |     |||| |
  |     |||| |_____________ Baud rate.
  |     ||||
  |     ||||_______________ RS232 handshake mode: @ = 3-wire, * = 7-wire.
  |     |||
  |     |||________________ # of stop bits (always 1).
  |     ||
  |     ||_________________ Parity: (N)one, (E)ven, (O)dd.
  |     |
  |     |__________________ Number of data bits (7 or 8).
  |
  |_________________________ Carrier state (Online or Local).


2.2  Status Box Icons

A number of gadgets are located in the Status Box:

  [ECHO]    - Toggles Local Echo on and off.  When Local Echo is on every
          character you type will be echoed back to the screen.

  [CHAT]    - Toggles Chat Mode on and off.

  [PAUSE]   - Sends an XOFF (CTRL-s) to the modem.

  [RESUME]  - Sends an XON (CTRL-q) to the modem.

  [BREAK]   - Sends either the current break character or, if the break
          character is zero, a True Break to the modem.

  [RETURN]  - Sends a Carriage Return to the modem.

  [F1]-[F0] - Clicking one of these gadgets is the same as pressing the
          corresponding Function Key (F0 is F10).

  [SH]        - Highlighting this gadget will 'shift' the Function Key gadgets,
          i.e. make them equivalent to shift-F1 ... shift-F10.



3.0  Editing your Setup

You can edit the serial port parameters and default directories by selecting
the EDIT SETUP option of the Project menu.  A window will open containing
various gadgets you can click on to change the parameters.  The CANCEL
gadget will abort the setup and the OK gadget use the new parameters.  Both
of these gadgets will close the window.


3.1  Setting Default Directories

The default directory gadgets will open a filebox from which you can choose
a directory.  The default directories are where Necromancer will look when
it is first loaded.


3.2  Setting the BREAK Character

The Break Character is the character that will be transmitted when the BREAK
Icon on the main screen is clicked.  It is used to cause whoever you are
connected with to abort an operation.  Most online services and bulletin
boards use a CTRL-c.  The input box on the edit screen requires the ASCII
number of the character so for a CTRL-c enter 3.

There may be cases where you need to send a True Break.  In these cases set
the character number to zero.


3.3 Setting the Serial Port Parameters

You can select the baud rate, parity, etc. by selecting the appropriate
gadget.  Note that at the present time Necromancer only supports one stop
bit.


3.4 Loading and Saving the Setup

When Necromancer is first loaded it will search for a setup file called
"Necro.conf".  If it finds this file it will load it in.  You can load in a
file with a different name at any time by selecting the LOAD gadget.  A
filebox will open requesting the name of the file to load.

You can also save a setup at any time and with any name by selecting the
SAVE gadget.  Again a filebox will open requesting the name of the file.
If you select an existing file it will be overwritten.    If you enter a
directory that does not exist another box will open asking you if the
directory should be created.

Note that the actual parameters will not be used by Necromancer until the OK
gadget is selected so you can make several different setups, save them to
different files, and then select the CANCEL gadget to close the window and
keep the parameters that you started with.



4.0  Macros

A macro is a collection of keystokes that will be transmitted over the modem
whenever you press one of the function keys or shift + function keys (i.e.
20 of 'em).  Clicking on a Function Key Icon is the same as pressing the
physical key.  Each macro can be up to 50 characters long.


4.1 Editing a Macro List

To edit a list of function keys select the MACROS option of the Project Menu.
A window will open with a string gadget for each macro.  To make changes
simply click on the box and type in the macro.    Note that the box is smaller
then the maximum length of a macro, the text will scroll in the box if it is
too long to fit.

Please note that the Macro Editor does not 'remember' the original macros,
both the OK and CANCEL gadgets do the same thing - close the window.  Always
save your macros to disk so that you can retrieve them if you make a mistake.


4.1.1 Special Sequences

There are certain special sequences that you can embed in the macro.  They
all begin with a `\' character:

    \b    - Linefeed
    \r    - Carriage Return
    \n    - Carriage Return
    \t    - TAB
    \f    - Form Feed (clear screen)
    \b    - Bell
    \?w - Wait (see below)

If you really want to put a `\' character in the macro just double it: `\\'.
Also any ASCII value from 1 to 26 may be included by entering the `^'
character followed by the corresponding letter (a = 1, b = 2, etc.).  For
example `^c' would place a CTRL-c (ASCII 3) in the macro.  If you wish to put
a `^' in the macro simply double it: `^^'.

The WAIT character does not actually send anything to the modem, it simply
tells Necromancer to pause for a bit.  The first character after the `\' must
be a number from 0 to 9.  0 = 1/2 second, 1 - 9 are that many seconds.    So
for example `\7w' tells Necromancer to wait for 7 seconds.  To wait for
longer then 9 seconds simply use more then one WAIT command.


4.2  Loading and Saving Macros

When Necromancer is first loaded it will search for a macro file called
"Necro.macs".  If it finds this file it will load it in.  You can load in a
file with a different name at any time by selecting the LOAD gadget.  A
filebox will open requesting the name of the file to load.

You can also save a set of macros at any time and with any name by selecting
the SAVE gadget.  Again a filebox will open requesting the name of the file.
If you select an existing file it will be overwritten.    If you enter a
directory that does not exist another box will open asking you if the
directory should be created.



5.0  Colors

Selecting the COLOR option of the Project Menu will open a small window that
allows you to modify the screen colors.  The current version of Necromancer
will not allow you to save the new colors.



6.0  Capturing Text

You can capture incoming text to a disk file at any time while online by
selecting the CAPTURE ON option of the Buffers Menu.  A filebox will open
asking for the name of the file to capture text to.  If you select an
existing file all new data will be appended to the end of the file.  If you
enter a directory that does not exist another box will open asking you if the
directory should be created. Once to file is open the name of the file will
be displayed on the status line to remind you that you are capturing text.

Once you have opened a capture file the SUSPEND option of the Buffers Menu
becomes active.  Selecting this option will halt the capturing of text but
will not close the file.  Simply selecting SUSPEND again will resume.

With a capture file open the CAPTURE ON menu option changes to CAPTURE OFF.
Selecting this option will close the capture file.



7.0  The Review Buffer

All incoming text is stored in a buffer called the Review Buffer.  Currently
this buffer will hold 80,000 characters or 3000 (80 character) lines, which-
ever comes first.  Once the buffer fills a line will be deleted from the top
of the buffer as each new line is received.


7.1  Viewing the Review Buffer

You can view the contents of this buffer by selecting the View Review option
of the Buffers Menu.  This will open a window and print the first screenful
of data (or as much as it can).

The Slider along the bottom of the window allows you to scroll around the
buffer.  Moving the slider to the right scrolls down and moving left scrolls
up.  Just remember that scrolling towards the Bottom gadget scrolls the text
toward the bottom of the buffer.

The Up and Down arrows scroll the screen up or down a single line.  If you
hold the mouse button down the scrolling will continue until you release the
button.

The Top and Bottom gadgets will move you directly to the top or bottom of the
buffer.


7.2  Clearing the Review Buffer

The entire contents of the buffer can be erased by selecting the Clear Review
option of the Buffers Menu.  You can erase the first line in the buffer by
opening the View Window (see section 7.1) and pressing the DEL key.


7.3  Saving the Review Buffer

You can save the contents of the review buffer by selecting the Save Review
option of Buffers Menu.  A filebox will open requesting the name of the file
to save to.  If you select an existing file it will be overwritten.  If you
enter a directory that does not exist another box will open asking you if the
directory should be created.



8.0  File Transfers

Necromancer uses XPR Libraries for all file transfers.    An XPR Library
implements a specific transfer protocol using a well defined, consistant
interface.  In other words two different XPR Libraries may implement two
totally different protocols but the routines they use to talk to the terminal
program are the same.  This allows you to add a new protocol to Necromancer
by simply placing a new XPR Library in your LIBS: directory.  Necromancer
fully supports all XPR libraries through version 2.0.


8.1  Selecting a Protocol

When Necromancer is booting it will search the following directories for XPR
Libraries (in this order): RAM:, LIBS:, the disk Necromancer was booted from.
Once it finds at least one library it will not search any further so all of
the libraries you wish to use must be in the same directory.  AT LEAST ONE
XPR LIBRARY MUST BE AVAILABLE OR NECROMANCER WILL ABORT!

Once the list of available libraries has been made it will be copied into the
Protocol Menu.    Then either xprzmodem.library or, if that one doesn't exist,
the first library on the list will be opened and initialized.  When you look
at the Protocol menu the active protocol will have a checkmark next to it.
Selecting a different protocol will close the current one and open the one
you selected.


8.2  Configuring a Protocol

You can configure a protocol in one of two ways.  The first it to use an ENV
string (ala the setenv command).  Read the documentation that comes with the
library for the proper syntax; each library is different.  Necromancer will
automatically search for the proper ENV string and pass it to the library
when it is opened.

The second method of configuring a protocol is to select the Configure option
of the Protocol Menu.  A requester will open allowing you to set the various
options.  What those options will be is wholly dependent on the protocol.
Some options require you to enter a string, some a number, and others simply
a YES/NO response.  Read the documentation that comes with the library.


8.3  Downloading Files

To begin a download simply make sure the host is ready and select the
Download option of the Transfer Menu.  Some protocols will get the filename
from the host, others require you to select a filename.  In the latter case
a filebox will open requesting the name of the file.  The filebox will open
into the default Download Directory.  If you select an existing file it will
be overwritten.  If you enter a directory that does not exist another box
will open asking you if the directory should be created.

Once the tranfser starts a status box will open to keep you informed of the
progress of the transfer.  The fields in this box are self-explainatory.
Not all of the fields may be used by the protocol you are using.


8.3.1  Auto-starting a Download

Some protocols allow the host to initiate the download.  This feature is
fully implemented by Necromancer.  One thing to keep in mind is that the
default Download Directory will *not* work in this case because the XPR
Library doesn't tell Necromancer to start a download, it simply starts the
download itself.  In this case the path used is set during configuration of
the protocol (see section 8.2).


8.3.2  Aborting a Download

You can abort a transfer by either pressing the ESCape key or by clicking
on the Close Window gadget of the Status Box.  It may take several seconds
for the abort to register depending on the protocol.


8.4  Uploading Files

To begin an upload simply make sure the host is ready and select the
Upload option of the Transfer Menu.  A filebox will open requesting the name
of the file to upload.    The filebox will open into the default Upload
Directory.

Once the tranfser starts a status box will open to keep you informed of the
progress of the transfer.  The fields in this box are self-explainatory.
Not all of the fields may be used by the protocol you are using.


8.4.1  Aborting an Upload

You can abort a transfer by either pressing the ESCape key or by clicking
on the Close Window gadget of the Status Box.  It may take several seconds
for the abort to register depending on the protocol.



9.0  The Phonebook

The Necromancer phonebook consists of up to 15 entries.  Each entry is made
up of a name, a remark, modem parameters, and of course the phone number
itself.  You can auto-dial from one to all of entries.    If you select more
then one number, each number will be dialed in turn until either one of them
connects or you abort.    The phonebook can be saved to disk so if you need
more then 15 numbers you can save them in different files and load themn in
as needed.


9.1  Editing the Phonebook

To edit the phonebook select the Edit Phonebook option of the FoneBook Menu.
A window will open and display the first entry.  On the right side of the
window are gadgets that are identical to the ones used to set modem
parameters in the Edit Setup window (see section 3.0).  On the left side of
the window are three string gadgets containing the name, comment, and phone
number strings.

The name string is the text that will show up on the FoneBook Menu for this
item (see section 9.2).  This field is mandatory.

The remark string will be displayed during Auto-Dial.  This field is totally
optional, you can leave it blank if you wish.

The phone number string is (of course) mandatory.  This string will be sent
verbatim to the modem to dial the number.  Note that Necromancer will prepend
'ATD' to the beginning of the string so don't add it yourself.  For example
to tone dial the number '555-1234' from a PBX that requires you to dial '9'
to get an outside line the command would be 'ATDT9,,555-1234'.  In the string
field you would enter 'T9,,555-1234'.


9.1.1  Moving Around in the Phonebook

The NEXT and PREV gadgets are used to step through the entries.  You will not
be allowed to leave the current entry if the Name and/or Phone number fields
are blank.  The only exception is that you can select PREV if you are on the
last (defined) entry.  In other words blank entries can not be embedded in
the phonebook.

The equivelent of a NEXT is perform when you press RETURN while editing the
phone number string (assuming the name and phone numbers strings are not
empty).  So the quickest way to add entries is to select the serial
parameters first and then enter the name, remark, and phone number strings.


9.1.2  Deleting Entries

You can delete the current entry by selecting the DELETE gadget.  A requester
will open asking you if you are sure that you want to delete the entry.  If
you say yes the entry is history so make sure that's what you wish to do.


9.1.3  Saving a PhoneBook

You can save the Phonebook by clicking on the SAVE gadget.  A filebox will
open requesting the name of the file to save to.  If you select an existing
file it will be overwritten.  If you enter a directory that does not exist
another box will open asking you if the directory should be created.


9.1.4  Loading a PhoneBook

When Necromancer is first loaded it will search for a macro file called
"Necro.fone".  If it finds this file it will load it in.  You can load in a
phonebook with a different name at any time by selecting the LOAD gadget.  A
filebox will open requesting the name of the phonebook to load.  Note that
all Necromancer phonebook filenames should end with '.fone'.


9.1.5  Leaving Edit Mode

When you are done editing the phonebook simply click on the OK gadget.    This
will remove the edit window and update the FoneBook menu.


9.2  Auto-Dialing

To dial one or more numbers simply pull down the FoneBook Menu and select the
numbers that you wish to dial.    If you select a number by accident simply
select it again to remove the checkmark.  Once you have all of the numbers
that you wish to dial selected just click on the Dial Number(s) option.

Once dialing begins a window will open that displays the name of the number
being dialed, the remark associated with the number and the time remaining.
When the time remaining reaches zero Necromancer will hang up and move to the
next number on the list (or retry the current number if you only selected a
single number.

The SKIP gadget will abort the current number and move on (as if the timer
had reached zero).  It will *not* remove the number from the list.

To remove a number permanently simple click on the (surprize!) REMOVE gadget.
If you remove the last remaining number from the list dialing will be
aborted.

To abort dialing click on either the ABORT or Close Window gadget.