Tag Archives: FLOCK()

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

SORT

Posted on by vivaclipper

SORT

Copy to a database (.dbf) file in sorted order

Syntax

      SORT TO <xcDatabase> ON <idField1> [/[A | D][C]]
            [, <idField2> [/[A | D][C]]...]
            [<scope>] [WHILE <lCondition>] [FOR <lCondition>]

Arguments

TO <xcDatabase> is the name of the target file for the sorted records and can be specified either as a literal file name or as a character expression enclosed in parentheses. Unless otherwise specified, the new file is assigned a (.dbf) extension.

ON <idField> is the sort key and must be a field variable.

/[A|D][C] specifies how <xcDatabase> is to be sorted. /A sorts in ascending order. /D sorts in descending order. /C sorts in dictionary order by ignoring the case of the specified character field. The default SORT order is ascending.

<scope> is the portion of the current database file to SORT. The default is 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 SORT within the given scope.

Description

SORT is a database command that copies records from the current work area to another database file in sorted order. Clipper SORTs character fields in accordance with the ASCII value of each character within the string unless the /C option is specified. This option causes the database file to be sorted in dictionary order–capitalization is ignored. Numeric fields are sorted in numeric order, date fields are sorted chronologically, and logical fields are sorted with true (.T.) as the high value. Memo fields cannot be sorted.

SORT performs as much of its operation as possible in memory, and then, it spools to a uniquely named temporary disk file. This temporary file can be as large as the size of the source database file. Note also that a SORT uses up three file handles: the source database file, the target database file, and the temporary file. In a network environment, you must lock the database file to be SORTed with FLOCK() or USE it EXCLUSIVEly.

Notes

. Deleted source records: If DELETED is OFF, SORT copies deleted records to the target database file; however, the deleted records do not retain their deleted status. No record is marked for deletion in the target file regardless of its status in the source file.

If DELETED is ON, deleted records are not copied to the target database file. Similarly, filtered records are ignored during a SORT and are not included in the target file.

Examples

      .  This example copies a sorted subset of a mailing list to a
         smaller list for printing:

      USE Mailing INDEX Zip
      SEEK "900"
      SORT ON LastName, FirstName TO Invite WHILE Zip = "900"
      USE Invite NEW
      REPORT FORM RsvpList TO PRINTER

Seealso

ASORT(), FLOCK(), INDEX, USE

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 – F

Posted on by vivaclipper

Fact

Fahrenheit

FClose()
FCount()
FCreate()
FErase()
FError()
FieldBlock()

FieldDeci()

FieldGet()

FieldName()
FieldPos()
FieldPut()

FieldSize()
FieldType()

FieldWBlock()

File()
FLock()

Floor

FOpen()

Found()

FRead()
FReadStr()
FRename()
FSeek()

FToC

FV

FWrite()

Harbour Database Functions

Posted on by vivaclipper

Database Functions

AFields Fills referenced arrays with database field information
Alias Returns the alias name of a work area
BOF Test for the beggining-of-file condition
dbAppend Appends a new record to a database file
dbClearFilter Clears the current filter condiction in a work area
dbCloseAll Close all open files in all work areas.
dbCloseArea Close a database file in a work area
dbCommit Updates all index and database buffers for a given workarea
dbCommitAll Flushes the memory buffer and performs a hard-disk write
dbCreate Creates an empty database from a array
dbDelete Mark a record for deletion in a database
dbEval Performs a code block operation on the current Database
DBF Alias name of a work area
dbFilter Return the filter expression in a work area
dbGoBottom Moves the record pointer to the bottom of the database
dbGoto Position the record pointer to a specific location
dbGoTop Moves the record pointer to the top of the database
dbRecall Recalls a record previousy marked for deletion
dbSeek Searches for a value based on an active index
dbSelectArea Change to another work area
dbSetDriver Establishes the RDD name for the selected work area
dbSetFilter Establishes a filter condition for a work area
dbSkip Moves the record pointer in the selected work area
dbSkipper Helper function to skip a database
dbStruct Builds a multidimensional array of a database structure
dbUseArea Opens a work area and uses a database file
Deleted Tests the record’s deletion flag
EOF Test for end-of-file condition
FCount Counts the number of fields in an active database
FieldDeci Determines the number of decimal places of a given numeric field
FieldGet Obtains the value of a specified field
FieldName Return the name of a field at a numeric field location
FieldPos Return the ordinal position of a field
FieldPut Set the value of a field variable
FieldSize Determines the size of a given field
FieldType Determines the type of a given field
Found Determine the success of a previous search operation
Header Return the length of a database file header
LastRec Returns the number of records in an active work area or database
LUpdate Yields the date the database was last updated
RecCount Counts the number of records in a database
RecNo Returns the current record number or identity
RecSize Returns the size of a single record in an active database
Select Returns the work area number for a specified alias
Used Checks whether a database is in use in a work area

RLock()

Posted on by vivaclipper

RLOCK()

Lock a record in a work area

Syntax

      RLOCK() --> lSuccess

Arguments

(This function has no arguments)

Returns

RLOCK() True (.T.) if record lock is successful; otherwise, it returns false (.F.).

Description

This function returns a logical true (.T.) if an attempt to lock a specific record in a selected or designated work area is successful. It will yield a false (.F.) if either the file or the desired record is currently locked. A record that is locked remains locked until another RLOCK() is issued or until an UNLOCK command is executed. On a Network enviroment the follow command need that the record is locked:

@…GET

DELETE (single record)

RECALL (single record)

REPLACE (single record)

Examples

      nId := 10
      USE testid INDEX testid NEW
      IF testid->( DBSEEK( nId ) )
         IF testid->( RLOCK() )
            DBDELETE()
         ENDIF
      ENDIF
      USE

Compliance

Clipper

Files

Library is rdd

Seealso

FLOCK()