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

DBEDIT()


Syntax:     DBEDIT([<expN1>] [,<expN2>] [,<expN3>] [,<expN4>]
            [,<array1>] [,<expC>] [,<array2>] [,<array3>] [,<array4>]
            [,<array5>] [,<array6>] [,<array7>])

Purpose:    To display and edit records from one or more work areas
            using a browse-style table layout that executes within a
            defined window area.

Arguments:  <expN1...expN4> are the coordinates of the DBEDIT()
            window.  Any, or all, of these arguments can be specified.

            <array1> is an array of <expC> containing field names or
            expressions of any type.  If this argument is not specified,
            DBEDIT() defaults to all fields in the current work area.

            <expC> is the name of a user-defined function that
            executes when an unrecognizable key is pressed or there are
            no keys pending in the keyboard buffer.  Specify the
            function name without parentheses or arguments.  Note that
            the behavior of DBEDIT() is affected by the presence of this
            argument.  Refer to the discussion below for more
            information.

            <array2> is an array of <expC> to be used as PICTURE
            strings for column formatting.  Specifying an <expC> instead
            of an array formats all columns with the same picture.

            <array3> is an array of <expC> for column headings.
            Specifying <expC> instead of an array gives the same heading
            for all columns.  To display multi-line headings, embed
            semi-colons.

            <array4> is an array of <expC> used to draw horizontal
            lines separating headings and the field display area.
            Specifying an <expC> instead of an array uses the same
            character for the heading line separator for all columns.

            <array5> is an array of <expC> used to draw vertical
            lines separating displayed columns.  Specifying an <expC>
            instead of an array uses the same separator for all columns.

            <array6> is an array of <expC> used to draw horizontal
            lines separating footings and the field display area.
            Specifying an <expC> instead of an array uses the same
            footing line separator for all columns.

            <array7> is an array of <expC> to display as column
            footings.  To force a column footing onto more than one
            line, embed a semi-colon where you want the string to
            break.  Specifying an <expC> instead of an array gives all
            footings the same value.

            All arguments are optional.  You must, however, pass a dummy
            argument for any argument you wish to skip.

Returns:    A logical value.

Usage:      DBEDIT() is an interface function that displays records from
            one or more work areas in a table form.  It formats the
            display according to the window coordinates and the fields
            array.  All cursor movement keys are handled within
            DBEDIT(), including PgUp, PgDn, Home, End, the four arrows,
            and all valid Ctrl key combinations that produce cursor
            movement.  The following are the active keys when a user
            function argument is not specified:


            Table: DBEDIT() Active Keys
            ----------------------------------------------------
            Key               Action
            ----------------------------------------------------
            Uparrow           Up one row
            Dnarrow           Down one row
            Leftarrow         Column left
            Rightarrow        Column right
            Ctrl-Leftarrow    Pan left one column
            Ctrl-Rightarrow   Pan right one column
            Home              Leftmost current screen column
            End               Rightmost current screen column
            Ctrl-Home         Leftmost column
            Ctrl-End          Rightmost column
            PgUp              Previous screen
            PgDn              Next screen
            Ctrl-PgUp         First row of current column
            Ctrl-PgDn         Last row of current column
            Return            Terminate DBEDIT()
            Esc               Terminate DBEDIT()
            ----------------------------------------------------

            User Function: When the user function argument (<expC>)
            is specified, all keys indicated above are active with the
            exception of Esc and Return.  When DBEDIT() calls the user
            function, it automatically passes two parameters: "status"
            and "fld_ptr."  The status parameter indicates the current
            state of DBEDIT() depending on the last key executed before
            the user function was called.  The following are the
            possible status values:


            Table: DBEDIT() Status Messages
            ----------------------------------------------------------
            Status      Description
            ----------------------------------------------------------
               0        Idle, any cursor movement keystrokes have been
                        handled and no keystrokes are pending
               1        Attempt to cursor past beginning-of-file
               2        Attempt to cursor past end-of-file
               3        Database file is empty
               4        Key exception
            ----------------------------------------------------------

            The other parameter, fld_ptr, is an index into the array of
            field names (<array1>).  If <array1> was not specified,
            fld_ptr points to the current field in the database
            structure and can be accessed using FIELD().

            When the user function has been called, you must return a
            value instructing DBEDIT() what action to perform next.  The
            following table summarizes the possible request values and
            their consequences:


            Table: Requests to DBEDIT() from User Function
            ----------------------------------------------------------
            Value       Description
            ----------------------------------------------------------
               0        Quit DBEDIT()
               1        Continue DBEDIT()
               2        Force reread/repaint and continue;
                        after repaint, process keys, and go to idle
               3        Append mode (not recommended)
            ----------------------------------------------------------

            The user function is called in a number of different
            instances:

            .  A key exception occurs.  This happens when DBEDIT()
               fetches a keystroke from the keyboard that is not a
               DBEDIT() executable key.  Any pending keys remain in the
               keyboard buffer until fetched within the user function or
               DBEDIT() continues.

            .  DBEDIT() goes to idle.  This happens when the keyboard is
               empty or after a screen refresh (request = 2) and all
               pending keys have been processed.  In this instance,
               there is one call to the user function.

            .  Beginning or end-of-file are encountered.  This is the
               same as idle.  All executable keys are performed and then
               there is one call with the indicating status message.

            Note that when DBEDIT() is first executed, all keys pending
            in the keyboard are executed and then DBEDIT() goes to idle
            with a user function call.  If no keys are pending, the idle
            state is immediate.

            The structure of the user function should be set up to
            handle all status messages received from DBEDIT().  Status
            messages characteristically indicate the current state of
            DBEDIT() and point to the type of action to be taken by the
            user function.  The structure therefore should consist of a
            CASE structure that branches control to a subprocedure for
            each status message to process.  Although you may be
            interested in less than all five of the status message
            values, your structure should at a minimum process idle
            states (status = 0) and key exceptions (status = 4).
            Ignored status messages can be processed by the OTHERWISE
            clause.  Tests for specific key presses should only take
            place within the called subprocedure.  The following block
            of code demonstrates the basic structure of a typical user
            function:

               FUNCTION UserFunc
               PARAMETERS status, fld_ptr
               PRIVATE request
               *
               key_stroke = LASTKEY()
               *
               DO CASE
               CASE status = 0
                  * Idle.
                  request = ProcessIdle(key_stroke)

               CASE status = 1
                  * Beginning-of-file.
                  request = ProcessBof(key_stroke)

               CASE status = 2
                  * End-of-file.
                  request = ProcessEof(key_stroke)

               CASE status = 3
                  * Empty database file.
                  request = ProcessEmpty()

               CASE status = 4
                  * Key exception.
                  request = KeyExcept(key_stroke)

               OTHERWISE
                  request = 1

               ENDCASE
               *
               RETURN request

            To allow further processing of keys and the subsequent use
            of LASTKEY() within called subprocedures, save the value of
            the last key pressed to a memory variable before entering
            the main CASE structure.  Then pass that key value
            throughout your subprocedure system as a parameter.  To
            allow execution of statements after the CASE structure, make
            your request to DBEDIT() by assigning the request value to a
            memory variable and then RETURN the value as the last
            statement in the user function.

            The two most important subprocedures in the user function
            architecture are the idle state processor and the key
            exception handler.  In the idle state processor, you perform
            the following two basic classes of actions:

               .  Update a status area on the screen
               .  Perform actions based on the last DBEDIT() key
                  executed

            The key exception handler is where most of the activity of
            the user function system takes place.  Here you process user
            requests for the following common actions:

               .  Exit from DBEDIT()
               .  Toggle the current record delete status
               .  Edit the current field
               .  Entry into a menu system

            As an example, the following user-defined function
            demonstrates a typical key exception handling procedure to
            process all of these actions:

               FUNCTION KeyExcept
               PARAMETER action_key
               *
               DO CASE
               CASE action_key = 27
                  * Esc...exit DBEDIT().
                  RETURN 0

               CASE action_key = 13
                  * Return...field edit (see discussion below).
                  RETURN FieldEdit()

               CASE action_key = 7 .AND. (.NOT. EOF()) .AND.;
               LASTREC()<> 0
                  * Del...toggle delete status.
                  IF DELETED()
                     RECALL
                  ELSE
                     DELETE
                  ENDIF
                  RETURN 1

               CASE action_key = -9
                  * F10...enter menu system.
                  RETURN MenuSys()

               OTHERWISE
                  * Any other key...slightly distasteful tone.
                  TONE(100, 1)
                  RETURN 1
               ENDCASE

            To edit the current field value, test for the field edit key
            in the key exception handler and then branch to a
            user-defined function--like the following--to GET the field
            name corresponding to the "fld_ptr" index in the field array
            (<array1>).

               FUNCTION FieldEdit()
               PRIVATE index_exp, index_val, filter_exp, field_name

               * Save current key expression and value.
               index_exp = INDEXKEY(0)
               index_val = &index_exp.

               * Save current filter expression.
               filter_exp = DBFILTER()

               * Edit current field value.
               SET CURSOR ON
               field_name = field_list[fld_ptr]
               @ ROW(), COL() GET &field_name.
               READ
               SET CURSOR OFF

               * Refresh screen if key value has changed.
               RETURN IF(index_val != &index_exp. .OR.;
                  (!&filter_exp.), 2, 1)

               Within FieldEdit() there are four important issues:

            The key value changes--if the key value of the controlling
            index has changed, update the screen so that the current
            record displays in its new position in the index.  When you
            send a refresh screen request to DBEDIT() (request = 2), the
            cursor remains at its current screen position but the screen
            display is updated to reflect the change of the current
            record in the index.  To set this up, save both the
            controlling index key expression and its current value
            before editing the current field value.  Then after the
            field edit is complete, send a request for a screen refresh
            if the new key value is not the same as the old key value.

            The current record is no longer within the filter scope--if
            after a change to a field value, the current record is no
            longer within the scope of the current filter condition,
            update the screen (request = 2) to remove the record from
            the display.  To set this up, first save the current filter
            expression using DBFILTER().  Then after editing the current
            field, evaluate the filter expression as a macro and refresh
            the screen if it returns false (.F.).

            The appearance of the cursor--by default, the DBEDIT()
            cursor is OFF.  You must therefore SET CURSOR ON before
            executing a READ and SET it OFF after the READ.

            Accessing the current field name--if you specify a field
            array (<array1>) as an argument to DBEDIT() you must use the
            same array name in FieldEdit().  If you have not, obtain the
            field name using FIELD() using "fld_ptr" as the argument.

            Nesting: You can call multiple copies of DBEDIT() within
            each copy of DBEDIT() allowing you multiple browse windows
            on the screen at one time.

Library:    EXTEND.LIB


----------------------------------- Examples -------------------------------

   This example demonstrates how to use DBEDIT() with a user function.

   SELECT 2
   USE Customer INDEX Customer
   SELECT 1
   USE Sales INDEX Sales
   SET RELATION TO Cust_num INTO Customer

   DECLARE field_list[4]

   field_list[1] = "Branch"
   field_list[2] = "Salesman"
   field_list[3] = "Amount"

   * Fields in another work area must include the alias.
   fields[4] = "Customer->Customer"

   DBEDIT(4, 0, 22, 79, field_list, "UserFunc")