Amiga Elysian Archive

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

/ Amiga Elysian Archive / AmigaElysianArchive.iso / prog / utils / sercli.shr / sercli / doc / sercli.doc < prev next >

Wrap

Text File | 1993-06-16 | 30.4 KB | 773 lines

COPYRIGHT & DISTRIBUTION sercli (an Amiga .device <-> FIFO interface tool) Copyright (C) 1993 Richard Rauch This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. The author may be reached via email as `Richard Rauch @ 1:280/304.3'. Using paper mail, `Richard Rauch, 11415 Grant Drive, Overland Park KS 66210'. There are no known copyright or patent inringements by this archive. Note that as of this writing, I consider sercli significantly far from complete. For this reason, I think that to wantonly distribute it would be a waste of storage space on BBSses and may leave an undue bad taste in some people's mouths...so I would appreciate limited distribution (that doesn't mean you _can't_ spread it, just that I don't expect it, and wouldn't spread it myself, at this point). Amiga(tm) is a registered trademark of Commodore-Amiga. ARexx is a trademark of William S. Hawes. Aztec is probably a trademark of Manx DICE is a trademark of Matt Dillon. SAS is alegedly a trademark of SAS DISCLAIMER An attempt has been made to be accurate, helpful, thorough, understandable, and useful, in preparing the software and documentation. If I succeeded, that is good. If not, you got what you paid for. I accept no responsibility for what you do with this information/software. As the end user, you must accept full resonsibility for deciding if this archive is safe or useful. Essentially, any authoritative statement made in here should be taken with an implicit crystal of NaCl. I am not aware of any patent or copyright infringements through the provided information (software and documentation). "I probably don't know what I'm talking about." ---rkr. If you are already familiar with sercli: See the file, "changes.text," for an overview of the update. It's changing slowly...for a long time I had little real direction for it; now that I have a _use_ for sercli, I am meandering around trying to locate a problem with the FIFO interface. Thus the RCS files are large, and sercli has features it doesn't really need. C'est la vi. ============= What IS this thing? This is the documentation for sercli, a program that is able to a shell through the serial port. To be more precise, it establishes a link between Dillon's FIFO and any serial-like Amiga .device. Dillon's FIFO must be present, as must serial.device (or some other appropriate .device). `Serial-like' means that it is intended to work with an Amiga .device that is written to look & act like the standard Amiga serial.device. I have only tested it with the standard serial.device and with my own nulser.device; it should work with CBM's multi-serial board, internal modems, etc., but I have never used such devices. It probably would NOT work with the parallel.device (though there is great similarity), or most other .devices. Normally, you would want only ONE sercli running per serial port (at the maximum); sercli and FIFO are flexible enough to let you do this, though you must specify a unique name for each such port -- this is BOTH the FIFO id and the name for an ARexx port opened by sercli. The sercli binary should be Pure -- i.e., you can make it Resident (I've not tested this, mostly because I only run one copy of it & besides, I am changing it often enough that a Resident copy would be more annoying than useful). For information on the FIFO side, and FIFO's features, see Matt Dillon's FIFO software. Using sercli's ARexx port, you can change MOST of sercli's configuration on-the-fly. The ARexx port does not support serial i/o operation at this time; some obvious enhancements to the ARexx interface could stand to be made, but I first intend to fix its problems with trying to cause FIFO to generate an EOF event. sercli is more of a TOOL than an application. It is intended to give easier access to the serial port for languages like AmigaBASIC, ARexx, and XLisp, which otherwise have limited (or non-existant) access to the serial port. Control is achieved via a config file, and then by using FIFO: to talk to sercli (and thence to the serial port) as if to a CON:, NewCON:, or RAW: window. What do you need in order to use sercli? You mean, besides an Amiga? *grin* You will need FIFO: in order to use sercli. (look for fifodv32.lzh or so) ARexx is strongly recommended, though not absolutely necessary in theory; I've never tested it in an ARexxless system. A technical bent (if not necessarily competance...*grin*) and a grasp of such terms as stdio, shell scripts, and stdio redirection ARE probably a necessity. How do you set sercli up? sercli is run from the a CLI or Shell. You will almost certainly need to write a config file (or modify an existing config file; at least one should be included in this archive). At a minimum, you will probably have to specifiy a bps value (see `bps' in the config docs below). If you run multiple copies of sercli at once, each will need a unique id tag as well (see `id' below). If you will be running multiple copies of sercli at once, try making sercli Resident (sercli is small, but it does take some space). When running the sercli program, it receives 1 (optional) command line argument: the name of a config file to use. If no such name is given, then sercli will use a default name of `sercli_config' in the current directory. sercli should NOT be launched from the WorkBench. As I've compiled it with DICE, sercli should simly exit harmlessly if you try to run it from the WB. (If you are a programmer who cares about making it run from the WB, and if you have DICE, then adding WB support should be trivial. Personally, I don't like WB & won't waste my time supporting it -- and I've used v1.1, v1.2, v1.3, and v2.1 of WB, so when I say I don't like it, you can be assured that I know whereof I speak.) Examples of starting sercli and where sercli will look for config info: sercli Look for `sercli_config' in CURRENT dir sercli /another_dir/custom_sercli_config Look for /another_dir/custom_sercli_config foo:bar/sercli Look for `sercli_config' in CURRENT dir The sercli config file: The config file should consist solely of config statements & comments. Config statements are defined by the form <keyword>':' <0 or more associated values> E.g.: bps: 1200 exclusive: NOTE: The keyword must be the _first_ thing on the line (NO LEADING SPACES); I've indented the keywords in this document to set them off clearly from the rest of the text. Keywords MUST also be immediately followed by the colon (no trailing spaces. Similarly, any embedded spaces _must_ be spaces (some text editors may try to use tabs for spaces wherever possible; conceivably, this could be a problem). Anything following the colon is assumed to be "parameter(s)" for the keyword. If more data follow the colon than the keyword needs, the excess will be ignored (not flagged as an error). NOTE: I used all lower case for the keywords for the sake of readability; sercli does not care if you use upper or lower case, though, or if you mix'n'match. Whatever grabs you. Later ALL keywords will be given in a complete list of all keywords supported by serlcli (config and ARexx) describing what they do, what paramters they take, and whether they are config or ARexx keywords. (See the section "What are these keywords", below). The keywords valid ONLY in the CONFIG FILES are: id device name device unit bps bits sbits 7wire 3wire xon/xoff no xon/xoff shared exclusive no rad boogie rad boogie no parity odd parity even parity window title window size alert ser alert loc no alert ser no alert loc COMMENTS are presently defined as any line BEGINNING with any of the following characters: <Nul>, <Space>, <Tab>, <Line Feed>, <Vertical Tab>, <Carriage Return>, '*', '#', ';', ':' The nice thing about this rather loose definition, is that it covers blank lines, lines with plain text (as long as they are indented), and common comment delimiters from assembly, LISP, and makefiles; the <VERTICAL TAB> is an anomoly that I don't remember the reasoning for, and the <NUL> shouldn't be appearing in plain text files, but is appropriate for internal reasons. Once I've got it going, what do I do? Once sercli is going, you can use it & FIFO to allow any Shell program to talk to the serial port. If you have a dumb terminal, or an already-going connection to someone over a modem, or a null-modem to another computer, you could just launch a new shell through the FIFO (see FIFO docs). Of course, you can also do more or less the same thing with the standard AUX: device, except that AUX: is not able to be configured at start-up, nor does it have an ARexx port, or a window. *grin* Also, AUX: does not seem to work quite correctly; last I tried it (under OS v1.3), the remote guy was able to run one command, then crash my system. Nice idea, Commodore, but you need to make these things _work_. Also, AUX: is only for the built-in serial.device... I also suggest extreme care in the way you talk to your modem. If your modem is configured to echo data sent to it in `command mode', and if you set FIFO up to echo data back as well, you can get feedback between FIFO and the modem, each echoing anything the other says; having done this with the AUX: device, I can tell you that you don't want to do this! (AUX: crashed when this happened to me.) There are two ways to get around this: Configure your modem to NOT echo data in command mode. Set FIFO to not echo data sent to it. The latter is probably the more desirable. In the bin directory of this archive, you will find two commands. One is called set_raw, and the other set_con. When you run set_raw from a Shell CON: window, it will put that window into `DOS RAW' mode (for lack of a better term). In this mode, several things will be differet: You cannot see what you type. This is GOOD; echo has been turned off; if you arrange for the program to run in the context of a FIFO, it will set that FIFO stream to RAW mode. All line-editing is gone. This can be viewed as good or bad. If you type a partial command, feel that you hit a wrong key, and try to back-space, then ^H (back-space) characters will be _stored_ as part of the command you were typing. This can be good or bad, depending. Generally, it's bad. The <Return> key will now not work quite as it should. To terminate a command in RAW mode, you must send a <Ctrl>-<J> (^J character). In order to get back to the normal `cooked' mode, do the following: hit ^J (to make sure you are starting a new command line) type the word set_con ...if you make ANY mistakes, hit ^J and start again. hit ^J again (to end this command) set_raw/set_con can be useful in some scripts (particularly in scripts that use FIFO/sercli to talk to your modem). I have also found them useful for other programs that normally require RAW: windows. E.g., XLisp and an old Conquest game both opened custom RAW: windows; with a quick patch to make them use * rather than RAW:..., and then running them in a script of the form: set_raw <command> set_con ...the programs would run from the same CLI/Shell window as was used to invoke them -- which incidentally means that they could be run over FIFO, through sercli, to your modem, and out into the real world for remote users to play with. With FIFO you might be able to turn off one of the FIFO flags (`c' for cooked, I think) in order to simply not have a cooked stream. This would have a similar effect to using set_raw, but I don't think it's reversable... Now, you have ONE last problem: When you use NewShell or NewCLI to create a new CLI/Shell process, you will get a little banner text as the first line on the new window: New Shell process <N> ...where <N> is the CLI Process number. Since the Shell has just started, it's probably in cooked mode. That banner gets sent out to the serial port, then echoed back, then echoed back, then echoed back, then echoed back... OUCH! To solve this, I suggest another little util of mine: rlaunch. In effect, rlaunch is a NewCLI command that: Does not print a `New Shell process <N>' banner. Does not have a default command/script to execute on startup. Lets you execute ANY or NO command (not just a script) on startup. Lets you wait on completion of the new Process. If you view the last one as a problem (which is reasonable; if you create a new process, you generally _don't_ want to wait on it to finish), then you can simply Run rlaunch. Poof, no problem. rlaunch takes EXACTLY TWO parameters: A name of a stream through which to run a command, and a command to execute. Pass an empty string ("") for the command if you want to do nothing in particular when starting up. The following commands are essentially synonymous: newshell fifo:sercli/rwkecs run rlaunch fifo:sercli/rwekcs "execute s:shell-startup" The only difference is that the `New Shell process <N>' banner is omitted. Substitute an alternate script (`sercl-startup', say, which perhaps calls `set_raw'), and you are no longer in danger getting stuck in a feedback loop. PROBABLY, any script you run through sercli should end with an `EndCLI' or `EndShell'. ARexx support? ARexx commands may be sent to sercli. The name of the ARexx message port is determined by the config file. If no such id string is placed in the config file, a default value is used. ARexx commands to sercli are exactly the same as config file lines, except that the words "config file line" should be replaced with "sercli ARexx command." Additionally, some config keywords are not valid as ARexx commands and vice versa, though the two mostly overlap. Lastly, some ARexx commands return values. The following ARexx commands are acknowledged (see the "How do you set sercli up?" (above) and "What are these keywords?" (below) sections for more info): bps bits sbits 7wire 3wire xon/xoff no xon/xoff shared exclusive no rad boogie rad boogie no parity odd parity even parity window title window size alert ser alert loc no alert ser no alert loc What are these keywords? Except where otherwise marked, all keywords are valid regarless of where they are received from (ARexx or config file). Some keywords are flags that engage a certain mode in sercli. If this is so, then there exist counter/matching keyword(s) to change sercli back (or sometimes to another state). For convenience, such "related" keywords are listed together as if a single keyword. Note that, where a parameter is listed, it is _required_. By saying "default" values exist, I mean if the value is never overridden by a config or ARexx specification, that the "default" is used. A malformed control (command or config) will generate an error message, but will otherwise be ignored. Numeric parameters may be entered in C notation. I.e., plain decimal digits will be interpreted as normal base-10 (decimal) numbers; if the number begins with a `0' followed by digit in the rainge `0'-`7', it will be interpreted as a base-8 (octal) number; if it begins with a `0' followed by a `x' or `X', it will be interpreted as a base-16 (hexadecimal) number. If multiple, CONFLICTING controls are given in a sequence, each overrides its predecessor. Other details may vary according to what serial port you are using (I am only familiar with the built-in one and a software null modem of my own devising). id (CONFIG only) id: <string> <string> becomes a rendevous(sp) point for FIFO: usage and ARexx message ports. DEFAULT: value is "sercli" (without the quotes, but _lower_case_). device name (CONFIG only) device name: <some.device> <some.device> is the name of the device that is to be used for i/o. User "serial.device" for the built-in serial port. DEFAULT: "serial.device". device unit (CONFIG only) device unit: <number> <number> is the unit number of the device to be used. Use 0 or 1 for the built-in serial port. With my nulser.device, 0 for `first suitable', or else a 1 or a 2. DEFAULT: 0. bps bps: <number> <number> is the Bits Per Second. Often this goes under the name "baud" (but sercli only responds to "bps"; "baud" is foreign to sercli). Actual _bytes_/second should be about 1/10th the bps setting. DEFAULT: 0 (this may result in an error, or in a default setting; dunno & haven't toyed with it.) bits bits: <number> <number> is how many bits per byte; generally should be 7 or 8. NOTE: This value corresponds to _both_ read bits and write bits, which are seperate under Preferences; sercli canNOT seperately set these. DEFAULT: 8 sbits sbits: <number> Stop bits per byte; generally should be 1 or 2. DEFAULT: 1 7wire 3wire 7wire: 3wire: These turn on/off RTS/CTS (hardware) serial handshaking. In order to conduct serial communications, you have at least 3 wires (transmit data, receive data, and a ground). Data are sent in bursts of one "byte", delimited by stop-bits/start-bits, perhaps with a parity bit. Because of this linear communication (one bit at a time), this is called "serial" communication. By using additional wires (run in parallel), the data flow can be controlled. In particular, Request To Send/Clear To Send connections are used (RTS/CTS). This should prevent the other end from sending us too much information when our input buffer is full (and vice versa). It is possible, however, that such additional control flow will affect performance. (I dunno; I don't have much practical high-speed experience. If you _do_ get close enough to the limits of the serial port's throughput that 3wire/7wire makes a difference, I would think that you are running dangerously close to losing data if you go with 3wire, especially if your system may be put under varying work-loads by other programs you run (can you say "ray-trace?").) DEFAULT: 3wire xon/xoff no xon/xoff xon/xoff: no xon/xoff: These turn on/off XON/XOFF flow controls. In a situation where you only have 3wire as an option, due to the nature of the remote end, XON/XOFF may save you, in a manner similar to RTS/CTS. XON/XOFF differs from RTS/CTS control in that XON/XOFF uses special control characters (EMBEDDED in the byte-stream) rather than seperate hardware lines. XON/XOFF can conflict with binary file transfers (e.g., sending a .lzh file via ZModem). DEFAULT: no xon/xoff shared exclusive shared: exclusive: In shared mode, sercli can share the same serial device/unit with other applications (such as terminal software or BBSses), provided that said applications also use shared mode. If shared mode is not supported by the others, you will have to arrange that the others be at least "disconnected," if not shut down altogether. NOTE: sercli doesn't fully understand sharing. It will (currently) try to keep it's fingers in the pie (serial port) all the time that it is operational. Because of the nature of the serial port in shared mode, sercli will get pieces of the input, while other programs will also get pieces (assuming that the other "sharing" programs are trying to be active as well). This IS something I intend to fix. So, in a sense, sercli can share, and in a sense it can't. DEFAULT: shared no rad boogie rad boogie no rad boogie: rad boogie: The ROM Kernal Ref. describes "rad boogie" as (to paraphrase) a mode that turns off several checks in order to perform faster. I do _not_ suggest using this mode lightly. Partly I am this way since I haven't had the opportunity to test it, and because turning off checking may lead to more trouble than help, as I suggested with 3wire vs 7wire mode above. This feature is offered because it was easy, and may be of some use. I suggest you read the RKMs to find out what rad boogie does (or read your serial device's manual/contact the manufacturer, if you're not using the built-in port)...or simply not use it until well exapserated. DEFAULT: no rad boogie no parity odd parity even parity no parity: odd parity: even parity: When data is sent one bit at a time, it is possible to sum the list of bits (each bit a 1 or a 0). The resulting sum will be either even or odd. Isn't that just amazing? With parity on (odd parity OR even parity), an additional bit (the Parity bit!) is sent with each byte (along with the 7 or 8 data bits and the 1 or 2 stop bits). Depending on whether the sum is odd or is even, and depending on whether odd or even parity is selected, the Parity bit will be set to 1 or 0, in order to make the whole come out as an odd or even sum. The parity bit is allegedly used to help detect errors in transmission. Whether to use Even or Odd Parity, depends on the conventions of the system you are connecting to (neither is any better than the other). Usually, one just uses NO parity. DEFAULT: no parity window title (ARexx only) window title: Calling SomeBBS "window title" is a MISNOMER; it really only sets the content of a string within the window title, not the whole title. RETURNS: The _entire_ (currently) old title is returned. DEFAULT: no user window size (ARexx only) window size: 640 10 Sets the size of the window that sercli keeps while running. RETURNS: The old window size. DEFAULT: computed according to initial text dimensions. alert ser alert loc no alert ser no alert loc alert ser: alert loc: no alert ser: no alert loc: A couple of "alert" messages were put into sercli when it was first written. (E.g., when exiting, a little blurb should be printed on both the Shell window and through the serial port.) Different blurbs are sent to the serial & parent shell. The keywords aren't very well matched to their effect... Don't turn on `alert ser' from the config file unless you are sure you won't get stuck in a feedback situation. The "loc" forms were more for symetry with the "ser" forms than out of major value. More "alert" type stuff may be added later. Possibly a gradation of priority/significance will be used (so instead of an on/off value for alerting ser/loc, you'd have a rating). The alert ser/loc settings are INDEPENDANT of one another. DEFAULTS: no alert ser alert loc Errors. Well, let's see... Detected errors are handled in one of three ways: sercli aborts (completely exits) This is what happens if any failure occurs while allocating some resource. Most errors should result in enough info being produced that you can find out what went wrong. A missing (or mis-named) config file being an exception (sercli will quitely use the internal defaults -- I should pro'ly fix that to at least emit a warning, _esp._ if a name was explicitly given the file could not be opened). Another exception is if the ARexx port cannot be set up, or if some allocation error occurs with the .device. However, these should mostly occur only if you are extremely low on RAM. sercli ignores the error The only error in this class that I know of off-hand is where the FIFO 4k buffer can be over-filled; the proper way of handling that is start an asynch FIFO write request and block further .device reads until the FIFO write request is replied. Failing to this is not very harmful (data from the .device can be lost this way, in theory), and this should eventually be patched up. Nothing generally fatal is ignored to my knowledge. sercli produces a notification & continues on its merry way Once the .device has been opened up, and errors that are reported will be printed to the program's standard output (generally, the Shell stream from which the program was launched). Additionally, bad config lines & bad ARexx commands will be handled this way. Bad config line error messages should include the line-number & line-content. For now, make SURE that you have spaces in the command/config, rather than TAB characters; sercli can be a little picky about this stuff. Where's sercli going? See the file `ToDo' for a longish list. As I write this, I'm fighting with making sercli generate proper EOF events when the user hits ^\ or hangs up. Part of my problem seems to lie somewhere in my code (I dunno where!), and part of it is a design flaw in FIFO. If I could find _my_ problem, I could live with the design flaw for a while. Programmer stuff. I'm about tapped out, I think, so I'll try to be brief. There is [or was] a monstrosity in serial.c/serial.h that needs to be fixed up (a horrible name; I wrote most of serial.c last spring, and when I came back to it this fall, I was totally stumped at what I'd wrought...*grin*). If you can help it, stay away from there. Comments in the code are relatively sparse (hey, go read one of the "Real programmers..." text files, eh?). Since I consider this a ways away from being "done," I'm not too worried about the comments. The following pieces should be, to one degree or another, fairly seperable from the project: serial.c (handles serial i/o) errors.c (handles error events) rexx.c (handles ARexx messages) misc.c (handles some misc. stuff) config.c (handles matching text to defined keywords) Some (ahem) of it is not as general as it could be (rexx.c has some sercli-specific stuff in it, errors.c is not really _implemented_ generally, but could be re-implemented with linked lists for pretty complete generality, and serial.c, is still lacking some things & using globals (yech, ptui, right? *e-vile grin*) ), but it all works. Compiling I use DICE v2.06.34 [.40 later I think, and now v2.07.54]. The dmakefile I use is included with the source. I think it was at one time compilable with Aztec, but I don't remember for certain & very much doubt it will compile under Aztec now. For other compilers, note particularly that I rely on DICE's autoinit feature, which opens the .libraries I need (like rexxsyslib.library (redundant name!) ) automatically. SAS and Aztec C will need to manually do several OpenLibrary() calls and check for failure, plus mirror with CloseLibrary() on exit. DICE also supports (as an option) BCPL(?)/C++ style line-comments (// to start the comment, EOL to end it). The source may at any given time be lightly sprinkled with these, as they are a little handier than block-comments for `hiding' old code. I also use the ANSI atexit() to set up a cleanup function; Aztec has atexit(), but apparently it has not been in SAS until fairly recently (something about a special "ANSI library upgrade," I've read about), and the SAS version is still not really compliant, according to someone on Usenet (I dunno who, sorry). I also use the _non-ANSI onbreak() function (I'm not very clear if SAS supports this, but I'm pretty sure it's not in Aztec). Since I ONLY use this to turn off ^C aborting, you should find it fairly easy to achieve the same net effect with your favorite compiler. RCS (src/rcs/#?,v) files: These are maintained by doing a `ci -l <filename>' command. Given the RCS files, you should be able to produce any version of sercli since v1.5. A dmake target also exists to catch `strays'. A dmake target also exists to assign a symbolic name to the most recent version of each of the sercli sources. Symbolic names are of the form `sercli_v1_9' (which would be sercli v1.9); symbolic names are used since the RCS versions are bumped each time a `ci' operation is done, and thus the RCS version numbers are meaningless -- WORSE, they have NO interrelationship; sercli.c 1.8 is NOT necessarily the same as dmakefile 1.8. Symbolic names have been used for sercli RCS files for as long as sercli has been kept in RCS. Though older versions kept all sercli RCS version numbers in lock-step, this has been recently fixed. RCS archives are only kept of the sources (not of docs). Dunno if it's worth changing. Changes (src/changes/#?) files: Every file src/(#?.[ch]|dmakefile) has a file by the same name in the src/changes/ dir. When a file is significantly altered, the changes/ file is updated to reflect this. Changes files are used in part to collect the doc/changes.text file, and in part to serve as reminders about what has been done so that a `ci' comment can be a little clearer. changes files are used by two dmake targets; one is to display the logged changes when catching `stray' revisions for the RCS files. The other is when building doc/changes.text (which results in the changes files being emptied, BTW). For other stuff relating to the programming of sercli, see the ToDo file and the src/#? files. ============= Richard Rauch 11415 Grant Dr. Fido 1:280/304.3 Overland Park, Ks. 66210 OpenLibrary BBS: 913 338 4079 Member of the League for Programming Freedom