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. The end.