home *** CD-ROM | disk | FTP | other *** search
/ High Voltage Shareware / high1.zip / high1 / DIR23 / TOUCH2.ZIP / 00README < prev    next >
Text File  |  1993-08-14  |  33KB  |  942 lines
  1.                 TOUCH2
  2.                   Version 1.11
  3.          A Communications Interface Application for the
  4.     LifeScan One Touch(R) II Blood Glucose Monitoring System *
  5.  
  6.     Copyright (c) 1993, Victor A. Abell, West Lafayette, Indiana
  7.             47907.  All rights reserved.
  8.  
  9.  
  10.                 Victor A. Abell
  11.                 1715 Summit Drive
  12.                 West Lafayette, IN 47906
  13.                 (317) 463-6865
  14.                 abe@cc.purdue.edu
  15.  
  16. This is version 1.10 of an application that provides a communications
  17. interface to the data port of the LifeScan One Touch(R) Blood Glucose
  18. Monitoring System meter.  The application gives access to almost all the
  19. features of the meter that can be manipulated via its data port -- excluded
  20. is support for functions that would disable communications between the
  21. application and the meter.  It provides limited data analysis -- an option
  22. that includes maximum, mean, minimum and standard deviation for check
  23. solution, check strip, meter error, and normal readings, plus a line graph
  24. of the normal readings.  It processes meter data in either measurement
  25. scale -- mg/dl or mmol/l.
  26.  
  27.  
  28. Application requirements
  29. ------------------------
  30.  
  31. An IBM compatible PC with: CGA Monitor (VGA required for graphing)
  32.                COM (serial) port
  33.                128K memory
  34.                DOS 5.0 or 6.0 **
  35. A LifeScan One Touch(R) II meter
  36. A LifeScan data port cable ***
  37.  
  38. **  The application has been tested under DOS 5.0 and 6.0, but it may work
  39.     under earlier versions.
  40.  
  41. *** You can obtain a data cable from LifeScan by calling:
  42.  
  43.         U.S.A:    1 800 227-8862
  44.         Canada:    1 800 663-5521
  45.  
  46.     Depending on the RS-232 connector leading from your PC's serial COM
  47.     port, you may need a 9 pin (female) to 25 pin (male) adapter, since the
  48.     LifeScan cable has a DB-25 female connector.  A DB-9 to DB-25 adapter is
  49.     available from Radio Shack for about $5.
  50.  
  51.  
  52. Documentation
  53. -------------
  54.  
  55. The TOUCH2 application is driven by simple, character-based menus and is
  56. intended to be self-explanatory.  Thus, there is no additional documenta-
  57. tion except for the following section on customization.
  58.  
  59.  
  60. Preparation
  61. -----------
  62.  
  63. To use TOUCH2 the only preparation you must make is setting the data port
  64. parameters of your meter.  Follow the instructions in your One TOUCH(R)
  65. II manual, particularly the chart on pp. 58, 59 (in my manual, at least.)
  66. You should set your meter to RS-232 mode and 9600 baud.
  67.  
  68.  
  69. Quick Start
  70. -----------
  71.  
  72. Set your meter's Data Management mode to RS-232 and its Baud Rate Mode to
  73. 9600.  Connect your meter to the cable and connect the cable to the COM1 or
  74. COM2 port on your PC.  Look at the file TOUCH2.CF, supplied with the
  75. distribution, to see if it defines the proper COM port:
  76.  
  77.     COM1:    port=1
  78. or
  79.     COM2:    port=2
  80.  
  81. Edit the port number to match the COM port into which you plugged the meter
  82. cable.  Don't worry about the other lines in TOUCH2.CF -- they probably
  83. won't affect your first use of the program.  If you do worry, you'll find
  84. explanations of them in the Customization section.
  85.  
  86. Execute TOUCH2:
  87.  
  88.     C:> TOUCH2
  89.  
  90. Follow the menus.  Turn on your meter when you want to access it from one
  91. of TOUCH2's menus.
  92.  
  93.  
  94. Customization
  95. -------------
  96.  
  97. The TOUCH2 application will customize itself from default values, from
  98. directives it finds in a configuration file, or from options on its call.
  99. The default configuration file is TOUCH2.CF in the current directory, but
  100. you may specify an alternate path to the configuration file in the TOUCH2
  101. environment variable.
  102.  
  103. For example, if you want to use this feature, and you want to store the
  104. configuration file in the root directory of your C: disk in the file
  105. TOUCH2.CF, use the DOS command:
  106.  
  107.         SET TOUCH2=C:\TOUCH2.CF
  108.  
  109. You may want to put this in your AUTOEXEC.BAT file.  No particular name
  110. is required for the configuration file; TOUCH2.CF is just an example.
  111.  
  112. If you always use TOUCH2 from the same directory, putting a TOUCH2.CF file in
  113. that directory is sufficient.  Then you don't need to define the TOUCH2
  114. environment variable.
  115.  
  116. After you have identified the configuration file, you must create it, using
  117. your favorite text editor.  It must contain text lines of the form:
  118.  
  119.             <keyword>=<value>
  120.  
  121. Empty lines and lines that begin with a pound sign (`#') -- comments -- are
  122. ignored.  Case is not significant.  Keywords and values may be specified in
  123. upper, lower or mixed case.  There may be spaces around the equal sign
  124. separator (`=') -- they will be ignored.  Spaces after <value> are assumed
  125. to be part of it.
  126.  
  127. TOUCH2 recognizes the following configuration file keywords and their
  128. shorthand forms.   It also recognizes any partial keyword that is singular --
  129. e.g., "bau" for "baudrate", but not "ba", since both "baudrate" and
  130. "background" begin with "ba".  The default values are used in the absence
  131. of a configuration file specification.
  132.  
  133.     Keyword        Value        Significance
  134.     -------        -----        ------------
  135.  
  136.     aftergraph    <string>    Set the printer control string to be
  137.                     issued at the end of the graph print
  138.                     file to <string>.  Usually <string>
  139.                     contains a form feed ASCII character
  140.                     (Ctrl-L or ^L) and other codes needed
  141.                     to reset the printer to its default
  142.                     state.  If this string is not defined,
  143.                     TOUCH2 assigns it and the "beforegraph"
  144.                     strings to the values for the default
  145.                     printer type, EPSON.
  146.  
  147.                     See the Graph Printing section for
  148.                     more information.
  149.  
  150.                     See the Defining Strings section for
  151.                     information on how to build a string
  152.                     that defines characters.
  153.  
  154.                     The "aftergraph" string may also be
  155.                     set with the "-a <string>" option on
  156.                     the TOUCH2 call line.
  157.  
  158.     ag                Shorthand for "aftergraph".
  159.  
  160.     bar        <string>    Define the character to be used on the
  161.                     printed graph for the bar line.
  162.  
  163.                     The default is the IBM printer
  164.                     character with the hexadecimal value
  165.                     cd (a double horizontal line). 
  166.  
  167.                     See the Defining Strings section for
  168.                     information on how to build a string
  169.                     that defines a character.
  170.  
  171.                     The "bar" character may also be set
  172.                     with the "-b <char>" option on the
  173.                     TOUCH2 call line.
  174.  
  175.     baudrate    300, 1200    Set the data port baud rate to one of
  176.             2400 or 9600    these four values.  The default is
  177.                     9600.
  178.  
  179.     br                Shorthand for "baudrate"
  180.  
  181.     background    COLOR        Set the background color to the COLOR
  182.                     value.  The default is BLUE.
  183.  
  184.                     See the Colors section for information
  185.                     on color choices.
  186.  
  187.     bk                Shorthand for "background"
  188.  
  189.     beforegraph    <string>    Set the printer control string to be
  190.                     issued at the beginning of the graph
  191.                     print file to <string>.  Usually
  192.                     <string> contains printer control codes
  193.                     to define 8 lines/inch spacing.  If the
  194.                     "aftergraph" string is not defined,
  195.                     TOUCH2 assigns it and the "beforegraph"
  196.                     strings to the values for the default
  197.                     printer type, EPSON.
  198.  
  199.                     See the Graph Printing section for
  200.                     more information.
  201.  
  202.                     See the Defining Strings section for
  203.                     information on how to build a string
  204.                     that defines characters.
  205.  
  206.                     The "beforegraph" string may also be
  207.                     set with the "-B <string>" option on
  208.                     the TOUCH2 call line.
  209.  
  210.     checksum    on or off    Turn dump record checksum verification
  211.                     on or off.  The default is on.
  212.  
  213.                     See the Checksum Verification section
  214.                     for an explanation of checksums and
  215.                     checksum verification handling.
  216.  
  217.                     The checksum verification mode may
  218.                     also be turned off with the "-C"
  219.                     option on the TOUCH2 call line.
  220.  
  221.     cksum                Shorthand for "checksum"
  222.  
  223.     comport        1 or 2        Set the serial communications port
  224.                     number to 1 or 2.  The default is 1.
  225.  
  226.     port                Shorthand for "comport"
  227.  
  228.     dump        <format>    Set the dump format to raw or
  229.                     QuattroPro.
  230.  
  231.                     The raw dump format matches the meter
  232.                     dump format.  There is a header line,
  233.                     all values are dumped, and all values
  234.                     are enclosed in quotation marks.
  235.                     
  236.                     The QuattroPro dump format contains no
  237.                     header line and only date, time and
  238.                     meter reading values.  The values are
  239.                     separated by commas, but are not
  240.                     enclosed in quotation marks.
  241.  
  242.                     The default dump format is raw, but the
  243.                     "-r" option on the TOUCH2 call may be
  244.                     used to deselect raw format and select
  245.                     QuattroPro.
  246.  
  247.     framesize    7 or 8        Set the data port frame size to 7 or 8.
  248.                     The default is 8.
  249.  
  250.     gmax        <number>    Set the y coordinate value of the
  251.                     maximum level line on the graph to
  252.                     <number>.  The maximum level line
  253.                     provides a visual reference for
  254.                     maximum acceptable glucose readings.
  255.  
  256.                     The default is 110 mg/dl or 6.1 mmol/l.
  257.  
  258.                     The maximum level value may also be
  259.                     set with the "-G <max>" option on
  260.                     the TOUCH2 call line.
  261.  
  262.     gmin        <number>    Set the y coordinate value of the
  263.                     minimum level line on the graph to
  264.                     <number>.  The minimum level line
  265.                     provides a visual reference for
  266.                     minimum acceptable glucose readings.
  267.  
  268.                     The default is 70 mg/dl or 3.9 mmol/l.
  269.  
  270.                     The minimum level value may also be
  271.                     set with the "-g <min>" option on
  272.                     the TOUCH2 call line.
  273.  
  274.     graphname    <path>        Set the default graph file path to
  275.                     <path>.  The default is TOUCH2.GRF.
  276.  
  277.     graphtitle    <title>        Set the graph title line to <title>.
  278.                     <title> may contain no more than 66
  279.                     characters.
  280.  
  281.                     The graph title line may be set with
  282.                     the "-t <ttl>" option on the TOUCH2
  283.                     call line and with the Title option
  284.                     on the dump menu.
  285.  
  286.                     The graph title line normally follows
  287.                     a page number in the graph output file.
  288.                     The page number may be suppressed using
  289.                     the "-P" option on the TOUCH2 call
  290.                     line, "pcd=off", or "pgctdisp=off".
  291.  
  292.                     See the Graph Title and Graph Title
  293.                     Variables sections for more information
  294.                     on the graph title line.  See also the
  295.                     "titlevar" configuration file
  296.                     directive.
  297.  
  298.     gttl                Shorthand for "graphtitle"
  299.  
  300.     intersection    <string>    Define the character to be used on the
  301.                     printed graph at the intersection of
  302.                     the bar and the maximum/minimum level
  303.                     lines.
  304.  
  305.                     The default is the IBM printer
  306.                     character with the hexadecimal value
  307.                     d8 (a single vertical line intersecting
  308.                     a double horizontal line).
  309.  
  310.                     See the Defining Strings section for
  311.                     information on how to build a string
  312.                     that defines a character.
  313.  
  314.                     The "intersection" character may also
  315.                     be set with the "-i <char>" option on
  316.                     the TOUCH2 call line.
  317.     
  318.     ic                Shorthand for "intersection"
  319.  
  320.     line        <string>    Define the character to be used on the
  321.                     displayed and printed graphs for the
  322.                     maximum/minimum level lines.
  323.  
  324.                     The default is the IBM printer
  325.                     character with the hexadecimal value
  326.                     b3 (a single vertical line).
  327.  
  328.                     See the Defining Strings section for
  329.                     information on how to build a string
  330.                     that defines a character.
  331.  
  332.                     The "line" character may also be set
  333.                     with the "-l <char>" option on the
  334.                     TOUCH2 call line.
  335.  
  336.     lpp        <number>    Set the number of lines per page on the
  337.                     printed graph to <number>.  The default
  338.                     is 81, assuming printing at 8 lines per
  339.                     inch.  The minimum is 11.
  340.  
  341.                     See the Graph Printing section for more
  342.                     information.
  343.  
  344.                     The "lpp" value may also be set with
  345.                     the "-L <num>" option on the TOUCH2
  346.                     call line.
  347.  
  348.     parity        none, even    Set the data port parity to none, even
  349.             or odd        or odd.  The default is none.
  350.  
  351.     pgctdisp    on or off    Set the display of the page count in
  352.                     the graph file output on or off.  The
  353.                     default is on.  The "-P" option on the
  354.                     TOUCH2 call line may also be used to
  355.                     turn off the display of the page count.
  356.  
  357.     pcd                Shorthand for "pgctdisp"
  358.  
  359.     qdumpname    <path>        Set the default QuattroPro format dump
  360.                     file path to <path>.  The default is
  361.                     TOUCH2.CSV.
  362.  
  363.     rdumpname    <path>        Set the default raw format dump file
  364.                     path to <path>.  The default is
  365.                     TOUCH2.DMP.
  366.  
  367.     startstop    1 or 2        Set the data port start and stop bit
  368.                     count to 1 or 2.  The default is 1.
  369.  
  370.     stst                Shorthand for "startstop"
  371.  
  372.     text        COLOR        Set the text color to COLOR.  The
  373.                     default is YELLOW.
  374.  
  375.                     See the Colors section for information
  376.                     on color choices.
  377.  
  378.     printer        <name>        Set the printer type to <name>.  The
  379.                     legal values are EPSON, PCL4 and PPDS.
  380.                     (Case is not significant.)
  381.  
  382.                     Setting the printer sets default
  383.                     values for the "aftergraph" and
  384.                     "beforegraph" printer control strings.
  385.                     See the Graph Printing section for more
  386.                     information.
  387.  
  388.                     The "printer" name may also be set
  389.                     with the "-p <name>" option on the
  390.                     TOUCH2 call line.
  391.  
  392.     promptbk    COLOR        Set the text prompt background color
  393.                     to COLOR.  The default is RED.
  394.  
  395.                     See the Colors section for information
  396.                     on color choices.
  397.  
  398.                     The prompt background color selection
  399.                     is ineffective when a graph is being
  400.                     displayed; the regular background color
  401.                     appears instead.  This is a limitation
  402.                     of VGA graphics mode.
  403.  
  404.     pbk                Shorthand for "promptbk"
  405.  
  406.     prompttext    COLOR        Set the prompt text color to COLOR.
  407.                     The default is BRIGHT WHITE.
  408.  
  409.                     See the Colors section for information
  410.                     on color choices.
  411.  
  412.     ptxt                Shorthand for "prompttext"
  413.  
  414.     titlevar    <n>,<val>    Set title variable n [0-9] to <val>.
  415.                     See the Graph Title and Graph Title
  416.                     Variables sections for more information
  417.                     on setting and using graph title line
  418.                     variables.
  419.  
  420.     tv                Shorthand for "titlevar"
  421.  
  422.     warn        on or off    Enables (on) or disables (off) warnings
  423.                     about incompatible display modes when
  424.                     TOUCH2 begins execution.  The default
  425.                     is on.
  426.  
  427.                     TOUCH2 works best when it can set the
  428.                     display mode to TEXTC80.  Other modes
  429.                     -- e.g., Hercules monochrome mode --
  430.                     may be adequate for some display
  431.                     operations, but may result in incorrect
  432.                     colors or other display variations.
  433.                     If TOUCH2 cannot put the display in
  434.                     TEXTC80 mode, it displays a warning
  435.                     screen when it begins execution.  This
  436.                     directive may be used to enable or
  437.                     disable the warning display.
  438.  
  439.                     The display warning mode may also be
  440.                     disabled with the "-w" option on the
  441.                     TOUCH2 call line.
  442.  
  443.  
  444. Colors
  445. ------
  446.  
  447. Color group 1 -- menu background, graph background, and text COLOR values
  448. may be:
  449.  
  450.   BLACK   BLUE   GREEN   CYAN   RED   MAGENTA   BROWN   WHITE
  451.  
  452. Color group 2 -- graph background and text COLOR values may be:
  453.  
  454.   GRAY              LIGHT BLUE    LIGHT GREEN   LIGHT CYAN   LIGHT RED
  455.   LIGHT MAGENTA   LIGHT BROWN   BRIGHT WHITE
  456.  
  457. Case is not significant: any of the above COLOR values may be specified in
  458. lower (or even mixed) case.  The space between LIGHT or BRIGHT and the color
  459. word is optional -- e.g., BRIGHT WHITE and BRIGHTWHITE are equivalent.
  460.  
  461. If a color from group 2 is specified as a menu or prompt background color,
  462. TOUCH2 displays a warning screen, explaining that the color cannot be used as
  463. a background for menus or prompts, and specifying how the color will be
  464. converted to one from group 1 -- e.g., GRAY will be converted to BLACK, LIGHT
  465. RED to RED, etc.  The menu background colors are limited to those from group
  466. 1, because TOUCH2 uses the TEXTC80 video display mode.  That mode allows 16
  467. text colors, but only 8 background colors.
  468.  
  469. TOUCH2 may also display a warning screen if it cannot set the display mode
  470. to TEXTC80 -- e.g., you have a Hercules monochrome adapter.  While some
  471. display operations may be correct, others, such a color generation, will
  472. not be.  Both warning screens may be disabled with the "warn=off" directive
  473. or the "-w" option on the TOUCH2 call line.
  474.  
  475. TOUCH2 imposes another limitation on color choices when it draws a graph.
  476. Since it uses the VRES16COLOR video mode to draw the graph, it cannot display
  477. a separate background color for the prompt.  The regular background color
  478. appears instead.  The graph background color may be chosen from either group
  479. 1 or 2.
  480.  
  481.  
  482. Checksum Verification
  483. ---------------------
  484.  
  485. Data records dumped from the meter contain a checksum that TOUCH2 can
  486. verify to insure that the records it has read match what the meter sent.
  487. As TOUCH2 reads the data record header and each data record, it computes a
  488. checksum from the characters of the record and compares it with the checksum
  489. value in the record that was computed by the meter when it sent the record.
  490.  
  491. If you get checksum verification error messages, you should check both ends
  492. of the cable that connects your meter to your computer.  A bad connection
  493. might cause some data record characters to be transmitted in error.
  494.  
  495. A less likely cause is that your computer's communication port is not fast
  496. enough to keep up with the meter speed you have chosen.  This is most apt
  497. to happen if you are using the 9600 baud rate.  You can try reducing the
  498. baud rate via the meter's baud rate mode menu.  Once you have changed the
  499. meter's baud rate, you must tell TOUCH2 about the change, using the
  500. communications parameter change menu or the "baudrate" configuration file
  501. directive.  (You can't use TOUCH2 to change the meter's baud rate, because
  502. that would disable communications between TOUCH2 and the meter.)
  503.  
  504. Finally, it is possible that your meter or the special circuitry in the
  505. meter cable is malfunctioning, or it is possible that TOUCH2 is not handling
  506. checksums correctly.  Contact LifeScan if you suspect your meter or cable
  507. is at fault; contact me if you think TOUCH2 is the villain.
  508.  
  509. When TOUCH2 encounters a checksum that can't be verified, it displays the
  510. checksum it computed, the one it received, and the record for which
  511. verification failed.  What follows depends on the source of the dump and the
  512. key you press.
  513.  
  514.     *  If you press the ESCape key, the dump operation will be aborted.
  515.     
  516.     *  If a file is the source of the dump records, and if you press any
  517.        key other than the ESCape key, TOUCH2 will accept the unverified
  518.        record and continue the dump operation.
  519.  
  520.     *  If the meter is the source of the dump records, TOUCH2 will stop
  521.        the dump operation and erase whatever dump records it has already
  522.        stored when you press any key.  It has to take this action because
  523.        dump data coming from the meter will probably have been lost while
  524.        TOUCH2 was waiting for you to press a key.
  525.  
  526. Checksum verification may be disabled with the "-C" option on the TOUCH2
  527. call line, or with the "checksum=off" and "cksum=off" configuration file
  528. directives.
  529.  
  530.  
  531. Meter Error Records
  532. -------------------
  533.  
  534. The meter may occasionally determine that a reading is erroneous.  It will
  535. mark such a reading with an asterisk on its display.  When error records
  536. are dumped from the meter, their reading values are followed by a question
  537. mark.
  538.  
  539. TOUCH2 displays error readings using the meter's asterisk display notation,
  540. but stores them in a dump file with the meter's question mark notation.
  541. TOUCH2 does not include error readings in the statistical summary, but does
  542. display them on the graph.
  543.  
  544. TOUCH2 does not write meter error readings to QuattroPro dump files unless
  545. you request they be written with the C option on the dump menu or the "-c"
  546. option on the TOUCH2 call line.
  547.  
  548.  
  549. Configuration File Example
  550. --------------------------
  551.  
  552. The following is a sample configuration file.  It sets the background color
  553. to white; the text color to black; the prompt background to blue; the prompt
  554. text to yellow; maximum (60 mg/dl) and minimum (150 mg/dl) level line values;
  555. the graph title line to my name; and the default dump file name to C:\MYDUMP.
  556.  
  557. #
  558. # Sample TOUCH2 configuration file
  559. #
  560. bk=WHITE
  561. qdump=C:\MYQPDMP.CSV
  562. text=black
  563. prompttext=yellow
  564. PbK = bLuE
  565. gmin=60
  566. gmax=150
  567. gttl=Victor A. Abell
  568.  
  569. Note the use of the partial keyword "qdump", legitimate because no other
  570. possible keyword begins with the same characters; the use of lower, upper
  571. and mixed case; and the spaces around the equal sign.
  572.  
  573. Here is a sample configuration file for a monochrome, Zenith SuperSport
  574. SX PC.  The color choices were selected to give the best contrast between
  575. the prompt line and the text and graphics displays.
  576.  
  577. #
  578. # Sample TOUCH2 configuration file for monochrome, Zenith SuperSport SX
  579. #
  580. bk=black
  581. text=brightwhite
  582. pbk=white
  583. ptxt=brown
  584.  
  585.  
  586. Saving and Reusing Dumps
  587. ------------------------
  588.  
  589. TOUCH2 will write a meter dump to a file in two formats, QuattroPro and
  590. raw.  The default format is raw.
  591.  
  592. The QuattroPro format contains only meter readings -- no header line -- and
  593. only date, time and meter reading values.  The values are separated by commas,
  594. but are not enclosed in quotation marks.  The default QuattroPro dump file
  595. path is TOUCH2.CSV.
  596.  
  597. The raw format contains a header line and all information provided by the
  598. meter -- date, time, reading type, reading and checksum.  Values are
  599. separated by commas and enclosed in quotation marks.  The raw format is the
  600. only file input format that can be reused.  The default raw dump file path
  601. is TOUCH2.DMP.
  602.  
  603. To write a dump file, select the Dump option from the main menu.  From the
  604. file menu select the dump type with `Q'.  If you select the QuattroPro
  605. format, you may then elect to include or exclude check, error, and high
  606. readings.  Select the File option from the dump menu.  (You may also want
  607. to specify a file path different from the TOUCH2.CSV or TOUCH2.DMP defaults.)
  608.  
  609. To reuse a dump file, select the Dump option from the main menu and the
  610. Read option from the dump menu.  (You may also have to specify a file
  611. path if the default of TOUCH2.DMP isn't acceptable.)  The file must be in
  612. the raw format -- TOUCH2 won't read a dump file written in the QuattroPro
  613. format.
  614.  
  615. You may switch from raw to QuattroPro format with the "-r" option on the
  616. TOUCH2 call line.  You may use the "dump=<format>" configuration file
  617. keyword and value to select either format.
  618.  
  619.  
  620. Graph Printing
  621. --------------
  622.  
  623. If you want to print a graph, select the TOUCH2 options that write a graph
  624. to a file -- Dump from the main menu, Graph from the dump menu and File from
  625. the graph menu.  Then copy the file to your printer -- e.g., to print a graph
  626. written to the default graph file path, use the DOS command:
  627.  
  628.     COPY TOUCH2.GRF PRN
  629.  
  630. You may put a title line on each page of the graph.  The title line may have
  631. no more than 66 characters and it may be defined with the "-t <ttl>" option
  632. on the TOUCH2 call line, with the "graphtitle" or "gttl" configuration file
  633. keyword and associated value, or via the Title option on the dump menu.  The
  634. title line normally follows a page number in the graph output file.  You can
  635. suppress the page number display with the "-P" option on the TOUCH2 call line,
  636. or the configuration file directives "pgctdisp=off" and "pcd=off".
  637.  
  638. When a graph is written to a file, presumably for printing, TOUCH2 puts a
  639. printer control string at the beginning and end of the file.  The beginning
  640. string ("beforegraph") is supplied to condition the printer for the special
  641. needs of the graph; the ending string ("aftergraph")  is supplied to reset
  642. the printer to its previous state.
  643.  
  644. TOUCH2 will supply three predefined strings for the EPSON, PCL4 and PPDS
  645. printer protocols.  See the Defining Strings section for information on
  646. interpreting the following values.
  647.  
  648.     Printer        String        Value
  649.  
  650.     EPSON        aftergraph    \f\e@
  651.             beforegraph    \e0\et1\e7\ex1
  652.  
  653.                     The "aftergraph" string issues a form
  654.                     feed and resets the printer.
  655.  
  656.                     The "beforegraph" string sets 8 lines
  657.                     per inch spacing and selects an IBM
  658.                     graphics character set.
  659.  
  660.     PCL4        aftergraph    \f\eE\4
  661.             beforegraph    \e&l8D\e(10U
  662.  
  663.                     The "aftergraph" string issues a form
  664.                     feed and resets the printer.
  665.  
  666.                     The "beforegraph" string sets 8 lines
  667.                     per inch spacing and the PC-8 font.
  668.  
  669.     PPDS        aftergraph    \f\e[K\1\0\6\4
  670.             beforegraph    \e0
  671.  
  672.                     The "aftergraph" string resets the
  673.                     printer.
  674.  
  675.                     The "beforegraph" string sets 8 lines
  676.                     per inch spacing.
  677.  
  678. If you don't want any special strings, set "aftergraph" to the empty string
  679. -- e.g., put this line in your configuration file
  680.  
  681.     aftergraph=
  682.  
  683. or use this option on the TOUCH2 call
  684.  
  685.     -a^@
  686.  
  687. TOUCH2 expects to print the graph at 8 lines per inch on 11 paper.  Thus,
  688. it sets its lines per page value to 81.  If you change the line spacing or
  689. use different size paper, change the lines per page value with the "lines"
  690. keyword or the "-L <num>" call line option.
  691.  
  692.  
  693. Graph Characters
  694. ----------------
  695.  
  696. TOUCH2 writes a bar graph, containing horizontal bars and vertical lines for
  697. the maximum and minimum level lines.  Normally TOUCH2 uses IBM graphics
  698. characters for the bars and the lines.  It uses the double horizontal line
  699. character (hexadecimal cd) for the bar, the single vertical line character
  700. (hexadecimal b3) for the level lines, and a separate character (hexadecimal
  701. d8) where the horizontal and vertical lines meet.  These three characters
  702. may be redefined with the "bar", "line" and "intersection" strings, or with
  703. the "-b <char>", "-i <char>" and "-l <char>" options on the TOUCH2 call.
  704. See the Defining Strings section for more information on how to build a
  705. string that defines a character.  Here's an example that uses configuration
  706. file keywords and values to set the bar character to `*', the line character
  707. to `|' and the intersection character to `+':
  708.  
  709.     bar=*
  710.     intersection=+
  711.     line=|
  712.  
  713.  
  714. Graph Title
  715. -----------
  716.  
  717. TOUCH2 lets you define a 66 character title line for each page of the graph
  718. output.  You may use the "graphtitle=<ttl>" configuration file directive or
  719. the "-t <ttl>" option on the TOUCH2 call.  However, you can't put embedded
  720. spaces in the <ttl> part of the "-t <ttl>" option, so use the configuration
  721. file directive if you want embedded spaces in your title.
  722.  
  723. When TOUCH2 encounters a dollar sign (`$') in the graph title line, it
  724. attempts to interpolate a built-in or pre-defined variable in its place.  The
  725. following characters define the dollar sign interpolations that are possible.
  726.  
  727.              Result
  728.     Characters   Length    Interpolation
  729.  
  730.     $$        1    single dollar sign -- `$'
  731.     $Dy        3    day of week -- e.g., "Mon"
  732.     $dy        2    month day number with leading 0 -- e.g., "01"
  733.     $dY        2    month day number without leading zero --
  734.                 e.g. " 1"
  735.     $Mo        3    month -- e.g., "Jul"
  736.     $mo        2    month number with leading zero -- e.g., "07"
  737.     $mO        2    month number without leading zero -- e.g., " 7"
  738.     $Yr        4    full year -- e.g., 1993
  739.     $yr        2    year less 1900 -- e.g. "93"
  740.     $Hr        2    hour with leading zero -- e.g., "09"
  741.     $hr        2    hour without leading zero -- e.g., " 9"
  742.     $Mn        2    minute without leading zero -- e.g., " 0"
  743.     $mn        2    minute with leading zero -- e.g., "00"
  744.     $Se        2    second without leading zero -- e.g., " 5"
  745.     $se        2    second with leading zero -- e.g., "05"
  746.     ${name}            value of environment variable <name>
  747.     $n            value of title variable n [0-9]
  748.  
  749. Note that the values of similarly named built-in variables -- e.g., $dy and
  750. $hr -- are not consistent for the handling of leading zeros.  TOUCH2 does this
  751. so that the easiest usage generates the most commonly expected result -- e.g.,
  752. $dy usually has a leading zero in yy/mm/dd forms, while $hr usually does not
  753. have one in hh:mm:ss forms.
  754.  
  755. Here's an example.  If the uninterpolated graph title line is:
  756.  
  757.     Victor A. Abell, $dY $Mo $yr
  758.  
  759. and today's date is July 7, 1993, the interpolated graph title line is:
  760.  
  761.     Victor A. Abell,  7 Jul 93
  762.  
  763. TOUCH2 always displays the interpolated graph title line on the dump menu and
  764. in the graph.  However, when you select the entry of a new title with the T
  765. option of the dump menu, TOUCH2 displays the uninterpolated line for you to
  766. inspect and change.
  767.  
  768. Remember that the length of the uninterpolated and interpolated graph title
  769. lines is limited to 66 characters.
  770.  
  771.  
  772. Graph Title Variables
  773. ---------------------
  774.  
  775. TOUCH2 will interpolate ten graph title variables, represented by $0 through
  776. $9, in the graph title line.  The graph title variables may be defined with
  777. the "titlevar=<n>,<val>" configuration file directive or the "-v <n>,<val>"
  778. option on the TOUCH2 call line.  However, you can't put embedded spaces in
  779. the <var> part of the "-v <var>" option, so use the configuration file
  780. directive if you want embedded spaces in a graph title variable.  You can
  781. define a variable in the configuration file and then redefine it with a call
  782. line option.
  783.  
  784. Here is an example.  Assume that TOUCH2.CF contains:
  785.  
  786.     titlevar=5,last month's
  787.     tv=0,7.2
  788.     graphtitle=Victor A. Abell, $5 A1C=$0
  789.  
  790. And the TOUCH2 call line is:
  791.  
  792.     touch2 -v 0,6.8
  793.  
  794. Then the title line displayed on the dump menu and placed in the graph is:
  795.  
  796.     Victor A. Abell, last month's A1C=6.8
  797.  
  798. The "-v 0,6.8" option on the TOUCH2 call line redefined the value of graph
  799. title variable $0 to be 6.8, replacing the value of 7.2 set by the "tv=0,7.2"
  800. configuration file directive.  ("tv" is shorthand for "titlevar".)
  801.  
  802.  
  803. Defining Strings
  804. ----------------
  805.  
  806. TOUCH2 uses strings in its configuration file and on its call to define
  807. special characters.  Here are the rules it follows:
  808.  
  809.     *  Non-special characters are taken from a string until a `\' is
  810.        encountered.
  811.  
  812.     *  The `\' leads a special character definition.  It may be followed
  813.        by:
  814.  
  815.        \        to define a `\' character
  816.  
  817.        e or E    to define an ESCape (hexadecimal 1b)
  818.  
  819.        f or F    to define a form feed (hexadecimal 0c)
  820.  
  821.        n or N    to define a line feed (hexadecimal 0a)
  822.  
  823.        r or R    to define a carriage return (hexadecimal 0d)
  824.  
  825.        t or T    to define a TAB (hexadecimal 09)
  826.  
  827.        ^        followed by any character in the set [@A-Z] to
  828.             define an ASCII control character -- ^@ produces
  829.             0; ^A, 1; etc.
  830.  
  831.        0o        (zero, lower case "oh") followed by 3 octal digits
  832.             to define an octal character value
  833.  
  834.        0t        (zero, lower case "tee") followed by 3 decimal digits
  835.             to define a decimal character value
  836.  
  837.        hh        two hexadecimal characters that define a single
  838.             character value
  839.  
  840. Here are some examples:
  841.  
  842.     \e0        defines a string with the two characters ESCape and
  843.             zero.
  844.  
  845.     \0o0330        defines the same string -- ESCape and zero.
  846.  
  847.     \0t0270        defines the same string -- ESCape and zero.
  848.  
  849.     \e[K\1\0\6    defines a string with ESCape, left bracket, capital
  850.             `K', hexadecimal 1, hexadecimal 0, and hexadecimal 6.
  851.  
  852.     \f\EE        defines a string with a form feed, an ESCape and a
  853.             capital `E'.
  854.     
  855.     \@        defines a hexadecimal 0 value
  856.  
  857. These strings may be used as values after keywords in the configuration file
  858. and on the TOUCH2 call.  When used on the TOUCH2 call you should be careful
  859. to avoid using characters that have special meaning to your command
  860. interpreter -- e.g., the vertical bar (`|').
  861.  
  862.  
  863. The TOUCH2 Call
  864. ---------------
  865.  
  866. Some options that may be specified with configuration file keywords and
  867. values may also be specified as options on the TOUCH2 call.  The option
  868. indicator is the minus sign (`-') and the option keywords are single
  869. characters.  When the same options are specified both ways, the call
  870. line values apply.
  871.  
  872. Strings and characters are defined as described in the Defining Strings
  873. section.  The options include:
  874.  
  875.     -a <string>    <string> is a string defining the "aftergraph" printer
  876.             control string.
  877.  
  878.     -b <char>    <char> is a string defining the printed graph bar
  879.             character.
  880.  
  881.     -B <string>    <string> is a string defining the "beforegraph"
  882.             printer control string.
  883.  
  884.     -c        selects the inclusion of check, error, and high
  885.             readings in a QuattroPro dump file.  The default is
  886.             to exclude these readings.
  887.  
  888.     -C        turn off checksum verification
  889.  
  890.     -g <min>    sets the graph minimum level line value to <min>.
  891.             The default is 70 mg/dl or 3.9 mmol/l.
  892.  
  893.     -G <max>    sets the graph maximum level line value to <max>.
  894.             The default is 110 mg/dl or 6.1 mmol/l.
  895.  
  896.     -h        causes the display of "help" (usage) output.  No
  897.             further processing takes place.  TOUCH2 also displays
  898.             the "help" output and stops when it detects an error
  899.             in its options or in the configuration file.
  900.  
  901.     -i <char>    <char> is a string that defines the printed graph
  902.             intersection character.
  903.  
  904.     -l <char>    <char> is a string that defines the displayed and
  905.             printed graph intersection character.
  906.  
  907.     -L <num>    <num> defines the number of lines on the printed graph
  908.             page.  The default is 81.  The minimum is 11.
  909.  
  910.     -p <name>    <name> defines the printer type -- EPSON, PCL4 or
  911.             PPDS.  The default is EPSON when the "aftergraph"
  912.             printer control string is undefined.
  913.  
  914.     -P        turns off the display of the page number in the graph
  915.             output file.
  916.  
  917.     -r        deselects a raw dump file format in favor of
  918.             the QuattroPro dump format.
  919.  
  920.     -t <ttl>    sets the graph title line to <ttl>.
  921.  
  922.             WARNING: <ttl> may not have embedded spaces -- use
  923.             the "graphtitle" configuration file directive to
  924.             embed spaces in the graph title line.
  925.  
  926.     -v <n>,<val>    sets title variable n [0-9] to <val>.
  927.  
  928.             WARNING: <val> may not have embedded spaces -- use
  929.             the "titlevar" configuration file directive to embed
  930.             spaces in title variables.
  931.  
  932.     -w        disables warnings about display mode.
  933.  
  934.  
  935. Comments
  936. --------
  937.  
  938. Please direct comments to me via e-mail -- abe@cc.purdue.edu.
  939.  
  940. Vic Abell
  941. August 14, 1993
  942.