home *** CD-ROM | disk | FTP | other *** search
/ Media Share 9 / MEDIASHARE_09.ISO / comm / xr301os2.zip / XROBOT.DOC < prev    next >
Text File  |  1993-05-23  |  22KB  |  568 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.  
  17.  
  18.  
  19.  
  20.  
  21.  
  22.  
  23.  
  24.  
  25.  
  26.  
  27.                                   XRobot 3.01
  28.  
  29.                  The FrontDoor Mail Robot for MS-DOS and OS/2
  30.  
  31.  
  32.                                   USER GUIDE
  33.  
  34.  
  35.                               Absolute Solutions
  36.  
  37.  
  38.  
  39.     SOFTWARE LICENSE AGREEMENT
  40.  
  41.     The XRobot computer software, information attached hereto, and any
  42.     modifications made to the enclosed information, hereafter referred to
  43.     as XRobot, is protected by applicable copyright laws and international
  44.     treaty provisions pertaining to intellectual property.
  45.  
  46.     XRobot is provided to you "as is", without warranty of any kind,
  47.     promise of merchantability, or fitness for a particular purpose,
  48.     either expressed or implied, all of which are hereby explicitly
  49.     disclaimed.
  50.  
  51.     Joaquim Homrighausen, hereafter "the author", only guarantees that
  52.     XRobot occupies disk space.
  53.  
  54.     You are hereby granted a non-exclusive license to use and test XRobot,
  55.     provided you accept and abide to all parts of this "SOFTWARE LICENSE
  56.     AGREEMENT".
  57.  
  58.     You agree and acknowledge that XRobot is a proprietary product of the
  59.     author, protected under international treaty provisions and other
  60.     applicable copyright laws. You further acknowledge and agree that all
  61.     rights, title, and interest in and to XRobot are and shall remain with
  62.     the author.
  63.  
  64.     The author shall in no event be liable for any indirect, incidental,
  65.     consequential, special, or exemplary damages or lost profits, even if
  66.     the author has been advised of the possibility of such damages.
  67.  
  68.     The author's cumulative liability to you or any other party for any
  69.     loss or damages resulting from any claims, demands, or action arising
  70.     out of or relating to this agreement shall not exceed the license fee
  71.     paid by you to the author for XRobot.
  72.  
  73.     You may not lease, rent, or sell XRobot. You may not disassemble,
  74.     modify, decompile, or reverse engineer XRobot.
  75.  
  76.     All organizations, clubs, schools, legal entities, sole proprietors,
  77.     commercial enterprises, companies, and government institutions (in
  78.     other words any juridcal person) must obtain a commercial license for
  79.     XRobot before using it.
  80.  
  81.     You may freely distribute and copy XRobot provided no fee is charged
  82.     (including trading) and the distribution archive contains an
  83.     unmodified copy of XRobot. XRobot may not be included in any public or
  84.     commercial archive distribution shipped on physical media such as CD-
  85.     ROMs or tapes.
  86.  
  87.     All brand and product names are trademarks or registered trademarks of
  88.     their respective holders.
  89.  
  90.  
  91.     Copyright 1987-1993 Joaquim Homrighausen; All rights reserved.
  92.  
  93.  
  94.  
  95.     CONTACTING THE AUTHOR
  96.  
  97.     If you need to contact me, use one of the following addresses.
  98.  
  99.         Joaquim Homrighausen
  100.         389, route d'Arlon
  101.         L-8011 Strassen
  102.         Luxembourg
  103.  
  104.         INTERNET    joho@abs.lu
  105.         FidoNet     2:270/17
  106.         FDNET       255:3001/2
  107.  
  108.  
  109.     COMMERCIAL LICENSE FEE
  110.  
  111.     Single copy is LUF (equal to Belgian Francs, BEF) 1000.- or USD $35.
  112.     Volume discounts and site licenses are available. Smaller
  113.     contributions are (of course) also welcome, but does not buy you a
  114.     commercial license.
  115.  
  116.  
  117.     UPDATE INFORMATION
  118.  
  119.     Please refer to the last section of this document for information
  120.     about corrections and update information.
  121.  
  122.  
  123.  
  124.     WHAT IS XROBOT
  125.  
  126.     XRobot is what the name implies, an easy to control utility designed
  127.     to aid you in your daily SysOp chores. It will simplify tasks like
  128.     sending and requesting one or more files to and from one or more
  129.     systems.
  130.  
  131.     These functions can involve a lot of extra work if the software you
  132.     are using does not handle everything properly.
  133.  
  134.     It is assumed that you know enough about your FrontDoor e-mail
  135.     environment and terms involved with it to understand some technical
  136.     descriptions. This is not a beginner's utility - it is easy to use,
  137.     but it does require some knowledge about operating an e-mail system in
  138.     general.
  139.  
  140.     The history of this program is quite long and credits are due to
  141.     several people who gave me ideas and hints (and complaints). It would
  142.     take up too much space if I were to list all of them here. One
  143.     individual should be named here though, Mats Knuts; I am not sure
  144.     XRobot would have been released back then without his constant nagging
  145.     and suggestions.
  146.  
  147.     XRobot has been around since early 1986.
  148.  
  149.  
  150.     CHANGES FROM VERSIONS PRIOR TO 3.00
  151.  
  152.         o   The option to send a message via a zonegate has been removed.
  153.  
  154.         o   The support for drive mappings has been removed.
  155.  
  156.         o   XROBOT.CTL is no longer supported. All necessary configuration
  157.             data is retrieved from FrontDoor's system files, specifically
  158.             SETUP.FD and NAMES.FD.
  159.  
  160.  
  161.     SOFTWARE REQUIREMENTS
  162.  
  163.         o   FrontDoor 2.02 or above.
  164.  
  165.         o   MS-DOS 3.x (or compatible) or OS/2 2.x. For MS-DOS
  166.             environments, SHARE must be loaded.
  167.  
  168.         o   Roughly 64kb of available RAM memory.
  169.  
  170.  
  171.     BLA BLA
  172.  
  173.     This is a complete rewrite of XRobot. No code from previous versions
  174.     has been used. XRobot was written using Zortech C++ 3.1 for DOS
  175.     (compiled in the small memory model) and Zortech C++ 3.1 for OS/2
  176.     (compiled in the 32-bit flat memory model).
  177.  
  178.  
  179.  
  180.     BASICS
  181.  
  182.     The basic functions are as mentioned to send and request files. You
  183.     can do this with several options and different type of addressing
  184.     methods.
  185.  
  186.     Most of the data is taken from a file referred to as the FrontDoor
  187.     system file, SETUP.FD hereafter. To make changes to SETUP.FD, use the
  188.     FDSETUP program included in the FrontDoor e-mail package.
  189.  
  190.     XRobot will search for SETUP.FD in the directory pointed to by the FD
  191.     or FRONTDOOR environment variable. If neither is set, it will attempt
  192.     to open SETUP.FD in the current directory.
  193.  
  194.     XRobot treats uppercase and lowercase characters the same as far as
  195.     command-line parameters goes, e.g. "SEND" is treated identical to
  196.     "Send". The order of the command-line parameters is irrelevant.
  197.  
  198.  
  199.     RUNNING THE PROGRAM
  200.  
  201.         XR <command> [<switches>]
  202.  
  203.     Running XRobot without any command-line parameters will display a
  204.     brief help message.
  205.  
  206.  
  207.     COMMANDS
  208.  
  209.         SEND        Send one or more files to one or more systems.
  210.         GET         Fetch one or more files from one or more systems.
  211.         POLL        Create empty ("poll") messages to one or more systems.
  212.         TEXT        Send one or more messages to one or more systems.
  213.         SWITCHES    Displays a list of command-line parameters.
  214.         MSGBITS     Displays a list of values for the /M parameter.
  215.  
  216.  
  217.  
  218.     COMMAND-LINE PARAMETERS
  219.  
  220.     Command-line parameters must be preceded by a hyphen (-) or a forward
  221.     slash (/) character. Data for a command-line parameter must follow
  222.     immediately.
  223.  
  224.         /A<path>    Used with the SEND command, this switch will force
  225.                     XRobot to insert <path> as the path for each file
  226.                     matching the given file specification (/F). E.g.
  227.  
  228.                     XR SEND /FC:\MYWORK\NEW.TXT /AC:\FD\OUTWORK /R2:270/17
  229.  
  230.                     would create one file attach message to send the
  231.                     specified file. The attach message's subject field
  232.                     (Re:) would contain C:\FD\OUTWORK\NEW.TXT.
  233.  
  234.         /D<days>    Used with the SEND and TEXT commands, this switch will
  235.                     force XRobot to only send those files updated (as
  236.                     indicated by their directory entry) since <days> days.
  237.  
  238.                     For the OS/2 version, the "LastWritten" date stamp is
  239.                     used.
  240.  
  241.         /F<file>    File to send or fetch (placed in subject (Re:) field
  242.                     when used in conjunction with the TEXT command).
  243.  
  244.                     This specifies which file(s) XRobot should send or
  245.                     request (get). For the SEND command, all files
  246.                     matching <file> will be sent.
  247.  
  248.                     XRobot will by default not include those files with
  249.                     SYSTEM or HIDDEN attribute. This behavior can be
  250.                     overriden with the /NI switch.
  251.  
  252.                     The OS/2 version supports "long" (HPFS) filenames. If
  253.                     they include a space, you should put <file> within
  254.                     double quotes, i.e. "A name with spaces", after /F.
  255.  
  256.         /I          Forces XRobot to insert ^aINTL information in all
  257.                     messages it creates. This is by default only done when
  258.                     the recipient address (/R) is located in a zone other
  259.                     than the zone of your primary network address.
  260.  
  261.         /M<bit><m>  Set or reset a specific message bit. <Bit> specifies
  262.                     which bit should be set or reset, and <m> must either
  263.                     contain a hyphen (-) character to reset <bit>, or a
  264.                     plus (+) character to set the bit.
  265.  
  266.                     Multiple message bits can be specified to set or
  267.                     reset, e.g. /MC+I- would set the CRASH message bit and
  268.                     reset the IMMEDIATE message bit.
  269.  
  270.                     See MSGBITS for a detailed description of available
  271.                     and default message bits.
  272.  
  273.  
  274.  
  275.         /N<1-10>    Specifies a username slot in SETUP.FD to use in all
  276.                     created messages' "By:" field instead of the default
  277.                     ("XRobot..").
  278.  
  279.         /NL         XRobot will by default add information about its 
  280.                     activities to the FrontDoor log file. This switch can
  281.                     be specified to disable logging.
  282.  
  283.                     XRobot will always create two log entries, regardless
  284.                     of if this switch is used or not.
  285.  
  286.         /NR         XRobot will by default update the FrontDoor rescan
  287.                     semaphores FDRESCAN.NOW and FMRESCAN.NOW when it has
  288.                     created one or more messages. By using this switch,
  289.                     you can prevent this behavior.
  290.  
  291.         /NI         Includes files with SYSTEM and/or HIDDEN attribute
  292.                     when used in conjunction with the SEND and TEXT
  293.                     commands. See the description of the /F switch for
  294.                     more information.
  295.  
  296.         /O<1-10>    Specifies which AKA (network address) in SETUP.FD
  297.                     XRobot should use as the originating address of the
  298.                     messages. If this switch is used, the automatic AKA
  299.                     matching is disabled.
  300.  
  301.         /R<addr>    Specifies a recipient (more than one /R switch may be
  302.                     specified to indicate multiple recipients). XRobot
  303.                     will honor short-form addressing and fetch the missing
  304.                     portions from your primary network address.
  305.  
  306.                     E.g. ".1" implies <YourPrimaryAddres>.1. "17", implies
  307.                     <YourPrimaryZone>:<YourPrimaryNet>/17.
  308.  
  309.         /T<file>    Includes the contents of <file> as the message text in
  310.                     all created messages for the SEND, GET, and POLL
  311.                     commands.
  312.  
  313.                     <File> may not include wildcard characters. For the
  314.                     TEXT command, the text specified after /T is inserted
  315.                     into the created messages' subject (Re:) field. To
  316.                     include space characters, use an undescore (_)
  317.                     character.
  318.  
  319.         /U          Forces XRobot to set the "File Update Request" message
  320.                     bit when used in conjunction with the GET command.
  321.  
  322.  
  323.  
  324.         /ZN /ZS     Used in conjunction with the SEND command, these
  325.                     switches instruct XRobot to scan your requestable
  326.                     directories (as defined in SETUP.FD) for the files
  327.                     specified with the /F switch.
  328.  
  329.                     /ZN uses the list of requestable directories specified
  330.                     for normal sessions, and /ZS uses the list of
  331.                     requestable directories specified for secure sessions.
  332.  
  333.                     Note that by using /ZN or /ZS, the /A switch is
  334.                     automatically disabled. The FrontDoor request alias
  335.                     definitions are first scanned, and if a match is made
  336.                     for a particular file specification, XRobot will
  337.                     proceed to search for the next specified file.
  338.  
  339.  
  340.     MSGBITS
  341.  
  342.     The meaning of these message bits is explained in the FrontDoor
  343.     documentation.
  344.  
  345.     The /M parameter is used to set or reset specific message bits to
  346.     alter the default behavior of XRobot. Certain defaults apply and some
  347.     bits cannot be removed (reset) from messages being created.
  348.  
  349.     For all commands, the "Local" bit is always set. For the GET command,
  350.     the "File Request" bit is always set unless the /U switch is also
  351.     used, in which case the "File Update Request" bit is always set. For
  352.     the SEND command, the "File" bit is always set. The "Kill/Sent" and
  353.     "Private" bits are by default set. For the POLL command, the "Direct"
  354.     bit is assumed.
  355.  
  356.     Some bits do not make any sense when combined. Such combinations
  357.     include the "Immediate" (or "Crash") and "Hold" bits.
  358.  
  359.     The following letters are used to represent message bits in
  360.     conjunction with the /M switch:
  361.  
  362.         A   Force pickup            (FPU)       K   Kill/Sent
  363.         B   Fax cover message       (FAX)       L   Local
  364.         C   Crash                               M   Return receipt (RRQ)
  365.         D   Direct                  (DIR)       O   Orphan
  366.         E   Del/Sent (file)         (KFS)       P   Private
  367.         F   File attach                         R   File request
  368.         G   Trunc/Sent (file)       (TFS)       S   Sent
  369.         H   Hold                                U   File update request
  370.         I   Immediate               (IMM)       X   In-transit
  371.         J   Confirmation receipt    (CFM)       Y   Received
  372.  
  373.  
  374.  
  375.     COMMAND-LINE EXAMPLES
  376.  
  377.         XR SEND /FC:\*.ARJ /FC:\FD\NEWS\FIDO*.NWS /R2:270/17 /R255:3000/0
  378.  
  379.         Would send all files matching C:\*.ARJ and C:\FD\NEWS\FIDO*.NWS to
  380.         2:270/17 and 255:3000/0.
  381.  
  382.  
  383.         XR GET /FFILES /R2:270/17 /R255:3000/0
  384.  
  385.         Would request "FILES" from 2:270/17 and 255:3000/0.
  386.  
  387.  
  388.         XR POLL /R2:270/17 /R255:3000/0
  389.  
  390.         Would create a "poll" message to 2:270/17 and 255:3000/0.
  391.  
  392.  
  393.         XR TEXT /FC:\*.TXT /R2:270/17 /R255:3000/0 /THello_There
  394.  
  395.         Would send all files matching C:\*.TXT as normal text messages
  396.         (the contents of the matching files are inserted into the message
  397.         text) to 2:270/17 and 255:3000/0. The messages' subject (Re:)
  398.         field would be "Hello There".
  399.  
  400.  
  401.         XR SEND /FC:\FD\NEWS\*.ARJ /R2:270/17 /D10
  402.  
  403.         Would send those files matching C:\FD\NEWS\*.ARJ that have been
  404.         updated in the last ten days to 2:270/17.
  405.  
  406.  
  407.     NAMES.FD AND RECIPIENT NAMES
  408.  
  409.     When specifying a recipient (/R), you may use name macros listed in
  410.     NAMES.FD. This is indicated to XRobot by preceding the recipient with
  411.     an asterisk (*), e.g. XR SEND MYFILE.ARJ /R*JoHo would search for
  412.     "JoHo" in NAMES.FD and use the address (and SysOp name, if defined)
  413.     associated with that macro.
  414.  
  415.     If you do not want to use NAMES.FD, but want to specify a recipient
  416.     name instead of the default "SysOp", you may do so by putting a comma
  417.     (,) followed by the recipient's name after the network address, e.g.
  418.     XR SEND MYFILE.ARJ /R2:270/17,Joaquim_Homrighausen.
  419.  
  420.  
  421.     REQUESTING FILES WITH PASSWORDS
  422.  
  423.     To request a file that is protected by a password, you must supply the
  424.     password when you specify the filename (/F switch). The filename and
  425.     password must be separated by a comma (,) character. E.g.
  426.     /Fsecret.arj,mypassword would request the file SECRET.ARJ with a
  427.     password of "mypassword".
  428.  
  429.  
  430.  
  431.     FDOPT SETTINGS
  432.  
  433.         NOISCR  XRobot will by default remove SoftCR characters from text
  434.                 files before importing them into the body of a message.
  435.                 This may be inappropriate in some environments.
  436.  
  437.                 If the NOISCR string is present in the FDOPT environment
  438.                 variable, XRobot will preserve any SoftCR characters in
  439.                 text files that are used for message text.
  440.  
  441.         INTL    If this string is present in the FDOPT environment
  442.                 variable, it has the same effect as specifying /I on the
  443.                 command-line to XRobot.
  444.  
  445.  
  446.  
  447.     RESPONSE FILES
  448.  
  449.     XRobot is capable of using response files for input to the /F and /R
  450.     switches, as well as a global response file for all commands and
  451.     actions you want it to carry out.
  452.  
  453.     To indicate that you want to use a response file, XRobot requires that
  454.     you preced them with an @ character, e.g. @<response.fil>. This
  455.     instructs XRobot to read the file "RESPONSE.FIL" and take its input
  456.     from the file as opposed to from the command-line. This allows you to
  457.     create pre-defined "sets" of recipients and files to send or request
  458.     and then reuse them.
  459.  
  460.     The format of a response file is that of a plain vanilla ASCII file
  461.     with each line terminated by a <CR><LF> combination (although XRobot
  462.     should be able to handle a single <CR> or <LF> as the line
  463.     terminator).
  464.  
  465.     Text following a semi-colon (;) is ignored and can be used as comments
  466.     to make your response files more readable. The maximum line length is
  467.     255 characters.
  468.  
  469.     Here is an example of a response file given to the /F switch, we'll
  470.     call the file RESPONSE.FIL to keep things simple:
  471.  
  472.         [RESPONSE.FIL]:
  473.         ;This is a comment
  474.  
  475.         C:\AUTOEXEC.BAT C:\CONFIG.SYS               ;This too is a comment
  476.         C:\FD\NEWS\FIDO*.NWS C:\FD\FRODO\FD211.ARJ  ;And this..
  477.         [END]
  478.  
  479.         XR SEND /F@response.fil /R2:270/17
  480.  
  481.         would instruct XRobot to send all files listed in RESPONSE.FIL to
  482.         2:270/17. The [RESPONSE.FIL] and [END] text is simply used to
  483.         indicate the contents of the file, you should not put that in your
  484.         own response files.
  485.  
  486.     Another example, for use with the /R switch follows, again, we will
  487.     call the file RESPONSE.FIL:
  488.  
  489.         [RESPONSE.FIL]:
  490.         ;This is another useless comment
  491.  
  492.         2:270/18 1:170/400 255:3000/0 *JoHo
  493.         [END]
  494.  
  495.         XR SEND /FMYFILE.ARJ /R@response.fil
  496.  
  497.         would instruct XRobot to send MYFILE.ARJ to all recipients listed
  498.         in RESPONSE.FIL. Note the use of "*JoHo" which forces XRobot to
  499.         scan NAMES.FD for the macro "JoHo".
  500.  
  501.  
  502.  
  503.     One other very powerful concept of response files as implemented in
  504.     XRobot is the use of labels. This allows you to put several different
  505.     sets of pre-defined files and recipients in one physical file and
  506.     instruct XRobot which set to use.
  507.  
  508.     A label is specified in a response file by preceding the first word on
  509.     a line by a colon (:). The length of the label may not exceed 255
  510.     characters and must not contain any spaces. To specify a label in
  511.     conjunction with a response file, use the format @response.fil@label.
  512.     An example follows (again, the response file is called RESPONSE.FIL):
  513.  
  514.         [RESPONSE.FIL]:
  515.         ;My global XRobot response file
  516.  
  517.         :MYNET
  518.         2:270/18 2:270/3 2:270/7
  519.  
  520.         :USNET
  521.         1:170/400 1:107/574 1:234/567
  522.         [END]
  523.  
  524.         XR SEND /FMYFILE.ARJ /R@response.fil@mynet
  525.  
  526.         would instruct XRobot to send MYFILE.ARJ to all recipients
  527.         starting at the "MYNET" label.
  528.  
  529.     When you have specified a label, XRobot will first search for the
  530.     label, and if found, read all input until the next label is found, or
  531.     the end of the file is encountered. If you do not specify a label, the
  532.     entire response file is read (all labels are ignored).
  533.  
  534.     One other use of response files is supported by XRobot, a global
  535.     response file. This allows you to specify multiple actions to be taken
  536.     by XRobot. Normally, this would require several calls from the DOS or
  537.     OS/2 prompt (or .BAT/.CMD file).
  538.  
  539.     If a global response file is used, no other parameters will be honored
  540.     and all input is read from the response file. The global response file
  541.     is specified as XR @response.fil. E.g.
  542.  
  543.         [RESPONSE.FIL]:
  544.         ;Some comments
  545.         SEND /FMYFILE.ARJ /R2:270/17 /R2:270/18
  546.         GET /FFILES /R2:270/17
  547.         ;Some more comments
  548.         TEXT /FC:\TEXTS\NEWS.NOW /R2:270/18 /MC+
  549.         SEND /F@many.fil /R@many.rcp
  550.         [END]
  551.  
  552.     Note the use of response files in the last SEND command.
  553.  
  554.     Enjoy.
  555.  
  556.  
  557.  
  558.     UPDATE INFORMATION
  559.  
  560.         3.01
  561.  
  562.         When using the /T parameter to put the contents of an ASCII file
  563.         into a text message, the program would incorrectly leave a NUL
  564.         character between the extended message information ("kludge
  565.         lines") and the beginning of the message text.
  566.  
  567.     // end of file "xrobot.doc"
  568.