===========================================================================

This file is a subset of the INSTALL.TXT file and describes how to
set up your serial connection and begin running the PCCOM program
to allow serial communication between your host and target PCs.

---------------------------------------------------------------------------

Setting Up the Hardware

    To program GEOS applications, you will need a two-machine
    development station.  As outlined in the booklet provided with
    your CD-ROM, the "host" machine must be a 386 or more powerful
    processor with eight or more megabytes RAM, and the "target"
    machine may be any PC-compatible.

    The first step to setting up your development station is to set
    up these two machines and to get them running.

    What You'll Need

         Once you have set up your host and target PCs according to the
         instructions (i.e. attached the video and cables, turned it on
         and gotten DOS running, etc.), you can begin setting up the
         GEOS SDK-specific hardware.

         Besides the host and target PCs, you will need one or more
         serial cables and a null modem.  (A null modem is a connecter
         that switches lines 2 and 3 in the serial connection.)  For
         easier development, you should keep the two machines close
         together, so six feet of serial cable should be adequate.

         Depending on your machine configurations, you may also need
         an assortment of gender changers and other adapters to complete
         the connection.

    Procedure

         First, set up your two PCs according to their included
         instructions.  When choosing locations for the PCs, keep
         in mind that you will be switching frequently between the
         two machines and that you will often be using the mouse
         on the target machine while typing on the keyboard of the
         host machine.

         Next, connect the two machines via serial cable and a null
         modem.  Be sure to remember which serial ports you used on
         both machines, as you will need to know when installing the
         software. You may need to add in gender changer(s), 9-to-25
         pin adapter(s), or other connectors, depending on your
         machines and your cables.

            ______                      ______
            |HOST|_________ null_______|TARGET|
            | PC |          modem      |  PC  |
            ------                      ------

         Which serial ports you use is up to you; be sure to remember
         which you use, however, because the installation program will
         ask you later.

         After the hookup is made, you must copy one file from the CD
         onto the target machine using the following steps (if you have
         not yet printed out this file, you may wish to do so to have
         the steps available while going through them):

            1.  Format a floppy disk.
                The disk must be able to be used in both the host and
                the target PC, so be sure to use the correct format for
                your hardware.

            2.  Copy PCCOM.COM from the CD to the disk.
                In DOS or another file manager, copy the file named
                PCCOM.COM from the root directory of the CD-ROM
                onto the floppy disk.

            3.  Copy the file from the floppy to the target machine.
                Copy PCCOM.COM from the floppy disk to the target
                machine's root directory.

            4.  Set the PTTY environment variable on the host machine.
                On the host machine, set the PTTY environment variable
                to the COM port and baud used by the host.  Use the DOS
                SET command; the PTTY variable has the following format:

                        PTTY=<port>,<baud>,<int>

                <port> is the COM number (1, 2, 3, or 4), and <baud>
                is the baud rate used with the port.  The <int>
                parameter indicates the interrupt level to be used by
                the communications software; normally, you can ignore
                this paramter because the software uses the default for
                the selected port.
                
                For example, the command

                        SET PTTY=3,19200

                will set the PTTY variable to COM 3 and 19200 bps.
                Be sure that the port and baud are correct for the
                host, and be sure that no spaces occur between the
                PTTY and the remaining characters.

            5.  Set the PTTY environment variable on the target machine.
                On the target machine, set the PTTY variable as you
                did on the host.  Be sure that the settings reflect
                the target's configuration.  Also, the baud rates on
                the host and target MUST be identical, or the machines
                will not communicate.

            6.  Run PCCOM on both machines.
                Once you have set the PTTY variables on both machines
                and connected the serial cables, run PCCOM.COM on both
                machines to verify the serial connection.  You should,
                for this test, run PCCOM in the same directory in which
                it resides.  For example, on the target you will most
                likely run PCCOM from the C:\ directory (the root).
                On the host, you will probably run it directly off the
                CD's root directory.

                When PCCOM runs, it should clear the screen and print
                the following at the top of the screen:

                    waiting for command from remote PC:

                Both machines should be showing the above line before
                you continue.  If they are not, go through these steps
                again and make sure you did all of them.

                To make sure the connection is working properly, type
                some random characters on the host.  Those characters
                should show up on the target's screen; similaraly,
                keystrokes on the target machine should show up on the
                host's screen.  If this does not happen properly, you
                should read "Troubleshooting the Serial Connection,"
                below.  If it does work, you may continue with the
                installation with step 7, below.

            7.  Exit PCCOM on the host.
                On the host machine, simply hit Enter to exit.  This
                will return you to the DOS prompt (assuming you ran
                PCCOM from a DOS prompt).  Now you are ready to continue
                with the installation process:

                If you hit F2 from within the installation program
                to get to this point, now type "exit" to get back
                into the installation program, and continue by following
                the instructions there.

                If you have not yet run the installation program,
                you may do so now on the host machine by going to
                the CD-ROM drive (on many machines, this will be D:)
                and typing INSTALL.  Simply follow the instructions
                it guides you through.

                Be sure to keep PCCOM running on the target machine,
                though, as certain files will be downloaded over the
                serial cable during installation.

    Troubleshooting the Serial Connection

         The SDK install procedure works well for those programmers
         who know which COM ports and IRQ levels their machines will
         use when communicating.  However, when something goes wrong
         with this process, it can be very difficult to determine the
         correct combination of port and interrupt numbers.  This
         section contains a systematic way to determine the correct
         configuration to use.

         Unless you had a problem running PCCOM, you will not have
         to read this section.

         THE CABLES

         Your machines should be connected by a null-modem serial
         line.  Lap-link cable works admirably for this purpose. 

         At some point as you try to set up communications between your
         machines, you may think that things should be working, but they
         aren't.  Under these circumstances, a judicious jiggle to the
         cable's connections may prove helpful.

         THE SETTINGS

         Communications between machines are controlled by some settings
         on both machines. To get communication working, you will be
         working with these settings.

         -  The COM port setting tells the PCCOM communication software
            which serial port the serial communication cable is plugged
            into. This value can range from one to four. 

         -  The communication speed determines how quickly your machines
            will try to communicate.  We suggest a speed of 19200 baud;
            if one of your machines (presumably your target machine) is
            slow, you may have to use 9600 baud instead.

         -  Each COM port has an IRQ level associated with it.  If
            you try to send a signal to a COM port using the wrong IRQ
            level, your machine tends to generate some bad interrupts
            and freeze.  Thus, if you do not know the IRQ level
            associated with a COM port but discover it through
            trial-and-error, you may want to note it down in case
            you ever need to use another COM port. 

         SETTING AND OVERRIDING THE PTTY VARIABLE

         For the communication software to work correctly, both your
         target and host machines must have a correctly set PTTY
         variable.  Type SET on both machines to find out what the
         present value is for PTTY.  The SET command should return
         output that includes a line that looks something like the
         following (the numbers may be different):

                PTTY=1,19200,4

         or

                PTTY=1,19200

         If you are reading this section, then at least one of these
         values on at least one of your machines has probably been
         set incorrectly. 

         -  The first number of this variable signals which COM port
            this machine will use to communicate.  This value may
            be different between machines; for example, your connection
            may be between your host's port 1 and your target's
            port 2.  This number must be an integer between one and four.

         -  The second number specifies the communication speed,
            measured in baud. This value must be the same on both
            machines. 

         -  The third number, if any, specifies the IRQ level to use
            when communicating. If there is no third number, then it
            is assumed that you are using the IRQ level normally
            associated with the given COM port.  (I.e. if the first
            number of your PTTY variable is 1 or 3, the communication
            software will assume you want to use IRQ level 4. If the
            first number of your PTTY variable is 2 or 4, IRQ level
            3 is assumed.)

            To change your PTTY variable, issue the command

                    SET PTTY=1,19200,4

            or

                    SET PTTY=1,19200

            Note that there are no spaces in this command other than
            that between SET and PTTY.  If you include a space before
            the equals sign, you are actually setting the value of a
            new variable, "PTTY  " (PTTY with a space after it).  If
            you place a space after the equals sign, the communication
            software won't be able to interpret the value.  Nor should
            there be spaces after the commas.

         When you have figured out the correct values to use when
         communicating, you will want to make sure there is a line in
         your AUTOEXEC.BAT file that sets the variable correctly.  The
         installation program does this for you when given the proper
         information.

         When invoking the PCCOM program, you can override the values
         set by the PTTY variable by passing the /c, /b, and /I flags.
         For instance, typing

                PCCOM /c:2 /b:9600 /I:3

         will invoke PCCOM using COM port 2, IRQ level 3, and a 9600
         baud communication rate, no matter what values have been set
         in the PTTY variable.

         TROUBLESHOOTING THE CONNECTION

         If you simply can't get PCCOM to work properly using the above
         information, you will have to use a brute-force method; use the
         following steps until the connection is established.  (It is
         good to keep notes as you go to be sure you remember the correct
         configuration in the future.)

         Step 1:  Make Your Best Guess

         When you troubleshoot your communication set-up, the most
         difficult problem to solve is the case where you don't know
         which COM port either machine is using.  If you are in this
         situation now, some research might be in order.  The
         documentation of one or more of your machines should contain
         a clue as to which COM port number is associated with a
         particular serial socket.  If you have another device which
         you know uses a serial port, then you can be sure that the
         cable is not hooked up to that port.  Thus, if you know that
         your target machine has a mouse plugged into serial port two,
         you know that you will not be communicating with a COM port
         number of two. 

         If you narrow down the COM port choices now, you will save
         yourself a lot of time in the steps to follow.

         Step 2: Invoke PCCOM on Both Machines

         At the DOS prompt, type PCCOM on both machines.  If you are
         passing flags to PCCOM at either machine, now is the time to
         pass them.  As you continue with troubleshooting, you will
         probably have to exit PCCOM on one or both machines several
         times to change COM port and IRQ level settings. You should
         of course always remember to start up PCCOM again, as no
         communication will take place if PCCOM is only running on
         one machine.

         Step 3: Type "abc" on the Host Machine

         Depending on what happens when you do this, you can narrow
         in on your communication problem.

         -   "abc" appears on the Target machine:  Success!
             You have found the correct communication settings.
             Edit your AUTOEXEC.BAT files so that your PTTY
             variables will be set correctly when you next restart
             your machines.  If you have been experimenting with
             communications settings, you may wish to change your
             PTTY variables immediately, or just restart your
             machines after changing the AUTOEXEC.BAT files.

         -   "DDD" appears on the Host machine:  Incorrect cables.
             You do not have a null-modem connection in the serial
             line between your machines.  The null-modem acts like
             a telephone line, making the host's "mouth" talk to the
             target's "ear" and the target's "mouth" talk to the
             host's "ear."  Without the null-modem connection, your
             machines will act as if they are talking on the phone,
             but one of them is holding their receiver upside down--
             listening at the mouthpiece and talking into the 
             earpiece.  Your host's voice is being echoed back into
             its own "ears," getting corrupted in the process.
             Use a null-modem connection.

             The good news is that your signal is in fact reaching
             the cable, and thus your host machine is using the
             correct COM port and IRQ level settings.

         -  "a" on Target, Host frozen:  Correct except IRQ level.
             The host successfully transmitted the "a" to the target.
             The target machine was listening at the right port and
             sent back a signal that it was ready for the next
             character. The host received this signal, but could not
             handle it and froze. Try a different IRQ level for your
             host (by using a different number for the third part of
             your host's PTTY variable or by using the /I: flag when
             next invoking PCCOM on the host machine).  Before
             continuing with tests, "unfreeze" your host by restarting
             it.  (You probably had to do this to change the IRQ
             level anyhow.)

         -   No text appears, Host is frozen:  Host IRQ level is wrong.
             The IRQ level you have chosen to use with your host's
             COM port is not correct for that COM port.  Note that
             there is no guarantee that you have chosen the correct
             COM port number either.  Try using a different IRQ level,
             and when you find the correct one for that COM port, you
             might want to note it down.  Before continuing with
             tests, "unfreeze" your host by restarting it.  (You
             probably had to do this to change the IRQ level anyhow.)

         -   No text appears, Target frozen, Host not:  Target IRQ wrong.
             You've almost achieved the right settings; your host
             machine is sending the signal correctly, and your target
             machine is listening at the right port.  However, your
             target machine is getting confused when the signal comes
             in.  Change the IRQ level setting on your target machine,
             either by changing the PTTY variable, or by passing an /I:
             flag to PCCOM.  Before continuing with tests, "unfreeze"
             your target by restarting it.  (You probably had to do
             this to change the IRQ level anyhow.)

         -   No text appears, Neither machine frozen:  Wrong COM port.
             The host machine successfully sent the signal to the
             COM port you selected.  However, the signal never got
             to the target machine.  Either the host's COM port
             setting was wrong so the signal was sent to the wrong
             port and never reached the cable, or the target's COM
             port was wrong so it was listening at the wrong port.
             It is possible that in fact both machines have the wrong
             COM port settings.

             Try using different COM port settings on one or both
             machines. (Do this by changing the first part of your
             PTTY variable or by passing a /c: flag to PCCOM.)  Of
             course, if you are rather sure about which COM port one
             of the machines is using, you should try changing the
             other one's settings first.

             Remember that the COM port value may be 1, 2, 3, or 4.
             If you know that some device is already using a port,
             than you need not test that port (assuming you haven't
             somehow managed to plug a serial cable and some other
             device into the same serial port socket).

         If you're unsure about your target machine settings, you
         should try reversing these tests, typing "abc" on the target
         machine to see what happens. The PCCOM communication is 
         bi-directional, so you may use the above tests just as well, 
         substituting the word "host" for "target," and vice versa.

===========================================================================
