Click above to get retro games delivered to your door ever month!

 C_DBF()

 DESCRIPTION

 C_DBF() scrolls through a database file to allow records to be
 viewed, tagged, and selected.  The display can be based on a
 complete database of any size or a subset of the database with or
 without an index.  The window display can scroll up, down, left,
 and right and is completely configurable.  All keyboard and display
 activity is controlled by a specified user-defined function (UDF)
 or by default actions if a UDF is not specified.  Searching options
 and the ability to resize and move the display window can also be
 controlled by the UDF.

 SYNTAX

 C_DBF(st_row, st_col, end_row, end_col, flds [,box] [,color] [,shadow]
 [,title] [,header1] [,header2] [,footer1] [,footer2] [,expr] [,forexpr]
 [,firstrec] [,lastrec] [,savescrn] [,udf] [,markarr] [,dir_arrows]
 [,show_del])

 PARAMETERS

 st_row (N), st_col (N), end_row (N), and end_col (N) define the
 upper left and lower right coordinates for the window.

 flds (C) is the database field(s) to display in the form of a macro
 expression which must evaluate to a character data type.  Note that
 the C_FTOMACRO() and C_ATOMACRO() functions can be used to
 construct a macro expression.
 Example:  "NAME + ' ' + ADDRESS + ' ' + str(ZIP,5) + space(5) + CODE"

 box (N) is the box type (0 - 5) to draw for the window.  If box is
 not specified, box type 2 (double box) is used.  The box types are
 as follows:

 BOX TYPE     DESCRIPTION
 --------     -----------
 0            No box
 1            Single top/bottom, single sides
 2            Double top/bottom, double sides
 3            Double top/bottom, single sides
 4            Single top/bottom, double sides
 5            Solid graphics characters

 color (C) is the color to display for the window and the highlight bar.

 shadow (N) is the type of shadow to display around the window.  The
 shadow types are as follows:  0 = no shadow, 1 = left side/bottom
 shadow, 2 = right side/bottom shadow.  If shadow is not specified,
 no shadow is displayed.

 title (C) is the title line for the window.  The title is automatically
 centered at the top of the window and remains stationary.

 header1 (C) is the first column header line for field descriptions.
 The header lines are automatically scrolled left and right with the
 window.

 header2 (C) is the second column header line for field
 descriptions.  The header lines are automatically scrolled left and
 right with the window.

 footer1 (C) is the first footer line.  The footer lines are automatically
 centered at the bottom of the window and remain stationary.

 footer2 (C) is the second footer line.  The footer lines are automatically
 centered at the bottom of the window and remain stationary.

 expr (C) is the macro expression defining the WHILE condition.  The
 WHILE condition specifies the records to be included in the display
 until the condition fails.  expr is usually used for an indexed
 database to include only a contiguous subset of the database.  expr
 must be in the form of a macro expression that evaluates to a
 logical data type.  If expr is not specified, all records in the
 database are included in the display.  Example:  "STATE = 'VA'"

 forexpr (C) is the macro expression that defines the acceptance of
 records to be included in the display.  forexpr is evaluated for
 every record in the scope of records to determine whether the
 record should be included in the display.  forexpr must be in the
 form of a macro expression that evaluates to a logical data type.
 If forexpr is not specified, all records in the scope are included.
 Examples:  "CITY != 'RICHMOND'"  /  "AMOUNT > 1000"

 firstrec (N) is the record number of the first record in the list
 used to speed the search when positioning to the top of the list.
 If the first item is not known, pass a zero (0) which is the default.

 lastrec (N) is the record number of the last record in the list
 used to speed the search when positioning to the end of the list.
 If the last item is not known, pass a zero (0) which is the default.

 savescrn (L) indicates whether or not the screen should be saved
 when C_DBF() is called and restored when exited.  Specify true
 (.T.) to save and restore the screen, or false (.F.) to overwrite
 the previous screen and leave the selection window on the screen
 when C_DBF() exits.  If savescrn is not specified, the default of
 true (.T.) is used.

 udf (C) is the name of the user-defined function (UDF) to maintain
 a dialog during the C_DBF() call.  The UDF is called continuously
 to allow complete access and control of the C_DBF() function.  udf
 should be passed in quotes and without parenthesis, for example,
 "DBF_UDF".  If udf is not specified, the default key control
 options are used.

 markarr (C) is the name of the array to use to store records
 numbers "marked" for selection when the user toggles record marking
 on or off.  The selection of a single record is always available in
 C_DBF(), but this option allows one, many, or all records to be
 selected by the user as in a check-off type list.  The markarr
 array must be declared before calling C_DBF() to the desired size.
 The array can not be larger than the 4096.  markarr must be passed
 to C_DBF() without quotes.  The markarr array specified will be
 filled with the record numbers selected by the user.  Additionally,
 the markarr can be filled with record numbers before calling
 C_DBF() to indicate records that have already been selected.  The
 presence or absence of the array in the argument list indicates
 whether item marking is enabled or disabled.  If a UDF is
 specified, it also controls the marking and unmarking of records by
 controlling the key definitions.  If markarr is not specified, the
 default of no record marking is used.

 dir_arrows (L) indicates whether or not directional arrows should
 be used in the C_DBF() display.  Specify true (.T.) if directional
 arrows should be displayed or false (.F.) not to display arrows.
 If dir_arrows is not specified, arrows will be displayed.

 show_del (L) indicates whether or not deleted records should be
 included in the display.  The Clipper command SET DELETED OFF must
 be issued before calling this function.  Specify true (.T.) to
 include deleted records or false (.F.) to exclude deleted records.
 If show_del is not specified, the default of false (.F.) is used.

 DEFAULT KEY DEFINITIONS AND ACTIONS (with no UDF)

 KEY PRESSED    ACTION TAKEN
 -----------    ------------
 ENTER          Exit C_DBF(), return highlighted record number
 ESC            Exit C_DBF(), return zero
 SPACE-BAR      Toggle record marking on/off
 HOME           Display first full page, highlight first record in window
 END            Display last full page, highlight last record in window
 PGUP           Display previous page, highlight first record in window
 PGDN           Display next full page, highlight first record in window
 UP-ARROW       Highlight previous record, scroll window up if at top
 DN-ARROW       Highlight next record, scroll window down if at bottom
 RT-ARROW       Pan right 10 columns
 LT-ARROW       Pan left 10 columns
 CTRL-RT-ARROW  Pan right, all the way
 CTRL-LT-ARROW  Pan left, all the way
 A-Z, a-z, 0-9  Find first character matching key pressed

 PARAMETERS AND RETURN VALUES FOR THE UDF

 The user-defined function for C_DBF() receives the following
 parameters when called:

 Mode - current mode state of C_DBF(), where:
   0 = Startup
   1 = Request action
   2 = Report previous action (not at top or end)
   3 = Report previous action (at top-of-list)
   4 = Report previous action (at end-of-list)
 Prev_action - the previous action taken by C_DBF()
 Window_pos - current window position for highlighted item
 Scrn_pos - current screen row for highlighted item
 Pan_offset - current offset of position left and right (1 is startup)

 The following action codes can be returned to C_DBF() to tell it
 what action to take:

 -1 = Ignore key, continue
 0  = Exit C_DBF(), return 0
 1  = Exit C_DBF(), return current record number
 2  = Perform default action based on last key pressed (automatic mode)
 3  = Request search for last key pressed
 4  = Redisplay current screen in window (database has not changed)
 5  = Toggle record marking on/off
 6  = Toggle record marking for all records on/off
 7  = Reset and redisplay window (database has changed)
 10 = Top of list
 11 = Bottom of list
 12 = Page up
 13 = Page down
 14 = Scroll up one
 15 = Scroll down one
 20 = Pan right - all the way
 21 = Pan left - all the way
 22 = Pan right - 1 full window
 23 = Pan left - 1 full window
 24 = Pan right - 1 column
 25 = Pan right - 5 columns
 26 = Pan right - 10 columns
 27 = Pan left - 1 column
 28 = Pan left - 5 columns
 29 = Pan left - 10 columns

 C_DBF() FUNCTIONS CALLED FROM THE UDF (SEEK, MOVE, RESIZE WINDOW)

 FUNCTION: _dbseek(seek_first, field, string)

 seek_first (N) indicates whether the search should begin at the top
 or continue from the current position.  Specify zero (0) to begin
 at the top or one (1) to continue from the current position.
 field (C) is the name of the database field in the index key tosearch.
 string (C) is the character string or single character to search
 for in the active index.

 Returns:  _dbseek() returns true (.T.) if the string was found or
 false (.F.) if not found.

 FUNCTION: _dbmove(dir, count)

 dir (C) is the direction to move the window, U=Up, D=Down, R=Right, L=Left
 count (N) is the number of rows or columns to move the window in
 the direction specified by dir.

 Returns:  _dbmove() returns true (.T.) if the window was
 successfully moved or false (.F.) if the window could not be moved.

 FUNCTION: _dbsize(dir, count)

 dir (C) is the direction to resize the window starting from the
 bottom going up and down or from the right going left and right.
 (U=Up, D=Down, R=Right, L=Left)
 count (N) is the number of rows or columns to resize the window in
 the direction specified by dir.

 Returns:  _dbsize() returns true (.T.) if the window was successfully
 resized or false (.F.) if the window could not be resized.

 RETURNS

 C_DBF() returns the highlighted record number if selected, or a
 zero (0) if C_DBF() is aborted.

 EXAMPLES

 use test  && (Contains fields:  Name-C25,  State-C2, Contact-C25,
           &&  Phone-C15)
 t1 = "CUSTOMER LIST"
 h1 = "Company Name              State  Contact                    Phone"
 f1 = "name + '  ' + state + space(6) + contact + '  ' + phone"

 && Call C_DBF() with default options
 ret=c_dbf(10,10,20,70,f1)

 && Call C_DBF() using mark array and other options
 private amark[lastrec()]     && declare mark array (dbf has 250 records)
 go top
 c1 = "W+/R,W/B"
 ret=c_dbf(10,10,20,70,f1,3,c1,2,t1,h1,"","","","","",0,0,.t.,"",amark)

 && Use C_DBF() to view only a specific state
 use test index test && (test.ntx indexed on state)

 mstate = space(2)
 @ 10,28 say "Enter State: " get mstate picture "!!"
 read

 seek mstate                && Position to first match - assume found
 expr = "state = mstate"    && WHILE expression
 c1 = "W+/R,W/B"
 ret=c_dbf(7,5,18,74,f1,3,c1,2,t1,h1,"","","",expr,"",0,0,.t.,"dbf_udf")

 Note that in the examples above, the code for the callable UDF
 "DBF_UDF" is contained in the file UDF_DBF.PRG on the ClipOn diskette.