home *** CD-ROM | disk | FTP | other *** search
/ Current Shareware 1994 January / SHAR194.ISO / textutil / delim12.zip / DOCS.TXT < prev    next >
Text File  |  1993-10-15  |  19KB  |  425 lines
  1.                              DELIMIT
  2.  
  3.                            Version 1.0
  4.  
  5.                 Copyright 1993 Jefferson P. Carey
  6. Delimit is a program that scans columnar reports (stored as ascii text
  7. files) and extracts relevant data, writing data to an ascii file in comma-
  8. delimited format.  A full explanation will follow, but I believe a simple
  9. example is the best way to show you the capabilities of Delimit.  In a
  10. nutshell, Delimit can take a report like this:
  11.  
  12. -----------------------------------------------------------------------------
  13.  
  14.                                   XYZ Corporation                   Page:   1
  15.                               Sales Commission Report
  16.                         For The Month Beginning 01/01/1993
  17.  
  18.  
  19. Salesperson ID   Item Number   Qty Sold   Cost Each   Item Sales   Commission
  20. --------------   -----------   --------   ---------   ----------   ----------
  21. 8342             981239872            5       74.95       374.75        56.21
  22.                  987243873           23       14.95       343.85        51.58
  23.                  989123783            3      274.85       824.55       123.68
  24.                                                       ----------   ----------
  25. Totals:                                                  1543.15       231.47
  26.  
  27.  
  28. Salesperson ID   Item Number   Qty Sold   Cost Each   Item Sales   Commission
  29. --------------   -----------   --------   ---------   ----------   ----------
  30. 8573             981239872            4       74.95       299.80        44.97
  31.                  987243873           27       14.95       403.65        60.55
  32.                  989123783            6      274.85      1649.10       247.37
  33.                                                       ----------   ----------
  34. Totals:                                                  2352.55       352.89
  35.  
  36.                                   XYZ Corporation                   Page:   2
  37.                               Sales Commission Report
  38.                         For The Month Beginning 02/01/1993
  39.  
  40.  
  41. Salesperson ID   Item Number   Qty Sold   Cost Each   Item Sales   Commission
  42. --------------   -----------   --------   ---------   ----------   ----------
  43. 8342             981239872            6       74.95       449.70        67.46
  44.                  987243873           25       14.95       373.75        56.06
  45.                  989123783            4      274.85      1099.40       164.91
  46.                                                       ----------   ----------
  47. Totals:                                                  1922.85       288.43
  48.  
  49.  
  50. Salesperson ID   Item Number   Qty Sold   Cost Each   Item Sales   Commission
  51. --------------   -----------   --------   ---------   ----------   ----------
  52. 8573             981239872            3       74.95       224.85        33.73
  53.                  987243873           22       14.95       328.90        49.34
  54.                  989123783            5      274.85      1374.25       206.14
  55.                                                       ----------   ----------
  56. Totals:                                                  1928.00       289.21
  57.  
  58. Grand Totals:                                            7746.55      1162.00
  59.  
  60. -----------------------------------------------------------------------------
  61.  
  62. and create a file containing the data from the report in comma-delimited
  63. format, like this:
  64.  
  65. "01/01/1993",8342,981239872,5,74.95,374.75,56.21
  66. "01/01/1993",8342,987243873,23,14.95,343.85,51.58
  67. "01/01/1993",8342,989123783,3,274.85,824.55,123.68
  68. "01/01/1993",8573,981239872,4,74.95,299.80,44.97
  69. "01/01/1993",8573,987243873,27,14.95,403.65,60.55
  70. "01/01/1993",8573,989123783,6,274.85,1649.10,247.37
  71. "02/01/1993",8342,981239872,6,74.95,449.70,67.46
  72. "02/01/1993",8342,987243873,25,14.95,373.75,56.06
  73. "02/01/1993",8342,989123783,4,274.85,1099.40,164.91
  74. "02/01/1993",8573,981239872,3,74.95,224.85,33.73
  75. "02/01/1993",8573,987243873,22,14.95,328.90,49.34
  76. "02/01/1993",8573,989123783,5,274.85,1374.25,206.14
  77.  
  78. What's the point?  In many organizations, out-of-date, unfriendly, and
  79. inflexible computer systems still prevail.  Many of these systems are
  80. capable of outputting a variety of highly informative reports (such as the
  81. one shown above), but lack the capability to be easily customized to
  82. provide other types of data output.  Essentially, the data exists in the
  83. system, but you can only see it presented in ways that the system
  84. designers intended (unchangeable reports).  In many cases the data
  85. presented in such reports could be of even greater value if it could be
  86. extracted and analyzed using software (databases, spreadsheets, etc.) on
  87. a PC.  Herein lies the value of Delimit.
  88.  
  89. Any modern data analysis PC software that's worth a dime can import
  90. data from a comma-delimited ascii file (exactly the kind of file created
  91. by Delimit).  Once the data is available to the PC software, the
  92. possibilities for analysis (and even new reports) are endless.
  93.  
  94. At this point, if you still don't understand the purpose of Delimit, this
  95. program probably isn't going to be of use to you.  Do me a favor and
  96. pass it on to a friend who might be interested.  You could be doing your
  97. friend a favor as well.
  98.  
  99. On the other hand, if you are faced with the same situation I've just
  100. described, read on.  The rest of this document will explain how to use
  101. Delimit, and includes examples for all of the features.
  102. Just one thing before we get started.  This program is being released as
  103. shareware...with a twist.  Individuals using it for personal use, and
  104. nonprofit organizations using it in their nonprofit ventures, are free to
  105. use Delimit without paying the registration fee, if they choose.  Anyone
  106. else using Delimit (for-profit businesses), beyond a reasonable trial
  107. period (use your own judgement here), must pay a registration fee of
  108. $24.95 to continue to use the program.  Registered users will receive a
  109. disk containing the latest version of Delimit, an upgrade notice when a
  110. newer version of the program is available, and a discount off the cost of
  111. registering the newer version.  Please note that individuals and
  112. nonprofit organizations electing to use Delimit without paying the
  113. registration fee are only entitled to free use of the program, and not to
  114. these additional benefits of registered users.
  115.  
  116. Yes, you could easily "cheat" and use Delimit without paying the
  117. registration fee.  But, my sincere hope is that those who use it will
  118. appreciate its real value (time saved, information gained, money saved,
  119. etc.) and will realize that their $24.95 is a worthwhile investment.
  120.  
  121. Delimit required a great deal of personal time and effort to develop.  I
  122. appreciate all of you who support my work through your registration. 
  123. Thank you!
  124.  
  125.  
  126.  
  127.              To register your copy of Delimit, print
  128.                  the file REGISTER.TXT, fill it
  129.               out and enclose payment, and mail it
  130.             to the address at the bottom of the form.                           Using Delimit
  131.  
  132. To use Delimit you need to create a configuration file for the report you
  133. want to process.  Don't worry, this configuration file is quite simple to
  134. make.  Below is the configuration file that was used to process the report
  135. shown earlier in the documentation.  I'll explain each line in this
  136. configuration file next.
  137.  
  138. -------------------------------------------------------------------------------------
  139.  
  140. [Settings]
  141. InputFile=sample.txt
  142. OutputFile=output.txt
  143. DiscardFile=discard.txt
  144. FilterDefault=Exclude
  145. BlankFieldFill=True
  146. IncludeOperator=And
  147. ExcludeOperator=And
  148. Trimming=True
  149. StringDelimiter="
  150. FieldDelimiter=,
  151.  
  152. [Include]
  153. 18,11,Numeric
  154.  
  155. [Exclude]
  156.  
  157. [Fields]
  158. 1,14,Numeric
  159. 18,11,Numeric
  160. 32,8,Numeric
  161. 43,9,Numeric
  162. 55,10,Numeric
  163. 68,10,Numeric
  164.  
  165. [Occasionals]
  166. 25,23,"For The Month Beginning",49,10,Alpha
  167.  
  168. -------------------------------------------------------------------------------------
  169.  
  170.  
  171. {Settings] section
  172. In this section you set the values of several parameters that affect the
  173. operation of Delimit.  Each parameter, and its possible values, is
  174. explained below.
  175.  
  176.      InputFile
  177.      This parameter specifies the name of the report that you want to
  178.      process.  You may specify a drive and path if the file is not in the
  179.      current directory.  This parameter is required.
  180.  
  181.      OutputFile
  182.      This parameter specifies the name of the report where you want
  183.      Delimit to send its output (the comma delimited data).  You may
  184.      specify a drive and path if the file will not be in the current
  185.      directory.  This parameter is required.
  186.  
  187.      DiscardFile
  188.      Later in the configuration file you will be able to specify which
  189.      lines Delimit should "throw out" when processing the report.  In
  190.      our example report we are only interested in lines with item sales
  191.      figures, and all other lines should be discarded.  If you include
  192.      this parameter in your configuration file, the discarded lines will
  193.      be written to the specified file.  This feature is useful for checking
  194.      that the proper lines were discarded when you are working on
  195.      creating a correct configuration file.  After running Discard, you
  196.      can look at the contents of the discard file and make sure no good
  197.      lines were discarded.  This parameter is optional.
  198.  
  199.      FilterDefault
  200.      This parameter tells Delimit whether to keep or discard lines in
  201.      the report by default.  The valid values for this parameter are
  202.      "Include" and "Exclude".  In some cases it will be easiest to specify
  203.      which lines contain data, so by default Delimit should exclude
  204.      lines from the report (i.e. it will discard (exclude) a line unless it
  205.      meets the criteria you have specified for keeping a line --
  206.      FilterDefault=Exclude).  In other cases, it will be easiest to
  207.      specify which lines to exclude (FilterDefault=Include).  For the
  208.      example report, we are going to specify which lines to keep so
  209.      FilterDefault=Exclude.
  210.  
  211.      BlankFieldFill
  212.      This parameter determines whether Delimit will fill a blank field
  213.      with the most recent nonblank value of that field.  The valid
  214.      values for this parameter are "True" and "False".  In the sample
  215.      report, the salesperson id is shown on the first line for each
  216.      salesperson, but on successive lines this field is blank.  In this
  217.      case, BlankFieldFill=True so that salesperson id's will be carried
  218.      down to successive lines in the comma delimited file, until a new
  219.      salesperson id is found.  If BlankFieldFill=False, the first few
  220.      lines of the comma delimited file would have looked like this:
  221.  
  222.           "01/01/1993",8342,981239872,5,74.95,374.75,56.21
  223.           "01/01/1993",,987243873,23,14.95,343.85,51.58
  224.           "01/01/1993",,989123783,3,274.85,824.55,123.68
  225.           "01/01/1993",8573,981239872,4,74.95,299.80,44.97
  226.           "01/01/1993",,987243873,27,14.95,403.65,60.55
  227.  
  228.      IncludeOperator
  229.      Later in this documentation I will explain how to specify
  230.      conditions that lines must meet in order to be included in
  231.      processing and output to the comma delimited file.  At times it
  232.      might be necessary to specify more than one condition that a line
  233.      must meet to be included.  This parameter specifies whether those
  234.      conditions should be combined with an AND or an OR.  For
  235.      example, you can specify that a line must meet condition x AND
  236.      condition y, or you can specify that a line must meet condition x
  237.      OR condition y.  Valid values for this parameter are "And" and
  238.      "Or".
  239.  
  240.      ExcludeOperator
  241.      Later in this documentation I will explain how to specify
  242.      conditions that lines must meet in order to be excluded from
  243.      processing and output to the comma delimited file.  At times it
  244.      might be necessary to specify more than one condition that a line
  245.      must meet to be excluded.  This parameter specifies whether those
  246.      conditions should be combined with an AND or an OR.  For
  247.      example, you can specify that a line must meet condition x AND
  248.      condition y, or you can specify that a line must meet condition x
  249.      OR condition y.  Valid values for this parameter are "And" and
  250.      "Or".
  251.  
  252.      Trimming
  253.      This parameter determines if Delimit will trim spaces from the
  254.      beginning and end of fields that are written to the comma
  255.      delimited file.  Valid values for this parameter are "True" and
  256.      "False".
  257.  
  258.      StringDelimiter
  259.      This parameter determines which ascii character will be used to
  260.      delimit strings in the output file.  The default is the double quote
  261.      character (").  Either specify a single character (such as " or ') or
  262.      specify the ascii value of a character in three digit decimal form
  263.      (such as 047 or 179).
  264.  
  265.      FieldDelimiter
  266.      This parameter determines which ascii character will be used to
  267.      separate fields in the output file.  The default is the comma
  268.      character (,).  Either specify a single character (such as , or |) or
  269.      specify the ascii value of a character in three digit decimal form
  270.      (such as 047 or 179).
  271.  
  272.  
  273. {Include} section
  274. In this section, you specify the conditions that each line in the report
  275. must meet in order to be included in the comma delimited file.  The
  276. format of the lines in this section is "column number, number of
  277. characters, condition".  The column number and number of characters
  278. specify the characters that must meet the condition.  The condition can
  279. be a string, a set of characters, or one of the words "Alpha", "Numeric",
  280. "Blank", or "NonBlank".  In the example report the line "18,11,Numeric"
  281. specified that the 11 characters, starting in column 18, must be a
  282. number for the line to be included.  Here are some more examples:
  283.  
  284.      The character in column 11 must be 'A', 'B', or 'C':
  285.      11,1,{ABC}
  286.  
  287.      The 3 characters starting in column 11 must be "Abc":
  288.      11,3,"Abc"
  289.  
  290.      The first 5 characters on the line must be blank:
  291.      1,5,Blank
  292.  
  293.      At least one of the first 5 characters must not be blank:
  294.      1,5,NonBlank
  295.  
  296.      None of the 10 characters starting in column 35 can be a number:
  297.      35,10,Alpha
  298.  
  299.      The 10 characters starting in column 35 must be a number:
  300.      35,10,Numeric
  301.      Note: "  123  " is a number, while "123  456" is not a valid
  302.      number.
  303.  
  304. If you put more than one line in this section, the conditions you specify
  305. on each line will be combined with one of the logical operators AND or
  306. OR, as determined by the value of the IncludeOperator parameter.  For
  307. example:
  308.  
  309.      The first character must be an 'A' AND the next 10 characters
  310.      must be a number:
  311.      [Settings]
  312.      IncludeOperator=And
  313.      [Include}
  314.      1,1,{A}
  315.      2,10,Numeric
  316.  
  317.      The first character must be an 'A' OR the next 10 characters must
  318.      be a number:
  319.      [Settings]
  320.      IncludeOperator=Or
  321.      [Include}
  322.      1,1,{A}
  323.      2,10,Numeric
  324.  
  325.  
  326. {Exclude] section
  327. The exclude section is identical to the include section, except that it is
  328. used to specify the lines that should be excluded rather than included. 
  329. Complex conditions can be specified using a combination of
  330. FilterDefault, IncludeOperator, ExcludeOperator, [Include}, and
  331. [Exclude] settings.  Some examples follow.
  332.  
  333.      Include all lines that have a number in the first 10 characters
  334.      AND have a '/' in columns 50 and 53 (a good way to search for
  335.      dates of the form MM/DD/YY) but do not have the word "Deleted"
  336.      beginning in column 17:
  337.      [Settings]
  338.      FilterDefault=Exclude
  339.      IncludeOperator=And
  340.      [Include]
  341.      1,10,Numeric
  342.      50,1,{/}
  343.      53,1,{/}
  344.      [Exclude]
  345.      17,7,"Deleted"
  346.  
  347.      Exclude any lines in which the first 5 characters are blank OR
  348.      contain the word "Total", unless there is a number in the 6
  349.      characters beginning in column 30:
  350.      [Settings]
  351.      FilterDefault=Include
  352.      ExcludeOperator=Or
  353.      [Exclude]
  354.      1,5,Blank
  355.      1,5,"Total"
  356.      [Include]
  357.      30,6,Numeric
  358.  
  359.  
  360. [Fields] section
  361. In the Fields section, you specify which columns from the included lines
  362. contain the data that you want sent to the output file.  Each line in the
  363. Fields section is of the form "column number, number of characters, field
  364. type".  The column number and number of characters specify which
  365. characters to extract from the line in the report.  The field type is either
  366. of the words "Alpha" or "Numeric".  If the field is alpha, it will be
  367. enclosed in quotes in the output file.  Numeric fields will not be enclosed
  368. in quotes.  For example, in the sample output file line below, the first
  369. field was specified as Alpha and the second field was specified as
  370. numeric.
  371.  
  372.      "John Doe", 25
  373.  
  374. You may specify an unlimited number of fields.  They will be sent to the
  375. output file in the order specified in the configuration file.
  376.  
  377.  
  378. [Occasionals] section
  379. An occasional is a combination of both an Include and a Field
  380. specification.  In many reports, data is listed only occasionally at the
  381. beginning of a section or at the top of a page.  In the sample report
  382. shown earlier, the reporting period is only shown at the top of each page
  383. on the line that contains the text "For The Month Beginning".  To
  384. include this data at the beginning of each line in the output file, an
  385. occasional was specified in the configuration file.  The format of the lines
  386. in the Occasionals section is "column number, number of characters,
  387. condition, field column, field characters, field type".  The first three
  388. parameters specify the condition that occasional lines meet, and the last
  389. three parameters specify the position on the line and type of the data to
  390. be written to the output file.  For example:
  391.  
  392.      Any lines containing the text "For The Month Beginning" starting
  393.      in column 25, contain a 10 character Alpha field starting in
  394.      column 49, is specified as:
  395.      25,23,"For The Month Beginning",49,10,Alpha.
  396.  
  397. The fields specified in the Occasionals section will not be output as the
  398. occasional lines are encountered, but instead, at the beginning of each
  399. and every line that is included from the report.  Take a look at the
  400. sample output file to see how this works.  You may have more than one
  401. occasional, with each one being output at the beginning of each included
  402. line.
  403.  
  404.  
  405. Running Delimit
  406. Once you have created a configuration file, just type DELIMIT followed
  407. by the name of the configuration file, then press the Enter key.  A
  408. sample report and configuration file have been included with Delimit. 
  409. The sample report is named SAMPLE.TXT and the configuration file for
  410. processing this report is named SAMPLE.CFG.  To run Delimit on this
  411. report, just type DELIMIT SAMPLE.CFG and press the Enter key.  The
  412. results will be written to the files OUTPUT.TXT and DISCARD.TXT.
  413.  
  414.  
  415. Contacting the Author
  416. I can be reached on CompuServe.  My ID is 70413,1360.
  417.  
  418. You may also contact me in writing at:
  419.      Jeff Carey
  420.      3735 Eastmont Avenue
  421.      Bloomington, IN 47403
  422.  
  423. I'd greatly appreciate any suggestions for improvement, constructive
  424. criticisms, or even compliments!
  425.