Power-Programmierung/CD1.mdf/xbase/library/dbase/screen/pages/pages.dat

Text File | 1986-11-25 | 9.4 KB | 200 lines

     Hello, dBase developers!

     This is PAGES, a dBase III Plus procedure which your programs can call
to provide on-screen displays.  I'm using PAGES here to display on-line
documentation, and it can also be used to display on-line reports that won't
scroll off the top of the screen, that the user can page through forward and
backward, that the user can search.

     I wrote PAGES to provide ELECTRONIC LEDGER CARDS for an accounting
program.  When a user of that accounting program wants to see the ledger
card for a customer, the customer information is generated on the fly
(the program works in real-time, not through batch updates), sent
to an ALTERNATE file instead of to the screen, and the alternate file is
passed to PAGES which displays it nicely on the screen.

     If you examine the menu bar on the bottom, you'll see that you can go
to the next page by pressing the N key (or Down arrow or PgDn).


     Now you're on page 2.  You can take a look at page 1 again, if you
like, by pressing the P key (or Up arrow or PgUp).

     This is pretty different from most dBase programs I've seen where once
something moves off the top of the screen, it's gone.  The idea behind PAGES
is that once a listing is captured, it can be manipulated interactively.

     In short, PAGES is a procedure for displaying more than one screenful
of information in any dBase III Plus application.  Of course, a single
screen of information can be displayed as well.

     There are other options available.  If you press the S key now,
you'll be asked for a phrase to search for.  Once you've searched once,
you can move to the next occurrence of a phrase by pressing the R key.

     You can also jump to pages by pressing a number key.  Go the next page
(page 3) by pressing the 3 key instead of N.


     Of course, you didn't have to press 3.  You could have moved directly
to page 6, for instance, by pressing the 6 key.  You can jump to a page
number with more than one digit:  Press the # key and you'll be asked for a
page number.  After you press RETURN, you'll move straight to that page.

     PAGES is reasonably bomb-proof in that if you ask to go to page 9 in a
file with only 6 pages, you'll be taken to the last page.  If you press the
# key and then tell PAGES you want to go to page 0.4 or page -3.2 or
something like that, naturally you'll be taken to page 1.

     Two other options on the menu line are Begin and End.  Press the B key
or the PC Home key and you'll go to page 1.  Press the E key or the PC End
key and you'll be taken to the last page.

     The menu item File allows you to switch to another file.  You can
examine the source code for PAGES, for example, by switching to PAGES.SRC
(.SRC because I'm using dBase psuedo-compiler).  Then you can come back
here:  the name of this file is PAGES.DAT

     I hope you did go look at pages.src because now I want to discuss the
code a little bit.  Starting with, how DID we switch to another file?
In a previous version of PAGES, I employed recursion:  PAGES would call
itself whenever you asked to switch files.  But recursion in dBase reaches
it maximum at 20 nested DO's.  This version has PAGES sends a message back
to whatever program called it saying, in effect, that it wants to be called
again.  Okay, so it's not Smalltalk, but it's a technique anyway.

     You may have noticed that PAGES puts lines on the screen fairly
rapidly.  Two comments on this:

     First, having learned dBase AFTER knowing C, it took a while to learn
to use dBase non-procedural, non-navigational commands.  For instance, lines
of text could be displayed in a do-while loop.  But it is much faster to use
the non-procedural dBase command LIST.  If you are interested in the
difference between procedural and non-procedural languages, I can recommend
a wonderful book:  Relational Database: Selected Writings, by C.J. Date
(Reading, MA: Addison-Wesley, 1986).

     Second, in running PAGES under Microsoft Windows, I found that, because
dBase III Plus is a well-behaved program that does not write directly to the
screen buffer (which is why it can run under Windows in the first place),
it's horribly slow in putting stuff on the screen.  Calling DOS to update
the screen, instead of doing an end run and jamming the screen buffer itself
like a lot of programs, IS important, but you still want to minimize dBase's
interaction with the screen:  list off trim(line) represents a significant
improvement over list off line, just as list represents a significant
improvement over a do-while loop.

     Some other odds and ends:

     We turn off the cursor with cursoff.bin, a tiny file that comes on the
sample/utilities disk of dBase III Plus.  Then we maintain our own blinking
cursor with set color to w*.  When we're done we set the cursor back on with
curson.bin.  In this way, the screen does not flicker and flash when we
redraw.


     PAGES maintains an internal model of which line number (i.e., which
recno() in line.dbf) is on what page, based on two simple formulas:

     page = int((recno() - MYTOP) / DEPTH) + 1
     recno() = ((page - 1) * DEPTH) + MYTOP

     For instance, if we're on line 102 and the display is 19 lines deep and
line 1 is the first good line in the file (MYTOP), then we're on int(102 -
1) / 19) + 1 = page 6.  Which is where we are now.
     Likewise, what is the first line on page 6?  ((6 - 1) * 19) + 1 = 96.
     You don't have to know any of this to use PAGES.

     I mentioned earlier that PAGES was written to provide on-screen
ledgers.  Since I've been using PAGES here merely to display its own
documentation, it might not be obvious how you would use it to display
ledgers or listings.

     If you turn the page, so to speak, I'll give you an example:
*************************** CODE FRAGMENT *************************
set alternate to temp.txt
set alternate on
@5,0 say "Working...."
set console off
set heading off
list off custcode,"  ",bill_date,"  ",job_num,"  ", ;
   substr(job_desc,1,28),"  ",bill_total for custcode = cust
sum bill_total to grand_total for custcode = code   && or seek, then while
? "Total... ",cust,"... $",grand_total
set alternate off
close databases
close alternate
set console on
close procedure                             && important!!
set procedure to pages
do PAGES with "temp.txt", 2, 18, 5, 3, 0, .F.  && explanation on next page
close procedure
set procedure to myproc
     The parameters to PAGES are:
     FILENAME = ASCII (SDF) text file containing anything you want.  In this
                demo, PAGES.DAT is just a word-processing file created by
                Sidekick.  In the code fragment above, TEMP.TXT is
                redirected output from dBase III LIST command.
     MYTOP    = first good line in the text file.  Usually 1, but not always.
     DEPTH    = how many lines to display.  From this and MYTOP, PAGES will
                figures out where to put the menu line.  It will also tell
                if you're asking the impossible (as defined by 25-line PC
                screen. Any one working on 43-line displays?)
     START    = what screen row() to start output
     SHOWPAGE = what screen row() to show "Page x of x" display
     SHOWRULE = what screen row() to show upper rule. 0 means don't show it.
     SWITCH_OK= is user allowed to switch to another file?

     PAGES will only clear the parts of the screen it owns:  this means you
can put things on the screen and call PAGES with the knowledge that your
messages on the top of the screen won't get wiped out.

     To sum up:

     Most dBase displays disappear forever once they scroll off the top of
the screen, but PAGES are not a one-shot deal.  PAGES displays exist on a
much more physical level than is usual in on-screen reports because we save
the reports in a database file and THEN display them.

     I'd like to mention, by the way, that any of the preceding sentences
which make sense to you were written by Amanda Claiborne, my wife.  She is
also responsible for those sentences in the documentation for my program
MAKEMEM which are intelligible.

    And speaking of MAKEMEM...  You can get this collection of dBase III
utilities written in C from places like PL Olympia's Darwin bulletin board
(301-251-9206) or the Ashton-Tate forum on CompuServe, or by sending $15 to
the programmer who remains, as always, your humble servant,

    Andrew Schulman, 12 Humboldt Street, Cambridge MA 02140, 617-876-2102


P.S.  Yes, Virginia, there are bugs.  The definition of a page is a bit
fluid and, consequently, the top line of, say, page 7 might be a different
line depending on whether you come at it from the beginning, by page
backwards from the end, or by jumping to the page number.  I would call this
a bug. The starting line of a page will also move around if you get there
through a search, but I wouldn't call that a bug.

      I see that I've neglected to tell you that PAGES is implemented as a
PROCEDURE file.  You should be able to SET PROCEDURE TO PAGES, then
DO PAGES WITH..., then SET PROCEDURE TO your normal procedure file.  I've
had some erratic behavior with this, so me know if it doesn't work for you
(and please let me know if it does).  It seems that you have to CLOSE
PROCEDURE first, but that doesn't seem right.

     You might also want to look at the file DEMO.PRG.