/*
 * $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
 *      
 *      Command             Cause
 *      
 *      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
 *      
 *
 *      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$
 */
