home *** CD-ROM | disk | FTP | other *** search
/ Usenet 1994 October / usenetsourcesnewsgroupsinfomagicoctober1994disk2.iso / unix / volume27 / conv123 / part01 / conv123.doc < prev    next >
Text File  |  1993-09-05  |  10KB  |  231 lines
  1.  
  2.  
  3. NAME
  4.     convert 123 - The ASCII to Lotus/123(TM) spreadsheet converter
  5.  
  6. SYNOPSIS
  7.     conv123 [inputfile] [outputfile]
  8.  
  9. INTRODUCTION
  10.     conv123 is a utility for reading a specially-formatted flat
  11.     ASCII file and converting it into a Lotus/123(TM) ".wk1" file.
  12.     Each specially-formatted ASCII file creates one entire spread-
  13.     sheet.  This spreadsheet file is in its final, directly-readable 
  14.     binary form, and need undergo no further translation before being
  15.     read directly by Lotus/123(TM).  This feature makes conv123 especially
  16.     suited to networked environments, where report writers or programs
  17.     running on transaction processing machines can easily and directly
  18.     create spreadsheet output, instantly ready for copying, downloading,
  19.     or direct access in the MS-DOS(TM) or Macintosh(TM) environments.
  20.     In addition to individual data values, certain common aggregate
  21.     functions (formulas) may be specified (sum,min,max,variance,std
  22.     deviation, and average), and five binary functions (addition,
  23.     subtraction, multiplication, division, and percentage) may also
  24.     be specified.
  25.  
  26.     The input file format has been optimized for generation by a
  27.     simple top-down, left-to-right report generator, and is human
  28.     readable.  The input logic has been made fairly intelligent,
  29.     automatically discerning between numeric and non-numeric values,
  30.     calculating formula ranges, and calculating the maximum number
  31.     of decimal places in a row or column.
  32.  
  33. OPTIONS
  34.     There are currently no command-line options for conv123.
  35.  
  36. PARAMETERS
  37.     The only parameters are the input and output file names, both
  38.     of which are optional; conv123 can act as a filter, and by
  39.     default accepts its input from stdin and sends its output to
  40.     stdout.
  41.  
  42. INPUT FILE FORMAT
  43.     The major feature of the input file format is a "definition"
  44.     line, consisting of all dashes (-) and spaces.  Each string of
  45.     contiguous dashes on the "definition" line will become a column
  46.     in Lotus/123(TM), the width of that column being determined by the
  47.     number of dashes.  Characters in the input file that fall outside
  48.     these "column definitions" are ignored.  In addition, up to two (2)
  49.     lines above the "definition" line can be used for header information,
  50.     though this is not required.  There may not be any white space before
  51.     the first dash on the definition line; in other words, the definition
  52.     line MUST begin in the first column of the input file.
  53.  
  54.     Following is an example input file, followed by a more detailed
  55.     explanation of its contents:
  56.  
  57.                    Jan          Feb         Mar         Qtr
  58.      Product      Sales        Sales       Sales       Total
  59.     ---------  -----------  ----------- ----------- -----------
  60.     widget-1     45000.87       54390.9    75947.12     @RSUM
  61.     widget-2     47000.78       64550.0    73647.77     @RSUM
  62.     widget-3     47800.11       67830.5    54536.37     @RSUM
  63.     widget-4     33003.30       76530.7    98653.83     @RSUM
  64.     widget-5     12000.44       64836.7    27637.91     @RSUM
  65.  
  66.                      @CSUM        @CSUM       @CSUM     @CSUM
  67.  
  68.     This is a fairly simple spreadsheet with ten rows and five
  69.     columns.  The fifth column is actually made of formulas
  70.     ("row sums"), as is the last row ("column sums").  conv123 is
  71.     smart enough to know that each data value in the first column
  72.     is non-numeric, and creates the formulas in the fifth column
  73.     accordingly, i.e., the "row sums" are sums of the values in
  74.     the second through the fourth columns.  In addition, since
  75.     conv123 keeps track of the maximum number of decimal places
  76.     used in a given row or column, the number of decimal places
  77.     displayed in Lotus/123(TM) will be two (2) for all formulas,
  78.     with the exception of the CSUM in the third column, which will
  79.     display with one (1) decimal place.  Note also that the position
  80.     of the number or formula code in each column is not significant,
  81.     as long as the entire values fits under the dashed-line column
  82.     definition(s).  Also, most spreadsheet programs will re-position
  83.     the values within each cell as the values are displayed.
  84.  
  85.  
  86. FORMULA CODES
  87.     As has been shown in the above example, cell contents may be
  88.     decimal numbers or character values, with the width of the cell
  89.     determined by the width of the contiguous dashes in the "definition"
  90.     line.  Cell contents may also be formula codes.  A formula code is
  91.     a contiguous set of characters, always beginning with a commercial
  92.     "at" sign (@).  There are three types: row, column and both.  The
  93.     type indicator is a single upper case letter, one of "R" (row), "C"
  94.     (column) or "B" (both), immediately following the "@" ("at" sign).
  95.     The formula function immediately follows the type indicator, and may
  96.     be and aggregate function or a binary function.  The range for an
  97.     aggregate function is calculated automatically, being the range from
  98.     the earliest available cell -- i.e., the cell farthest "above" for
  99.     columns, or farthest to the "left" for rows -- to the cell immediately
  100.     adjacent to the formula definition.  Note that this "farthest" cell
  101.     location is re-adjusted when a non-numeric cell definition is 
  102.     encountered, being set to begin at the next numeric cell (this does
  103.     not include non-cells, i.e., positions within the spreadsheet with
  104.     no value).  The automatic range start position may be overridden for
  105.     "row" functions by placing a numeric value at the end of the formula
  106.     code (still contiguous).  A numeric value at the end of a formula code
  107.     is treated as an absolute starting column number, with the first column
  108.     defined as column one (1).
  109.  
  110.     The range for a binary function is simply the last two adjacent
  111.     cells "above" the formula definition for column functions, and
  112.     "left" of the formula definition for row functions.  The adjacent
  113.     cell is always used in the calculation; an override number after
  114.     the function code in a row function is treated as an absolute
  115.     column number overriding the penultimate cell.  For commutative
  116.     functions (addition and multiplication), order is not significant.
  117.     For non-commutative functions (subtraction and division), the
  118.     definition is a - b, or a/b, where a is the penultimate cell, and b
  119.     is the immediately adjacent cell.  If there is an override column
  120.     number, THIS ORDER IS REVERSED -- i.e., b - a and b/a, where a is
  121.     the overriding column number and b is the immediately adjacent cell.
  122.     This situation is made clearer in the examples below.
  123.  
  124.     Following is a summary of the available functions, which MUST be in
  125.     upper case where applicable:
  126.  
  127.     SUM -- Performs addition on a range of cells.
  128.     AVG -- Takes the average value on a range of cells.
  129.     MIN -- Extracts the minimum value on a range of cells.
  130.     MAX -- Extracts the minimum value on a range of cells.
  131.     VAR -- Calculates the variance on a range of cells.
  132.     STD -- Calculates the standard deviation on a range of cells.
  133.      +  -- Adds two cells.
  134.      -  -- Subtracts two cells.
  135.      *  -- Multiplies two cells.
  136.      /  -- Divides two cells.
  137.      %  -- Divides two cells, and multiplies the result by 100.
  138.     NUL -- This is actually not a function, but performs the task
  139.            of a "placeholder", preventing the "resetting" of auto-
  140.            matically calculated numeric ranges without creating
  141.            cell contents.  This function is most frequently used to
  142.            extend the row range of aggregate column functions.
  143.  
  144.  
  145. FORMULA EXAMPLES
  146.     Here are some sample input lines, with result following.
  147.  
  148.     input:
  149.     ---------  -----------  ----------- ----------- -----------
  150.     widget-1      100.00       200.00      300.00     @RSUM
  151.  
  152.     result:
  153.     ---------  -----------  ----------- ----------- -----------
  154.     widget-1        100.00       200.00      300.00      600.00
  155.  
  156.  
  157.     input:
  158.     ---------  -----------  ----------- ----------- -----------
  159.     widget-1       100.00       200.00      300.00     @R+
  160.  
  161.     result:
  162.     ---------  -----------  ----------- ----------- -----------
  163.     widget-1        100.00       200.00      300.00      500.00
  164.  
  165.  
  166.     input:
  167.     ---------  -----------  ----------- ----------- -----------
  168.     widget-1       100.00       200.00      300.00     @R/
  169.  
  170.     result:
  171.     ---------  -----------  ----------- ----------- -----------
  172.     widget-1        100.00       200.00      300.00        0.67
  173.  
  174.  
  175.     input:
  176.     ---------  -----------  ----------- ----------- -----------
  177.     widget-1       100.00       200.00      300.00     @R/3
  178.  
  179.     result:
  180.     ---------  -----------  ----------- ----------- -----------
  181.     widget-1        100.00       200.00      300.00        1.50
  182.  
  183.     Note in the above example that the order of divisor/dividend as
  184.     regards the immediately adjacent cell is the reverse of the
  185.     previous example.
  186.  
  187.  
  188.     input:
  189.     ---------  ---------  --------- --------- ----------- ------- ----------
  190.     widget-1     100.00     200.00      @RSUM      300.00   400.0     @RSUM
  191.     widget-2     100.00     100.00      @RSUM      100.00   200.0     @RSUM4
  192.                                          @NUL
  193.                   @CSUM      @BSUM      @CSUM
  194.  
  195.     result:
  196.     ---------  ---------  --------- --------- ----------- ------- ----------
  197.     widget-1      100.00     200.00    300.00      300.00   400.0     700.00
  198.     widget-2      100.00     100.00    200.00      100.00   200.0     500.00
  199.  
  200.                   200.00     500.00      0.00
  201.  
  202.  
  203.  
  204. SPECIAL CONSIDERATIONS
  205.  
  206.     The dashed-line definitions must begin at the first character
  207.     of the line in which they occur.
  208.  
  209.     Output files are basically in Lotus(TM) .WK1 format, and output
  210.     files should be named with this extension to provide maximum
  211.     information to spreadsheet programs.
  212.  
  213.     Binary functions in column formula codes are allowed, but rarely
  214.     make much sense.
  215.  
  216.     The program is simple by design, and makes no attempt to incorporate
  217.     useful, more complex features such as absolute cell positioning,
  218.     general-purpose formulae, macros, etc.
  219.  
  220.  
  221. BUGS
  222.  
  223.     The maximum number of columns is currently hard-coded into the 
  224.     program at 124; memory should be dynamically allocated to support
  225.     an arbitrary spreadsheet size.
  226.  
  227.     Optimizations could be applied at several points.
  228.  
  229.     Starting/ending points for formulae should be arbitrarily
  230.     specifiable.
  231.