Usenet 1994 January

home *** CD-ROM | disk | FTP | other *** search

/ Usenet 1994 January / usenetsourcesnewsgroupsinfomagicjanuary1994.iso / sources / unix / volume27 / conv123 / part01 / grph123.doc < prev next >

Wrap

Text File | 1993-09-05 | 14.8 KB | 368 lines

NAME graph 123 - The ASCII to Lotus/123(TM) named graph converter SYNOPSIS grph123 filename [outputfile] INTRODUCTION grph123 is a utility for reading a specially-formatted flat ASCII file and converting it into a Lotus/123(TM) ".WK1" file. Each set of specially-formatted ASCII data creates one "named graph" record, and stores the data for the named graph in a spreadsheet file, which may therefore contain multiple named graphs. This spreadsheet file is in its final, directly- readable binary form, and need undergo no further translation or conversion before being read directly by Lotus/123(TM). This feature makes grph123 especially suited to networked environments, where report writers or programs running on transaction processing machines can easily and directly create spreadsheet/graph output, instantly ready for copying, downloading, or direct access in the MS-DOS(TM) or Macintosh(TM) environments. Control of most of the Lotus(TM) named graph features is allowed. Familiarity with the graph function of Lotus/123(TM) will help greatly in under- standing this utility. OPTIONS There are currently no command-line options for grph123. PARAMETERS The only parameters are the input file name (required) and an optional output file name. If the output file name is not supplied, output is sent to stdout, and may therefore be re- directed. grph123 cannot currently be used as a filter, i.e., have its input "piped" to it. INPUT FILE FORMAT Each line of the input file has a one-character "type" at the start of the line, followed by the data values suitable for that "type" of line. Each graph entry must have an "n"-type record, at least one "d"-type record, and an "e"-type record, in that order. All "d" (data)-type records for each graph should be together, each "L"-type record must follow the associated "d"-type record, and all records for each graph must be contiguous. Besides these restrictions (easy ones for report writers to meet), record order is not significant to the utility. This can be an advantage if, for example, you wish to place the record controlling the x-axis or y-axis scale _after_ the data, when you most conveniently know the minimum and maximum values. grph123 attempts to understand each input line as well as it can, and ignores blank or null records, and white space at the beginning or end of a record, or in-between data values. Input records that have incorrect or insufficient data are ignored, and the Lotus/123(TM) defaults are used (see DEFAULTS section below). If string values have embedded blanks, they must be surrounded by double quotes ("like this"). Following is a description of each record type, followed by some examples. The "record type" is the letter that must be the first field of each input record. "Max size" is the maximum size (in bytes) of the field following. If more than the maximum number of characters is supplied, grph123 usually truncates the input. Record Max Type Size Meaning ------ ---- -------------------------------------------------- n 15 This is the "name" record type, and is one of the required types. The string value following is placed into the Lotus/123(TM) graph record as its name, which means that it appears on the circular menu after the Graph/Name/Use sequence. Example: n "Durable Ships" T 39 This the "main title" of the graph, and appears at the top of the graph, above the subtitle (if any). Example: T "SHIPMENTS OF DURABLE GOODS" t 39 This the "subtitle" of the graph, and appears at the top of the graph, below the main title. Example: t "Monthly for 1991" b 39 This the "bottom title" of the graph, and appears at the bottom of the graph, below the x-axis values on a non-pie chart. Example: b "Month" s 39 This the "side title" of the graph, and appears 90-degrees rotated at the side of a non-pie chart, to the left of the y-axis. Example: s "Dollars" g The "g" type record is an important one, and could be thought of as the "g)raph control" record. Up to four fields may be specified on this record, which must be IN THIS ORDER (i.e., if you wish to specify the fourth field, the first three MUST ALSO be specified): g [graph type] [grid control] [color control] [skip factor] [graph type] is one of L)INE, B)AR, P)IE, S)TACKED-BAR, or X)Y. Note that only the first letter of each field is actually significant and required, and that case is ignored. This makes the examples: g line, g L, and g loquat equivalent expressions; the first example is preferred for clarity. The default graph type is LINE. [grid control] is one of n)one, h)orizonal, v)ertical, or b)oth. The default grid control is NONE, or no grid. [color control] is either of b)lack&white or c)olor. If c)olor is specified, and the monitor being used is a color monitor, then each individual data range will be displayed in a different color. The default color control is B)&W, or no color. [skip factor] is an integer from 1 to 256, and is the number of values to skip between labeled data points. The default is (usually) no skipping. Example: g line horizontal color 2 f The "f" type record is the line f)ormat record, and is used to control the appearance of the line displayed on each of the six ranges allowed by Lotus/123(TM). There are, therefore, up to six values allowed on the record, controlling the appearance of lines on a LINE or XY graph. The format of the "f"-type record is as follows: f [line format]... [line format] (up to 6 times) [line format] is one of n)one, l)ine, s)ymbol, or b)oth line and symbol. The line format will be carried to the legend. Here is an example of a line format record controlling three data ranges: Example: f line line both l 19 The "l" type record is the l)egend record, and is is used to define the text labeling displayed for each line example of the six ranges allowed by Lotus/123(TM). There are, therefore, up to six string values allowed on the record, each a maxi- mum of 19 characters. The format of the "l"-type record is as follows: l [legend string]... [legend string] (up to 6) [legend string] is a delimited string of up to 19 characters. Example: l "30 days" "60 days" "90 days" L The "L"-type record is the L)abel record, and is is used to define the text labeling displayed for each data line of the six ranges allowed by Lotus/123(TM). There are, therefore, up to six string values allowed on the record. Each of these values is actually placed in the spreadsheet, so they may be of arbitrary length; however, they will be placed in the data row at the end of the y-axis data in columns of default length, so they may not be entirely visible when the spreadsheet is viewed. (See the "a"-type record below for information on how to orient the values around the data point(s) on the actual graph.) It is possible to label EVERY data point on a graph. Each "L"-type record MUST follow the associated data record. "L"-type records out of order will be ignored. Each string value on the line matches the corresponding data point on the previous data record; therefore, if the earlier values (the ones toward the left of the line) are not to be labeled, their places must be held by a null string, represented by contiguous double quotes (""). The format of the "L"-type record is as follows: L [label string]... [label string] (up to 6) [label string] is a delimited string, and must have double quotes surrounding the value if there are embedded blanks. Example: L 14.5 "" "not known" "15.90" a The "a" type record is the label a)lignment record, and is used to control the position of the labels created by the "L"-type record for line or XY graphs. Up to six values are allowed, each value controlling the display position of a data label range. The format of the "a"-type record is as follows: a [alignment]... [alignment] (up to 6 times) [alignment] is one of c)enter, l)eft, r)ight, a)bove, or b)elow. Example: a above below d The "d" type record is the d)ata record, and is one of the required types. Each line of this record should contain a minimum of two values, an x-axis value and a y-axis value (independent and dependent variables). Since Lotus/123(TM) allows up to six "data ranges" (dependent variables), each data record may contain up to seven values, one x-axis value and up to six y-axis values. The format of the "d"-type record is as follows: d [x-axis value] [y-axis value]... (up to 6 y-axis values) The x-axis values are string values for all types of graphs except the XY graph, where x-axis values are numeric. X-axis string values follow the same rules as other string values, but should not exceed about 12 characters or so, as they will start to crowd the visual output (you may wish to experiment with the skip factor in those cases). Example: d "Jan" 5000000.00 7300000.00 p The "p" type record is the decimal p)laces record, and is used to control the numer of decimal places in each dependent data range created by the "d"-type record. Up to six integer values are allowed. The format of the "p"-type record is as follows: p [decimal places]... (up to 6 times) [decimal places] is a decimal integer in the range 0 to 6. Integers below 0 or above six will be set at 0 and 6 respectively. Example: p 3 3 y The "y" type record is the y)-axis min/max record, and is used to control the "scale" of the graph when the automatic scaling is insufficient or too inconsistent. There are two numeric values expected. The format of the "y"-type record is as follows: y [min value] [max value] [min value] and [max value] are decimal numbers. Example: y 2000000.0 15000000 x The "x" type record is the x)-axis min/max record, and is used to control the "scale" of the graph when the automatic scaling is insufficient or too inconsistent. There are two numeric values expected. Use some caution when specifying x-axis min and max values on non-XY graphs. The format of the "x"-type record is as follows: x [min value] [max value] [min value] and [max value] are decimal numbers. Example: x 10.0 45.0 e The "e" type record is an important and required one, as it triggers actual graph record creation. It MUST appear after all other graph information, and will reset internal flags in preparation for the next set of graph information. Example: e # The "#" type record is a comment record; any values may follow up to the end-of-line. Example: # This is a comment record MISSING VALUES For the purposes of this utility, a missing value may be defined by any value less than or equal to -2000000000.00 (minus two thousand million). SPECIAL CONSIDERATIONS FOR PIE CHARTS Although grph123 will accept multiple data ranges for pie graphs, Lotus/123 makes use of only the A and B data ranges, with the B data range controlling shading (or color if the color flag is on and a color monitor is used) and explosion. The X-axis values are used as labels, and percentages are displayed auto- matically. The bottom and side titles are not used. FILE EXAMPLE Here is an example of a file that defines two graphs. The first is a line graph, and the second is a pie graph. Note that in the first graph example, the first x-axis value is in double quotes, and the following ones are not; both are interpreted exactly the same way, since there are no embedded blanks. In addition, there are two "data ranges" (dependent variables) in the first graph example, and all values are displayed with two decimal places, regardless of input format. In the second (pie chart) example, the five slices of the pie are shaded in colors 1 through 5, with slice three exploded. # First, a line graph n "30-60-90 graph1" T "SUMMARY BACKLOG BY WEEK" t "30-60-90 days" b "Manufacturing Wk" s "Dollar" g line horizontal b&w 2 f both both l "30 day" "60 day" a above above d "9039" 6533515.10 14500000 L 6.53 14.5 d 9040 6229610.10 14220000 L labelit "label it" d 9042 7685293.90 14500000 d 9043 10008108.35 15800000 p 2 2 y 5000000 18000000 e # # Now, a pie graph # n "Sales by Terr" T "SALES BY TERRITORY" t "August 1992" g PIE none color d widgets 45000 1 d loffles 53000 2 d scouse 50000.17 103 d framjits 63000 4 d gopples 77342 5 p 2 0 e BUGS grph123 should be able to run as a filter. Tabs as delimiters do not behave consistently.