home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 249.lha / BrBox_v1.0 / BrBox.doc < prev    next >
Text File  |  1989-06-05  |  10KB  |  216 lines
  1.  
  2.  
  3.             ****************************************
  4.             **  BrBox V1.0  by John Schuncke, Jr. **
  5.         **           29 May 1986              **
  6.             ****************************************
  7.  
  8.  
  9. WHY THIS PROGRAM EXISTS:
  10.          This program is a software serial-port status monitor.
  11.     A breakout box is a hardware monitor which you plug into a
  12.     serial port cable to monitor the status of all the signals
  13.     in the cable.  It's quite useful for debugging cabling or
  14.     monitoring the status of a serial device, like a modem.
  15.          BrBox is a software breakout box for the standard Amiga
  16.     serial port.  It monitors the only 5 serial-port status lines
  17.     that the Amiga serial port hardware deals with:
  18.  
  19.         RTS:  Request To Send, pin 4 of the DB-25 serial connector.
  20.             This line is generated by the Amiga and
  21.             used (sometimes) by the serial device.  It
  22.             indicates (usually) that the computer is
  23.             ready to send data to the device.
  24.         CTS:  Clear To Send, pin 5.
  25.             This line is the serial device's response
  26.             to RTS.  The line will be active when the
  27.             device is ready to receive data from the
  28.             computer.  (This signal and RTS are often used
  29.             for handshaking between a computer and a
  30.             serially-interfaced printer.)
  31.         DSR:  Data Set Ready, pin 6. 
  32.             This line is generated by the serial device
  33.             and indicates that it is ready to handle data.
  34.         CD:  Carrier Detect, pin 8.
  35.             This line is a signal from the serial device
  36.             (almost always a modem) that a data carrier
  37.             signal is present on the phone line and a
  38.             valid connection is present.
  39.         DTR:  Data Terminal Ready, pin 20.
  40.             This line, generated by the Amiga, indicates
  41.             that it (acting as a data terminal) is ready
  42.             to handle data.
  43.  
  44. HOW TO RUN THE PROGRAM:
  45.        From CLI,
  46.         BrBox        <- if you don't mind tying up your CLI
  47.         RUN BrBox    <- if you want it to run independently
  48.         RUNBACK BrBox    <- ditto, but nicer (I think)
  49.         etc... I think you get the idea.
  50.        From WorkBench,
  51.         just click the pretty icon.  (If you've never seen a
  52.         real hardware breakout box, the icon sorta looks like
  53.         one, in a crude low-res way.  Not enought LED's on
  54.         the icon, though.)
  55.  
  56. WHAT THE SOFTWARE DOES:
  57.        BrBox opens a little window on the Workbench screen which
  58.     contains a close gadget, depth arrangers, a "hidden" drag bar,
  59.     and the abbreviations of the 5 serial lines mentioned above on
  60.     a white background.  (The background writes over the drag bar,
  61.     which is why the drag bar is "hidden."  But it's really there
  62.     and functional.)
  63.        Each string will be in black letters if the serial signal
  64.     it represents is inactive (indicating the signal is "off") or
  65.     in red letters if the signal is active ("on").  Therefore,
  66.     if you have a modem on the serial port, dial onto your
  67.     favorite BBS, and connect, your modem will probably turn the
  68.     Carrier Detect line on to tell the computer about it.  The
  69.     letters "CD" in the window will turn from black to red, and
  70.     stay red as long as you have a carrier.
  71.  
  72.     ****QUICK NOTE:  I say that the letters will be black or red,
  73.         but that's a function of your Preferences color scheme.
  74.         If you're using the straight-out-of-the-box Workbench
  75.         Preferences colors, "red" will actually be "orange".
  76.         In reality, an inactive signal will be symbolized by a
  77.         string printed in color 2, and an active one will be
  78.         represented in color 3.  'Nuff 'sed.
  79.  
  80.     The monitor function is in real-time; if your phone line takes
  81.     noise hits that cause the modem carrier to fluctuate on and off,
  82.     the "CD" string will go from red to black to red, up to 5 times
  83.     per second (which is the monitoring cycle speed of the software.)
  84.  
  85.     When you're tired of the program, just click the close gadget.
  86.     The monitor will neatly close up and go away.
  87.     
  88. WHY I WROTE THE PROGRAM:
  89.          Some modems don't have LED's to indicate the status of
  90.     serial port lines.  This can be a real handicap if your
  91.     modem also doesn't report (Hayes-like) events like loss
  92.     of carrier.  The same can be said for most other serially-
  93.     interfaced hardware, like printers.
  94.          Also, it was (sorta) fun.  And an education.
  95.  
  96. WHAT THE PROGRAM WON'T DO:
  97.          - accept command line arguments.  It won't get upset
  98.         at arguments, it'll just ignore them.
  99.          - monitor any serial device except the original
  100.         Amiga internal serial port.  The program directly
  101.         reads the serial port hardware (if you're curious,
  102.         it reads the "B" CIA chip at address $BFD000).
  103.         Since aftermarket serial-port add-ins don't use
  104.         the same hardware, this program can't know they're
  105.         there.
  106.          - monitor any other serial-port line.  The serial data
  107.         fluctuates far too fast for a 5-times-per-second loop
  108.         to capture even 1 transition in 60 at 300 baud, and
  109.         increasing cycle speed sufficiently would probably
  110.         eat the CPU's lunch in terms of multitasking.
  111.         As to other RS-232 status lines you may know of, such
  112.         as Ring Indicator (RI)...well, they aren't implemented
  113.         in the Amiga serial port.  Nothing to monitor there.
  114.          - attach itself to another (non-Workbench) screen.  I
  115.         thought about this a bit, and decided that I'd rather
  116.         not try that just yet.  Maybe next version.  'Cides,
  117.         if you close the screen that BrBox's window is on,
  118.         without closing BrBox, the GURU will nail you dead.
  119.         And I'd rather not have burden of that responsibility
  120.         on my heart. ;-)
  121.          - make me any money.  Self-explanatory.
  122.  
  123. WHAT KIND OF LEGAL MUMBO-JUMBO IS THIS?
  124.          I've done some thinking.  (Please, don't act TOO surprised.)
  125.     I was, for one mad moment, considering releasing this as share-
  126.     ware.  Then I realized that (A) no one would pay for this,
  127.     (B) it's probably aready been done someplace, (C) it's cute,
  128.     but it's only a dumb little monitor program.
  129.          Then I thought about my copyright rights.  I could copyright
  130.     this puppy, but make it freely-distributable.
  131.          Then I thought about my fun in the CP/M hacking world, where
  132.     truly public-domain software was common.  All that completely
  133.     open and non-proprietary software was a very fertile breeding
  134.     ground for good software development and good software developers.
  135.          So, the upshot of my thinking (asides from a lot of smoke
  136.     issuing from my ears) was:
  137.  
  138.     THIS SOFTWARE IS PLACED IN THE PUBLIC DOMAIN.  I, JOHN SCHUNCKE,
  139.     JR., RETAIN NO PROPRIETARY RIGHTS TO THE CODE, ALGORITHMS, OR
  140.     LOOK AND FEEL (hah!) OF THIS PROGRAM.
  141.  
  142.          You may hack it, slice it, dice it, or redo it to say clever
  143.     things instead of "CTS", "CD",  etc.  If you care to, recode it in
  144.     BCPL or COBOL or whatever programming language you worship.
  145.     You can (and are encouraged to) study the source code, especially
  146.     if you're a beginning assembler programmer on the Amiga.  If you
  147.     can modify the program to make it more useful, meaningful, or
  148.     interesting to you, DO IT!  (And please tell me about it!  See
  149.     the section at the end of this document on how to contact me.)
  150.          On the flipside, though, I'll still be working on the program.
  151.     This is version 1.0, the initial release.  It's not super-duper
  152.     tested (only alpha-tested, so far), and I still have trivial
  153.     improvements in the back of my mind.  So, I'll keep hacking the
  154.     program and releasing it to the general public as I go.
  155.  
  156. HOW I WROTE THE PROGRAM:
  157.          This program was written in 68000 assembler language.
  158.          It was assembled using MetaComCo version 11.00 ASSEM.
  159.          It was linked with BLINK, but I forget which version.
  160.          The INCLUDE files were for AmigaDOS/EXEC 1.2.
  161.          I plagarized liberally from the startup-code sample
  162.     included with the assembler package, and from sample programs
  163.     in _Amiga Assemble Language Programming_, by Jake Commander,
  164.     TAB books, (C) 1987.  This book, along with the mandatory
  165.     Addison-Wesley/CBM manuals (_Rom Kernal Manual_, both volumes,
  166.     and _Hardware Reference Manual_) and the _Amiga Programmer's
  167.     Handbook_ (by Eugene P. Mortimore, Sybex Books, (C) 1987),
  168.     was technical guidance I so desperately needed.
  169.          This .doc was keyed in using MicroEMACS V1.1.  So was
  170.     the program source code.
  171.          I typed with my fingers.  I believe God still holds
  172.     the patent on fingers.  (ATHEISTS, PLEASE DON'T STONE ME!)
  173.          The icons for the program and for the assembler listing,
  174.     such as they are, were created using Deluxe Paint II as
  175.     brushes and converted to icons with Hermes' IconLab (the
  176.     crippled demo version).  The rather cute icon for this doc
  177.     file I ripped off from a local user's group collection.
  178.  
  179. OTHER NEAT NOTES:
  180.          Version 1.0 notes:
  181.         This version has been tested (as of release date) on
  182.         my own computer only.  This computer is a circa-1986
  183.         512K Amiga 1000 with an A1010 external drive and a
  184.         SupraModem 2400 external modem on the serial port most
  185.         of the time, and running WB/KS 1.2.  Hence, I don't
  186.         know if BrBox will work with the hardware of an A500
  187.         or B2000, or with WB/KS 1.3.  I bet I will soon, though!
  188.  
  189.         >> OH Yeah, one other thing.  BrBox uses the default font
  190.         at the time it initializes, so I hope you're using
  191.         a 80-character-per-line, 8-pixel-high font like Topaz
  192.         8, or the text may overrun the depth-arranger gadgets.
  193.  
  194. HOW TO GET MY ATTENTION
  195.         Throw me lots of money.  #8-)
  196.  
  197.         Seriously,if you have any questions, brickbats,
  198.         bouquets, or donations of any size, or have come up
  199.         with an especially neat modification to the program,
  200.         or have discovered a horrible bug, please contact me
  201.         in any of the following ways:
  202.  
  203.         E-mail to John Schuncke on any of the following
  204.            local-area (in Omaha) BBSes:
  205.             Wind Dragon Inn, (402) 291-8053
  206.             Amiga++,         (402) 291-3636
  207.             Larry's Hot Tub, (402) 571-4316
  208.  
  209.         E-mail through Internet/ARPANet/Milnet to:
  210.             SAC.CCSO-OLA@E.ISI.EDU
  211.  
  212.         U.S. Mail to:
  213.             John L. Schuncke, Jr.
  214.             1905 Thurston Ave., Apt. #8
  215.             Bellevue, NE  68005
  216.