                    Amiga Empire by Chris Gray - SEREmp


SEREmp is the Amiga Empire client program which communicates with a remote
player over a serial port. By default, it will use the standard Amiga
serial port and will "autobaud" between 2400, 1200 and 300 baud, allowing
connections with either 8 data bits and no parity, or with 7 data bits and
even parity. Parameters specified on the shell command line, or via
WorkBench Tool Type entries, can override these defaults. SEREmp should be
compatible with Matt Dillon's 'Getty' program, and with startup by BBS
programs. Note that SEREmp does not automatically start up EmpServ, the
Amiga Empire server program, so in Getty or BBS applications, EmpServ must
have been previously started. When SEREmp is started from the WorkBench, it
can be started directly by double clicking on the SEREmp icon, or
indirectly by double clicking on a project icon whose Default Tool entry
indicates SEREmp. In the former case, the Tool Type entries for SEREmp
itself are used. In the latter case, the Tool Type entries for the project
are used. When started from a shell, the '-' in front of flags can be
omitted. In the following descriptions, the shell flag is given, followed
by the Tool Type name that has the same function, if any. Flag values which
are on-off switches can be specified in Tool Types with any of 'ON', 'OFF',
'YES' or 'NO'. The various parameters that can be specified are:

    -d [DEVICE=] [default serial.device] - specify which serial device is
        to be used. There must be a corresponding driver file in your DEVS:
        directory. The default name, 'serial.device' corresponds to the
        standard serial port built in to all Amigas. Other valid names
        include 'siosbx.device', which would refer to ASDG's dual port
        board. There must be no spaces between the 'd' and the device name.

    -u [UNIT=] [default 0] - specify which unit of the device to use. The
        standard 'serial.device' only supports one unit, so '0' should be
        used. 'siosbx.device' supports two units per board installed. CBM's
        seven-port board presumeably supports units 0 through 6. At the
        programming level, this unit number is given as the 'unit'
        parameter on the 'OpenDevice' call. There must be no spaces between
        the 'u' and the unit number.

    -b [BAUD=] [default 0] - specify the baud rate to use for the
        connection. Any value can be given here, and some serial devices
        will support them, but you will normally use a standard value like
        1200, 2400, 9600, etc. Value 0 is special, in that it indicates
        that autobaud selection is desired. This is the most common value
        to use with modems. The modem will come up first in 2400 baud, and
        SEREmp will try to read a carriage return. If it fails, it will
        switch to 1200 baud and try again. A second failure will result in
        a try at 300 baud. If that fails, it will switch back to 2400 baud
        and repeat the cycle. The tests are done with 8 data bits and no
        parity bit, and if a carriage return with the high bit set is
        received, SEREmp will assume even parity with 7 data bits. Thus,
        with a baud selection of 0, connecting players must enter 1, 2 or
        3 carriage returns before they get the initial connection message.
        With other values, the connection message is sent a couple of
        seconds after the connection is established, without waiting for
        any input characters. There must be no spaces between the 'b' and
        the baud rate.

    -s [SHARED=] [default not shared] - specify whether the serial port is
        to be opened in shared mode or not. In shared mode, the open will
        succeed even if some other program already has the port open, so
        long as they have opened it in shared mode also. Similarly, in
        shared mode, subsequent programs can open the same port. In non-
        shared mode, there must be no other programs with the port open,
        and no future requests, shared or otherwise, will be allowed until
        SEREmp exits.

    -x [XONOFF=] [default disabled] - specify whether or not XON/XOFF
        handshaking is to be enabled. This handshaking allows the remote
        user to suspend output by typing a control-S, and resume it by
        typing a control-Q. There is a timeout on all serial port
        activities, but this may not work correctly with all devices, thus
        it may be possible for a user to suspend a SEREmp indefinitely if
        this is enabled. The timeout does work correctly with the built-in
        serial port.

    -i [IGNORECD=] [default disabled] - if this flag is specified, then
        SEREmp will ignore the presence or absence of the CD (carrier
        detect) signal on the serial port. Normally, this signal is used to
        indicate when a connection is made via a modem. If the modem or
        terminal you are using does not generate this signal, then you can
        specify this flag to force SEREmp to connect, without waiting for
        the CD signal.

    -7 [7WIRE=] [default disabled] - specify whether the serial device is
        to use 7-wire hardware handshaking or not. The default is to ignore
        all wires on the serial port except the transmit and receive data
        lines. This hardware protocol is mostly useful for programs which
        transfer data at high rates to other programs. Various serial
        devices will support it with varying degrees of success. How well
        it works will also depend on the serial cable you are using, and on
        the support of the device on the other end of the cable.

    -p[neo] [PARITY=] [default no parity] - specify the parity setting for
        the serial port. On WorkBench, the choices are 'NONE', 'EVEN' and
        'ODD'. From a shell they are 'n', 'e' and 'o'. There must be no
        space between the 'p' and the parity letter.

    -tr [RETRY=] [default 60] - number of seconds to wait between attempts
        to open the specified serial port. This retrying allows SEREmp to
        wait for non-shared access to the port when another program
        currently has the port open. As usual, there must be no spaces
        between the 'tr' and the value.

    -tp [PROBE=] [default 1] - number of seconds to wait between probes of
        the serial port to see if there is a call incoming. One second is
        fairly short, but going to much more than 10 seconds could result
        in callers thinking the system is not running.

    -td [DISCONNECT=] [default 3] - number of seconds to pause after an
        incoming call has terminated before looking for another call.
        Normally, during the wait period, the DTR line to the modem will be
        inactive. This delay is often needed to fully disconnect two
        modems.

    -tt [TIMEOUT=] [default 5 * 60] - number of seconds (the default is 5
        minutes) of inactivity on the serial port before a timer goes off
        and attempts to terminate the session. This timeout is applied to
        all reads and writes to the port. Its purpose is to clear a call
        that is hung due to a user using control-S and then disconnecting.
        The previous release of Amiga Empire had a problem with this.

    -FLUSH [FLUSH] - If this flag appears then SEREmp will send the server a
        rt_flush instead of a rt_writeWorld after each country logs out.
        This can take 10-15 secs on a large world, and should probobly
        only be used on single-user systems, or when you are paranoid
        about losing data. NOTE: This flag is different from the flush
        option inside Empire itself!

    -TEST [TEST] - Use the test message port instead of the standard port.
        Used with the EmpServ -t flag to allow testing Empire while the main
        system is still running.

    -NORESET [NORESET] - Turns off the "ATZ" that is normally sent to the
        modem when autobaud is selected.

A few special-purpose shell command line flags have no WorkBench
equivalent. They were included for compatibility with Matt Dillon's 'Getty'
program, but are of use to any BBS program wishing to start up SEREmp as
well. They are:

    -Getty - specify that a Getty connection is being made. This forces the
        port to be opened in shared mode, and disables any parameter
        setting by SEREmp - the port is used in whatever state it is left
        by the calling program. Any baud rate, parity, 7wire, or xon/xoff
        switches specified will be ignored.

    -DEVICE device-name - specifies which serial device to use. This is
        equivalent to the '-d' or 'DEVICE=' flags. Note that in this case
        there must be at least one space between the '-DEVICE' and the
        device name.

    -UNIT unit-number - specifies which unit of the serial device to use.
        This is equivalent to the '-u' or 'UNIT=' flags. In this case also,
        there must be at lease one space between the '-UNIT' and the unit
        number.

Shell Examples

    Run SEREmp

Use 'serial.device' unit 0, with autobaud/parity selection, no XON/XOFF
protocol, no 7-wire protocol, exclusive access, expect CD to be active, use
an open retry time of 1 minute, a call probe time of 1 second, a disconnect
interval of 3 seconds and a port timeout of 15 minutes.

    Run SEREmp -dsiosbx.device -u1 -b2400 -po -7 -s -tt60

Use the ASDG 'siosbx.device', unit 1, at a fixed baud rate of 2400 with
odd parity. Enable the 7-wire protocol, pay attention to CD, open the
device for shared use, use an open retry time of 1 minute, a call probe
time of 1 second, a disconnect interval of 3 seconds and a port timeout of
1 minute.

    Run SEREmp -b9600 -pe -i

Use 'serial.device', unit 0, with a fixed baud rate of 9600 with even
parity. Open the device for exclusive use, and ignore the CD signal.
Everything else is the default. I use this setting to connect to the ADDS
Viewpoint terminal I have connected to my standard serial port.


WorkBench Examples

The same examples as above, done with WorkBench Tool Types are:

1)
    <no Tool Type entries needed for the first example>

2)
    DEVICE=siosbx.device
    UNIT=1
    BAUD=2400
    PARITY=ODD
    7WIRE=ON
    SHARED=YES
    TIMEOUT=60

3)
    BAUD=9600
    PARITY=EVEN
    IGNORECD=YES
