fivedev/harbour-core
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
931663c13175d8f970a3dd030dab15011fb687af
harbour-core/harbour/doc/en/rddmisc.txt
Luiz Rafael Culik bdedc8a862 See changelog 20000411 20:30
2000-04-11 23:23:28 +00:00

1014 lines
28 KiB
Plaintext
Raw Blame History

/*
* $Id$
*/
/*
* The following parts are Copyright of the individual authors.
* www - http://www.harbour-project.org
*
* Copyright 1999 Luiz Rafael Culik <culik@sl.conex.net>
* DB*() documentation
* ORD*() documentation
* RDD*() documentation
*
* See doc/license.txt for licensing terms.
*
*/
/* $DOC$
* $FUNCNAME$
* AFIELDS()
* $CATEGORY$
* Database
* $ONELINER$
* Fills referenced arrays with database field information
* $SYNTAX$
* AFields(<aNames>[,<aTypes>][,<aLen>][,<aDecs>]) --> <nFields>
* $ARGUMENTS$
* <aNames> Array of field names
*
* <aTypes> Array of field names
*
* <aLens> Array of field names
*
* <aDecs> Array of field names
* $RETURNS$
* <nFields> Number od fields in a database or work area
* $DESCRIPTION$
* This function will fill a series of arrays with field
* names,field types,field lenghts, and number of field
* decimal positions for the currently selected or designed
* database. Each array parallels the different descriptors
* of a file's structure.The first array will consist of the
* names of the fields in the current work area.All other arrays
* are optional and will be filled with the corrensponding data.
* This function will return zero if no parameters are specified
* or if no database is avaliable in the current work area.Otherwise,
* the number of fields or the lenght of the shortest array argument,
* witchever is smaller, will be returned.
* $EXAMPLES$
* FUNCTION Main()
* LOCAL aNames:={},aTypes:={},aLens:={},aDecs:={},nFields:=0
*
* USE Test
*
* dbGoTop()
* nFields:=aFields(aNames,aTypes,aLens,aDecs)
*
* ? "Number of fields", nFields
*
* RETURN NIL
* $STATUS$
* R
* $COMPLIANCE$
* AFIELDS() is fully CA-Clipper compliant.
* $FILES$
* Library is Rdd.lib
* $END$
*/
/* $DOC$
* $FUNCNAME$
* ALIAS()
* $CATEGORY$
* Database
* $ONELINER$
* Returns the alias name of a work area
* $SYNTAX$
* Alias([<nWorkArea>]) --> <cWorkArea>
* $ARGUMENTS$
* <nWorkArea> Number of a work area
* $RETURNS$
* <cWorkArea> Name of alias
* $DESCRIPTION$
* This function returns the alias of the work area indicated by <nWorkArea>
* If <nWorkArea> is not provided, the alias of the current work area is
* returned.
* $EXAMPLES$
* FUNCTION Main()
*
* USE Test
* select 0
* qOut( IF(Alias()=="","No Name",Alias()))
* Test->(qOut(Alias())
* qOut(Alias(1))
*
* RETURN NIL
* $STATUS$
* R
* $COMPLIANCE$
* ALIAS() is fully CA-Clipper compliant.
* $FILES$
* Library is Rdd.lib
* $SEEALSO$
* DBF()
* $END$
*/
/* $DOC$
* $FUNCNAME$
* BOF()
* $CATEGORY$
* Database
* $ONELINER$
* Test for the beggining-of-file condition
* $SYNTAX$
* BOF() --> <lBegin>
* $RETURNS$
* BOF() Logical true (.T.) or false (.F.)
* $DESCRIPTION$
* This function determines if the beggining of the file marker has been
* reached. If so, the function will return a logical true (.T.); otherwise,
* a logical false(.F.) will be returned.
* By default, BOF() will apply to the currently selected database unless
* the function is preceded by an alias
* $EXAMPLES$
* FUNCTION Main()
* USE Tests NEW
* DBGOTOP()
* ? "Is Eof()",EOF()
* DBGOBOTTOM()
* ? "Is Eof()",EOF()
* USE
* RETURN NIL
* $STATUS$
* R
* $COMPLIANCE$
* BOF() is fully CA-Clipper compliant.
* $FILES$
* Library is Rdd.lib
* $SEEALSO$
* EOF(),FOUND(),LASTREC()
* $END$
*/
/* $DOC$
* $COMMANDNAME$
* ZAP
* $CATEGORY$
* Command
* $ONELINER$
* Remove all records from the current database file
* $SYNTAX$
* ZAP
* $DESCRIPTION$
* This command removes all of the records from the database in the
* current work area.This operation also updates any index file in
* use at the time of this operation.In addition, this command removes
* all items within an associated memo file.
* In a network enviroment,any file that is about to be ZAPped must
* be used exclusively.
* $EXAMPLES$
* USE Tests NEW index Tests
* ZAP
* USE
* $STATUS$
* R
* $COMPLIANCE$
* This command is CA Clipper compliant
* $SEEALSO$
* DELETE,PACK,USE
* $END$
*/
/* $DOC$
* $FUNCNAME$
* DELETED()
* $CATEGORY$
* Database
* $ONELINER$
* Tests the record's deletion flag.
* $SYNTAX$
* DELETED() --> lDeleted
* $RETURNS$
* DELETED() return a logical true (.T.) or false (.F.).
* $DESCRIPTION$
* This function returns a logical true (.T.) is the current record in the
* selected or designated work area ha ben marked for deletion.If not, the
* function will return a logical false (.F.).
* $EXAMPLES$
* FUNCTION Main()
* USE Test New
* DBGOTO()
* DBDELETE()
* ? "Is Record Deleted",Test->(DELETED())
* DBRECALL()
* USE
* RETURN NIL
* $STATUS$
* R
* $COMPLIANCE$
* This function is CA-Clipper compliant
* $FILES$
* Library is Rdd.lib
* $SEEALSO$
* DBDELETE()
* $END$
*/
/* $DOC$
* $FUNCNAME$
* EOF()
* $CATEGORY$
* Database
* $ONELINER$
* Test for end-of-file condition.
* $SYNTAX$
* EOF() --> <lEnd>
* $RETURNS$
* <lEnd> A logical true (.T.) or false (.F.)
* $DESCRIPTION$
* This function determines if the end-of-file marker has been reached.
* If it has, the function will return a logical true (.T.); otherwise
* a logical false (.F.) will be returnd
* $EXAMPLES$
* FUNCTION Main()
* USE Tests NEW
* DBGOTOP()
* ? "Is Eof()",EOF()
* DBGOBOTTOM()
* ? "Is Eof()",EOF()
* USE
* RETURN NIL
* $STATUS$
* R
* $COMPLIANCE$
* EOF() is fully CA-Clipper compliant.
* $FILES$
* Library is Rdd.lib
* $SEEALSO$
* BOF(),FOUND(),LASTREC()
* $END$
*/
/* $DOC$
* $FUNCNAME$
* FCOUNT()
* $CATEGORY$
* Database
* $ONELINER$
* Counts the number of fields in an active database.
* $SYNTAX$
* FCOUNT() --> nFields
* $RETURNS$
* <nFields> Return the number of fields
* $DESCRIPTION$
* This function returns the number of fields in the current or designated
* work area.If no database is open in this work area, the function will
* return 0.
* $EXAMPLES$
* FUNCTION Main()
* USE Tests NEW
* ? "This database have ",Tests->(FCOUNT()),"Fields"
* USE
* RETURN Nil
* $STATUS$
* R
* $COMPLIANCE$
* This function is CA-Clipper compliant
* $FILES$
* Library is Rdd.lib
* $SEEALSO$
* FIELDNAME(),TYPE()
* $END$
*/
/* $DOC$
* $FUNCNAME$
* FIELDGET()
* $CATEGORY$
* Database
* $ONELINER$
* Obtains the value of a specified field
* $SYNTAX$
* FIELDGET(<nField>) --> ValueField
* $ARGUMENTS$
* <nField> Is the numeric field position
* $RETURNS$
* <ValueField> Any expression
* $DESCRIPTION$
* This function returns the value of the field at the <nField>th location
* in the selected or designed work area.If the value in <nField> does not
* correspond to n avaliable field position in this work area, the function
* will return a NIL data type.
* $EXAMPLES$
* FUNCTION Main()
* USE Test NEW
* ? Test->(FieldGet(1))
* USE
* RETURN NIL
* $STATUS$
* R
* $COMPLIANCE$
* This function is CA-Clipper Compliant.
* $FILES$
* Library is Rdd.lib
* $SEEALSO$
* FIELDPUT()
* $END$
*/
/* $DOC$
* $FUNCNAME$
* FIELDNAME()
* $CATEGORY$
* Database
* $ONELINER$
* Return the name of a field at a numeric field location.
* $SYNTAX$
* FIELDNAME/FIELD(<nPosition>) --> cFieldName
* $ARGUMENTS$
* <nPosition> Field order in the database.
* $RETURNS$
* <cFieldName> returns the field name.
* $DESCRIPTION$
* This function return the name of the field at the <nPosition>th position.
* If the numeric value passed to this function does not correspond to an
* existing field in the designated or selected work area,this function
* will return a NULL byte.
* $EXAMPLES$
* FUNCTION Main()
* LOCAL x
* USE Tests NEW
* FOR x := 1 to Tests->(FCOUNT())
* ? "Field Name",FieldName(x)
* NEXT
* USE
* RETURN Nil
* $STATUS$
* R
* $COMPLIANCE$
* This function is CA-Clipper compatible.
* $FILES$
* Library is Rdd.lib
* $SEEALSO$
* DBSTRUCT(),FCOUNT(),LEN(),VALTYPE()
* $END$
*/
/* $DOC$
* $FUNCNAME$
* FIELDPOS()
* $CATEGORY$
* Database
* $ONELINER$
* Return the ordinal position of a field.
* $SYNTAX$
* FIELDPOS(<cFieldName>) --> nFieldPos
* $ARGUMENTS$
* <cFieldName> Name of a field.
* $RETURNS$
* <nFieldPos> is ordinal position of the field.
* $DESCRIPTION$
* This function return the ordinal position of the specified field <cField>
* in the current or aliased work areaIf there isn't field under the name
* of <cField> or of no database is open in the selected work area, the func-
* tion will return a 0.
* $EXAMPLES$
* FUNCTION Main()
* USE Test NEW
* ? Test->(FIELDPOS("ID"))
* USE
* RETURN NIL
* $STATUS$
* R
* $COMPLIANCE$
* This function is CA-Clipper compliant.
* $FILES$
* Library is Rdd.lib
* $SEEALSO$
* FIELDGET(),FIELDPUT()
* $END$
*/
/* $DOC$
* $FUNCNAME$
* FIELDPUT()
* $CATEGORY$
* Database
* $ONELINER$
* Set the value of a field variable
* $SYNTAX$
* FIELDPUT(<nField>, <expAssign>) --> ValueAssigned
* $ARGUMENTS$
* <nField> The field numeric position
*
* <expAssign> Expression to be assigned to the specified field
* $RETURNS$
* <ValueAssigned> Any expression
* $DESCRIPTION$
* This function assings the value in <expAssing> to the <nField>th
* field in the current or designated work area.If the operation is
* successful,the return value of the function will be the same value
* assigned to the specified field.If the operation is not successful,
* the function will return a NIL data type
* $EXAMPLES$
* USE Tests New
* FIELDPUT(1,"Mr. Jones")
* USE
* $STATUS$
* R
* $COMPLIANCE$
* This function is CA-Clipper compatible.
* $FILES$
* Library is Rdd.lib
* $SEEALSO$
* FIELDGET()
* $END$
*/
/* $DOC$
* $FUNCNAME$
* FLOCK()
* $CATEGORY$
* Database
* $ONELINER$
* 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.0 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
* $STATUS$
* R
* $COMPLIANCE$
* This function is CA-Clipper compatible
* $FILES$
* Library is Rdd.lib
* $SEEALSO$
* RLOCK()
* $END$
*/
/* $DOC$
* $FUNCNAME$
* FOUND()
* $CATEGORY$
* Database
* $ONELINER$
* Determine the success of a previous search operation.
* $SYNTAX$
* FOUND() --> lSuccess
* $ARGUMENTS$
* None.
* $RETURNS$
* <lSuccess> A logical true (.T.) is successful;otherwise, false (.F.)
* $DESCRIPTION$
* This function is used to test if the previous SEEK,LOCATE,CONTINUE,
* or FIND operation was successful.Each wrk area has its own FOUND()
* flag,so that a FOUND() condition may be tested in unselected work
* areas by using an alias.
* $EXAMPLES$
* nId:=100
* USE Tests NEW INDEX Tests
* SEEK nId
* IF FOUND()
* ? Tests->Name
* ENDIF
* USE
* $STATUS$
* R
* $COMPLIANCE$
* This function is CA-Clipper compatible
* $FILES$
* Library is Rdd.lib
* $SEEALSO$
* EOF()
* $END$
*/
/* $DOC$
* $FUNCNAME$
* HEADER()
* $CATEGORY$
* Database
* $ONELINER$
* Return the length of a database file header
* $SYNTAX$
* HEADER() --> nBytes
* $RETURNS$
* <nBytes> The numeric size of a database file header in bytes
* $DESCRIPTION$
* This function returns the number of bytes in the header of the
* selected database ot the database in the designated work area.
*
* If used in conjunction with the LASTREC(),RECSIZE() and DISKSPACE()
* functions,this functions is capable of implementing a backup and
* restore routine.
* $EXAMPLES$
* USE Tests New
* ? Header()
* $STATUS$
* R
* $COMPLIANCE$
* This function is CA-Clipper compatible
* $FILES$
* Library is Rdd.lib
* $SEEALSO$
* DISKSPACE(),LASTREC(),RECSIZE()
* $END$
*/
/* $DOC$
* $FUNCNAME$
* LASTREC()
* $CATEGORY$
* Database
* $ONELINER$
* Returns the number of records in an active work area or database.
* $SYNTAX$
* LASTREC() | RECCOUNT()* --> nRecords
* $RETURNS$
* <nRecords > The number of records
* $DESCRIPTION$
* This function returns the number of records present in the database
* in the selected or designated work area.If no records are present
* the value of this function will be 0.
* $EXAMPLES$
* USE Tests NEW
* ? LASTREC(), RECCOUNT()
* $TESTS$
* $STATUS$
* R
* $COMPLIANCE$
* This function is CA Clipper compatible
* $PLATFORMS$
* All
* $FILES$
* Library is Rdd.lib
* $SEEALSO$
* EOF()
* $END$
*/
/* $DOC$
* $FUNCNAME$
* LUPDATE()
* $CATEGORY$
* Database
* $ONELINER$
* Return the last modification date of a (.dbf) file
* $SYNTAX$
* LUPDATE() --> dModification
* $ARGUMENTS$
* None
* $RETURNS$
* <dModification> the date of last change to the open database file in
* the current work area. If there is no database file in USE, LUPDATE()
* returns a blank date.
* $DESCRIPTION$
* LUPDATE() is a database function that determines the date the database
* file in the current work area was last modified and CLOSEd. By default,
* LUPDATE() operates on the currently selected work area. It will operate
* on an unselected work area if you specify it as part of an aliased
* expression as shown in the example below.
* $EXAMPLES$
* This example demonstrates that the modification date of
* database file is not changed until the database file is closed:
*
* ? DATE() // Result: 09/01/90
* USE Sales NEW
* ? LUPDATE() // Result: 08/31/90
* //
* APPEND BLANK
* ? LUPDATE() // Result: 08/31/90
* CLOSE DATABASES
* //
* USE Sales NEW
* ? LUPDATE() // Result: 09/01/90
*
* This example uses an aliased expression to access LUPDATE()
* for a database file open in an unselected work area:
*
* USE Sales NEW
* USE Customer NEW
* ? LUPDATE(), Sales->(LUPDATE())
* $TESTS$
* $STATUS$
* R
* $COMPLIANCE$
* This function is CA Clipper compliant
* $PLATFORMS$
* All
* $FILES$
* Library is Rdd.lib
* $SEEALSO$
* FIELDNAME(),LASTREC(),RECSIZE()
* $END$
*/
/* $DOC$
* $FUNCNAME$
* NETERR()
* $CATEGORY$
* Database
* $ONELINER$
* Determine if a network command has failed
* $SYNTAX$
* NETERR([<lNewError>]) --> lError
* $ARGUMENTS$
* <lNewError> if specified sets the value returned by NETERR() to the
* specified status. <lNewError> can be either true (.T.) or false (.F.).
* Setting NETERR() to a specified value allows the runtime error handler
* to control the way certain file errors are handled. For more
* information, refer to Errorsys.prg.
* $RETURNS$
* NETERR() returns true (.T.) if a USE or APPEND BLANK fails. The initial
* value of NETERR() is false (.F.). If the current process is not running
* under a network operating system, NETERR() always returns false (.F.).
* $DESCRIPTION$
* NETERR() is a network function. It is a global flag set by USE,
* USE...EXCLUSIVE, and APPEND BLANK in a network environment. It is used
* to test whether any of these commands have failed by returning true
* (.T.) in the following situations:
*
* NETERR() Causes
* <20><><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>
* Command Cause
* <20><><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>
* USE USE EXCLUSIVE by another process
* USE...EXCLUSIVE USE EXCLUSIVE or USE by another process
* APPEND BLANK FLOCK() or RLOCK() of LASTREC() + 1 by another user
* <20><><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>
*
* NETERR() is generally applied in a program by testing it following a USE
* or APPEND BLANK command. If it returns false (.F.), you can perform the
* next operation. If the command is USE, you can open index files. If it
* is APPEND BLANK, you can assign values to the new record with a REPLACE
* or @...GET command. Otherwise, you must handle the error by either
* retrying the USE or APPEND BLANK, or terminating the current operation
* with a BREAK or RETURN.
* $EXAMPLES$
* This example demonstrates typical usage of NETERR(). If the
* USE succeeds, the index files are opened and processing continues.
* If the USE fails, a message displays and control returns to the
* nearest BEGIN SEQUENCE construct:
*
* USE Customer SHARED NEW
* IF !NETERR()
* SET INDEX TO CustNum, CustOrders, CustZip
* ELSE
* ? "File is in use by another"
* BREAK
* ENDIF
* $STATUS$
* R
* $COMPLIANCE$
* This function is CA Clipper compliant
* $SEEALSO$
* FLOCK(),RLOCK()
* $END$
*/
/* $DOC$
* $FUNCNAME$
* RECCOUNT()
* $CATEGORY$
* Database
* $ONELINER$
* Determine the number of records in the current (.dbf) file
* $SYNTAX$
* RECCOUNT()* | LASTREC() --> nRecords
* $ARGUMENTS$
*
* $RETURNS$
* RECCOUNT() returns the number of physical records in the current
* database file as an integer numeric value. Filtering commands such as
* SET FILTER or SET DELETED have no effect on the return value.
* RECCOUNT() returns zero if there is no database file open in the current
* work area.
*
* $DESCRIPTION$*
* RECCOUNT() is a database function that is a synonym for LASTREC(). By
* default, RECCOUNT() operates on the currently selected work area. It
* will operate on an unselected work area if you specify it as part of an
* aliased expression (see example below).
* $EXAMPLES$
* This example illustrates the relationship between COUNT and
* RECCOUNT():
*
* USE Sales NEW
* ? RECCOUNT() // Result: 84
* //
* SET FILTER TO Salesman = "1001"
* COUNT TO nRecords
* ? nRecords // Result: 14
* ? RECCOUNT() // Result: 84
*
* This example uses an aliased expression to access the number
* of records in an unselected work area:
*
* USE Sales NEW
* USE Customer NEW
* ? RECCOUNT(), Sales->(RECCOUNT())
* $TESTS$
*
* $STATUS$
* R
* $COMPLIANCE$
*
* $SEEALSO$
* EOF(),LASTREC()
* $INCLUDE$
*
* $END$
*/
/* $DOC$
* $FUNCNAME$
* RECNO()
* $CATEGORY$
* Database
* $ONELINER$
* Return the identity at the position of the record pointer
* $SYNTAX$
* RECNO() --> Identity
* $ARGUMENTS$
*
* $RETURNS$
* RECNO() returns the identity found at the position of the record
* pointer.
* $DESCRIPTION$
* RECNO() is a database function that returns the identity found at the
* current position of the record pointer. Identity is a unique value
* guaranteed by the structure of the data file to reference a specific
* record of data file. The data file need not be a traditional Xbase
* file. Therefore, unlike earlier versions of HARBOUR, the value
* returned need not be a numeric data type.
*
* Under all RDDs, RECNO() returns the value at the position of the record
* pointer; the data type and other characteristics of this value are
* determined by the content of the accessed data and the RDD active in the
* current work area. In an Xbase database this value is the record
* number.
* $EXAMPLES$
* USE Sales VIA "DBFNTX"
* .
* . < statements >
* .
* DBGOTOP()
* RECNO() // Returns 1
* $TESTS$
*
* $STATUS$
* R
* $COMPLIANCE$
*
* $SEEALSO$
* DBGOTO()
* $INCLUDE$
*
* $END$
*/
/* $DOC$
* $FUNCNAME$
* RECSIZE()
* $CATEGORY$
* Database
* $ONELINER$
* Determine the record length of a database (.dbf) file
* $SYNTAX$
* RECSIZE() --> nBytes
* $ARGUMENTS$
*
* $RETURNS$
* RECSIZE() returns, as a numeric value, the record length, in bytes, of
* the database file open in the current work area. RECSIZE() returns zero
* if no database file is open.
* $DESCRIPTION$
* RECSIZE() is a database function that determines the length of a record
* by summing the lengths of each field then adding one for the DELETED()
* status flag. When this value is multiplied by LASTREC(), the product is
* the amount of space occupied by the file's records.
*
* RECSIZE() is useful in programs that perform automatic file backup.
* When used in conjunction with DISKSPACE(), the RECSIZE() function can
* assist in ensuring that sufficient free space exists on the disk before a
* file is stored.
*
* By default, RECSIZE() operates on the currently selected work area. It
* will operate on an unselected work area if you specify it as part of an
* aliased expression (see example below).
* $EXAMPLES$
* The following user-defined function, DbfSize(), uses RECSIZE()
* to calculate the size of the current database file:
*
* FUNCTION DbfSize
* RETURN ((RECSIZE() * LASTREC()) + HEADER() + 1)
*
* This example illustrates the use of RECSIZE() to determine the
* record length of database files open in unselected work areas:
*
* USE Customer NEW
* USE Sales NEW
* //
* ? RECSIZE(), Customer->(RECSIZE())
* ? DbfSize(), Customer->(DbfSize())
* $TESTS$
*
* $STATUS$
* R
* $COMPLIANCE$
*
* $SEEALSO$
* DISKSPACE(),FIELDNAME(),HEADER(),LASTREC()
* $INCLUDE$
*
* $END$
*/
/* $DOC$
* $FUNCNAME$
* RLOCK()
* $CATEGORY$
* Database
* $ONELINER$
* Lock the current record in the active work area
* $SYNTAX$
* RLOCK() --> lSuccess
* $ARGUMENTS$
*
* $RETURNS$
* RLOCK() returns true (.T.) if the record lock is obtained; otherwise, it
* returns false (.F.).
* $DESCRIPTION$
* RLOCK() is a network function that locks the current record, preventing
* other users from updating the record until the lock is released.
* RLOCK() provides a shared lock, allowing other users read-only access to
* the locked record while allowing only the current user to modify it. A
* record lock remains until another record is locked, an UNLOCK is
* executed, the current database file is closed, or an FLOCK() is obtained
* on the current database file.
*
* For each invocation of RLOCK(), there is one attempt to lock the current
* record, and the result is returned as a logical value. An attempt to
* obtain a record lock fails if another user currently has a file or
* record lock, or EXCLUSIVE USE of the database file. An attempt to
* RLOCK() in an empty database returns true (.T.).
*
* By default, RLOCK() operates on the currently selected work area. It
* will operate on an unselected work area if you specify it as part of an
* aliased expression (see example below). This feature is useful since
* RLOCK() does not automatically attempt a record lock for related files.
*
* As a general rule, RLOCK() operates solely on the current record. This
* includes the following commands:
*
* @...GET
*
* DELETE (single record)
*
* RECALL (single record)
*
* REPLACE (single record)
*
*
* Notes
*
* SET RELATION: HARBOUR does not automatically lock all
* records in the relation chain when you lock the current work area
* record. Also, an UNLOCK has no effect on related work areas.
* $EXAMPLES$
* This example deletes a record in a network environment, using
* RLOCK():
*
* USE Customer INDEX CustName SHARED NEW
* SEEK "Smith"
* IF FOUND()
* IF RLOCK()
* DELETE
* ? "Smith deleted"
* ELSE
* ? "Record in use by another"
* ENDIF
* ELSE
* ? "Smith not in Customer file"
* ENDIF
* CLOSE
*
* This example specifies RLOCK() as an aliased expression to
* lock a record in an unselected work area:
*
* USE Sales SHARED NEW
* USE Customer SHARED NEW
* //
* IF !Sales->(RLOCK())
* ? "The current Sales record is in use by another"
* ENDIF
* $TESTS$
*
* $STATUS$
* R
* $COMPLIANCE$
*
* $SEEALSO$
* FLOCK()
* $INCLUDE$
*
* $END$
*/
/* $DOC$
* $FUNCNAME$
* SELECT()
* $CATEGORY$
* Database
* $ONELINER$
* Determine the work area number of a specified alias
* $SYNTAX$
* SELECT([<cAlias>]) --> nWorkArea
* $ARGUMENTS$
* <cAlias> is the target work area alias name.
* $RETURNS$
* SELECT() returns the work area of the specified alias as a integer
* numeric value.
* $DESCRIPTION$
* SELECT() is a database function that determines the work area number of
* an alias. The number returned can range from zero to 250. If <cAlias>
* is not specified, the current work area number is returned. If <cAlias>
* is specified and the alias does not exist, SELECT() returns zero.
*
* Note: The SELECT() function and SELECT command specified with an
* extended expression argument look somewhat alike. This shouldn't be a
* problem since the SELECT() function is not very useful on a line by
* itself
* $EXAMPLES$
* This example uses SELECT() to determine which work area
* USE...NEW selected:
*
* USE Sales NEW
* SELECT 1
* ? SELECT("Sales") // Result: 4
*
* To reselect the value returned from the SELECT() function, use
* the SELECT command with the syntax, SELECT (<idMemvar>), like this:
*
* USE Sales NEW
* nWorkArea:= SELECT()
* USE Customer NEW
* SELECT (nWorkArea)
* $TESTS$
*
* $STATUS$
* R
* $COMPLIANCE$
*
* $SEEALSO$
* ALIAS(),USED()
* $INCLUDE$
*
* $END$
*/
/* $DOC$
* $FUNCNAME$
* USED()
* $CATEGORY$
* Database
* $ONELINER$
* Determine whether a database file is in USE
* $SYNTAX$
* USED() --> lDbfOpen
* $ARGUMENTS$
*
* $RETURNS$
* USED() returns true (.T.) if there is a database file in USE; otherwise,
* it returns false (.F.).
* $DESCRIPTION$
* USED() is a database function that determines whether there is a
* database file in USE in a particular work area. By default, USED()
* operates on the currently selected work area. It will operate on an
* unselected work area if you specify it as part of an aliased expression.
* $EXAMPLES$
* This example determines whether a database file is in USE in
* the current work area:
*
* USE Customer NEW
* ? USED() // Result: .T.
* CLOSE
* ? USED() // Result: .F.
* $TESTS$
*
* $STATUS$
* R
* $COMPLIANCE$
*
* $SEEALSO$
* ALIAS(),SELECT()
* $INCLUDE$
*
* $END$
*/
Reference in New Issue View Git Blame Copy Permalink