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

Function:    NO_FLOCK()

Purpose:     Network file lock function with specific error trapping

Syntax:      NO_FLOCK( [ alias [, color [, msg1 [, msg2 [, msg3 ]]]]] )

Arguments:   alias       - Optional character string work area alias name
                           to lock.  If omitted or an invalid parameter is
                           passed the default is the current work area.

             color       - Optional character string color setting in
                           which to display error messages.  If omitted or
                           an invalid value is passed, the default color
                           is IF( ISCOLOR(), "W+/R", "N/W" )

             msg1        - Optional character string first line message to
                           appear in the error box if an error occurs.  If
                           omitted or an invalid parameter is passed, the
                           default messages shown below are used.

             msg2        - Optional character string second line message
                           to appear in the error box if an error occurs.
                           If omitted or an invalid parameter is passed,
                           the default messages shown below are used.

             msg3        - Optional character string third line message to
                           appear in the error box if an error occurs.  If
                           omitted or an invalid parameter is passed, the
                           default messages shown below are used.

Returns:     True if a lock on the database file in the currently selected
             work area failed.  A return value of false indicates the file
             lock was placed successfully.

Description: NO_FLOCK() is a network database function that simplifies the
             tedious task of network database locking mechanics.  This
             function, if successful, will place a Clipper FLOCK() on the
             database file in the current work area, or upon the file in
             the work area designated by the parameter ALIAS.  NO_FLOCK()
             will return to the current select area if an alias is given.

             The benefit of using NO_FLOCK() over a simple FLOCK() call is
             the automatic re-try built into NO_FLOCK().  If the file lock
             fails the user is presented with a BOXASK() message
             indicating that they may re-try or cancel the attempt.  This
             BOXASK() message will timeout after 30 seconds and re-try the
             FLOCK().

Notes:       The default first, second and third line messages that appear
             in the BOXASK() message box are as follows:

                  +------------------------------------------------+
                  |                                                |
                  |                File lock failed!               |
                  |     Another user must have this file locked    |
                  |           Do you want to re-try? (Y/n)         |
                  |                                                |
                  +------------------------------------------------+


             If you want to supply your own message(s) but do not want to
             designate a different alias other that the current work area,
             you may either supply the current work area alias as the
             first parameter (ALIAS()), or pass an invalid argument such
             as a null string or a logical.

             You should use the default messages unless you make sure the
             message you give will let the user know they have the option
             to re-try.

             If an invalid alias name is supplied as the first parameter,
             i.e.  the work area alias name is not in use, NO_FLOCK() will
             return .T. and set the appropriate RLIBERROR() value.

             The default answer to the third line prompt is YES, retry.
             This will keep the lock attempt in a loop.  The function used
             to get this response is BOXASK() and is set with a timeout
             value of 30 seconds.  If the user does not respond within
             this time, the function will timeout and attempt to do the
             file lock.  This allows a lock error condition to
             automatically recover without user intervention (like in the
             middle of the night!)

Example:     *-- place a file lock to perform a REPLACE ALL
             IF NO_FLOCK()
                BOXASK( "File unavailable for update at this time",;
                         "Press any key to continue" )
             ELSE
                REPLACE ALL flag_field WITH "*"
                UNLOCK                           && !!!!!!!
             ENDIF


             *-- another example: lock two database files at one time
             IF NO_FLOCK("Customer") .OR.  NO_FLOCK("Orders")
                BOXASK( "File unavailable for update at this time",;
                         "Press any key to continue" )
             ELSE
                *-- do multiple updates here
                UNLOCK ALL
             ENDIF

Source:      RL_NO_FL.PRG

See also:    OPENED(), NO_APPEND(), NO_RLOCK()