home *** CD-ROM | disk | FTP | other *** search
/ Shareware Overload / ShartewareOverload.cdr / database / pages2.zip / PAGES.DAT < prev    next >
Text File  |  1986-11-25  |  10KB  |  200 lines

  1.  
  2.      Hello, dBase developers!
  3.  
  4.      This is PAGES, a dBase III Plus procedure which your programs can call
  5. to provide on-screen displays.  I'm using PAGES here to display on-line
  6. documentation, and it can also be used to display on-line reports that won't
  7. scroll off the top of the screen, that the user can page through forward and
  8. backward, that the user can search.
  9.  
  10.      I wrote PAGES to provide ELECTRONIC LEDGER CARDS for an accounting
  11. program.  When a user of that accounting program wants to see the ledger
  12. card for a customer, the customer information is generated on the fly
  13. (the program works in real-time, not through batch updates), sent
  14. to an ALTERNATE file instead of to the screen, and the alternate file is
  15. passed to PAGES which displays it nicely on the screen.
  16.  
  17.      If you examine the menu bar on the bottom, you'll see that you can go
  18. to the next page by pressing the N key (or Down arrow or PgDn).
  19.  
  20.  
  21.      Now you're on page 2.  You can take a look at page 1 again, if you
  22. like, by pressing the P key (or Up arrow or PgUp).
  23.  
  24.      This is pretty different from most dBase programs I've seen where once
  25. something moves off the top of the screen, it's gone.  The idea behind PAGES
  26. is that once a listing is captured, it can be manipulated interactively.
  27.  
  28.      In short, PAGES is a procedure for displaying more than one screenful
  29. of information in any dBase III Plus application.  Of course, a single
  30. screen of information can be displayed as well.
  31.  
  32.      There are other options available.  If you press the S key now,
  33. you'll be asked for a phrase to search for.  Once you've searched once,
  34. you can move to the next occurrence of a phrase by pressing the R key.
  35.  
  36.      You can also jump to pages by pressing a number key.  Go the next page
  37. (page 3) by pressing the 3 key instead of N.
  38.  
  39.  
  40.      Of course, you didn't have to press 3.  You could have moved directly
  41. to page 6, for instance, by pressing the 6 key.  You can jump to a page
  42. number with more than one digit:  Press the # key and you'll be asked for a
  43. page number.  After you press RETURN, you'll move straight to that page.
  44.  
  45.      PAGES is reasonably bomb-proof in that if you ask to go to page 9 in a
  46. file with only 6 pages, you'll be taken to the last page.  If you press the
  47. # key and then tell PAGES you want to go to page 0.4 or page -3.2 or
  48. something like that, naturally you'll be taken to page 1.
  49.  
  50.      Two other options on the menu line are Begin and End.  Press the B key
  51. or the PC Home key and you'll go to page 1.  Press the E key or the PC End
  52. key and you'll be taken to the last page.
  53.  
  54.      The menu item File allows you to switch to another file.  You can
  55. examine the source code for PAGES, for example, by switching to PAGES.SRC
  56. (.SRC because I'm using dBase psuedo-compiler).  Then you can come back
  57. here:  the name of this file is PAGES.DAT
  58.  
  59.      I hope you did go look at pages.src because now I want to discuss the
  60. code a little bit.  Starting with, how DID we switch to another file?
  61. In a previous version of PAGES, I employed recursion:  PAGES would call
  62. itself whenever you asked to switch files.  But recursion in dBase reaches
  63. it maximum at 20 nested DO's.  This version has PAGES sends a message back
  64. to whatever program called it saying, in effect, that it wants to be called
  65. again.  Okay, so it's not Smalltalk, but it's a technique anyway.
  66.  
  67.      You may have noticed that PAGES puts lines on the screen fairly
  68. rapidly.  Two comments on this:
  69.  
  70.      First, having learned dBase AFTER knowing C, it took a while to learn
  71. to use dBase non-procedural, non-navigational commands.  For instance, lines
  72. of text could be displayed in a do-while loop.  But it is much faster to use
  73. the non-procedural dBase command LIST.  If you are interested in the
  74. difference between procedural and non-procedural languages, I can recommend
  75. a wonderful book:  Relational Database: Selected Writings, by C.J. Date
  76. (Reading, MA: Addison-Wesley, 1986).
  77.  
  78.      Second, in running PAGES under Microsoft Windows, I found that, because
  79. dBase III Plus is a well-behaved program that does not write directly to the
  80. screen buffer (which is why it can run under Windows in the first place),
  81. it's horribly slow in putting stuff on the screen.  Calling DOS to update
  82. the screen, instead of doing an end run and jamming the screen buffer itself
  83. like a lot of programs, IS important, but you still want to minimize dBase's
  84. interaction with the screen:  list off trim(line) represents a significant
  85. improvement over list off line, just as list represents a significant
  86. improvement over a do-while loop.
  87.  
  88.      Some other odds and ends:
  89.  
  90.      We turn off the cursor with cursoff.bin, a tiny file that comes on the
  91. sample/utilities disk of dBase III Plus.  Then we maintain our own blinking
  92. cursor with set color to w*.  When we're done we set the cursor back on with
  93. curson.bin.  In this way, the screen does not flicker and flash when we
  94. redraw.
  95.  
  96.  
  97.      PAGES maintains an internal model of which line number (i.e., which
  98. recno() in line.dbf) is on what page, based on two simple formulas:
  99.  
  100.      page = int((recno() - MYTOP) / DEPTH) + 1
  101.      recno() = ((page - 1) * DEPTH) + MYTOP
  102.  
  103.      For instance, if we're on line 102 and the display is 19 lines deep and
  104. line 1 is the first good line in the file (MYTOP), then we're on int(102 -
  105. 1) / 19) + 1 = page 6.  Which is where we are now.
  106.      Likewise, what is the first line on page 6?  ((6 - 1) * 19) + 1 = 96.
  107.      You don't have to know any of this to use PAGES.
  108.  
  109.      I mentioned earlier that PAGES was written to provide on-screen
  110. ledgers.  Since I've been using PAGES here merely to display its own
  111. documentation, it might not be obvious how you would use it to display
  112. ledgers or listings.
  113.  
  114.      If you turn the page, so to speak, I'll give you an example:
  115. *************************** CODE FRAGMENT *************************
  116. set alternate to temp.txt
  117. set alternate on
  118. @5,0 say "Working...."
  119. set console off
  120. set heading off
  121. list off custcode,"  ",bill_date,"  ",job_num,"  ", ;
  122.    substr(job_desc,1,28),"  ",bill_total for custcode = cust
  123. sum bill_total to grand_total for custcode = code   && or seek, then while
  124. ? "Total... ",cust,"... $",grand_total
  125. set alternate off
  126. close databases
  127. close alternate
  128. set console on
  129. close procedure                             && important!!
  130. set procedure to pages
  131. do PAGES with "temp.txt", 2, 18, 5, 3, 0, .F.  && explanation on next page
  132. close procedure
  133. set procedure to myproc
  134.      The parameters to PAGES are:
  135.      FILENAME = ASCII (SDF) text file containing anything you want.  In this
  136.                 demo, PAGES.DAT is just a word-processing file created by
  137.                 Sidekick.  In the code fragment above, TEMP.TXT is
  138.                 redirected output from dBase III LIST command.
  139.      MYTOP    = first good line in the text file.  Usually 1, but not always.
  140.      DEPTH    = how many lines to display.  From this and MYTOP, PAGES will
  141.                 figures out where to put the menu line.  It will also tell
  142.                 if you're asking the impossible (as defined by 25-line PC
  143.                 screen. Any one working on 43-line displays?)
  144.      START    = what screen row() to start output
  145.      SHOWPAGE = what screen row() to show "Page x of x" display
  146.      SHOWRULE = what screen row() to show upper rule. 0 means don't show it.
  147.      SWITCH_OK= is user allowed to switch to another file?
  148.  
  149.      PAGES will only clear the parts of the screen it owns:  this means you
  150. can put things on the screen and call PAGES with the knowledge that your
  151. messages on the top of the screen won't get wiped out.
  152.  
  153.      To sum up:
  154.  
  155.      Most dBase displays disappear forever once they scroll off the top of
  156. the screen, but PAGES are not a one-shot deal.  PAGES displays exist on a
  157. much more physical level than is usual in on-screen reports because we save
  158. the reports in a database file and THEN display them.
  159.  
  160.      I'd like to mention, by the way, that any of the preceding sentences
  161. which make sense to you were written by Amanda Claiborne, my wife.  She is
  162. also responsible for those sentences in the documentation for my program
  163. MAKEMEM which are intelligible.
  164.  
  165.     And speaking of MAKEMEM...  You can get this collection of dBase III
  166. utilities written in C from places like PL Olympia's Darwin bulletin board
  167. (301-251-9206) or the Ashton-Tate forum on CompuServe, or by sending $15 to
  168. the programmer who remains, as always, your humble servant,
  169.  
  170.     Andrew Schulman, 12 Humboldt Street, Cambridge MA 02140, 617-876-2102
  171.  
  172.  
  173. P.S.  Yes, Virginia, there are bugs.  The definition of a page is a bit
  174. fluid and, consequently, the top line of, say, page 7 might be a different
  175. line depending on whether you come at it from the beginning, by page
  176. backwards from the end, or by jumping to the page number.  I would call this
  177. a bug. The starting line of a page will also move around if you get there
  178. through a search, but I wouldn't call that a bug.
  179.  
  180.       I see that I've neglected to tell you that PAGES is implemented as a
  181. PROCEDURE file.  You should be able to SET PROCEDURE TO PAGES, then
  182. DO PAGES WITH..., then SET PROCEDURE TO your normal procedure file.  I've
  183. had some erratic behavior with this, so me know if it doesn't work for you
  184. (and please let me know if it does).  It seems that you have to CLOSE
  185. PROCEDURE first, but that doesn't seem right.
  186.  
  187.      You might also want to look at the file DEMO.PRG.
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.  
  196.  
  197.  
  198.  
  199.  
  200.