FN_LOGLR()
 Log logical record
------------------------------------------------------------------------------
 Syntax
 
      fn_logLR( <cRecord>, <nLockDir>, <nTimeOut> ) -> lSuccess
 
 Arguments

     <cRecord>   - a character string containing the name of the
                   "record" to be logged in the log table for
                   possible later locking.

     <nLockDir>  - Locking directive.  Only used if you're in
                   "extended lock mode", otherwise ignored.
                   The following locking directives are valid:

          0 = Log Record (the default).  This only logs the record in
              the table; it does not lock the record.
          1 = Log and lock record with an exclusive lock.
              This will log the record and lock it for exclusive use
              by one user. He is the only one who can read and write
              this record.
          3 = Log and lock record with a shareable, read-only lock.
              This will log a record and lock it with a read-only lock.
              While this record is locked anyone can read it, no one can
              update it. If you wish to update this record with a write,
              the read-only lock must be changed to an exclusive lock.

     <nTimeOut>  - Amount of time to wait for a lock in 1/18th
                   of a second ticks.  0 = Don't wait (the
                   default).  This parameter is only valid if
                   you're in extended lock mode (lock mode 1),
                   otherwise, it will be ignored.

 Returns

     <lSuccess>, .t. if the call succeeds, .f. if it doesn't.
     Check FN_ERROR() for specific error codes.  The valid codes
     are:

                  0  = Success
                254  = Timeout failure
                255  = Failure

 Description

     This call places a logical record in the log table and
     optionally locks it.

     Logical Records are simply "names" that are locked by
     workstations.  The server maintains the tables for each
     workstation.  They don't represent actual files or
     physical byte ranges, but they could.  You can use these
     logical records to lock anything of significance.

     The server maintains a "log table" for each workstation.
     To lock something, it must first be "logged".  After
     everything is logged, then a "lock" is issued.

     You can unlock the entire set of logged records at once,
     or just one at a time.  You can remove the logged records
     from the table all at once, or one at a time.

     This is most useful in a Clipper application if you want
     to lock a "bunch of things", but treat the package as
     one lock.  For example, say an employee record consists of
     one record in EMPLOYEE.DBF and a few records in "TIMECARD.DBF"
     and still more records in "HISTORY.DBF."  Perhaps you want
     to show a bunch of this data on the screen and you don't
     want anyone to change anything about this employee while
     you're working.

     The "employee" is thus a "conceptual" thing.  You can't
     rlock() the employee, what does that mean?  Which record
     from which file?

     Instead, you can issue a logical lock on "SCOTT, GLENN" or
     better yet, on the employee's ID number.

     Now, if every application _cooperates_ and checks the
     status of the logical lock on "SCOTT, GLENN" before
     updating, then you in effect have created a lock on multiple
     records in multiple databases.

     The sequence would look something like this:

            fn_logLr( "SCOTT, GLENN" )
            if fn_lkLRSet()
               qout( "Got the lock" )
               // Do processing here on this employee
            else
               qout( "Lock failed, try later" )
            endif
            fn_clLRSet()      // unlock everything and clear log table


     IMPORTANT!  There's no _real_ (i.e., physical) locking going
     on here.  If some application does not obey the logicial
     locking protocol you define (i.e., lock the employee id),
     then this won't work.

     You could implement this sort of scheme by using a .DBF and
     thus it would not be NetWare-specific, but one advantage to
     this technique is that if the workstation reboots, the locks
     will eventually get cleared when the first of two things happens:

         - the workstation loads the shell and attaches to
           the server again

         - the watchdog process in the server detects the station
           is gone and clears the connection.

 Examples


 Source: N:\SRC\SYNCHRO\LOGREC.PRG

 Author: Glenn Scott