home *** CD-ROM | disk | FTP | other *** search
/ Power-Programmierung / CD1.mdf / xbase / library / clipper / progr_ba / status.man < prev    next >
Text File  |  1992-03-01  |  23KB  |  595 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.                                  STATUS version 1.10
  9.                                       (c) 1992
  10.                                          by
  11.                                 John T. Opincar, Jr.
  12.                                    CID: 71631,541
  13.  
  14.                                   February 27, 1992
  15.  
  16.           =================================================================
  17.                                   COPYRIGHT NOTICE
  18.           =================================================================
  19.           PLEASE READ THIS!
  20.  
  21.           You are free to distribute STATUS in any manner you choose and
  22.           use STATUS in any setting, including commercial without any
  23.           obligation to me.  The only thing that I ask is that you do not
  24.           distribute modified versions of STATUS without including the
  25.           original code and documentation in its entirety.  If you feel
  26.           inclined to distribute STATUS with your own  modifications (which
  27.           I would discourage), ***PLEASE*** keep your changes in seperate
  28.           files, and make the seperation and changes obvious to anyone who
  29.           might subsequently encounter the ZIP.
  30.  
  31.           I have been informally supporting STATUS on CIS, and do not want
  32.           a zillion messages about problems introduced by others.  In lieu
  33.           of making your own changes, I would prefer that you send me e-
  34.           mail describing the additional features you would like to see in
  35.           STATUS.  The exceptional performance gains yielded by STATUS are
  36.           the result of several key assumptions about how it will be used.
  37.           Before making a suggestion, please read the section in the
  38.           documentation entitled, "What Makes STATUS Tick." The main
  39.           motivation behind this version of STATUS was input I received
  40.           from users.
  41.  
  42.           Finally, some users of the first version expressed a desire to
  43.           pay for STATUS, even though no payment was requested.  If you
  44.           wish to send in a payment (none is required, but WILL be
  45.           appreciated) send it to:
  46.             John T. Opincar, Jr.
  47.             6531 West Medalist
  48.             Plano, TX 75023
  49.  
  50.           =================================================================
  51.                                     INTRODUCTION
  52.           =================================================================
  53.           This small library was inspired by a thread I encountered while
  54.           lurking on NANFORUM.  The purpose of these functions is to
  55.           provide the user with feedback on the progress of PACKs and
  56.           INDEXes without incurring significant overhead.  This is
  57.           accomplished by hooking the timer interrupt and updating the
  58.           progress display isosynchronously using the current values of
  59.           RECNO() and LASTREC() in the currently SELECTed database.
  60.  
  61.           This is the second version of STATUS.  New features include:
  62.  
  63.  
  64.  
  65.                                           1
  66.  
  67.  
  68.  
  69.  
  70.  
  71.  
  72.  
  73.  
  74.             * Simultaneous display of a progress bar and percent number
  75.             * The ability to specify color as either a number or Clipper
  76.               color string
  77.             * The ability to specify the charcter used to fill in the
  78.               progress bar
  79.             * StatusPack(), a high-level interface to the STATUS functions
  80.               that will let you use STATUS without really getting your
  81.               hands dirty
  82.  
  83.           The best example of how to use the STATUS functions is in
  84.           TIMENTXP.PRG.  If StatusPack() does not do exactly what you want,
  85.           then you will need to use the lower level functions.  A brief
  86.           overview of how to do this follows:
  87.             1) Enable/Disable the display of the progress bar using
  88.                StatusBar()
  89.             2) Enable/Disable the display of the percent number using
  90.                StatusNumber()
  91.             3) USE or SELECT the database which will be acted upon
  92.             4) Position the record pointer to the first record to be
  93.                processed.  The record numbers must be encountered in
  94.                natural order, ie no index should be controlling the
  95.                ordering of the records.  A filter can be in effect, eg
  96.                !deleted().
  97.             5) Call StatusOn()
  98.             6) Begin processing records, eg PACK or INDEX ON TO
  99.             7) Call StatusOff()
  100.  
  101.           You can use these functions in your Clipper 5.x code (NOT Summer
  102.           '87 compatible) by including STATUS.LIB in your link file.  If
  103.           you wish to check the return codes of STATUS functions, #include
  104.           "status.ch" in your program files.
  105.  
  106.           Please read the rest of this SHORT documentation carefully before
  107.           attempting to use these functions.
  108.  
  109.  
  110.           -----------------------------------------------------------------
  111.                                      STATUSBAR()
  112.           -----------------------------------------------------------------
  113.  
  114.           SYNTAX
  115.           ------
  116.           StatusBar(<nRow>, [<nCol>, <barChar>, <barColor>]) -> nErrorCode
  117.  
  118.           RETURNS
  119.           -------
  120.           0 if everything is OK, a negative error code otherwise.  The
  121.           possible error codes returned by StatusBar() are BAD_PARM_COUNT,
  122.           TYPE_MISMATCH, and BAD_COORDS.  For a complete explanation, see
  123.           "Description of Error Codes" below.
  124.  
  125.  
  126.  
  127.  
  128.  
  129.  
  130.  
  131.                                           2
  132.  
  133.  
  134.  
  135.  
  136.  
  137.  
  138.  
  139.  
  140.           ARGUMENTS
  141.           ---------
  142.           <nRow> is the row where the progress bar will be displayed.  If
  143.           <nRow> is negative, then display of the progress bar will be
  144.           disabled.  Note that when a negative value is specified for
  145.           <nRow>, <nRow> is the only argument expected to be passed.
  146.  
  147.           <nCol> is the column where the progress bar will be displayed.
  148.  
  149.           <barChar> can be either a character or the ASCII value of the
  150.           character which will be used in the progress bar.
  151.  
  152.           <barColor> can be either a number or Clipper color specification,
  153.           eg. "W+/R".  See "Specifying Colors As Numbers" below, if you are
  154.           unfamiliar with numeric color attributes and would like to use
  155.           them.
  156.  
  157.           DESCRIPTION
  158.           -----------
  159.           StatusBar() allows you to specify the position, color, and
  160.           composition of the progress display bar.  You can also disable
  161.           the display of the progress bar by passing a negative value for
  162.           <nRow>.  Note that the number of arguments expected by
  163.           StatusBar() changes depending on the value of <nRow>.  If <nRow>
  164.           is negative, then StatusBar() expects exactly one argument.  If
  165.           more arguments are passed, StatusBar() will return an error code,
  166.           BAD_PARM_COUNT, and the erroneous call to StatusBar() will have
  167.           no effect.  If <nRow> is non-negative, exactly 4 arguments are
  168.           expected.
  169.  
  170.           StatusBar() should be called before StatusOn().  Note that only
  171.           one call to StatusBar() is needed, assuming that you do not want
  172.           to change the position, color, or display character for
  173.           subsequent progress displays.
  174.  
  175.           You can have both a progress bar and percent number displayed
  176.           simultaneously.  See StatusNumber() below.
  177.  
  178.           EXAMPLES
  179.           --------
  180.           /* Set progress bar display at position 10,5 using a shaded block
  181.              character in high intensity white on red. */
  182.           StatusBar(10, 5, 176, 'w+/r')
  183.           use EMPLOYEE exclusive new
  184.           StatusOn()
  185.           pack
  186.           StatusOff()
  187.  
  188.           /* Note that subsequent progress display will use settings from
  189.              last call to StatusBar() */
  190.           dbGoTop()
  191.           StatusOn()
  192.           index on upper(NAME) to EMPLNAME
  193.           StatusOff()
  194.  
  195.  
  196.  
  197.                                           3
  198.  
  199.  
  200.  
  201.  
  202.  
  203.  
  204.  
  205.  
  206.  
  207.           /* Disable progress bar display */
  208.           StatusBar(-1)
  209.  
  210.           /* Erroneous call to StatusBar() that will be ignored */
  211.           ? StatusBar(-1, 5, 176, 'w+/r')    /* returns BAD_PARM_COUNT */
  212.  
  213.           /* Another erroneous call to StatusBar() that will be ignored */
  214.           ? StatusBar(5, 5)                  /* returns BAD_PARM_COUNT */
  215.  
  216.           SEE ALSO
  217.           --------
  218.           StatusNumber()
  219.  
  220.  
  221.           -----------------------------------------------------------------
  222.                                    STATUSNUMBER()
  223.           -----------------------------------------------------------------
  224.  
  225.           SYNTAX
  226.           ------
  227.           StatusNumber(<nRow>, [<nCol>, <numColor>]) -> nErrorCode
  228.  
  229.           RETURNS
  230.           -------
  231.           0 if everything is OK, a negative error code otherwise.  The
  232.           possible error codes returned by StatusNumber() are
  233.           BAD_PARM_COUNT, TYPE_MISMATCH, and BAD_COORDS.  For a complete
  234.           explanation, see "Description of Error Codes" below.
  235.  
  236.           ARGUMENTS
  237.           ---------
  238.           <nRow> is the row where the percent number will be displayed.  If
  239.           <nRow> is negative, then display of the percent number will be
  240.           disabled.  Note that when a negative value is specified for
  241.           <nRow>, <nRow> is the only argument expected to be passed.
  242.  
  243.           <nCol> is the column where the percent number will be displayed.
  244.  
  245.           <numColor> can be either a number or Clipper color specification,
  246.           eg. "W+/R".
  247.           See "Specifying Colors As Numbers" below, if you are unfamiliar
  248.           with numeric color attributes and would like to use them.
  249.  
  250.           DESCRIPTION
  251.           -----------
  252.           StatusNumber() allows you to specify the position and color of
  253.           the percent number.  You can also disable the display of the
  254.           percent number by passing a negative value for <nRow>.  Note that
  255.           the number of arguments expected by StatusNumber() changes
  256.           depending on the value of <nRow>.  If <nRow> is negative, then
  257.           StatusNumber() expects exactly one argument.  If more arguments
  258.           are passed, StatusNumber() will return an error code,
  259.           BAD_PARM_COUNT, and the erroneous call to StatusNumber() will
  260.  
  261.  
  262.  
  263.                                           4
  264.  
  265.  
  266.  
  267.  
  268.  
  269.  
  270.  
  271.  
  272.           have no effect.  If <nRow> is non-negative, exactly 3 arguments
  273.           are expected.
  274.  
  275.           StatusNumber() should be called before StatusOn().  Note that
  276.           only one call to StatusNumber() is needed, assuming that you do
  277.           not want to change the position or color of the percent number
  278.           for subsequent progress displays.
  279.  
  280.           You can have both a percent number and progress bar displayed
  281.           simultaneously.  See StatusBar() above.
  282.  
  283.           EXAMPLES
  284.           --------
  285.           /* Set percent number at position 10,5 in high intensity white on
  286.              red. */
  287.           StatusNumber(10, 5, 'w+/r')
  288.           use EMPLOYEE exclusive new
  289.           StatusOn()
  290.           pack
  291.           StatusOff()
  292.  
  293.           /* Note that subsequent progress display will use settings from
  294.              last call to StatusNumber() */
  295.           dbGoTop()
  296.           StatusOn()
  297.           index on upper(NAME) to EMPLNAME
  298.           StatusOff()
  299.  
  300.           /* Disable percent number display */
  301.           StatusNumber(-1)
  302.  
  303.           /* Erroneous call to StatusNumber() that will be ignored */
  304.           ? StatusNumber(-1, 5, 'w+/r') /* returns BAD_PARM_COUNT */
  305.  
  306.           /* Another erroneous call to StatusNumber() that will be ignored
  307.           */
  308.           ? StatusNumber(5, 5)          /* returns BAD_PARM_COUNT */
  309.  
  310.           SEE ALSO
  311.           --------
  312.           StatusBar()
  313.  
  314.  
  315.           -----------------------------------------------------------------
  316.                                      STATUSON()
  317.           -----------------------------------------------------------------
  318.  
  319.           SYNTAX
  320.           ------
  321.           StatusOn([<nTicks>]) -> nErrorCode
  322.  
  323.  
  324.  
  325.  
  326.  
  327.  
  328.  
  329.                                           5
  330.  
  331.  
  332.  
  333.  
  334.  
  335.  
  336.  
  337.  
  338.           ARGUMENTS
  339.           ---------
  340.           <nTicks> is the number of timer ticks (approx. 1/18 seconds per
  341.           tick) between updates of the progress display.  This argument is
  342.           optional and will default to 18 if not passed.
  343.  
  344.           RETURNS
  345.           -------
  346.           0 if everything is OK, a negative error code otherwise.  The
  347.           possible error codes returned by StatusOn() are BAD_PARM_COUNT,
  348.           TYPE_MISMATCH, BAD_TICKS, NO_DBF_USED, and BAD_ORDER.
  349.  
  350.           DESCRIPTION
  351.           -----------
  352.           StatusOn() activates the timed display of progress information at
  353.           the specified coordinates.  The display will be updated every
  354.           <nTicks> based on the current position of the record pointer
  355.           relative to the total number of records in the database.
  356.           Progress will be displayed using a bar up to 50 characters wide
  357.           and/or a number between 0 and 100 representing the percentage of
  358.           the task which has been completed (see StatusBar() and
  359.           StatusNumber() above).
  360.  
  361.           There are two important restrictions on the use of StatusOn().
  362.           First, the currently SELECTed area CANNOT be changed between the
  363.           calls to StatusOn() and StatusOff().  Second, the records of the
  364.           currently selected database must be traversed in their natural
  365.           order, ie record #1 must come before record #2, etc.  There are
  366.           good reasons for these restrictions.  See "What Makes STATUS
  367.           Tick" below.  These restrictions reflect the two primary uses of
  368.           STATUS -- to display the progress of the INDEX and PACK.
  369.  
  370.           A reasonable value for <nTicks> is 18 which means that the
  371.           progress display will be updated every second.  Keep in mind that
  372.           smaller values for <nTicks> incur greater overhead because the
  373.           progress display is updated more frequently.
  374.  
  375.           NOTE: StatusOn() should only be called AFTER the database for
  376.           which progress will be monitored has been USEd or SELECTed and
  377.           the record pointer has been positioned to the first record to be
  378.           processed.
  379.  
  380.           NOTE: Every call to StatusOn() should be followed by a call to
  381.           StatusOff() before the currently SELECTed area is changed.
  382.  
  383.           EXAMPLES
  384.           --------
  385.           See TIMENTXP.PRG
  386.  
  387.           SEE ALSO
  388.           --------
  389.           StatusOff()
  390.  
  391.  
  392.  
  393.  
  394.  
  395.                                           6
  396.  
  397.  
  398.  
  399.  
  400.  
  401.  
  402.  
  403.  
  404.           -----------------------------------------------------------------
  405.                                      STATUSOFF()
  406.           -----------------------------------------------------------------
  407.  
  408.           SYNTAX
  409.           ------
  410.           StatusOff() -> NIL
  411.  
  412.           DESCRIPTION
  413.           -----------
  414.           StatusOff() turns off the progress display.  StatusOff() should
  415.           always be called after StatusOn() and before the currently
  416.           SELECTed database is CLOSEd or another area is SELECTed.
  417.  
  418.           SEE ALSO
  419.           --------
  420.           StatusOn()
  421.  
  422.  
  423.           -----------------------------------------------------------------
  424.                                     STATUSPACK()
  425.           -----------------------------------------------------------------
  426.  
  427.           SYNTAX
  428.           ------
  429.           StatusPack(<cDbfName>, [<aNtxInfo>]) -> lSuccess
  430.  
  431.           ARGUMENTS
  432.           ---------
  433.           <cDbfName> is the name of the database to be PACKed and have its
  434.           indices built.  Do NOT add the .DBF extension.
  435.  
  436.           <aNtxInfo> is an array of arrays.  Each sub-array should contain
  437.           the index name as its first element and the index key as its
  438.           second element.  <aNtxInfo> is optional.  If not passed, then the
  439.           database will only be PACKed.
  440.  
  441.           RETURNS
  442.           -------
  443.           .T. if the PACK and INDEX operations were successful.
  444.  
  445.           DESCRIPTION
  446.           -----------
  447.           StatusPack() is a high-level interface to the rest of the STATUS
  448.           functions.  It displays a box with a line for the pack progress
  449.           display and one line to display the progress for each index to be
  450.           built.  If the specified database is already in USE, it will be
  451.           closed and an attempt will be made to re-USE it EXCLUSIVEly.
  452.  
  453.  
  454.  
  455.  
  456.  
  457.  
  458.  
  459.  
  460.  
  461.                                           7
  462.  
  463.  
  464.  
  465.  
  466.  
  467.  
  468.  
  469.  
  470.           EXAMPLES
  471.           --------
  472.           StatusPack('people', { {'peopname', 'upper(LAST)+upper(FIRST)'},;
  473.                                  {'peopphon', 'PHONE'}, ;
  474.                                  {'peopcity', 'upper(CITY)'}, ;
  475.                                  {'peopzip', 'ZIP'} })
  476.  
  477.  
  478.           =================================================================
  479.                              DESCRIPTION OF ERROR CODES
  480.           =================================================================
  481.           Error codes are returned as negative integers.  These codes are
  482.           defined in STATUS.CH.  A brief explanation of what each of these
  483.           codes means follows.
  484.  
  485.           BAD_PARM_COUNT (-1)
  486.           -------------------
  487.           The wrong number of arguments was passed to a function.
  488.  
  489.           TYPE_MISMATCH  (-2)
  490.           -------------------
  491.           The wrong type of argument was passed to a function.
  492.  
  493.           BAD_COORDS     (-3)
  494.           -------------------
  495.           Invalid coordinates were passed to either StatusBar() or
  496.           StatusNumber().  Note that a negative row can be passed as the
  497.           first and only argument to either StatusBar() or StatusNumber()
  498.           which disables the respective display.  In any other case,
  499.           negative coordinates are invalid.
  500.  
  501.           BAD_TICKS      (-4)
  502.           -------------------
  503.           A zero or negative value was passed to StatusOn() as the <nTicks>
  504.           argument.
  505.  
  506.           NO_DBF_USED    (-5)
  507.           -------------------
  508.           StatusOn() was called and no database was in USE in the currently
  509.           SELECTed area.
  510.  
  511.           BAD_ORDER      (-6)
  512.           -------------------
  513.           StatusOn() was called and the database in USE in the currently
  514.           SELECTed area had an index controlling its order.
  515.  
  516.  
  517.           =================================================================
  518.                             SPECIFYING COLORS AS NUMBERS
  519.           =================================================================
  520.           Both StatusBar() and StatusNumber() take a color as one of their
  521.           arguments.  You can specify color as a Clipper color string, or
  522.           you can pass a number.  I detest the cumbersome xBase color
  523.           string system and never use it in my own code.  If you also use
  524.  
  525.  
  526.  
  527.                                           8
  528.  
  529.  
  530.  
  531.  
  532.  
  533.  
  534.  
  535.  
  536.           color numbers, then you probably don't need to see this, but I
  537.           included it for the sake of completeness.
  538.  
  539.           Black               0         Dark Gray           8
  540.           Blue                1         Light Blue          9
  541.           Green               2         Light Green         10
  542.           Cyan                3         Light Cyan          11
  543.           Red                 4         Light Red           12
  544.           Magenta             5         Light Magenta       13
  545.           Brown               6         Yellow              14
  546.           Light Gray          7         White               15
  547.  
  548.           To construct foreground and background combinations, use the
  549.           following formula:  (background * 16) + foreground.  Note that
  550.           using any of the colors in the second column as the background
  551.           value may cause blinking depending on the current state of the
  552.           video adapter.
  553.  
  554.           Note that many of these colors and combinations thereof will not
  555.           be available on monochrome and LCD displays.
  556.  
  557.           =================================================================
  558.                                WHAT MAKES STATUS TICK?
  559.           =================================================================
  560.           The use of STATUS has very little impact on the time required to
  561.           PACK and INDEX databases.  One user compared three different
  562.           methods of packing and indexing on a large database.  The first
  563.           method was straight PACK and INDEX with no progress display which
  564.           was used as a baseline.  The second method was to include a user-
  565.           defined progress display function as part of the index
  566.           expression.  This resulted in 50% increase in the time required
  567.           to PACK and INDEX the database.  The third method was using
  568.           STATUS which resulted in a mere 2% increase.
  569.  
  570.           There are two key reasons for this.  First, STATUS uses the timer
  571.           interrupt to update the progress display isosynchronously.  This
  572.           means that the rate at which the display is updated is driven by
  573.           the needs of the user, not by the number of records in the
  574.           database.  A naive progress display UDF will update the display
  575.           every time it is called, ie once for every record.  If there are
  576.           more than 100 records in the database, then some of these updates
  577.           will re-write what is already on the screen.  As the number of
  578.           records in the database becomes large, the majority of updates
  579.           are useless.  A sophisticated UDF can avoid these needless
  580.           updates by calculating a delta value or tracking time.  Thus,
  581.           isosynchronous display alone, does not make STATUS any better
  582.           than a well-written UDF.
  583.  
  584.           However, any UDF, no matter how well-written must still incur the
  585.           overhead of a Clipper function call and building a Clipper stack
  586.           frame is relatively expensive.  This points out the second key to
  587.           STATUS's superior performance: no Clipper function call is
  588.           required.  STATUS directly accesses the record number and record
  589.           count in the Workareas structure.
  590.  
  591.  
  592.  
  593.                                           9
  594.  
  595.