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

Function:    NO_RLOCK()

Purpose:     Network record lock function with specific error trapping

Syntax:      NO_RLOCK( [ 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 record in the currently
             selected work area failed.  A return value of False indicates
             that the lock was placed successfully.

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

             The benefit of using NO_RLOCK() over a simple RLOCK() call is
             the automatic re-try built into NO_RLOCK().  If the record
             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
             RLOCK().

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

             +---------------------------------------------------------+
             |                                                         |
             |                      Lock failed!                       |
             |    Another user must have this file or record 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_RLOCK() 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 record lock to perform a REPLACE
             IF NO_RLOCK()
                BOXASK( "Record unavailable for update at this time",;
                         "Press any key to continue" )
             ELSE
                REPLACE flag_field WITH "U"
                UNLOCK                        && !!!!!!!
             ENDIF

             *-- Example #2: lock two database file records at one time
             IF NO_RLOCK("Customer") .OR.  NO_RLOCK("Orders")
                BOXASK( "Record unavailable for update at this time",;
                        "Press any key to continue" )
             ELSE
                REPLACE CUSTOMER->lastorder WITH DATE(),;
                        ORDERS->count WITH ORDERS->count + 1
                UNLOCK ALL
             ENDIF

Source:      RL_NO_RL.PRG

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