home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 2 BBS / 02-BBS.zip / MSGXP200.ZIP / MSGX.DOC < prev    next >
Text File  |  1992-05-04  |  23KB  |  542 lines
  1.      
  2.      
  3.      
  4.      
  5.      
  6.      
  7.      
  8.                                    MsgX
  9.      
  10.                         Message Extraction Utility
  11.                                         
  12.                                Version 2.00
  13.                                         
  14.                                         
  15.                                         
  16.                                         
  17.                                         
  18.                                         
  19.                                         
  20.                                         
  21.                                         
  22.                                         
  23.                                         
  24.                                         
  25.                                         
  26.                                 Dave Fisher
  27.                                         
  28.                         LiveNet, 1:170/110@fidonet
  29.      
  30.      
  31.      Description
  32.      
  33.      MsgX is a message extraction program that will select messages
  34.      from any *.MSG or Squish formatted area base and store them in a
  35.      text file or archive.  MsgX can extract messages based on date
  36.      ranges (see /Date) or on specified number of messages (see
  37.      /LimitSize).
  38.      
  39.      MsgX is mainly intended to act as an archival, storage, and
  40.      management tool for message areas (national echos or local) and
  41.      can be run on a daily, weekly, or monthly basis.  The collected
  42.      messages can optionally be compressed into an archive using your
  43.      favorite archival program.  If desired, MsgX will also add an
  44.      entry in the specified FILES.BBS for the newly created archive.
  45.      
  46.      MsgX can archive multiple areas to one archive in a single pass.
  47.      
  48.      If you are running MsgX under OS/2, you will need the file
  49.      MSGAPI.DLL in one of the directory paths specified using the
  50.      LIBPATH variable.
  51.      
  52.      If you are running MsgX under DOS, please note that this program
  53.      may not work on 8086 processors.  Supported processors are 80286
  54.      and above.
  55.      
  56.      Current message area formats supported are Squish and *.MSG
  57.      areas.
  58.      
  59.      Usage
  60.      
  61.      MsgX [@CtlFile] AreaTag(OutputFile) [, AreaTag(OutputFile), ...]
  62.           /[no]AppendMsgs                   default: NoAppendMsgs
  63.           /Archive = <path+file name>       default: "Constructed"
  64.           /[no]Compress                     default: NoCompress
  65.           /Config = <path+file name>        default: MsgX.Cfg
  66.           /[no]Control                      default: NoControl
  67.           /Dates = (from_date, to_date)     default: All dates
  68.           /Description = "<filesbbs desc>"  default: "Constructed"
  69.           /[no]Kill                         default: NoKill
  70.           /LimitSize = <number of messages> default: No Limit
  71.                OR
  72.           /LimitSize = (threshold, del cnt) default: No Limit
  73.           /[no]Log                          default: NoLog
  74.           /LogFile = <path+file name>       default: None
  75.           /LogLevel = <1..4>                default: 4
  76.           /Margin = <right margin>          default: 79
  77.           /[no]Quiet                        default: NoQuiet
  78.           /[no]Seenbys                      default: NoSeenBys
  79.           /Skip = <number of messages>      default: 0
  80.           /[no]Statistics                   default: Statistics
  81.           /Title = "<header title>"         default: "Constructed"
  82.           /[no]Update                       default: NoUpdate
  83.           /[no]Write                        default: Write
  84.      
  85.      Notes on the syntax:
  86.      
  87.           Qualifiers can appear in any order, and are only significant
  88.           to four characters.  Thus, /Statistics is the same as /Stat.
  89.           
  90.           If a qualifier follows a quote mark ("), please separate
  91.           with a space.  For example, the following line is incorrect:
  92.           
  93.           /description = "Mens Issue Forum"/noseenbys/update
  94.           
  95.           The following is correct:
  96.           
  97.           /description = "Mens Issue Forum" /noseenbys/update
  98.           
  99.           Normally, qualifiers can be next to each other, but due to
  100.           technicalities with the language used for MsgX and the
  101.           operating system, the above caveat applies.
  102.      
  103.      Disclaimer!
  104.      
  105.      This program is shareware.  There is absolutely no warranty for
  106.      this program or guarantee that it will work.  The user of the
  107.      program assumes all risk.  While I feel confident that this
  108.      program will not harm your system in any way, by using this
  109.      program, you agree to assume full responsibility for any adverse
  110.      effect to your system.
  111.      
  112.      Ok.  Now with that out of the way -- please send me mail and let
  113.      me know if you are using MsgX!  I'd like to get an idea of
  114.      whether this program has been useful for others, as it has been
  115.      for me.  Also, please send any comments, suggestions and/or
  116.      problem reports.  I can be reached at:
  117.      
  118.           Dave Fisher
  119.           LiveNet, 1:170/110@fidonet.org
  120.           
  121.           
  122.      
  123.      Parameters
  124.      
  125.      @CtlFile
  126.      ---------------------------------------------------------
  127.      
  128.      If a control file is specified, all command line parameters and
  129.      qualifiers will be read form that file instead of the command
  130.      line itself.  This is helpful is you have too many options or
  131.      areas specified, and they will not fit on the command line due to
  132.      the limitation imposed from the operating system.
  133.      
  134.      If @CtlFile is specified, do not specify any other parameters on
  135.      the command line.  For example:  "MsgX @c:\bbs\msgxos2" is valid
  136.      whereas "MsgX @c:\bbs\msgxos2 /Date=( previous week )" is not.
  137.      In this example, /Date should be written in msgxos2.ctl.
  138.      
  139.      If an extention is not specified, MsgX will default to the
  140.      extension to .CTL.  See file Example.Ctl for more information.
  141.      
  142.      
  143.      AreaTag(Output_File_Name)
  144.      ---------------------------------------------------------
  145.      
  146.      This parameter is the areatag name as specified in Maximus's
  147.      message control file (usually named MSGAREA.CTL).  You can
  148.      specify as many tag names as will fit on the command line.
  149.      Separate each tag name with a comma.  Note that local message
  150.      areas and the netmail area do not have "echotag" names.  In order
  151.      to extract messages from these areas, you will have to specify
  152.      the name of the area as defined by the "Area [name]" statement in
  153.      MSGAREA.CTL.  For echos, use the "MsgName [name]" names.
  154.      
  155.      AreaTag may include wildcard match characters '*' for multiple
  156.      character matches, and/or '?' for single character matches.
  157.      
  158.      An optional file name may also be specified within parenthesis.
  159.      This is the name of the text file that will be created.  This
  160.      text file includes a very short header and then all the collected
  161.      messages from the area.
  162.      
  163.      If the /Compress option is enabled, the files will be created
  164.      within the Work Directory.  They will be deleted after they are
  165.      successfully compressed.  Therefore, do not specify a path for
  166.      the text files if you are compressing them.  If you are not
  167.      compressing the files, then Output_File_Name can have a fully
  168.      qualified path.  If it does not, the file will be created in the
  169.      current directory.
  170.      
  171.      The output file name can include one or more of the following
  172.      date expansion macros:
  173.      
  174.          %a - The abbreviated weekday name
  175.          %A - The full weekday name
  176.          %b - The abbreviated month name
  177.          %B - The full month name
  178.          %d - Day-of-month as a decimal (01-31)
  179.          %j - Day-of-year as a decimal (001-365)
  180.          %J - Day-of-year as a year/julian decimal (n001-n365)
  181.               where 'n' is the last digit of the year
  182.          %m - Month as a decimal (01-12)
  183.          %w - Weekday as a decimal (1-7), Sunday being 1,
  184.                                           Saturday 7
  185.          %W - Weekday as a decimal (1-7), Monday being 1,
  186.                                           Sunday 7
  187.          %y - Year without century (00-99)
  188.          %Y - Year including century (1970-2069)
  189.      
  190.      All macros are expanded based on the TO date of the date range.
  191.      Please note that each macro is case sensitive.
  192.      
  193.      NOTE:  If no file name is given within, the default file name
  194.      will be the AreaTag name with the extension of .TXT.
  195.      
  196.      For example:
  197.      
  198.           MsgX OS2BBS, OS2, OS2LAN, OS2HW, OS2DOS
  199.                /Dates = ( previous week )
  200.                /Archive = c:\max\files\echos\OS%y%m%d
  201.                /Compress
  202.                /Update
  203.      
  204.      This will extract all messages from the indicated areas for the
  205.      previous week.  They will be stored in individual text files
  206.      named OS2BBS.TXT, OS2.TXT, etc. and compressed within one archive
  207.      named OS920321.ZIP (if the end of the week was March 20, 1992 and
  208.      the archive method was PKZIP).
  209.      
  210.      The example could have also been written like this:
  211.      
  212.           MsgX OS2BBS(OA%y%m%d), OS2(OB%y%m%d), OS2LAN(OC%y%m%d),
  213.                OS2HW(OD%y%m%d), OS2DOS(OE%y%m%d)
  214.                /Dates = ( previous week )
  215.                /Archive = c:\max\files\echos\OS%y%m%d
  216.                /Compress
  217.                /Update
  218.      
  219.      Where each individual text file is now named with the year,
  220.      month, and day as the archive.
  221.      
  222.      MsgX will automatically determine whether the area is Squish or
  223.      *.MSG format.
  224.      
  225.      
  226.      Qualifiers
  227.      
  228.      /[no]AppendMsgs
  229.      ---------------------------------------------------------
  230.      
  231.      The qualifier will first extract any text files from the
  232.      specified archive into the Work Directory.  Any extracted
  233.      messages will then be appended to these files (if the file names
  234.      match the files that were in the archive, of course).
  235.      
  236.      Appending messages is the default behavior of MsgX.  So if a file
  237.      was left in the Work Directory by mistake and that file matched
  238.      the name of the current extraction, there is a risk that messages
  239.      will be appended to that file.  Thus, it is a good idea to let
  240.      MsgX take full control of the Work Directory.
  241.      
  242.      /Archive
  243.      ---------------------------------------------------------
  244.      
  245.      If the /Compress qualifier is active, you can specify the name of
  246.      the archive.  (MsgX will ignore an extension if you put one on
  247.      it.)
  248.      
  249.      If you are only extracting ONE area and do not specify an archive
  250.      name with /Archive (or in the configuration file), MsgX will
  251.      create an archive with the same base name as the text file of
  252.      messages.
  253.      
  254.      If you are extracting MULTIPLE areas and do not specify an
  255.      archive name with /Archive (or in the configuration file), MsgX
  256.      will create the archive ECHOS.ZIP in the current directory.
  257.      
  258.      The archive name can be a fully qualified path and may include
  259.      any of the date expansion macros (%d, %m, etc.).
  260.      
  261.      /[no]Compress
  262.      ---------------------------------------------------------
  263.      
  264.      This qualifier allows you to compress the output file(s) into a
  265.      .ZIP archive.  If extracting only one area, the name of the
  266.      archive will be identical to the output file name, except the
  267.      extension will be changed to .ZIP.  If extracting multiple areas,
  268.      the name of the archive must be specified using /Archive.
  269.      
  270.      If the archive exists, new message text files will either be
  271.      added or updated in the archive.  If the archive does not exist,
  272.      then a new one will be created.
  273.      
  274.      After the archive is successfully created or updated, the
  275.      original uncompressed output text file(s) will be deleted.
  276.      
  277.      Config = <path+file name>
  278.      ---------------------------------------------------------
  279.      
  280.      This is the name of the configuration file.  The default is
  281.      MsgX.Cfg in the current directory.  You can also define the
  282.      environment variable MSGX_CONFIG=<path+file name> instead of
  283.      using this qualifier.
  284.      
  285.      /[no]Control
  286.      ---------------------------------------------------------
  287.      
  288.      This qualifier controls whether CONTROL information (such as
  289.      PATH, REALNAME, etc) should be included in the message.  The
  290.      default is /NoControl.
  291.      
  292.      /Dates=(from_date, to_date)
  293.      ---------------------------------------------------------
  294.      
  295.      This qualifier will designate which dated messages should be
  296.      selected from the area.  Messages will be selected based on the
  297.      date they were received into the BBS (not the date the message
  298.      was written).
  299.      
  300.      The 'from_date' and 'to_date' is formatted as dd-mmm-yyyy.  For
  301.      example, January 1, 1992 is represented as 1-Jan-1992, December
  302.      25, 1991 as 25-Dec-1991, etc.
  303.      
  304.      The following keywords can be used in place of 'from_date' and
  305.      'to_date':
  306.      
  307.          /date = ( current month )
  308.          /date = ( current week )
  309.          /date = ( current day )
  310.      
  311.          /date = ( previous month )
  312.          /date = ( previous week )
  313.          /date = ( previous day )
  314.      
  315.      The calculated 'current' or 'previous' date will be relative to
  316.      the current computer date/time.  These keywords can be very
  317.      helpful if you want to have the messages archived automatically
  318.      at the end of the week or month.
  319.      
  320.      /Description = "<filesbbs desc>"
  321.      ---------------------------------------------------------
  322.      
  323.      If you choose the /Update option, you can specify the description
  324.      line for the archive file.  This description line may include any
  325.      of the date expansion macros available (%m, %y, etc.).
  326.      
  327.      If the archive already existed, and message text files were
  328.      therefore added or updated, the FILESBBS will not be updated.
  329.      The file will only be updated when a new archive has been
  330.      created.
  331.      
  332.      /[no]Kill
  333.      ---------------------------------------------------------
  334.      
  335.      This will kill any messages that are successfully extracted.  If
  336.      /NoWrite is specifed, messages will still be deleted.  This gives
  337.      MsgX the ability to manage the size and/or content of a message
  338.      base.
  339.      
  340.      /LimitSize = <number of messages>
  341.      /LimitSize = ( threshold, delete_count )
  342.      ---------------------------------------------------------
  343.      
  344.      This qualifier has two possible meanings, depending upon the
  345.      number of parameters used.  In both cases, this qualifier will
  346.      override any date ranges specified.  If /Compress is specified,
  347.      messages will first be archived and then deleted.
  348.      
  349.      If you wish to save the first or so messages, be sure to specify
  350.      /Skip.
  351.      
  352.      The first form indicates the final size of the message base.
  353.      Thus, if there are 212 messages in the message base and
  354.      /LimitSize=200 is indicated, the first 12 messages will deleted
  355.      (unless /Skip is used, in which case the first 12 messages after
  356.      the specified number of messages are skipped).
  357.      
  358.      The second form indicates that a certain number of messages
  359.      (delete_count) should be deleted only if there are 'threshold'
  360.      number of messages already there.  For example, if there are 212
  361.      messages in the message base and /LimitSize=( 200, 50 ), then the
  362.      first 50 messages will be extracted from the message base,
  363.      resulting in a final message base size of 162.  If SMOG were run
  364.      again, then nothing would be extracted since 162 is less than 200
  365.      messages.  Once again, if /Skip is specified, then the specified
  366.      number of messages will first be skipped.
  367.      
  368.      /[no]Log
  369.      ---------------------------------------------------------
  370.      
  371.      This qualifier will turn the logging function on and off.
  372.      
  373.      /LogFile = <path+file name>
  374.      ---------------------------------------------------------
  375.      
  376.      This qualifier defines the name of the log file.
  377.      
  378.      /LogLevel = <1..4>
  379.      ---------------------------------------------------------
  380.      
  381.      This qualifier defines the level of message detail in the log
  382.      file.  Level 1 is the least detailed, while Level 4 is the most
  383.      verbose.  The levels indicate the 'importance' of a message,
  384.      where Level 1 is the most important (usually error messages).
  385.      
  386.      /Margin=<right margin>
  387.      ---------------------------------------------------------
  388.      
  389.      This qualifier will control the length of the line for each
  390.      message.  The default is 79, but can be changed to anything
  391.      between 1 and 132.
  392.      
  393.      /[no]Quiet
  394.      ---------------------------------------------------------
  395.      
  396.      This qualifier controls whether the program should emit an
  397.      printed output.  If /Quiet, the only output will be the program
  398.      copyright line and any error messages.  The default is /NoQuiet.
  399.      
  400.      /[no]Seenbys
  401.      ---------------------------------------------------------
  402.      
  403.      This qualifier controls whether the SEENBY's lines should be
  404.      included in the message extraction.  The default is /NoSeenBy.
  405.      
  406.      /Skip = <number of messages>
  407.      ---------------------------------------------------------
  408.      
  409.      This qualifier specifies the number of message to skip before
  410.      attempting an extraction and/or deletion.
  411.      
  412.      If you are extracting or deleting from a Squish message base,
  413.      this qualifier will be ignored since MsgX will set the number of
  414.      messages to skip based on the "-$s" command in Squish.Cfg.
  415.      
  416.      /[no]Statistics
  417.      ---------------------------------------------------------
  418.      
  419.      This qualifier will produce a day-by-day and summary statistical
  420.      analysis of the messages received.  Information includes average
  421.      messages per day, average bytes per day, largest message size,
  422.      etc.  The default is /Statistics.
  423.      
  424.      
  425.      /Title = "<header title>"
  426.      ---------------------------------------------------------
  427.      
  428.      This qualifier will override the default header title for the
  429.      message text file.  Normally, MsgX will center a title at the top
  430.      of the file of extracted messages.  This title is either derived
  431.      from the MsgInfo statement in the MsgArea.Ctl file, or
  432.      constructed from the area tag name (if the area definition was
  433.      read from Squish.Cfg or Areas.Bbs).  In the latter case, all
  434.      underscores will be replaced with spaces, and words will be
  435.      capitalized.
  436.      
  437.      This default construction can be overriden if /Title is
  438.      specified.  However, please note that if you have specified
  439.      multiple areas (or wildcards) that this title will be displayed
  440.      at the top of each file.  Thus, if you would like to customize
  441.      the title, you may want to only specify one area per run of MsgX.
  442.      
  443.      /[no]Update
  444.      ---------------------------------------------------------
  445.      
  446.      This qualifier tells MsgX to update the file indicated by
  447.      /FilesBBS.
  448.      
  449.      If you do not specify a description (using /Description), then
  450.      the line added to this file will be in the following format:
  451.      
  452.      If running MsgX for only ONE area:
  453.      
  454.           <Archive file name> <Title> - <Date Range>, where 'Title' is
  455.           the name of the area from you Maximus message area control
  456.           file (MsgInfo statement).
  457.      
  458.      If running MsgX for multiple areas:
  459.      
  460.           <Archive file name> <Title> - <Date Range>, where 'Title' is
  461.           a list of area tag names, separated by commas.
  462.           
  463.      If a the file specified by /FilesBBS does not exist, one will be
  464.      created.
  465.      
  466.      /[no]Write
  467.      ---------------------------------------------------------
  468.      
  469.      This qualifier will control whether the output text file will
  470.      created.  At first glance, this may seem like a silly qualifier
  471.      since this is the primary purpose of MsgX!  However, MsgX also
  472.      does a brief analysis of the entire area and will display some
  473.      statistical information about the area.  If you only want the
  474.      statistical information, you can specify /NoWrite, and an output
  475.      file will not be created.
  476.      
  477.      
  478.      Examples
  479.      
  480.      The following examples are broken apart on several lines for
  481.      display reasons.  They would be entered on one line when actually
  482.      executed.
  483.      
  484.      Msgx MENS_ISSUES(men%%y%%b.txt)
  485.           /Desc="Men's Issues Forum for the Month of %b, %y"
  486.           /Archive=c:\max\files\echos\men%%y%%b
  487.           /noseenbys/nocontrol
  488.           /dates=( current month )/compress/update
  489.      
  490.      The above command exists in a batch file.  Notice the double
  491.      percent signs (%%).  This is necessary since we are not
  492.      indicating a batch substitution, and want the batch file to
  493.      ignore the percent sign.  Only one percent sign will actually be
  494.      passed to MsgX.  If today's date is February 29, 1992, MsgX will
  495.      create the file Men92Feb.txt and archive this to the file
  496.      \max\files\echos\Men92Feb.Zip.
  497.      
  498.      MsgX os2 /dates=( previous week )
  499.      
  500.      If the current date is February 12, 1992, MsgX will create the
  501.      file Os2.txt in the current directory.  This is the week of Feb
  502.      2, 1992 to Feb 8, 1992.
  503.      
  504.      The following is a OS/2 .CMD file that runs MsgX:
  505.      
  506.      /*----------------------------------------------------------*
  507.       * WEEKLY.CMD                                               *
  508.       *                                                          *
  509.       * Rexx procedure to perform weekly maintenance activities  *
  510.       *----------------------------------------------------------*/
  511.      
  512.      "c:"
  513.      cd "\bbs\msgx"
  514.      
  515.      /* Note: the following is really one long line */
  516.      
  517.      msgxp "mens_issues(men.%%j)
  518.          /archive=c:\max\files\echos\MN%%y%%m%%d
  519.          /compress/update/quiet/dates=( previous week )"
  520.      
  521.      if ( rc > 0 ) then
  522.      do
  523.          echo "Echo not extracted.  MsgX error " rc
  524.          exit
  525.      end
  526.      
  527.      /* Note: the following is really one long line */
  528.      
  529.      msgxp "os2(os2.%%j), Os2bbs(os2bbs.%%j), os2prog(os2prog.%%j),
  530.             os2lan(os2lan.%%j), os2hw(os2hw.%%j), os2dos(os2dos.%%j)
  531.          /archive=c:\max\files\echos\OS%%y%%m%%d
  532.          /compress/update/quiet/dates=( previous week )"
  533.      
  534.      if ( rc > 0 ) then
  535.      do
  536.          echo "Echo not extracted.  MsgX error " rc
  537.          exit
  538.      end
  539.      
  540.      exit
  541.      
  542.