Club Amiga de Montreal - CAM/CAM_CD_1.iso/files/249.lha/BrBox_v1.0/BrBox.doc

Text File | 1989-06-05 | 9.5 KB | 216 lines

            ****************************************
            **  BrBox V1.0  by John Schuncke, Jr. **
        **           29 May 1986              **
            ****************************************


WHY THIS PROGRAM EXISTS:
         This program is a software serial-port status monitor.
    A breakout box is a hardware monitor which you plug into a
    serial port cable to monitor the status of all the signals
    in the cable.  It's quite useful for debugging cabling or
    monitoring the status of a serial device, like a modem.
         BrBox is a software breakout box for the standard Amiga
    serial port.  It monitors the only 5 serial-port status lines
    that the Amiga serial port hardware deals with:

        RTS:  Request To Send, pin 4 of the DB-25 serial connector.
            This line is generated by the Amiga and
            used (sometimes) by the serial device.  It
            indicates (usually) that the computer is
            ready to send data to the device.
        CTS:  Clear To Send, pin 5.
            This line is the serial device's response
            to RTS.  The line will be active when the
            device is ready to receive data from the
            computer.  (This signal and RTS are often used
            for handshaking between a computer and a
            serially-interfaced printer.)
        DSR:  Data Set Ready, pin 6.
            This line is generated by the serial device
            and indicates that it is ready to handle data.
        CD:  Carrier Detect, pin 8.
            This line is a signal from the serial device
            (almost always a modem) that a data carrier
            signal is present on the phone line and a
            valid connection is present.
        DTR:  Data Terminal Ready, pin 20.
            This line, generated by the Amiga, indicates
            that it (acting as a data terminal) is ready
            to handle data.

HOW TO RUN THE PROGRAM:
       From CLI,
        BrBox        <- if you don't mind tying up your CLI
        RUN BrBox    <- if you want it to run independently
        RUNBACK BrBox    <- ditto, but nicer (I think)
        etc... I think you get the idea.
       From WorkBench,
        just click the pretty icon.  (If you've never seen a
        real hardware breakout box, the icon sorta looks like
        one, in a crude low-res way.  Not enought LED's on
        the icon, though.)

WHAT THE SOFTWARE DOES:
       BrBox opens a little window on the Workbench screen which
    contains a close gadget, depth arrangers, a "hidden" drag bar,
    and the abbreviations of the 5 serial lines mentioned above on
    a white background.  (The background writes over the drag bar,
    which is why the drag bar is "hidden."  But it's really there
    and functional.)
       Each string will be in black letters if the serial signal
    it represents is inactive (indicating the signal is "off") or
    in red letters if the signal is active ("on").  Therefore,
    if you have a modem on the serial port, dial onto your
    favorite BBS, and connect, your modem will probably turn the
    Carrier Detect line on to tell the computer about it.  The
    letters "CD" in the window will turn from black to red, and
    stay red as long as you have a carrier.

    ****QUICK NOTE:  I say that the letters will be black or red,
        but that's a function of your Preferences color scheme.
        If you're using the straight-out-of-the-box Workbench
        Preferences colors, "red" will actually be "orange".
        In reality, an inactive signal will be symbolized by a
        string printed in color 2, and an active one will be
        represented in color 3.  'Nuff 'sed.

    The monitor function is in real-time; if your phone line takes
    noise hits that cause the modem carrier to fluctuate on and off,
    the "CD" string will go from red to black to red, up to 5 times
    per second (which is the monitoring cycle speed of the software.)

    When you're tired of the program, just click the close gadget.
    The monitor will neatly close up and go away.

WHY I WROTE THE PROGRAM:
         Some modems don't have LED's to indicate the status of
    serial port lines.  This can be a real handicap if your
    modem also doesn't report (Hayes-like) events like loss
    of carrier.  The same can be said for most other serially-
    interfaced hardware, like printers.
         Also, it was (sorta) fun.  And an education.

WHAT THE PROGRAM WON'T DO:
         - accept command line arguments.  It won't get upset
        at arguments, it'll just ignore them.
         - monitor any serial device except the original
        Amiga internal serial port.  The program directly
        reads the serial port hardware (if you're curious,
        it reads the "B" CIA chip at address $BFD000).
        Since aftermarket serial-port add-ins don't use
        the same hardware, this program can't know they're
        there.
         - monitor any other serial-port line.  The serial data
        fluctuates far too fast for a 5-times-per-second loop
        to capture even 1 transition in 60 at 300 baud, and
        increasing cycle speed sufficiently would probably
        eat the CPU's lunch in terms of multitasking.
        As to other RS-232 status lines you may know of, such
        as Ring Indicator (RI)...well, they aren't implemented
        in the Amiga serial port.  Nothing to monitor there.
         - attach itself to another (non-Workbench) screen.  I
        thought about this a bit, and decided that I'd rather
        not try that just yet.  Maybe next version.  'Cides,
        if you close the screen that BrBox's window is on,
        without closing BrBox, the GURU will nail you dead.
        And I'd rather not have burden of that responsibility
        on my heart. ;-)
         - make me any money.  Self-explanatory.

WHAT KIND OF LEGAL MUMBO-JUMBO IS THIS?
         I've done some thinking.  (Please, don't act TOO surprised.)
    I was, for one mad moment, considering releasing this as share-
    ware.  Then I realized that (A) no one would pay for this,
    (B) it's probably aready been done someplace, (C) it's cute,
    but it's only a dumb little monitor program.
         Then I thought about my copyright rights.  I could copyright
    this puppy, but make it freely-distributable.
         Then I thought about my fun in the CP/M hacking world, where
    truly public-domain software was common.  All that completely
    open and non-proprietary software was a very fertile breeding
    ground for good software development and good software developers.
         So, the upshot of my thinking (asides from a lot of smoke
    issuing from my ears) was:

    THIS SOFTWARE IS PLACED IN THE PUBLIC DOMAIN.  I, JOHN SCHUNCKE,
    JR., RETAIN NO PROPRIETARY RIGHTS TO THE CODE, ALGORITHMS, OR
    LOOK AND FEEL (hah!) OF THIS PROGRAM.

         You may hack it, slice it, dice it, or redo it to say clever
    things instead of "CTS", "CD",  etc.  If you care to, recode it in
    BCPL or COBOL or whatever programming language you worship.
    You can (and are encouraged to) study the source code, especially
    if you're a beginning assembler programmer on the Amiga.  If you
    can modify the program to make it more useful, meaningful, or
    interesting to you, DO IT!  (And please tell me about it!  See
    the section at the end of this document on how to contact me.)
         On the flipside, though, I'll still be working on the program.
    This is version 1.0, the initial release.  It's not super-duper
    tested (only alpha-tested, so far), and I still have trivial
    improvements in the back of my mind.  So, I'll keep hacking the
    program and releasing it to the general public as I go.

HOW I WROTE THE PROGRAM:
         This program was written in 68000 assembler language.
         It was assembled using MetaComCo version 11.00 ASSEM.
         It was linked with BLINK, but I forget which version.
         The INCLUDE files were for AmigaDOS/EXEC 1.2.
         I plagarized liberally from the startup-code sample
    included with the assembler package, and from sample programs
    in _Amiga Assemble Language Programming_, by Jake Commander,
    TAB books, (C) 1987.  This book, along with the mandatory
    Addison-Wesley/CBM manuals (_Rom Kernal Manual_, both volumes,
    and _Hardware Reference Manual_) and the _Amiga Programmer's
    Handbook_ (by Eugene P. Mortimore, Sybex Books, (C) 1987),
    was technical guidance I so desperately needed.
         This .doc was keyed in using MicroEMACS V1.1.  So was
    the program source code.
         I typed with my fingers.  I believe God still holds
    the patent on fingers.  (ATHEISTS, PLEASE DON'T STONE ME!)
         The icons for the program and for the assembler listing,
    such as they are, were created using Deluxe Paint II as
    brushes and converted to icons with Hermes' IconLab (the
    crippled demo version).  The rather cute icon for this doc
    file I ripped off from a local user's group collection.

OTHER NEAT NOTES:
         Version 1.0 notes:
        This version has been tested (as of release date) on
        my own computer only.  This computer is a circa-1986
        512K Amiga 1000 with an A1010 external drive and a
        SupraModem 2400 external modem on the serial port most
        of the time, and running WB/KS 1.2.  Hence, I don't
        know if BrBox will work with the hardware of an A500
        or B2000, or with WB/KS 1.3.  I bet I will soon, though!

        >> OH Yeah, one other thing.  BrBox uses the default font
        at the time it initializes, so I hope you're using
        a 80-character-per-line, 8-pixel-high font like Topaz
        8, or the text may overrun the depth-arranger gadgets.

HOW TO GET MY ATTENTION
        Throw me lots of money.  #8-)

        Seriously,if you have any questions, brickbats,
        bouquets, or donations of any size, or have come up
        with an especially neat modification to the program,
        or have discovered a horrible bug, please contact me
        in any of the following ways:

        E-mail to John Schuncke on any of the following
           local-area (in Omaha) BBSes:
            Wind Dragon Inn, [phone]
            Amiga++,         [phone]
            Larry's Hot Tub, [phone]

        E-mail through Internet/ARPANet/Milnet to:
            [e-mail]

        U.S. Mail to:
            John L. Schuncke, Jr.
            1905 Thurston Ave., Apt. #8
            Bellevue, NE  68005