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