Tag Archives: RLOCK()

UNLOCK

Posted on by vivaclipper

UNLOCK

Release file/record locks set by the current user

Syntax

      UNLOCK [ALL]

Arguments

ALL releases all current locks in all work areas. If not specified, only the lock in the current work area is released.

Description

UNLOCK is a network command that releases file or record locks set by the current user. Use it when you want to release the current lock without setting a new lock. Both FLOCK() and RLOCK() release the current lock before setting a new one.

After an UNLOCK, an update to a shared database file and associated index and memo files becomes visible to DOS and other applications, but is not guaranteed to appear on disk until you perform a COMMIT or close the file.

Refer to the “Network Programming” chapter in the Programming and Utilities Guide for more information on the principles of locking and update visibility.

Notes

. SET RELATION: UNLOCK does not automatically release a record lock along a RELATION chain unless you UNLOCK ALL.

Examples

      .  This example attempts an update operation that requires a
         record lock.  If the RLOCK() is successful, the record is updated
         with a user-defined function and the RLOCK() is released with UNLOCK:

      USE Sales INDEX Salesman SHARED NEW
      IF RLOCK()
         UpdateRecord()
         UNLOCK
      ELSE
         ? "Record update failed"
         BREAK
      ENDIF

Seealso

DBUNLOCK(), DBUNLOCKALL(), FLOCK(), RLOCK(), SET RELATION

SET EXCLUSIVE

Posted on by vivaclipper

SET EXCLUSIVE*

Establish shared or exclusive USE of database files

Syntax

      SET EXCLUSIVE ON | off | <xlToggle>

Arguments

ON causes database files to be opened in exclusive (nonshared) mode.

OFF causes database files to be opened in shared mode.

<xlToggle> is a logical expression that must be enclosed in parentheses. A value of true (.T.) is the same as ON, and a value of false (.F.) is the same as OFF.

Description

In a network environment, SET EXCLUSIVE determines whether a USE command specified without the EXCLUSIVE or SHARED clause automatically opens database, memo, and index files EXCLUSIVE. When database files are opened EXCLUSIVE, other users cannot USE them until they are CLOSEd. In this mode, file and record locks are unnecessary.

When EXCLUSIVE is ON (the default), all database and associated files open in a nonshared (exclusive) mode unless the USE command is specified with the SHARED clause. Use EXCLUSIVE only for operations that absolutely require EXCLUSIVE USE of a database file, such as PACK, REINDEX, and ZAP.

When EXCLUSIVE is OFF, all files are open in shared mode unless the USE command is specified with the EXCLUSIVE clause. Control access by other users programmatically using RLOCK() and FLOCK().

SET EXCLUSIVE is a compatibility command and not recommended. It is superseded by the EXCLUSIVE and SHARED clauses of the USE command.

Refer to the “Network Programming” chapter for more information.

Notes

. Error handling: Attempting to USE a database file already opened EXCLUSIVE by another user generates a runtime error and sets NETERR() to true (.T.). After control returns to the point of error, you can test NETERR() to determine whether the USE failed.

Seealso

FLOCK(), NETERR(), RLOCK(), USE, DBUSEAREA()

REPLACE

Posted on by vivaclipper

Assign new values to field variables

Syntax

      REPLACE <idField> WITH <exp>
            [, <idField2> WITH <exp2>...]
            [<scope>] [WHILE <lCondition>] [FOR <lCondition>]

Arguments

<idField> is the name of the field variable to be assigned a new value. If <idField> is prefaced with an alias, the assignment takes place in the designated work area.

WITH <exp> defines the value to assign to <idField>.

<scope> is the portion of the current database file to REPLACE. The default is the current record, or NEXT 1. Specifying a condition changes the default to ALL records in the current work area.

WHILE <lCondition> specifies the set of records meeting the condition from the current record until the condition fails.

FOR <lCondition> specifies the conditional set of records to REPLACE within the given scope.

Description

REPLACE is a database command that assigns new values to the contents of one or more field variables in the current record in the specified work areas. The target field variables can be character, date, logical, memo, or numeric. REPLACE performs the same function as the assignment operator (:=) except that it assumes that an unaliased reference is to a field variable. This means that you can assign new values to field variables using assignment statements provided that the field variable references are prefaced with an alias, the FIELD alias, or declared using the FIELD declaration statement.

The default scope of REPLACE is the current record unless a scope or condition is specified. If a scope or condition is specified, the replace operation is performed on each record matching the scope and/or condition.

Warning! When you REPLACE a key field, the index is updated and the relative position of the record pointer within the index is changed. This means that REPLACEing a key field with a scope or a condition may yield an erroneous result. To update a key field, SET ORDER TO 0 before the REPLACE. This ensures that the record pointer moves sequentially in natural order. All open indexes, however, are updated if the key field is REPLACEd.

In a network environment, REPLACEing the current record requires an RLOCK(). REPLACEing with a scope and/or condition requires an FLOCK() or EXCLUSIVE USE of the current database file. If a field is being REPLACEd in another work area by specifying its alias, that record must also be locked with an RLOCK(). Refer to the “Network Programming” chapter for more information.

Examples

      .  This example shows a simple use of REPLACE:

         USE Customer NEW
         APPEND BLANK
         USE Invoices NEW
         APPEND BLANK
         //
         REPLACE Charges WITH Customer->Markup * Cost,;
            Custid WITH Customer->Custid,;
            Customer->TranDate WITH DATE()

      .  This example uses assignment statements in place of the
         REPLACE command:

         FIELD->Charges := Customer->Markup * FIELD->Cost
         FIELD->Custid := Customer->Custid
         Customer->TranDate := DATE()

Seealso

COMMIT, FLOCK(), RLOCK()

RECALL

Posted on by vivaclipper

Restore records marked for deletion

Syntax

      RECALL [<scope>] [WHILE <lCondition>]
             [FOR <lCondition>]

Arguments

<scope> is the portion of the current database file to RECALL. The default scope is the current record, or NEXT 1. If a condition is specified, the default scope becomes ALL.

WHILE <lCondition> specifies the set of records meeting the condition from the current record until the condition fails.

FOR <lCondition> specifies the conditional set of records to RECALL within the given scope.

Description

RECALL is a database command that restores records marked for deletion in the current work area. This is the inverse of the DELETE command. If DELETED is ON, RECALL can restore the current record or a specific record, if you specify a RECORD scope. Note that once you PACK a database file, all marked records have been physically removed from the file and cannot be recovered.

In a network environment, RECALLing the current record requires an RLOCK(). RECALLing several records requires an FLOCK() or EXCLUSIVE USE of the current database file. Refer to the “Network Programming” chapter for more information.

Examples

      .  This examples show the results of RECALL:

      USE Sales NEW
      //
      DELETE RECORD 4
      ? DELETED()               // Result: .T.
      //
      RECALL
      ? DELETED()               // Result: .F.

Seealso

DELETE, DELETED, FLOCK(), PACK, RLOCK(), SET DELETED

DELETE

Posted on by vivaclipper

DELETE

Mark records for deletion

Syntax

      DELETE [<scope>] [WHILE <lCondition>]
             [FOR <lCondition>]

Arguments

<scope> is the portion of the current database file to DELETE. If a scope is not specified, DELETE acts only on the current record. If a conditional clause is specified, the default becomes ALL records.

WHILE <lCondition> specifies the set of records meeting the condition from the current record until the condition fails.

FOR <lCondition> specifies the conditional set of records to DELETE within the given scope.

Description

DELETE is a database command that tags records so they can be filtered with SET DELETED ON, queried with DELETED(), or physically removed from the database file with PACK. In addition, display commands such as LIST and DISPLAY identify deleted records with an asterisk (*) character. Once records are deleted, you can reinstate them by using RECALL. If you want to remove all records from a database file, use ZAP instead of DELETE ALL and PACK.

Any deleted record can be recalled as long as the PACK or ZAP command has not been issued. Once the PACK or ZAP command has been issued, the deleted data cannot be retrieved.

In a network environment, DELETE requires the current record be locked with RLOCK() if you are deleting a single record. If you are deleting several records, the current database file must be locked with FLOCK() or USEed EXCLUSIVEly. Refer to the “Network Programming” chapter in the Programming and Utilities Guide for more information.

Notes

. DELETE with SET DELETED ON: If the current record is deleted with SET DELETED ON, it will be visible until the record pointer is moved.

Examples

      .  This example demonstrates use of the FOR clause to mark a set
         of records for deletion:
      USE Sales INDEX Salesman NEW
      DELETE ALL FOR Inactive

Seealso

DBEVAL(), DELETED(), FLOCK(), PACK, RECALL, RLOCK()

APPEND BLANK

Posted on by vivaclipper

APPEND BLANK

Add a new record to the current database file

Syntax

      APPEND BLANK

Description

APPEND BLANK is a database command that adds a new record to the end of the current database file and then makes it the current record. The new field values are initialized to the empty values for each data type: character fields are assigned with spaces; numeric fields are assigned zero; logical fields are assigned false (.F.); date fields are assigned CTOD(“”); and memo fields are left empty.

If operating under a network with the current database file shared, APPEND BLANK attempts to add and then lock a new record. If another user has locked the database file with FLOCK() or locked LASTREC() + 1 with RLOCK(), NETERR() returns true (.T.). Note that a newly APPENDed record remains locked until you lock another record or perform an UNLOCK. APPEND BLANK does not release an FLOCK() set by the current user.

Examples

      .  This example attempts to add a record to a shared database
      file and uses NETERR() to test whether the operation succeeded:

      USE Sales SHARED NEW
      .
      . <statements>
      .
      APPEND BLANK
      IF !NETERR()
         <update empty record>...
      ELSE
         ? "Append operation failed"
         BREAK
      ENDIF

Seealso

APPEND FROM, FLOCK(), NETERR(), RLOCK()

Harbour All Functions – R

Posted on by vivaclipper

RangeRem

RangeRepl

RAt

Rate

RD / RMDIR / DirRemove

ReadKey

ReadVar()

RecCount

RecNo
RecSize

RemAll

RemLeft
RemRight
ReplAll
Replicate

ReplLeft

ReplRight

RestToken
Right

RLock

Round

Row

RToD

RTrim

NetErr()

Posted on by vivaclipper

NETERR()

Tests the success of a network function

Syntax

      NETERR([<lNewError>]) --> lError

Arguments

<lNewError> Is a logical Expression.

Returns

<lError> A value based on the success of a network operation or function.

Description

This function return a logical true (.T.) is a USE, APPEND BLANK, or a USE…EXCLUSIVE command is issue and fails in a network enviroment. In the case of USE and USE…EXCLUSIVE commands, a NETERR() value of .T. would be returned if another node of the network has the exclusive use of a file. And the case of the APPEND BLANK command, NETERR() will return a logical true (.T.) if the file or record is locked by another node or the value of LASTREC() has been advanced The value of NETERR() may be changed via the value of <lNewError>. This allow the run-time error-handling system to control the way certains errors are handled.

Examples

      USE test NEW INDEX test
      IF ! NetErr()
          SEEK test->Name := "HARBOUR"
          IF Found()
             ? test->Name
          ENDIF
      ENDIF
      USE

Compliance

Clipper

Files

Library is rdd

Seealso

FLOCK(), RLOCK()

FLock()

Posted on by vivaclipper

FLOCK()

Locks a file

Syntax

      FLOCK() --> lSuccess

Returns

<lSuccess> A true (.T.) value, if the lock was successful;otherwise false (.F.)

Description

This function returns a logical true (.T.) if a file lock is attempted and is successfully placed on the current or designated database. This function will also unlock all records locks placed by the same network station.

Examples

      USE tests New
      IF FLOCK()
         SUM tests->Ammount
      ENDIF
      USE

Compliance

Clipper

Files

Library is rdd

Seealso

RLOCK()

dbUnlockAll()

Posted on by vivaclipper

DBUNLOCKALL()

Unlocks all records and releases all file locks in all work areas.

Syntax

      DBUNLOCKALL()

Description

This function will remove all file and record locks in all work area.

Examples

      nId := 10
      USE tests INDEX testid NEW
      USE tests1 INDEX tests NEW
      IF testid->( DBSEEK( nId ) )
         IF testid->( RLOCK() )
            DBDELETE()
         ELSE
            DBUNLOCK()
         ENDIF
      ELSE
         DBUNLOCKALL()
      ENDIF
      USE

Compliance

Clipper

Files

Library is rdd

Seealso

DBUNLOCK(), FLOCK(), RLOCK()