5. THE COMMUNICATIONS SYSTEM

        To open the communications system, tap the telephone icon
        at the bottom of the mail editor screen.

        To return to the mail editor, tap the close box in the
        lower right corner of the communications system screen.

        The communications system maintains a set of services.
        Each service contains information on how to connect to
        a particular server, and send and receive mail.

        Tapping on "Service" brings up a list of available services
        and some options for creating, renaming and deleting
        services.  A sample service is created when eNotes is
        installed to give you an idea of how a simple set up could
        look.

        Immediately below this is a large rectangle.  Tapping the
        label at the top of the rectangle allows you to select from
        various screens containing configuration options for the
        current service.  The content of each one of these screens
        is dealt with in the sections below.


5.1. Creating, Deleting and Renaming Services

        1.  Tap on "Service".
        2.  Tap your choice from the list that appears.
        3.  If creating, or renaming a service, fill in the name
            in the box that appears, then tap "Create" or "Rename"
            as appropriate.

        Note that service names have no significance other than
        as labels in the "Service" list.


5.2. The Connection Screen

        The main feature of this screen is the "Connect" button.
        Tapping this will attempt to connect to the currently
        selected service.

        The "Send outgoing mail" and "Retrieve new mail" checkboxes
        tell eNotes what to do when you tap the "Connect" button.
        You can turn off either one if you want to only send or
        only receive mail when you next connect.

        The "Leave copies on server" ensures that no messages are
        deleted from the server (regardless of the settings on the
        Options screen detailed in the next section).  This is useful
        if you use eNotes to check on a mail account that you also
        access from your desktop computer.

        When you connect, eNotes displays some running information
        on the status of the connection in the blank area above the
        various buttons.  This area is referred to as "the log".


5.3. The Options Screen

        The options screen allows you set change the way eNotes
        handles messages.

        The "Display scripts as they run" displays information
        about the state of the connection and disconnection scripts
        in the log as they are running.  (See the "The Connection
        Script Screen" section for more information.)

        The "Don't retrieve messages larger than" checkbox and
        accompanying slider allow you to limit the size of the
        messages that the Newton will transfer from the server.
        With this turned off, the Newton will attempt to download
        any sized message.  If the message is too big to fit in
        memory in one piece (usually about ten to twenty kilobytes,
        depending on your Newton model and memory usage) the Newton
        will discard the message.  It is a good idea to leave this
        checkbox turned on to avoid low memory situations.

        The "Delete oversized messages from server" checkbox
        allows you to specify what the Newton does with messages
        that are too big to transfer.  If this box is turned on,
        these messages are deleted from the server without being
        downloaded.

        Turning on the "Delete previously received messages from
        server" checkbox tells the Newton to delete from the server
        copies of any messages that the Newton has downloaded in
        a previous session.  Note that the Newton will never download
        a message it already has a copy of whether or not this box
        is checked.


5.4. The Modem Screen

        The modem screen is used to tell the Newton about the
        physical details of the connection.

        The "Connect via modem" button tells the Newton to try to
        use a modem to connect to the server.  The phone number
        that the Newton will dial can be set in the space below
        the button.

        (Note that the Newton allows you to set other modem
        preferences from the Extras drawer.  See your MessagePad
        handbook for details.)

        The "Connect via serial link" button tells the Newton to
        ignore the modem and assume there is a cable running from
        the Newton serial port directly to the server.  It is
        possible to use this, along with a fancy connection script,
        to get eNotes to dial with a serial modem that isn't Newton
        compatible.

        The settings below this are standard communications settings.
        If you are unsure what the values should be for your server,
        check the program you use to connect from your desktop
        computer.  Most desktop communications programs have similar
        types of settings that you can copy over to eNotes.

        WARNING It is important that you have at least one of the
                "Software flow control", "Hardware flow control"
                or "Use MNP error correction" checkboxes turned
                on.  The Newton may lose the connection when
                receiving mail if you do not.

        NOTE    The "Use MNP error correction" mode will work even
                if your modem does not support MNP.  The Newton
                has the ability to emulate MNP in software.


5.5. The Identification Screen

        The identification screen is where you tell the Newton
        about your email address and give it the information it
        needs to authenticate itself to the server.

        You should fill in the "Own address" box with your own
        e-mail address in full.

        The "User name" box should contain your user name (or login
        name) on the server.

        The "Pass word" box should contain the pass word you use
        to log in to the server.  Note that once you have filled
        in this box and switched out of the identification screen,
        your pass word will be displayed as a series of bullets.
        Someone who picks up your Newton cannot view your pass
        word.

        If you need to use a different user name and pass word to
        connect to the mail server than you do to log in to your
        server account, then check the "Use a separate POP3 name
        and pass word" box and fill out the boxes underneath.  If
        you are unsure whether this applies to you, ask your service
        provider.


5.6. The Server Screen

        The server screen tells eNotes where to find the mail
        server and what sort of behaviour to expect from it.

        The "POP3 host", "POP3 port", "SMTP host" and "SMTP port"
        boxes tell the Newton the name of the hosts running the
        POP3 and SMTP servers, and the ports on which they are
        running.  If you are unsure of what values these should
        take, ask your service provider.

        The "Telnet echoes typed text" checkbox should usually be
        left on, unless the server is running "srialpop".  See the
        "Information for Service Providers" section for more
        information on "srialpop".

        Tap on "eNotes sends end of line as" to choose the end of
        line character that eNotes should send.  For most UNIX
        servers, the default value of "CR" should be just fine.


5.7. The Connection Script Screen

        The connection script tells the Newton what to do once it
        has established a connection to the server.  In the simplest
        case (as shown in the connection script for the sample
        service) this simply involves logging in.  Other systems
        may require you to connect to the server through an annex,
        which requires additional commands.

        The connection script should leave the Newton sitting at
        a shell prompt.  The newton will then use the command
        "telnet <POP3/SMTP host> <POP3/SMTP port>" to connect to
        the POP3 and SMTP servers.  Don't worry if you don't
        understand what this command does.


5.7.1. Connection Script Lines

        The connection script is made up of a series of lines.
        Each line instructs the Newton to perform an action.
        The possible actions are:

            - Wait for some particular text
            - Send some particular text
            - Wait for a set amount of time
            - Send your user name (from the Identification screen)
            - Send your pass word (from the Identification screen)

        When a connection is first established, the Newton steps
        through performing the action of each line of the connection
        script in order.

        To add a line to a script, tap the "New" button in the
        lower right corner.

        To remove a line from a script, tap the small trash can
        icon at the right side of that line.

        On a Newton with version 2.0 of the operating system, you
        can rearrange lines simply by dragging the separator bar
        at the top of the line.  Dragging a line to the edge of
        the screen will place it on the clipboard.


5.7.2. Writing a connection script

        It is a good idea before writing your script to connect to
        your server from a communications program on your desktop,
        log in by hand and then print out a transcript of the
        session.  You can then see exactly what the server sends
        and exactly what you need to type in response.

        If you still don't understand scripts, take a look at the
        following section.


5.7.3. An example connection script

        To give you an idea of how scripts work, an example script
        is provided in the "Sample Service" which is available when
        eNotes is first installed.  The following is a walk through
        of that script, with some explanatory notes.  Although your
        scripts may look very different to this hopefully the sample
        can give you a general idea of how scripts work.

           1. Send a carriage return
                Many systems need to be prodded a little before they
                give a prompt.  By using the "Send text" option,
                leaving the text field blank and checking the "CR"
                box you can send a single carriage return to do this.

           2. Wait for the text "login:"
                This is the standard UNIX login prompt.  Two things
                are worth noting:
                a) eNotes is not case sensitive when checking for
                received text, so "login:", "Login:" and "LoGiN:"
                would all have the same effect, and
                b) The "CR" and "LF" checkboxes also work when the
                command is "Wait for text".  In this case the Newton
                will wait for the specified text followed by a carriage
                return and/or linefeed.  Most scripts won't use these
                checkboxes with "Wait for text".

            3. Send user name
                This sends the user name which you entered on the
                Identification Screen.  Note that the "CR" box is
                checked to send a carriage return after it.

            4. Wait for the text "password:"
                Now we wait for the password prompt...

            5. Send pass word
                ...and send the pass word followed by a carriage return.

            6. Wait for the text ">"
                This waits for UNIX to provide a prompt.  Not all
                systems use ">" for a prompt, so don't assume that
                yours will.

            7. Send text "biff n; mesg n"
                This turns off notification of new mail and messages
                sent from other users with the "write" command.  Not
                all UNIX systems support these, but if yours does
                then it is a good idea to turn them off this way.

            8. Wait for text ">"
                Make sure that eNotes is left sitting at a shell prompt.



5.8. The Disconnection Script Screen

        The disconnection script is run by the Newton after eNotes
        has finished sending and receiving messages.  At the start
        of the disconnection script, eNotes leaves the UNIX server
        at a shell prompt.

        After the disconnection script has run, eNotes hangs up
        the connection.


5.9. It doesn't work!  What now?

        OK, so you've been through all this, created your service
        and tapped "Connect", and your Newton gets half way through
        and then stops or gives you an error.  The following is a
        list of common problems and things to try.

        If all of these fail, try talking to your service provider -
        they may be able to help.

        If that fails, get in touch with us.  We'd be more than
        happy to help you get eNotes up and running.  See the
        section "Contacting Eclipse" for more information.


        The Newton tells me that the modem isn't responding.

            - Check the cables and make sure the modem has power.
            - Make sure your modem is Newton compatible.  You may
              need to install modem enablers (freely available from
              Apple) and/or change your current modem setup in the
              Newton's modem preferences.

        The Newton tells me there is no dial tone.

            - Check the connection from the modem to the phone line.
            - In some countries the Newton cannot detect a dial
              tone.  If this is the case then see your MessagePad
              Handbook for information on how to set the modem
              preferences to disable dial tone detection.

        The Newton dials up OK, says "Logging in" and then freezes.

            - eNotes is not getting through your connection script.
              First make sure you have "Display scripts as they
              run" turned on in the Options screen.  This will help
              show where in your connection script eNotes is getting
              lost.

        Even with "Displays scripts" turned on it just says "Logging in"
        and then freezes.

            - Try sending a carriage return as the first thing in
              your script.  Some hosts require a bit of a prod
              before they will respond.

            - If that doesn't work, try adding a couple of seconds
              pause before sending the carriage return.

        eNotes seems to get through the connection script, then it says
        "Sending mail" or "Retrieving mail" and just sits there.
                
            - Make sure your server is running POP3 and SMTP
              daemons, and that the host name and ports for these
              are set correctly on the Server screen.  Your service
              provider should be able to give you this information.
              Be very careful to get these exactly right, and make
              sure they don't contain spaces.

            - Check that the value of "eNotes sends end of line as"
              on the Server screen is correct.  Once again, your
              service provider should be able to tell you what the
              server expects.

            - Make sure that your server sends a carriage return
              followed by a line feed as its end of line.  On many
              servers you can do this by adding "stty onlcr" as a
              shell command in your connection script.  Your service
              provider should also be able to help you with this.

        eNotes gives me a message like "The server has returned an
        invalid response....(The response was USER <your user name>)"

            - You probably have the "Telnet echoes typed text"
              box on the Server screen unchecked when it should
              be checked, or vice versa.

        eNotes gives me -48402 errors will connecting, or tells me that
        "The message is too big for downloading" even on relatively
        small messages.

            - Some package, or combination of packages, is using
              lots of memory on your Newton.

            - Make sure that the Extras drawer and/or the Notes app are
              the only others packages open when you try to connect.

            - Try resetting your Newton immediately before connecting.
              (Press the small button inside the battery compartment.)
              You do not lose any data by doing this, and it ensures
              that eNotes has the maximum amount of memory available.

            - You may want to have a look at some of the many shareware
              and freeware applications available that help conserve
              memory.

            - eNotes 2 will use some of the advanced memory management
              features of OS 2.0 to entirely alleviate this sort of
              memory problem.

        I have the "Leave messages on server" box unchecked, but eNotes
        seems to leave them there anyway.

            - Try adding a few seconds delay to the end of your
              disconnection script.  Some POP3 servers take a little
              while to process deletions when you log out, and if
              eNotes hangs up first then they won't finish the job.

        eNotes gives me an error or locks up my Newton as soon as I try
        to open it.

            - eNotes has problems with some packages that allow
              freezing of apps in the Extras drawer.  You must make
              sure that eNotes is unfrozen manually before it is
              opened.  This will be fixed in version 2.
        
        I have a MessagePad 110, and the Newton sometimes switches
        off or gives errors after I've connected.

            - You need to install the "MP110 Power Off Update"
              available from Apple.
                


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

6. INFORMATION FOR SERVICE PROVIDERS

        If you run a server and you are interested in supporting
        eNotes then this section is for you.


6.1. Security Concerns

        If you do not normally provide shell accounts and are
        concerned with the security problems of doing so, you may
        wish to take a look at a program called "srialpop".
        "srialpop" acts as a fake shell with only two commands
        enabled: a simple form of "telnet", and "logout".

        You can even restrict the hosts and ports which the telnet
        command allows the user to connect to.

        "srialpop" is freely available and you should be able to
        find it on a site near you.

        A point worth noting: the "telnet" built into srialpop does
        no character echoing, so the "Telnet echoes typed text"
        option should be disabled on the eNotes Server screen.


6.2. Providing an eNotes Configuration to Users

        If you successfully get eNotes configured and you wish to
        save your users the trouble of having to enter all the
        configuration information into the Newton, get in touch
        with Eclipse.  We can provide you with a version of your
        configuration as a small Newton package on disk.

        You can then give this package to your users on disk or
        online and have them install it using the Newton Package
        Installer, which is freely available from Apple.

        You may also offer to install it for your users.  If you
        have a Windows PC or a Macintosh this is very easy to
        do and is a service your users would probably appreciate.


7. CONTACTING ECLIPSE

        Feel free to contact us with questions, bugs, suggestions,
        criticisms or even just some positive comments.

        When contacting us with configuration problems, please tell
        us what sort of Newton and modem you are using as well as
        the exact text of any error messages you get and exactly
        where they occur.  It would also be helpful if you included
        a copy of your connection script.


        You can reach us via e-mail at:         enotes@pobox.com
        Or telephone:                           +61 3 9349 1276
        Or fax:                                 +61 3 9349 2815

        Eclipse are:

                Daniel Harris           UNIX development
                Sydney Low              Design/Marketing
                Pete Yandell            Newton Code/Manual

        eNotes is brought to you by Instant Information.


8. WHAT'S NEW IN THIS VERSION?

        1.6b1 is primarily a bug fix release.  See the "Known Bugs and
        Problems" section for more information on the bugs that have
        been repaired and the problems remaining.

        Some small features have been added:
        - eNotes has a patch that works around a bug in the Linux POP3
          server that previously caused it to fail
        - There is now a "Copy to notes" option available when eNotes
          is running on a Newton with OS 2.0
        - The copy protection flag on the eNotes package has been turned
          off, so eNotes can now be transferred between Newtons or from
          a Newton to a card


        1.6b0 had the following additions from 1.5b0:

        - This manual!
        - eNotes now works under OS 2.0, although it doesn't support
          many of OS 2.0's cool new features
        - eNotes no longer requires srialpop - it can be set up to
          simply run telnet from your shell
        - Improved connection and disconnection script editing
        - More flexible configuration of deleting messages from server
        - Fixed to look at the built in modem preferences correctly.
          All those people who need to ignore dial tones can use it now!
        - Added handling for dialling up to a host and then connecting to
          a separate POP3/SMTP server
        - Some useful bulk message deletion options in the mail reader
        
        And some bug fixes:
        - Stopped eNotes from displaying any messages whose subject
          only begins with the selected subject rather than matching it
        - Fixed crashes when switching modes or services while the
          Newton is connected by stopping the user from switching!
        - Fixed error message display so any unprintable output
          characters aren't displayed as confusing rectangles
        - Added support for a few more strange POP3 and SMTP servers
        - Fixed a whole pile of minor, obscure bugs
        
        
9. KNOWN BUGS AND PROBLEMS

        Version 1.6b1 no longer has the following problems:

        - -48809 errors on some Newtons with OS 2.0 and a memory card
        - -8007 errors and lockups when cancelling a connection on
          a MessagePad 100 or 110
        - Communications should have fewer buffer overflows and
          similar problems, as well as slightly quicker performance
        - The Date header field is now handled more robustly.  Their
          are a lot of mailers out there that don't follow the
          specification on this.

        The following should now be fixed, but we've been unable to
        test the patches.  Anybody getting any of these errors should
        let us know immediately.

        - -48418 errors during communications
        - -48201 errors starting eNotes on German Newtons
        

        The following problems still exist:

        - The Newton can ignore the flow control settings, and even
          the baud rate setting for some combinations of modem and
          modem enabler.

        - There is a woeful lack of undo support for things like
          script editing.

        - eNotes reports some errors (such as engaged signals)
          as "Unknown communications errors" under NOS 2.0

        - The "Delete Messages" feature can sometimes give a -48022
          error on a MessagePad 120 when deleting large numbers of
          messages.  This leaves a message without a body in the
          database.  Viewing this message will display the body of
          another message, and trying to delete it will cause
          further problems.  (Apple's manual lists -48022 as
          "Internal error - something unexpected happened".  We're
          trying to find out what on earth that's supposed to mean.)



10. WHAT CAN I EXPECT IN THE NEXT VERSION?

        eNotes 1.6 will be the last major upgrade that supports
        OS 1.3, although versions with bug fixes may be released.
        
        eNotes 2.0 will support the new features of OS 2.0 to a much
        greater extent.  You can expect it to be smaller, faster and
        integrated better with the rest of the system.



eNotes is a trademark of Eclipse.
Instant Information Pty Ltd markets eNotes on behalf of Eclipse.
eNotes is brought to you by Pete Yandell, Sydney Low and Daniel Harris.
Copyright 1994-1996 Daniel Harris, Sydney Low and Pete Yandell.
