home *** CD-ROM | disk | FTP | other *** search
/ Media Share 9 / MEDIASHARE_09.ISO / bbs / fdrpr110.zip / FDRPR.DOC < prev    next >
Text File  |  1994-03-02  |  27KB  |  680 lines
  1. FDRPR 1.10 - FrontDoor Request Processor for RemoteAccess      2 Mar 1994
  2. -------------------------------------------------------------------------
  3.  
  4.     Copyright 1993, 1994 Mats Wallin            All rights reserved
  5.  
  6.  
  7.     Introduction
  8.     ------------
  9.  
  10.         FDRPR is a Request Processor for RemoteAccess. A Request
  11.         Processor is a program that FrontDoor executes whenever it
  12.         receives a file request. It is then the Request Processor
  13.         that processes the list of requested files, and returns
  14.         a list of files to FrontDoor, that FrontDoor then will
  15.         send.
  16.  
  17.         The advantage with a Request Processor, is that it can
  18.         be adapted for a special BBS program, or any other
  19.         program on the system that uses the Request Processor.
  20.  
  21.         This Request Processor uses the advantages of the file
  22.         system that RemoteAccess 2.00 and later versions uses.
  23.         This will speed up most file requests, especially for
  24.         systems using CD-ROMs, or accesses the file area over
  25.         a network. It will also, optionally, update the download 
  26.         counters for requested files.
  27.  
  28.         Another advantage of this Request Processor, is the possibility
  29.         to "check" a file request locally. E.g. you can run it
  30.         manually, and see what the result of a file request would
  31.         be for the system requesting files.
  32.  
  33.         One more advantage with this request processor, and that is
  34.         the possibility for it to return a message to the requesting
  35.         system, containing the descriptions of the requested files.
  36.  
  37.  
  38.  
  39.     Requirements
  40.     ------------
  41.  
  42.         FDRPR requires the following thing to run:
  43.  
  44.         * FrontDoor 2.11 or later
  45.  
  46.         * RemoteAccess 2.00 or later
  47.  
  48.         * The environment variable FD pointing to the directory 
  49.           where SETUP.FD is located, or SETUP.FD in the current 
  50.           directory
  51.  
  52.         * A list of requestable directories in the file specified 
  53.           in FDSETUP.
  54.  
  55.         * A list of alias file names, in the file specified in 
  56.           FDSETUP.
  57.  
  58.         * The environment variable RA pointing to the directory 
  59.           where CONFIG.RA is located, or CONFIG.RA in the current 
  60.           directory
  61.  
  62.  
  63.     Installation
  64.     ------------
  65.  
  66.         It's very easy to install FDRPR. All that is needed, is to
  67.         copy the files in the distribution archive to the directory
  68.         you would like it be in, and then type:
  69.  
  70.         FDRPR INSTALL
  71.  
  72.         The program will then make the necessary changes to your
  73.         SETUP.FD file, and FD will in the future use FDRPR when
  74.         a file request is received.
  75.  
  76.         You should probably also study, and modify, the included
  77.         FDRPR.CFG file, to make sure FDRPR behaves the way you
  78.         would prefer. 
  79.  
  80.  
  81.     How to use it
  82.     -------------
  83.  
  84.         FDRPR is executed by FrontDoor every time someone requests
  85.         a file. FDRPR needs some parameters to be able to know
  86.         what to do, and FrontDoor is capable of supplying these
  87.         parameters.
  88.  
  89.         The following is a list of the switches that FDRPR
  90.         supports. Switches can start either with a slash (/) or 
  91.         with a dash (-). All switches can be shortened to the shortest
  92.         unique name. The switches that accepts a value, can use
  93.         either a colon (:) or a equal character (=) between the
  94.         switch name and the actual value.
  95.  
  96.         /address:<aka>      Address of system requesting files
  97.         /bps:<bps>          BPS rate of connection
  98.         /check:<filename>   Check result of requesting specified file
  99.         /info:<filename>    Name of file containing info about
  100.                             requesting system. This parameter can be
  101.                             specified instead of /address, /bps and
  102.                             /operator
  103.         /minutes:<min>      Max # of minutes for the file request
  104.         /node:<task>        Task number
  105.         /operator:<name>    Name of SysOp requesting files
  106.         /request:<filename> Name of file containing requested files
  107.         /secure             Session is password protected
  108.         /target:<filename>  Name of file where found files should be written
  109.         /unsecure           Session is not password protected
  110.  
  111.         FrontDoor needs to fill in some information in the command
  112.         line, and to do that, it uses the same macros as it does
  113.         for Service Requests. The macros useful for FDRPR is:
  114.  
  115.         =A   The requesting system's network address. Eg.
  116.              2:270/17.
  117.  
  118.         =B   The baud rate of the connection. Eg. 9600.
  119.  
  120.         =E   Same as =T, but the filename does not include the
  121.              complete PATH.
  122.              (Only available with FD 2.11a / 2.20b or later 
  123.              versions).
  124.              This macro is prefered over the =T macro.
  125.  
  126.         =F   Name of file containing information about requesting
  127.              system.
  128.  
  129.         =H   Number of minutes until next event not allowing
  130.              file requests
  131.  
  132.         =M   Same as =F, but the filename does not include the
  133.              complete PATH.
  134.              (Only available with FD 2.11a / 2.20b or later 
  135.              versions).
  136.              This macro is prefered over the =F macro.
  137.  
  138.         =O   The operator of the requesting system. Eg.
  139.              Bilbo_Baggins.
  140.  
  141.         =Q   Same as =R, but the filename does not include the
  142.              complete PATH.
  143.              (Only available with FD 2.11a / 2.20b or later 
  144.              versions).
  145.              This macro is prefered over the =R macro.
  146.  
  147.         =R   Name of file containing requested files
  148.  
  149.         =T   Name of file where found files should be written
  150.  
  151.         =X   Whether or not the session is password protected.
  152.              This macro can have two values, SECURE or
  153.              UNSECURE.
  154.  
  155.         =Y   The current task number used by FD, or 0 in the
  156.              shareware version.
  157.  
  158.         =W   Whether or not the system requesting files is 
  159.              listed in your nodelist. This macro can have two
  160.              values, LISTED or UNLISTED.
  161.  
  162.         If the =O macro is used, it should be enclosed with double
  163.         quote characters (") characters to prevent DOS to treat 
  164.         some special characters, e.g. < > and |, in a way that would 
  165.         prevent FDRPR from working correctly.
  166.  
  167.         This means, that a typical command line to run FDRPR, would
  168.         look like this:
  169.  
  170.         FDRPR /REQUEST:=R /TARGET:=T /=X /INFO:=F /MINUTES:=H
  171.  
  172.         or, to make it shorter:
  173.  
  174.         FDRPR /R:=R /T:=T /=X /I:=F /M:=H
  175.  
  176.         An alternative command line would be:
  177.  
  178.         FDRPR /R:=R /T:=T /=X /A:=A /O:"=O" /B:=B /M:=H
  179.  
  180.         When using FD 2.11a or 2.20b, or later versions, the 
  181.         command line aboves should be replaced with:
  182.  
  183.         FDRPR /R:=Q /T:=E /I:=M /=X /M:=H /N:=Y /=W
  184.  
  185.         or
  186.  
  187.         FDRPR /R:=Q /T:=E /=X /A:=A /O:"=O" /B:=B /M:=H /N:=Y /=W
  188.  
  189.         In most cases, one of the lines above would be the one needed, 
  190.         and should be entered in 
  191.         FDSETUP->Mailer->File Requests->Request Processor->Program
  192.  
  193.         Even if it is possible to specify a fixed # of minutes for
  194.         a file request on the command line, it should be done in
  195.         FDSETUP. FDRPR uses that number in SETUP.FD, the
  196.         possibility to specify a number of minutes on the command
  197.         line should only be used to let FD specify the number of 
  198.         minutes left to next event not allowing file requests.
  199.  
  200.  
  201.     FDRPR commands
  202.     --------------
  203.  
  204.         There are a few commands that can be specified when running
  205.         FDRPR to do certain things. The following is a list of
  206.         these commands, and what they do:
  207.  
  208.         CREATE          Create list of directories/alias names
  209.         INSTALL         Install FDRPR in FrontDoor's setup
  210.         UPDATE          Update the list of directories/alias names
  211.  
  212.         The CREATE and UPDATE commands will create the *.RQU and 
  213.         *.RQS files from your FD and RA configuration. CREATE always
  214.         creates new files, UPDATE will only create them if any
  215.         of the original file have been updated.
  216.  
  217.         It's not necessary to use CREATE and/or UPDATE. Every time
  218.         FDRPR is run, it will check if it's needed to update these
  219.         files, and if it is, it is done on the fly. But to save 
  220.         time for the systems requesting files, it can be a good
  221.         idea to update them manually every time you've changed
  222.         your list of requestable directories, the list with alias
  223.         names, or your RA's file area configuration.
  224.  
  225.  
  226.     Configuration file
  227.     ------------------
  228.  
  229.         The behaviour of FDRPR can also be defined in a
  230.         configuration file. The configuration file should be located 
  231.         in the same directory as the .EXE file, and with the same 
  232.         basename (i.e. FDRPR if you don't rename it). The extension 
  233.         should either be .CFG, or, if you prefer to have one 
  234.         configuration file per task, .%TASK%. If the .%TASK% file
  235.         exists, it will always be used. The .CFG file is only used if
  236.         the .%TASK% file doesn't exist.
  237.  
  238.         Many of the switches can either be specified as 'switch' or
  239.         'noswitch'. The setting is enabled when no isn't used, and
  240.         disabled when no is used.
  241.  
  242.         There are some macros that can be used in the configuration
  243.         file, to make maintainance easier. When using these macros,
  244.         they should be begin with the characters percent (%) and 
  245.         left bracket ([) and end with a right bracket (]). E.g. 
  246.         The macro CFGDIR should be written as %[CFGDIR]. Besides the
  247.         macros listed below, all environment variables can also be 
  248.         used as macros.
  249.  
  250.         The following macros exists:
  251.  
  252.         CfgDir
  253.                 This macro translates to the directory where the 
  254.                 FDRPR.CFG file is located. It can be useful
  255.                 when specifying the location of other files.
  256.  
  257.  
  258.         The following switches is available in the configuration
  259.         file:
  260.         
  261.         [no]advert              
  262.                 If enabled, FDRPR will add a text stating that 
  263.                 the message was created by FDRPR. It is not 
  264.                 possible to disable this in the unregistered version.
  265.  
  266.  
  267.         [no]cdrom               
  268.                 If enabled, FDRPR will use the CD-ROM settings in
  269.                 RACONFIG, and have the same kind of CD-ROM support
  270.                 that RA has, e.g. to make sure no other line
  271.                 currently uses the same device, and then copy the 
  272.                 requested file to the temporary CD-ROM directory.
  273.  
  274.  
  275.         [no]descriptions        
  276.                 If enabled, FDRPR will send a message with file
  277.                 descriptions for all successfully requested files.
  278.         
  279.  
  280.         [no]freefiles           
  281.                 If enabled, FDRPR will honor the Free File setting
  282.                 for a file or file area, and not perform any limit
  283.                 checks for these files.
  284.  
  285.  
  286.         [no]moretime
  287.                 If enabled, FDRPR will request more time from the
  288.                 remote mailer, to be able to process the entire
  289.                 request, if needed. If this setting is disabled, 
  290.                 the remote mailer will probably disconnect the line
  291.                 if FDPRQRA requires more then 30 seconds to finish
  292.                 the search.
  293.  
  294.  
  295.         [no]passworderrors
  296.                 If enabled, FDRPR will include all files that should
  297.                 have been sent if the correct password was used, in 
  298.                 the message with the list of failed requests. By
  299.                 default, only the requested filename will be included
  300.                 in the message.
  301.  
  302.                 NOTE! The reason this option is disabled by default, is 
  303.                       that it could be a big security risk to inform
  304.                       another system that there is a file available,
  305.                       which requires a password.
  306.  
  307.  
  308.         [no]reportfailures
  309.                 If enabled, FDRPR will create a netmail message
  310.                 to you with information about failed file requests.
  311.  
  312.  
  313.         [no]reportrequests
  314.                 If enabled, FDRPR will create a netmail message
  315.                 to you with information about successful file requests.
  316.  
  317.  
  318.         [no]resolvepath
  319.                 If enabled, FDRPR uses path resolution when trying
  320.                 to compare the paths specified in RACONFIG, and the
  321.                 paths listed in your list of requestable directories
  322.                 and aliasnames. This ensures that FDRPR always
  323.                 will be able to match these paths correct.
  324.                 However, in some environments, this seems to fail.
  325.                 I'm aware of one CD-ROM interface which doesn't
  326.                 seem to support this correctly. If you're having
  327.                 problems with file areas that are not recognized by
  328.                 FDRPR, disable this option.
  329.  
  330.                 The resolvepath setting can in some CD-ROM environments 
  331.                 (OS/2?) also slow down the creation of the lists of
  332.                 requestable directories/alias names. If this seems to
  333.                 take a long time to run, try to specify noresolvepath.
  334.  
  335.  
  336.         [no]updcount
  337.                 If enabled, FDRPR will update the download counters
  338.                 for all successfully requested files
  339.  
  340.  
  341.         [no]logfile:<file>
  342.                 If this setting is specified as LOGFILE:<file>, log
  343.                 information will be written to the specified logfile. 
  344.                 If NOLOGFILE is specified, no loggin will be performed. 
  345.                 If neither LOGFILE or NOLOGFILE is specified, log 
  346.                 information will be written to FD's logfile.
  347.                 
  348.                 Errors detected during initialization will always be
  349.                 written to FD's logfile, ignoring this setting.
  350.  
  351.  
  352.         workdir:<dir>
  353.                 The directory where the temporary .PKT files are
  354.                 created, before FD sends them to the destination.
  355.                 If this parameter is not specified, the .PKT files
  356.                 will be written to the directory pointed to by
  357.                 the TEMP or TMP environment variable. If neither of
  358.                 these environment variables are specified, the .PKT
  359.                 file will be written to the root directory of the
  360.                 current drive.
  361.  
  362.  
  363.         message:<file>
  364.                 File containing a template of the text that should
  365.                 be used for the message with descriptions of the
  366.                 successfully requested files, which is sent to
  367.                 the requesting system.
  368.  
  369.                 See below for information about these message
  370.                 templates.
  371.  
  372.  
  373.         failmessage:<file>
  374.                 File containing a template of the text that should
  375.                 be used for the message with the reason for a failed
  376.                 request, which is sent to the requesting system.
  377.  
  378.                 See below for information about these message
  379.                 templates.
  380.  
  381.  
  382.  
  383.     Message templates
  384.     -----------------
  385.  
  386.         The exact contents and layout of the messages that are sent
  387.         to the requesting system, can be decided by the SysOp. Two
  388.         different messages can be sent; the message containing file
  389.         descriptions for successfully requested files, and the
  390.         message with reasons why a request failed.
  391.  
  392.         Each message should have it's own template, e.g. a file 
  393.         describing the format and contents. The names of these files
  394.         are defined in the configuration file.
  395.  
  396.         The template files are just normal textfiles, that can be
  397.         created/edited in any text editor. It's possible to insert
  398.         some unique text in each message, and to do that, a macro
  399.         is used. The exact format of the lines with file descriptions
  400.         and reasons for request failures can also be configured.
  401.  
  402.         When using a macro, it should begin with the characters
  403.         percent (%) and left bracket ([), and end with a right 
  404.         bracket (]). E.g. The macro TOTALSIZE should be written 
  405.         as %[TOTALSIZE]. Either lower or upper characters can be 
  406.         used, there is no difference between them.
  407.  
  408.         A macro that requires parameters, should have the parameters
  409.         inside the [] characters. Ex: %[Include C:\FD\FILE.TXT].
  410.  
  411.         The following macros exists:
  412.  
  413.         PrgName
  414.                 The name of the request processor
  415.  
  416.         Version
  417.                 The version of the request processor
  418.                 
  419.         YourName 
  420.                 The full name of the SysOp requesting files
  421.  
  422.         YourFirstName
  423.                 The first name of the SysOp requesting files
  424.  
  425.         YourLastName
  426.                 The last name of the SysOp requesting files
  427.  
  428.         YourAka
  429.                 The address of the requesting system
  430.  
  431.         MyName
  432.                 Your name, as defined in FDSETUP
  433.  
  434.         MyFirstName
  435.                 Your first name, as defined in FDSETUP
  436.  
  437.         MyLastName
  438.                 Your last name, as defined in FDSETUP
  439.  
  440.         MyAka
  441.                 Your address. FDRPR will use AKA matching when
  442.                 deciding which address should be used
  443.  
  444.         FileCnt
  445.                 The number of found files, which will be sent to the
  446.                 requesting system
  447.  
  448.         FailCnt
  449.                 The number of requests that failed
  450.  
  451.         TotalSize
  452.                 The number of bytes that will be sent
  453.  
  454.         TotalSizeK
  455.                 The number of kilo bytes that will be sent
  456.  
  457.         Include <file>
  458.                 Insert contents of <file> in message
  459.                 <file> can also contain macros 
  460.  
  461.         Aliases
  462.                 Insert list of all alias names that can be requested. 
  463.                 If the alias file (the one defined in FDSETUP)
  464.                 contains comments, these comments will be included in
  465.                 this list. 
  466.                 A comment in the alias file is added at the end of
  467.                 a line with an alias name, after a ; character.
  468.  
  469.         IfFile <file1> <file2>  
  470.                 If <file1> will be sent to the requesting system,
  471.                 the contents of <file2> will be added to the message
  472.                 that is sent.
  473.                 <file1> should only specify the filename, not a drive
  474.                 or directory, but can contain wildcard characters.
  475.                 <file2> can also contain macros
  476.  
  477.         If a macro is used, that is not in the list above, FDRPR
  478.         will check to see if it is an environment variable, and if it
  479.         is, use it. An example of an environement variable that could
  480.         be useful, is TASK.
  481.  
  482.         Each template should contain ONE line that is used to format
  483.         the file descriptions / request failure reasons. The line
  484.         should start with either a @ or # character. This line can
  485.         contain normal text, or some format codes.
  486.         
  487.         Both @ and # can be used with all formatting codes, the
  488.         difference is that codes beginning with a # character,
  489.         and resulting in a numeric value, will have it's value
  490.         zero padded to the left, while codes beginning with a @
  491.         will not.
  492.  
  493.         The length of each formatting is decided by appending some
  494.         underscore (_) characters after the format code. The length 
  495.         of the field will be the total length of the format code, 
  496.         and the underscore characters following directly after.
  497.  
  498.         The format codes that are available for the message with
  499.         file descriptions are:
  500.  
  501.                 @C      - The description of the file
  502.                 @D      - The date of the file
  503.                 @F      - The name of the file
  504.                 @K / #K - The size of the file, in kilobytes
  505.                 @S / #S - The size of the file, in bytes
  506.                 @T / #T - The number of downloads for this file
  507.  
  508.         The exact format of the @D code depends on the length of the
  509.         field, and the DOS country setting. The following formats are 
  510.         possible:
  511.  
  512.                 10 Sep 1993
  513.                 10 Sep 93
  514.                 10-09-93
  515.                 09-10-93
  516.                 93-09-10
  517.                 100993
  518.                 091093
  519.                 930910
  520.  
  521.         An example of a formatting line could be:
  522.  
  523.         @F__________  @K__k @D______ [#T] @C_______________________________
  524.  
  525.         Which would result in:
  526.  
  527.         FDRPR110.ARJ    40k 93-09-10 [05] FD Request Processor for RA
  528.  
  529.  
  530.  
  531.         The format codes that are available for the message with
  532.         request failure reasons are:
  533.  
  534.                 @F      - The name of the requested file
  535.                 @R      - The reason the request failed
  536.  
  537.  
  538.  
  539.     The lists of requestable directories and alias names
  540.     ----------------------------------------------------
  541.  
  542.         FDRPR will create some files containing information
  543.         about the requestable directories and the alias filenames.
  544.         These files will be stored in the same directory and with 
  545.         the same name, as the files specified in FDSETUP, but with
  546.         another extension. The extension used is .RQS for the files
  547.         used during secure sessions, and .RQU for the files used 
  548.         during unsecure sessions.
  549.  
  550.         These files will be maintained automatically by FDRPR,
  551.         and is updated every time the list of requestable
  552.         directories, alias names, or FILES.RA, is modified. It is 
  553.         important that these file are not removed, since it is much 
  554.         slower to create them every time, then to use them from the 
  555.         last run.
  556.  
  557.         IMPORTANT!  If your lists of requestable directories or
  558.                     list of alias names, uses the .RQS or .RQU 
  559.                     extensions, make sure that you changes this 
  560.                     to another extension. If you don't rename 
  561.                     the file, FDRPR will overwrite your list 
  562.                     with it's own list.
  563.                     It is also important that your list of
  564.                     requestable directories, and the list of
  565.                     alias names, doesn't have the same basename 
  566.                     (the name before the extension). If they have, 
  567.                     FDRPR will not work properly, since it then 
  568.                     will overwrite its own files.
  569.  
  570.  
  571.         If your list with requestable directories contains a
  572.         directory which isn't defined as a file area in RemoteAccess,
  573.         FDRPR will switch over to the same kind of request
  574.         processing as FrontDoor does, e.g. to scan all the files
  575.         in that directory. This makes it possible to have a directory
  576.         with files that should be requestable, but not available from
  577.         the BBS.
  578.  
  579.         If a directory should be available for both unsecure and
  580.         secure sessions, it is sufficient to specify this directory
  581.         in the file with directories for unsecure sessions. FDRPR will
  582.         read both files for a secure session. This makes maintainence
  583.         easier, since you don't have to update two files with the same
  584.         directory names.
  585.  
  586.         The files with alias names are handled in the same way, so
  587.         it's sufficient to list alias names that should be available
  588.         for both unsecure and secure sessions in the file for unsecure
  589.         sessions.
  590.  
  591.  
  592.  
  593.     Alias definitions
  594.     -----------------
  595.  
  596.         Normally, an alias definition that uses a wildcard in the
  597.         filename that should be sent, sends all files that matches
  598.         this wildcard name. 
  599.  
  600.         If you would prefer that only the newest file matching
  601.         the wildcard name is sent, use a vertical bar (|) character
  602.         instead of the asterisk (*) in the filename. E.g.
  603.  
  604.         NODELIST    C:\FILES\FIDO\NODELIST.A*
  605.  
  606.         could be replaced with
  607.  
  608.         NODELIST    C:\FILES\FIDO\NODELIST.A| 
  609.         
  610.  
  611.  
  612.     Use FDRPR to test file requests locally
  613.     -----------------------------------------
  614.  
  615.         FDRPR could be used to check a file request locally, to
  616.         get some information why a certain file request fails, or
  617.         just to test your setup.
  618.  
  619.         To run FDRPR like this, enter the following command:
  620.  
  621.         FDRPR /CHECK:<file>
  622.  
  623.         To test a file request that requires a password, use the
  624.         following command:
  625.  
  626.         FDRPR /CHECK:"<file> !<password>"
  627.  
  628.         To test more then one file request at the same time, use the
  629.         following command:
  630.  
  631.         FDRPR /CHECK:"<file1> [!<pwd1>],<file2> [!<pwd2>][,...]"
  632.  
  633.         To make the request more realistic, you can also add any of
  634.         the other switches. But the only switches that would make
  635.         any difference, is the /SECURE and the /BPS:<bps> switches,
  636.         and the /ADDRESS switch, which would have FDRPR create the
  637.         PKT file it should have sent to the requesting system.
  638.  
  639.  
  640.  
  641.     Legal notice
  642.     ------------
  643.  
  644.         FDRPR is provided to you as is, without warranty of any
  645.         kind. In no event shall Mats Wallin be liable to you or
  646.         anyone else for any damages or costs arising from the use
  647.         or inability to use this program.
  648.  
  649.         FDRPR is protected by copyright laws, and may not be 
  650.         modified, reversed engineered, sold or distributed in any
  651.         way that would involve some sort of trade, without written
  652.         permission from Mats Wallin.
  653.  
  654.         FrontDoor is a trademark of Joaquim Homrighausen.
  655.  
  656.         RemoteAccess is a trademark of Wantree Development.
  657.  
  658.  
  659.  
  660.     Registering
  661.     -----------
  662.  
  663.         FDRPR may be used during a 30 day trial period to allow
  664.         you to determine its suitability for your particular
  665.         application. After this trial period you must register
  666.         the program, if you are continuing to use it.
  667.  
  668.         Please see the file REGINFO.TXT for information on
  669.         how to register FDRPR.
  670.  
  671.  
  672.     Bug reports, suggestions, etc.
  673.     ------------------------------
  674.  
  675.         If you find any bugs, or have suggestions or comments on 
  676.         this program, I would appreciate if you would let me know.
  677.         Send the information to me at:
  678.  
  679.         2:201/329@fidonet       or      mw@fido.lu
  680.