Fresh Fish 2

home *** CD-ROM | disk | FTP | other *** search

/ Fresh Fish 2 / FFMCD02.bin / new / dev / asm / tbsource / shellterm / final / shellterm.doc < prev next >

Wrap

Text File | 1993-12-21 | 23.2 KB | 697 lines

27/05-93 ShellTerm V1.19 Updated: 05/08-92 - for version 1.01 - Preliminary docs Updated: 06/08-92 - for version 1.02 - Preliminary docs Updated: 08/08-92 - for version 1.03 - Almost finished docs Updated: 11/08-92 - for version 1.04 - Release version Updated: 14/08-92 - for version 1.05 - Bug fixes Updated: 28/08-92 - for version 1.06 - Additions and beta testing Updated: 30/08-92 - for version 1.07 - Additions and beta testing Updated: 04/09-92 - for version 1.08 - Additions Updated: 06/09-92 - for version 1.09 - Release 2 Updated: 20/10-92 - for version 1.10 - Bug fixes Updated: 13/11-92 - for version 1.11 - Private release Updated: 01/01-93 - for version 1.12 - Release 3 Updated: 02/01-93 - for version 1.13 - Additions Updated: 06/02-93 - for version 1.14 - Bug fixes Updated: 10/02-93 - for version 1.15 - Release 4. 'Feature' removed Updated: 24/03-93 - for version 1.16 - Release 5. Major bug fix Updated: 25/03-93 - for version 1.17 - Release 6. Additions Updated: 22/05-93 - for version 1.18 - Additions Updated: 27/05-93 - for version 1.19 - Release 7. Additions Copyright (C) Tomi Blinnikka 1993, All Rights Reserved. ^^^^^^^^^^^^^^^^^^^^ This program is SHAREWARE. This means that you can copy it and give it to all your friends, upload it to a BBS or include it in a PD-library (FISH etc.). BUT (!!!) if you use this program frequently you must pay $5 - $10. The other restrictions are: all of the files must be included in their original form without additions, deletions, or modifications of any kind and it IS NOT TO BE SOLD. THIS INCLUDES GERMAN PD DEALERS. If you wish to use this program for commercial purposes, you need written permission. The ShellTerm program is provided "AS IS" without warranty of any kind, and the author is not responsible for any damage this software may or may not do. TABLE OF CONTENTS ~~~~~~~~~~~~~~~~~ 1. What does it do? - Short description of what this program does and/or does not do. 2. What do you need? - A list of software/hardware needed. 3. Compatibility - A list of computers this program works on. 4. Setting up - Instructions on how to set up ShellTerm 5. How to run it - Instructions on starting the program and what arguments it takes. 6. Using ShellTerm - A short description of all functions 6.1 Main menu 6.2 Dialer menu 6.3 Preferences menu 6.4 Serial settings 6.5 Terminal settings 7. The phonebook - Explanation of the autodialer and phonebook. 8. Hints & tips - Hints & tips. Other programs to enhance using ShellTerm etc. 9. Problems - Possible problems you may run into. 10. Other interesting stuff 11. Error messages 12. Versions - A list of all versions. The newest first. 13. Future versions 14. Bugs - List of bugs found. 15. ShareWare fee - More information on the ShareWare fee. 16. Beta Testers - A list of beta testers. 17. 'Registered' users - A list of users that have payed the ShareWare fee. 18. Bug reports etc. - How to contact the author 1. WHAT DOES IT DO? ~~~~~~~~~~~~~~~~~~~ This is a simple terminal program that runs in a CLI/Shell window. Its primary use is with dumb terminals hooked up to an AUX-handler. This is the reason ShellTerm doesn't open a window or screen. It uses standard input and output. I use it as a substitute for JrComm (Copyright John P. Radigan) when I'm using my dumb terminal (it's next to my bed... that explains most of the stupid mistakes in these docs :) and want to call a BBS without having to get out of bed and walk over to my Amiga. 2. WHAT DO YOU NEED? ~~~~~~~~~~~~~~~~~~~~ You'll need an Amiga computer (see compatibility list), with Kickstart 2.04 (version 37 or higher). Basically you'll also want a HAYES compatible modem or some other piece of equipment connected to the device you specify. 3. COMPATIBILITY ~~~~~~~~~~~~~~~~ ShellTerm will work on any Commodore Amiga, running on Kickstart 2.04 or higher. This includes the following: A500(+), A600, A1000, A1200, A2000, A2500/20, A2500/30, A3000 (16 MHz or 25 Mhz model), A4000/40, A4000/30. The program SHOULD work on any upgrades (based on the Amiga Development Guidelines, see Amiga ROM Kernel Reference Manual (Release 2): Includes and Autodocs, introduction). ShellTerm works with all internal modems (I have a Supra 2400zi) and extra serial boards that support the normal device commands (I also have the A2232 serial board, but I missed a bug with it on versions under 1.16 :). 4. SETTING UP ~~~~~~~~~~~~~ Unpack the archive somewhere and copy the files wherever you wish, but the following is recommended: Filename Where to copy ===================================================================== ShellTerm C: WatchPort C: Scripts/ST S: Scripts/ShellTerm-StartUp S: ShellTerm.DOC Wherever (I use DOCS:) ShellTerm.DOC.info Wherever (I use DOCS:) CONTENTS Wherever CONTENTS.info Wherever CHANGES Wherever CHANGES.info Wherever If for some reason the flags of the files in the directory ShellTerm/Scripts are not '-s--rwed', set them with the command 'Protect ShellTerm/Scripts/#? SWERD'. 5. HOW TO RUN IT ~~~~~~~~~~~~~~~~ You can run the program from a CLI/SHELL/etc. but you can't hang an icon on it and start it from the Workbench. I decided to drop the Workbench startup code to make the program a little bit smaller. To run the program, enter the following into your CLI/SHELL/etc. 1> ShellTerm FROM [FILENAME] PORT [NAME] FROM specifies the prefs file to load and use. PORT specifies a name for the user port to open. See HINTS & TIPS 8. You cannot, however, redirect input to the program, i.e. ShellTerm <NIL: won't work. RUNning is also out of the question and will give the same error text as redirecting. Or then use the script in the scripts directory. It will take the following options: FROM [FILENAME] - Same as ShellTerm's SCREEN [SCREEN NAME] - A name for the screen to open (DEFAULT: ShellTerm Screen) DEPTH [SCREEN DEPTH] - The depth of the screen to open (DEFAULT: 1) WINDOW [WINDOW NAME] - A name for the Shell to open (DEFAULT: ShellTerm Window) PORT [NAME] - Same as ShellTerm's The ST script needs and uses a program called PSX, by Steve Tibbett, to open the public screen. You can change this to your favorite public screen manager if it allows you to specify the screen specifications from the command line. 6. USING SHELLTERM ~~~~~~~~~~~~~~~~~~ Once the program has been started, anything typed into the CLI/Shell will be sent to the selected device. If the device does not echo the characters, you will not see anything. Normally there is a modem at the end of the device and you will see whatever was typed. Try typing "AT <RETURN>". If it works, you'll receive an OK text from the modem. If however there was terminal hooked up, the characters should have appeared on its screen. If this didn't work, please check the device's parameters from the Preferences menu. Say the characters are messed up, try checking the serial speed. Pressing CTRL-P will show you the menus. The CTRL-P sequence is not sent over to the device. You will be displayed with the options available. Press the key enclosed in parenthesis to select an item. A short description of all items follows. 6.1 Main menu ~~~~~~~~~~~~~ Show statistics Shows how many bytes have been transferred to and from the device. Clear statistics Clears the "Bytes received/sent" counters. Send break Sends a break signal to the device. Send CTRL-P Sends CTRL-P to the device. It is not sent when the menus are entered. CTRL-P is DLE, decimal #16, hex $10, octal &020. Reset font Changes the CLI/Shell font to plain (no bold, underline, reverse etc.). Clear screen Clears the screen and returns back to terminal mode. Reset modem Resets the modem with the Hayes command "ATZ". Hangup line Hangs up line using the Hayes commands. Three plus signs (+) are sent first, followed by a delay of approx. 3 seconds, after which "ATH" is sent. Upload Starts the program you've specified as the uploader. Normally SZ. Download Starts the program you've specified as the downloader. Normally RZ. Dialer Goes to the phonebook and autodialer. Explained later. Preferences Allows you to change the communication parameters of the port and some terminal settings. These and other functions are described below. Open capture Asks for the filename for the capture. All input from the device will be copied to this capture file. If the file already exists, the new stuff will be appended. Close capture Closes the capture file. Program and author Displays some information on the program and information author. Quit Quits ShellTerm. Exit menus Exits the menus and returns "online". 6.2 Dialer menu ~~~~~~~~~~~~~~~ 0 - 9 These keys select or deselect entries 1 - 10. Relist entries Shows the entries (numbers) in the phonebook. Single dial Asks "Number to dial:". Enter the number you would like to dial. Dial list Dials the entries selected from the phonebook. Clear list Deselects all entries from list. All Selects all entries from list for dialing. Edit mode Enters edit mode. When this mode is on and an entry is selected, the number for this entry is asked. To turn it off, select a second time. Prefix Asks for the dial prefix. Main menu Goes back to the main menu. Exit menus Exits the menus and returns "online". 6.3 Preferences menu ~~~~~~~~~~~~~~~~~~~~ Serial settings Goes to the serial settings menu. Described below. Terminal settings Goes to the terminal settings menu. Described below. Reset settings Reset settings to defaults: 9600, 8N1, no translating and no BS & DEL swapping. View settings Shows the current settings. NOTE! These might be incorrect if a change of some item could not be made. Currently the device name and unit will show the device that couldn't be opened. Load prefs Loads the preferences and phonebook. Write prefs Saves the preferences and phonebook. Name prefsfile Names the file used with load and save. Upload program Asks for the external program that is to be run for uploads. Normally this is a program called SZ (as on *N*X machines). Download program Asks for the external program that is to be run for downloads. Normally this is a program called RZ (as on *N*X machines). Upload dir(ectory) The directory to CD to before uploads. If not found/specified the current directory will be used. Download dir(ectory) The directory to CD to before downloads. If not found/specified the current directory will be used. Assign CTRL-P With this, you can assign CTRL-P to any key. The ASCII code of the will be displayed in 'View settings'. When you have assigned CTRL-P to some key, you can send the CTRL-P sequence over to the device with the key you assigned. Main menu Goes back to the main menu. Exit menus Exits the menus and returns "online". 6.4 Terminal settings ~~~~~~~~~~~~~~~~~~~~~ CR translate, OUT Describes what to do every time a CR is to be sent. Asks "(N)one, (S)trip, (A)dd LF:". If 'None' is selected, a CR is sent. If 'Strip' is selected, nothing is sent. If 'Add LF' is selected a CR and an LF is sent. LF translate, OUT Describes what to do every time an LF is to be sent. Asks "(N)one, (S)trip, (A)dd CR:". If 'None' is selected, an LF is sent. If 'Strip' is selected, nothing is sent. If 'Add CR' is selected a CR and an LF is sent. CR translate, IN The same as "CR translate, OUT" except it affects characters coming from the device to the CLI/Shell. LF translate, IN The same as "LF translate, OUT" except it affects characters coming from the device to the CLI/Shell. Local echo Toggles local echo on/off. If enabled, everything typed into the CLI will be displayed. Default is off. Swap BS & DEL Swaps BackSpace and DELete, when they are entered into the CLI/Shell. Ansi mode When this is set on, the screen will be cleared before the menus are shown. Cursor remap Remaps the Amiga cursor keys as 'EMACS cursor keys'. I'm not sure if this totally true, since tcsh etc. also use these. But then again there might be an EMACS standard. Previous menu Goes to the previous menu, Preferences. Main menu Goes back to the main menu. Exit menus Exits the menus and returns "online". 6.5 Serial settings ~~~~~~~~~~~~~~~~~~~ Speed Pressing a key from 0 through 9 will change the speed used on the device. Possible speeds are: (1) 110 bps (2) 300 bps (3) 1200 bps (4) 2400 bps (5) 4800 bps (6) 9600 bps (7) 19 200 bps (8) 38 400 bps (9) 57 600 bps (0) 115 200 bps If someone REALLY REALLY REALLY (You get the point) needs it, I can change the code to ask for the baud/bps rate (I think you've guessed that you will have to pay the shareware fee to get this done.) Name and Unit Asks for the device name and unit. After they've been given, ShellTerm tries to open it. Re-open device This will close the device and try to re-open it. Set databits Toggles between 7 and 8 databits. Set stopbits Toggles between 1 and 2 stopbits. XON/XOFF Turns XON/XOFF handshaking on and off. NOT TESTED! Previous menu Goes to the previous menu, Preferences. Main menu Goes back to the main menu. Exit menus Exits the menus and returns "online". 7. THE PHONEBOOK ~~~~~~~~~~~~~~~~ ShellTerm has a phonebook and autodialer. The phonebook file is currently the same file as the preferences file (changed for version 1.06) 'S:ShellTerm.PREFS'. As of version (well, at least IN version) 1.06 the phonebook entries are entered with the program itself. Go to the autodialer and turn the edit mode on. Then select the entry you wish to edit/give the number to. When you're finished just turn of the edit mode and dial away. If you wish to save the phonebook, you'll have to go to the preferences menu and select 'Save prefs'. 8. HINTS & TIPS ~~~~~~~~~~~~~~~ 1. A scrollback buffer is available simply by using the Console Buffer program by William J. Fritz (CB is Copyright (c) 1990 by William J. Fritz). 2. If you use my RingDetect program see its docs to see how to quit the program from a script and how to restart it again after quitting ShellTerm. On a multi-user Amiga (like mine), each user can have their own prefs-file by simply making an alias in their '.login' file or the global '.login' file. You can use something like this: alias st $home/.strc Where 'st' will be the alias that starts ShellTerm, '$home' a variable to the users home directory and '.strc' the name of the prefs file. 3. To emulate 'Quiet' mode, simply enter the menus. 4. To do downloads / uploads use one of the RZ and SZ commands available. Different protocols are widely available. RZ and SZ are for ZModem transfers. 5. To use a *N*X, through modem or otherwise, use the ANSI termcap: set term = ansi setenv TERM ansi or tset ansi This way the Shell will display things correctly (including IRC!). It works at least on BSD systems. 6. To make sure the modem doesn't hang up if you quit ShellTerm for some purpose, set the modem to not hang up when DTR is dropped. 7. A program called WatchPort is included with the ShellTerm archive. Thanks go to Klaus Seistrup for this program. It will allow a script to wait for ShellTerm to quit before continuing. A short quote from him: ---Cut Here--- "Now, my plans for the port of ShellTerm is to use it as an identifier to decide when to return to TrapDoor again. I imagine something like this might do it: FKey "7:SPAWN \"Execute S:ShellTerm.launch\"" and the script S:ShellTerm.launch: NewShell CON:blah/blah/blah FROM S:ShellTerm.bat WatchPort ShellTerm_MyPort1 And S:ShellTerm.bat contains just one line: ShellTerm PORT=ShellTerm_MyPort1 " ---Cut Here--- He uses this combination with trapdoor. It is of course possible to use it with other programs that require waiting. See HINTS & TIPS 8. 8. To open ShellTerm on its own screen, open a public screen with your favorite public screen manager and use a script like the one included in this archive in the directory ShellTerm/Scripts. 9. PROBLEMS ~~~~~~~~~~~ The program reads and writes characters to and from the selected serial device. If however you have a BBS software, or any other program that uses the same device, most characters will go to the other program. You may not notice this if you go straight to the dialer and start dialing. I have often started to wonder what bug i've managed to get into the dialer when it won't recognize a busy... After some debugging I realized that half of the characters were going to another task! There will most likely be a problem with high speed modems. I doubt very much that ShellTerm will keep up with USRobotics (R) HST modems. I don't even want to think of the new V.FAST that's coming! 10. OTHER INTERESTING STUFF ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ShellTerm was written in assembler with the one and only Cygnus Editor. It was compiled with A68k and Blink. The size of the source code is ~63000 bytes, equalling ~3200 lines of code. It is lightly commented. The version number is bumped up every time I feel like it, which is usually when I get bored of adding things, have found a bug or feel like releasing the whole thing. 11. ERROR MESSAGES ~~~~~~~~~~~~~~~~~~ The ShellTerm program will display necessary error messages. I HATE PROGRAMS THAT DON'T TELL WHAT-THE-HELL IS GOING ON! That clear? If ShellTerm doesn't give any output, something is seriously wrong or I was lazy :). The only thing ShellTerm won't report is that it won't run on anything under 2.04. It will simply quit returning a failure number. 12. VERSIONS ~~~~~~~~~~~~ Version Size Date Description ---------------------------------------------------------------------- 1.19 22600 26/05/93 Added a version number to the prefs file. I also added some empty space so newer versions will load older prefs files until a radical change happens in it. Added some stuff to the docs. 1.18 22596 22/05/93 Added scripts to archive. Added XON/XOFF, but never tested it. Fixed the bug with setting parameters. Changed a lot of code that had to do with opening/closing devices, creating/ deleting Requests/MsgPorts. 1.17 21864 25/03/93 Added possibility to open a port with a specific name. It is specified when ShellTerm is run and not in the prefs file! This is to save the trouble of making separate prefs files for every application. 1.16 21736 24/03/93 Fixed a major bug in the routine that opens the device. ShellTerm should now work on multiple serial boards and maybe some other exotic devices. 1.15 21828 10/02/93 The dialer won't be in Edit mode if quit. Thus you won't accidentally erase an entry if you first quit the dialer (while in edit mode) and then come back to dial. 1.14 ~22000 06/02/93 Fixed a bug in the parser. Had to press <ENTER> twice if using CSH (I accidentally cleared the last byte of the CLI-args). 1.13 21808 02/01/93 Added 'Execute' option. 1.12 21668 01/01/93 Release 3. All bugs should be fixed. Should work on all machines, not sure about dnet. Changed the parser to stand up to Commodore's guidelines. 1.11 ~22000 13/11/92 Private registered copy. 1.10 ~22000 20/10/92 Added public ports. Bug fixes. 1.09 21632 06/09/92 Release 2. Docs checked. 1.08 ~22000 04/09/92 Added: Cursor remap. Minor optimization. 1.07 ~21000 30/08/92 Tried to get this version out as a release. Docs updated a bit more and added 'Hints & Tips'. Added: Upload/Download programs and dirs, capture file. 1.06 ~18000 28/08/92 Bugs fixed. The dialer should work, toggling between (data/stop)bits are shown correctly even if the operation fails, added a greater delay while dialing a list/single entry (at least my phone line couldn't keep up) Added: 'Send Break', preferences file, 'Swap BS & DEL', Phonebook entry editor, assigning of CTRL-P to a key. Docs updated. 1.05 16116 14/08/92 Bugs fixed: Send CTRL-P works now. 1.04 16116 11/08/92 Bugs fixed: Dialer now knows about NO CARRIER and dials after removing an entry. Added: Clear screen and Reset font. Release version. Forgot to check the docs :( 1.03 ~16000 08/08/92 Bugs fixed: Dialer should recognize the BUSY and CONNECT texts from the modem now. Minor optimization. The next version should be a release :) 1.02 ~17000 06/08/92 Bugs fixed: Input is now flushed on starting to prevent ugly things from happening when going into the menus and there has been options on the CMDline. Added: Preferences (local echo, speed CR/LF translating, data & stop bits) Minor optimization. 1.01 ~10000 05/08/92 A beta tester version, now with phonebook. 1.00 ???? 04/08/92 A simple version without many bugs and quite slow. 0.00a- ???? ??/??/92 Wrote the program basics and main routines. 0.99a 13. FUTURE VERSIONS ~~~~~~~~~~~~~~~~~~~ Future version will have the bug fixes for the bugs I haven't found and you have :). And if some really needs to use this with the dnet.device (as I've heard), mail me some info on it etc. I'll look into it myself if I find the time. I have also been pressed towards adding a VT100 emulation... This I'm afraid is not going to happen, at least yet... :(. A log for the dialer is also one idea I have. 14. BUGS ~~~~~~~~ ShellTerm has been run with enforcer and mungwall. It will be run with devmon as soon as I can find it again :). In other words, I haven't found any bugs, so this part in the docs is totally useless! :) 15. SHAREWARE FEE ~~~~~~~~~~~~~~~~~ As of version 1.04, ShellTerm is ShareWare. I am not asking for a huge amount of money so I hope I will get some response. The fee is only $5 to $10 (USD), or whatever that happens to make at the moment you're reading this, in german marks (DM). If you're from Finland a sum of 20 FIM to 50 FIM is great (Yeah, so what if I changed the $10 to $12 ? You Finnish guys don't have to pay so much for postage :). Any amount in Coca-Cola (TM) will also do. 16. BETA TESTERS ~~~~~~~~~~~~~~~~ Thank you all who beta tested ShellTerm. Thanks go to Radix (thank you for the Clear Screen and Reset font ideas), Forge, mlelstv, Arc, Jasper and jlaine and MKsa (for the Swap BS & DEL idea and the others i haven't implemented). If you wish to become a beta tester contact me at one of the addresses below. If a beta tester wishes to be anonymous or the opposite, wishes their full name to be listed, please let me know! 17. 'REGISTERED' USERS ~~~~~~~~~~~~~~~~~~~~~~ Anyone who pays will get their name here if they wish so. Klaus Seistrup -Paid with WatchPort 18. BUG REPORTS ETC... ~~~~~~~~~~~~~~~~~~~~~~ Please send donations, bug reports, and list of features you would like to have included in future versions to Tomi Blinnikka Syystie 10 00780 Helsinki FINLAND Contact me at the address above or on the following BBS: MITS +358-0-458 2066 (MITS - Microdata International Telecomm Service) MITS +358-0-458 2077 MITS +358-0-458 2088 (Sec. level 40 or higher ONLY) Email me at 'docbliny@mits.mdata.fi' or catch me on the #amiga conference on IRC! "...trademark of Xerox Corporations. Reading legal mush can turn your brain to guacamole! Epson is registered trademark of Epson America ..." -Amiga RKRM Includes & AutoDocs, fourth page. Tomi Blinnikka docbliny@mits.mdata.fi