Beijing Paradise BBS Backup/PARADISE.ISO/software/BBSDOORW/XR301OS2.ZIP/XROBOT.DOC

Text File | 1993-05-23 | 21.1 KB | 568 lines

                                  XRobot 3.01

                 The FrontDoor Mail Robot for MS-DOS and OS/2


                                  USER GUIDE


                              Absolute Solutions



    SOFTWARE LICENSE AGREEMENT

    The XRobot computer software, information attached hereto, and any
    modifications made to the enclosed information, hereafter referred to
    as XRobot, is protected by applicable copyright laws and international
    treaty provisions pertaining to intellectual property.

    XRobot is provided to you "as is", without warranty of any kind,
    promise of merchantability, or fitness for a particular purpose,
    either expressed or implied, all of which are hereby explicitly
    disclaimed.

    Joaquim Homrighausen, hereafter "the author", only guarantees that
    XRobot occupies disk space.

    You are hereby granted a non-exclusive license to use and test XRobot,
    provided you accept and abide to all parts of this "SOFTWARE LICENSE
    AGREEMENT".

    You agree and acknowledge that XRobot is a proprietary product of the
    author, protected under international treaty provisions and other
    applicable copyright laws. You further acknowledge and agree that all
    rights, title, and interest in and to XRobot are and shall remain with
    the author.

    The author shall in no event be liable for any indirect, incidental,
    consequential, special, or exemplary damages or lost profits, even if
    the author has been advised of the possibility of such damages.

    The author's cumulative liability to you or any other party for any
    loss or damages resulting from any claims, demands, or action arising
    out of or relating to this agreement shall not exceed the license fee
    paid by you to the author for XRobot.

    You may not lease, rent, or sell XRobot. You may not disassemble,
    modify, decompile, or reverse engineer XRobot.

    All organizations, clubs, schools, legal entities, sole proprietors,
    commercial enterprises, companies, and government institutions (in
    other words any juridcal person) must obtain a commercial license for
    XRobot before using it.

    You may freely distribute and copy XRobot provided no fee is charged
    (including trading) and the distribution archive contains an
    unmodified copy of XRobot. XRobot may not be included in any public or
    commercial archive distribution shipped on physical media such as CD-
    ROMs or tapes.

    All brand and product names are trademarks or registered trademarks of
    their respective holders.


    Copyright 1987-1993 Joaquim Homrighausen; All rights reserved.



    CONTACTING THE AUTHOR

    If you need to contact me, use one of the following addresses.

        Joaquim Homrighausen
        389, route d'Arlon
        L-8011 Strassen
        Luxembourg

        INTERNET    [e-mail]
        FidoNet     2:270/17
        FDNET       255:3001/2


    COMMERCIAL LICENSE FEE

    Single copy is LUF (equal to Belgian Francs, BEF) 1000.- or USD $35.
    Volume discounts and site licenses are available. Smaller
    contributions are (of course) also welcome, but does not buy you a
    commercial license.


    UPDATE INFORMATION

    Please refer to the last section of this document for information
    about corrections and update information.



    WHAT IS XROBOT

    XRobot is what the name implies, an easy to control utility designed
    to aid you in your daily SysOp chores. It will simplify tasks like
    sending and requesting one or more files to and from one or more
    systems.

    These functions can involve a lot of extra work if the software you
    are using does not handle everything properly.

    It is assumed that you know enough about your FrontDoor e-mail
    environment and terms involved with it to understand some technical
    descriptions. This is not a beginner's utility - it is easy to use,
    but it does require some knowledge about operating an e-mail system in
    general.

    The history of this program is quite long and credits are due to
    several people who gave me ideas and hints (and complaints). It would
    take up too much space if I were to list all of them here. One
    individual should be named here though, Mats Knuts; I am not sure
    XRobot would have been released back then without his constant nagging
    and suggestions.

    XRobot has been around since early 1986.


    CHANGES FROM VERSIONS PRIOR TO 3.00

        o   The option to send a message via a zonegate has been removed.

        o   The support for drive mappings has been removed.

        o   XROBOT.CTL is no longer supported. All necessary configuration
            data is retrieved from FrontDoor's system files, specifically
            SETUP.FD and NAMES.FD.


    SOFTWARE REQUIREMENTS

        o   FrontDoor 2.02 or above.

        o   MS-DOS 3.x (or compatible) or OS/2 2.x. For MS-DOS
            environments, SHARE must be loaded.

        o   Roughly 64kb of available RAM memory.


    BLA BLA

    This is a complete rewrite of XRobot. No code from previous versions
    has been used. XRobot was written using Zortech C++ 3.1 for DOS
    (compiled in the small memory model) and Zortech C++ 3.1 for OS/2
    (compiled in the 32-bit flat memory model).



    BASICS

    The basic functions are as mentioned to send and request files. You
    can do this with several options and different type of addressing
    methods.

    Most of the data is taken from a file referred to as the FrontDoor
    system file, SETUP.FD hereafter. To make changes to SETUP.FD, use the
    FDSETUP program included in the FrontDoor e-mail package.

    XRobot will search for SETUP.FD in the directory pointed to by the FD
    or FRONTDOOR environment variable. If neither is set, it will attempt
    to open SETUP.FD in the current directory.

    XRobot treats uppercase and lowercase characters the same as far as
    command-line parameters goes, e.g. "SEND" is treated identical to
    "Send". The order of the command-line parameters is irrelevant.


    RUNNING THE PROGRAM

        XR <command> [<switches>]

    Running XRobot without any command-line parameters will display a
    brief help message.


    COMMANDS

        SEND        Send one or more files to one or more systems.
        GET         Fetch one or more files from one or more systems.
        POLL        Create empty ("poll") messages to one or more systems.
        TEXT        Send one or more messages to one or more systems.
        SWITCHES    Displays a list of command-line parameters.
        MSGBITS     Displays a list of values for the /M parameter.



    COMMAND-LINE PARAMETERS

    Command-line parameters must be preceded by a hyphen (-) or a forward
    slash (/) character. Data for a command-line parameter must follow
    immediately.

        /A<path>    Used with the SEND command, this switch will force
                    XRobot to insert <path> as the path for each file
                    matching the given file specification (/F). E.g.

                    XR SEND /FC:\MYWORK\NEW.TXT /AC:\FD\OUTWORK /R2:270/17

                    would create one file attach message to send the
                    specified file. The attach message's subject field
                    (Re:) would contain C:\FD\OUTWORK\NEW.TXT.

        /D<days>    Used with the SEND and TEXT commands, this switch will
                    force XRobot to only send those files updated (as
                    indicated by their directory entry) since <days> days.

                    For the OS/2 version, the "LastWritten" date stamp is
                    used.

        /F<file>    File to send or fetch (placed in subject (Re:) field
                    when used in conjunction with the TEXT command).

                    This specifies which file(s) XRobot should send or
                    request (get). For the SEND command, all files
                    matching <file> will be sent.

                    XRobot will by default not include those files with
                    SYSTEM or HIDDEN attribute. This behavior can be
                    overriden with the /NI switch.

                    The OS/2 version supports "long" (HPFS) filenames. If
                    they include a space, you should put <file> within
                    double quotes, i.e. "A name with spaces", after /F.

        /I          Forces XRobot to insert ^aINTL information in all
                    messages it creates. This is by default only done when
                    the recipient address (/R) is located in a zone other
                    than the zone of your primary network address.

        /M<bit><m>  Set or reset a specific message bit. <Bit> specifies
                    which bit should be set or reset, and <m> must either
                    contain a hyphen (-) character to reset <bit>, or a
                    plus (+) character to set the bit.

                    Multiple message bits can be specified to set or
                    reset, e.g. /MC+I- would set the CRASH message bit and
                    reset the IMMEDIATE message bit.

                    See MSGBITS for a detailed description of available
                    and default message bits.



        /N<1-10>    Specifies a username slot in SETUP.FD to use in all
                    created messages' "By:" field instead of the default
                    ("XRobot..").

        /NL         XRobot will by default add information about its
                    activities to the FrontDoor log file. This switch can
                    be specified to disable logging.

                    XRobot will always create two log entries, regardless
                    of if this switch is used or not.

        /NR         XRobot will by default update the FrontDoor rescan
                    semaphores FDRESCAN.NOW and FMRESCAN.NOW when it has
                    created one or more messages. By using this switch,
                    you can prevent this behavior.

        /NI         Includes files with SYSTEM and/or HIDDEN attribute
                    when used in conjunction with the SEND and TEXT
                    commands. See the description of the /F switch for
                    more information.

        /O<1-10>    Specifies which AKA (network address) in SETUP.FD
                    XRobot should use as the originating address of the
                    messages. If this switch is used, the automatic AKA
                    matching is disabled.

        /R<addr>    Specifies a recipient (more than one /R switch may be
                    specified to indicate multiple recipients). XRobot
                    will honor short-form addressing and fetch the missing
                    portions from your primary network address.

                    E.g. ".1" implies <YourPrimaryAddres>.1. "17", implies
                    <YourPrimaryZone>:<YourPrimaryNet>/17.

        /T<file>    Includes the contents of <file> as the message text in
                    all created messages for the SEND, GET, and POLL
                    commands.

                    <File> may not include wildcard characters. For the
                    TEXT command, the text specified after /T is inserted
                    into the created messages' subject (Re:) field. To
                    include space characters, use an undescore (_)
                    character.

        /U          Forces XRobot to set the "File Update Request" message
                    bit when used in conjunction with the GET command.



        /ZN /ZS     Used in conjunction with the SEND command, these
                    switches instruct XRobot to scan your requestable
                    directories (as defined in SETUP.FD) for the files
                    specified with the /F switch.

                    /ZN uses the list of requestable directories specified
                    for normal sessions, and /ZS uses the list of
                    requestable directories specified for secure sessions.

                    Note that by using /ZN or /ZS, the /A switch is
                    automatically disabled. The FrontDoor request alias
                    definitions are first scanned, and if a match is made
                    for a particular file specification, XRobot will
                    proceed to search for the next specified file.


    MSGBITS

    The meaning of these message bits is explained in the FrontDoor
    documentation.

    The /M parameter is used to set or reset specific message bits to
    alter the default behavior of XRobot. Certain defaults apply and some
    bits cannot be removed (reset) from messages being created.

    For all commands, the "Local" bit is always set. For the GET command,
    the "File Request" bit is always set unless the /U switch is also
    used, in which case the "File Update Request" bit is always set. For
    the SEND command, the "File" bit is always set. The "Kill/Sent" and
    "Private" bits are by default set. For the POLL command, the "Direct"
    bit is assumed.

    Some bits do not make any sense when combined. Such combinations
    include the "Immediate" (or "Crash") and "Hold" bits.

    The following letters are used to represent message bits in
    conjunction with the /M switch:

        A   Force pickup            (FPU)       K   Kill/Sent
        B   Fax cover message       (FAX)       L   Local
        C   Crash                               M   Return receipt (RRQ)
        D   Direct                  (DIR)       O   Orphan
        E   Del/Sent (file)         (KFS)       P   Private
        F   File attach                         R   File request
        G   Trunc/Sent (file)       (TFS)       S   Sent
        H   Hold                                U   File update request
        I   Immediate               (IMM)       X   In-transit
        J   Confirmation receipt    (CFM)       Y   Received



    COMMAND-LINE EXAMPLES

        XR SEND /FC:\*.ARJ /FC:\FD\NEWS\FIDO*.NWS /R2:270/17 /R255:3000/0

        Would send all files matching C:\*.ARJ and C:\FD\NEWS\FIDO*.NWS to
        2:270/17 and 255:3000/0.


        XR GET /FFILES /R2:270/17 /R255:3000/0

        Would request "FILES" from 2:270/17 and 255:3000/0.


        XR POLL /R2:270/17 /R255:3000/0

        Would create a "poll" message to 2:270/17 and 255:3000/0.


        XR TEXT /FC:\*.TXT /R2:270/17 /R255:3000/0 /THello_There

        Would send all files matching C:\*.TXT as normal text messages
        (the contents of the matching files are inserted into the message
        text) to 2:270/17 and 255:3000/0. The messages' subject (Re:)
        field would be "Hello There".


        XR SEND /FC:\FD\NEWS\*.ARJ /R2:270/17 /D10

        Would send those files matching C:\FD\NEWS\*.ARJ that have been
        updated in the last ten days to 2:270/17.


    NAMES.FD AND RECIPIENT NAMES

    When specifying a recipient (/R), you may use name macros listed in
    NAMES.FD. This is indicated to XRobot by preceding the recipient with
    an asterisk (*), e.g. XR SEND MYFILE.ARJ /R*JoHo would search for
    "JoHo" in NAMES.FD and use the address (and SysOp name, if defined)
    associated with that macro.

    If you do not want to use NAMES.FD, but want to specify a recipient
    name instead of the default "SysOp", you may do so by putting a comma
    (,) followed by the recipient's name after the network address, e.g.
    XR SEND MYFILE.ARJ /R2:270/17,Joaquim_Homrighausen.


    REQUESTING FILES WITH PASSWORDS

    To request a file that is protected by a password, you must supply the
    password when you specify the filename (/F switch). The filename and
    password must be separated by a comma (,) character. E.g.
    /Fsecret.arj,mypassword would request the file SECRET.ARJ with a
    password of "mypassword".



    FDOPT SETTINGS

        NOISCR  XRobot will by default remove SoftCR characters from text
                files before importing them into the body of a message.
                This may be inappropriate in some environments.

                If the NOISCR string is present in the FDOPT environment
                variable, XRobot will preserve any SoftCR characters in
                text files that are used for message text.

        INTL    If this string is present in the FDOPT environment
                variable, it has the same effect as specifying /I on the
                command-line to XRobot.



    RESPONSE FILES

    XRobot is capable of using response files for input to the /F and /R
    switches, as well as a global response file for all commands and
    actions you want it to carry out.

    To indicate that you want to use a response file, XRobot requires that
    you preced them with an @ character, e.g. @<response.fil>. This
    instructs XRobot to read the file "RESPONSE.FIL" and take its input
    from the file as opposed to from the command-line. This allows you to
    create pre-defined "sets" of recipients and files to send or request
    and then reuse them.

    The format of a response file is that of a plain vanilla ASCII file
    with each line terminated by a <CR><LF> combination (although XRobot
    should be able to handle a single <CR> or <LF> as the line
    terminator).

    Text following a semi-colon (;) is ignored and can be used as comments
    to make your response files more readable. The maximum line length is
    255 characters.

    Here is an example of a response file given to the /F switch, we'll
    call the file RESPONSE.FIL to keep things simple:

        [RESPONSE.FIL]:
        ;This is a comment

        C:\AUTOEXEC.BAT C:\CONFIG.SYS               ;This too is a comment
        C:\FD\NEWS\FIDO*.NWS C:\FD\FRODO\FD211.ARJ  ;And this..
        [END]

        XR SEND /[e-mail] /R2:270/17

        would instruct XRobot to send all files listed in RESPONSE.FIL to
        2:270/17. The [RESPONSE.FIL] and [END] text is simply used to
        indicate the contents of the file, you should not put that in your
        own response files.

    Another example, for use with the /R switch follows, again, we will
    call the file RESPONSE.FIL:

        [RESPONSE.FIL]:
        ;This is another useless comment

        2:270/18 1:170/400 255:3000/0 *JoHo
        [END]

        XR SEND /FMYFILE.ARJ /[e-mail]

        would instruct XRobot to send MYFILE.ARJ to all recipients listed
        in RESPONSE.FIL. Note the use of "*JoHo" which forces XRobot to
        scan NAMES.FD for the macro "JoHo".



    One other very powerful concept of response files as implemented in
    XRobot is the use of labels. This allows you to put several different
    sets of pre-defined files and recipients in one physical file and
    instruct XRobot which set to use.

    A label is specified in a response file by preceding the first word on
    a line by a colon (:). The length of the label may not exceed 255
    characters and must not contain any spaces. To specify a label in
    conjunction with a response file, use the format @response.fil@label.
    An example follows (again, the response file is called RESPONSE.FIL):

        [RESPONSE.FIL]:
        ;My global XRobot response file

        :MYNET
        2:270/18 2:270/3 2:270/7

        :USNET
        1:170/400 1:107/574 1:234/567
        [END]

        XR SEND /FMYFILE.ARJ /[e-mail]@mynet

        would instruct XRobot to send MYFILE.ARJ to all recipients
        starting at the "MYNET" label.

    When you have specified a label, XRobot will first search for the
    label, and if found, read all input until the next label is found, or
    the end of the file is encountered. If you do not specify a label, the
    entire response file is read (all labels are ignored).

    One other use of response files is supported by XRobot, a global
    response file. This allows you to specify multiple actions to be taken
    by XRobot. Normally, this would require several calls from the DOS or
    OS/2 prompt (or .BAT/.CMD file).

    If a global response file is used, no other parameters will be honored
    and all input is read from the response file. The global response file
    is specified as XR @response.fil. E.g.

        [RESPONSE.FIL]:
        ;Some comments
        SEND /FMYFILE.ARJ /R2:270/17 /R2:270/18
        GET /FFILES /R2:270/17
        ;Some more comments
        TEXT /FC:\TEXTS\NEWS.NOW /R2:270/18 /MC+
        SEND /[e-mail] /[e-mail]
        [END]

    Note the use of response files in the last SEND command.

    Enjoy.



    UPDATE INFORMATION

        3.01

        When using the /T parameter to put the contents of an ASCII file
        into a text message, the program would incorrectly leave a NUL
        character between the extended message information ("kludge
        lines") and the beginning of the message text.

    // end of file "xrobot.doc"