USE

USE

Open an existing database (.dbf) and its associated files

Syntax

      USE [<xcDatabase>
            [INDEX <xcIndex list>]
            [ALIAS <xcAlias>] [EXCLUSIVE | SHARED]
            [NEW] [READONLY]
            [VIA <cDriver>]]

Arguments

<xcDatabase> is the name of the database file to be opened and may be specified either as a literal file name or as a character expression enclosed in parentheses.

INDEX <xcIndex list> specifies the names of 1 to 15 index files to be opened in the current work area. Specify each index as a literal file name or as a character expression enclosed in parentheses. The first index in the list becomes the controlling index. If you specify an <xcIndex> as an expression and the value returned is spaces or NIL, it is ignored.

ALIAS <xcAlias> specifies the name to associate with the work area when the database file is opened. You may specify the alias name as a literal name or as a character expression enclosed in parentheses. A valid <xcAlias> may be any legal identifier (i.e., it must begin with an alphabetic character and may contain numeric or alphabetic characters and the underscore). Within a single application, Harbour will not accept duplicate aliases. If this clause is omitted, the alias defaults to the database file name.

EXCLUSIVE opens the database file for nonshared use in a network environment. All other users are denied access until the database file is CLOSEd.

SHARED opens the database file for shared use in a network environment. Specifying this clause overrides the current EXCLUSIVE setting.

NEW opens <xcDatabase> in the next available work area making it the current work area. If this clause is not specified, <xcDatabase> is opened in the current work area.

READONLY opens <xcDatabase> with a read-only attribute. This lets you open database files marked read-only. If you cannot open the <xcDatabase> this way, a runtime error is generated. If this clause is not specified, <xcDatabase> is opened as read-write.

VIA <cDriver> specifies the replaceable database driver (RDD) with which to process the current work area. <cDriver> is the name of the RDD specified as a character expression. If <cDriver> is specified as a literal value, it must be enclosed in quotes.

If the VIA clause is omitted, the DBFNTX driver is used by default. Note that if the specified driver is not linked, an unrecoverable error occurs.

In no arguments are specified, the database file open in the current work area is closed.

Description

USE opens an existing database (.dbf) file, its associated memo (.dbt) file, and optionally associated index (.ntx or .ndx) file(s) in the current or the next available work area. In Harbour, there are 250 work areas with a maximum of 255 total files open in DOS 3.3 and above. Before USE opens a database file and its associated files, it closes any active files already open in the work area. When a database file is first opened, the record pointer is positioned at the first logical record in the file (record one, if there is no index file specified).

In a network environment, you may open database files as EXCLUSIVE or SHARED. EXCLUSIVE precludes the USE of the database file by other users until the file is closed. SHARED allows other users to USE the database file for concurrent access. If the database file is SHARED, responsibility for data integrity falls upon the application program. In Harbour, FLOCK() and RLOCK() are the two basic means of denying other users access to a particular work area or record. If a USE is specified and neither EXCLUSIVE nor SHARED is specified, the database file is opened according to the current EXCLUSIVE setting. In Harbour, all USE commands should explicitly specify how the database file is to be opened, EXCLUSIVE or SHARED. The implicit open mode specified by SET EXCLUSIVE is supplied for compatibility purposes only and not recommended.

Opening a database file in a network environment requires some special handling to be successful. First, attempt to USE the database file without specifying the INDEX list. Then, test for the success of the operation using NETERR(). If NETERR() returns false (.F.), the open operation succeeded and you can SET INDEX TO the index list. A USE will fail in a network environment if another user has EXCLUSIVE USE of the database file. Refer to the “Network Programming” chapter in the Programming and Utilities Guide for more information on opening files in a network environment.

You can open index files with USE or SET INDEX. The first index in the list of indexes defines the current ordering of records when they are accessed. This index is referred to as the controlling index. You can change the current controlling index without closing any files by using the SET ORDER command.

To close a database and its associated files in the current work area, specify USE or CLOSE with no arguments. To close database files in all work areas, use CLOSE DATABASEs. To close index files in the current work area without closing the database file, use CLOSE INDEX or SET INDEX TO with no arguments.

Refer to the “Basic Concepts” chapterfor more information about the Harbour database paradigm.

Notes

. Setting the maximum open files: Control of the number of file handles available to a Harbour application is controlled by a combination of the CONFIG.SYS FILES command, and the F parameter of the CLIPPER environment variable. The F parameter specifies the maximum number of files that can be opened at any one time within the current Harbour program. Harbour determines the number of files that can be opened using the smaller of the two parameters. For example, if the FILES command is set to 120 and the F parameter is set to 50, the maximum number of files that can be opened is 50. In a network environment, file handles also need to be set in the network configuration file.

The file limit is controlled by the operating system. Under DOS versions less than 3.3, the maximum number of files that can be opened at one time is 20 files. In DOS versions 3.3 and greater, the maximum limit is 255 files.

. Opening the same database file in more than one work area: Although opening a database file in more than one work area is possible in a network environment, this practice is strongly discouraged. If done, each file must be opened with a different alias, otherwise a runtime error will occur.

. Opening two database files with the same names, in different directories: Although opening two database files with the same names in different directories is possible, the database files MUST have unique alias names; otherwise, a runtime error will occur.

Examples

      .  This example opens a shared database file with associated
         index files in a network environment.  If NETERR() returns
         false (.F.), indicating the USE was successful, the indexes
         are opened:

      USE Accounts SHARED NEW
      IF !NETERR()
         SET INDEX TO AcctNames, AcctZip
      ELSE
         ? "File open failed"
         BREAK
      ENDIF

      .  This example opens a database file with several indexes
         specified as extended expressions.  Note how the array
         of index names is created as a constant array:

      xcDatabase = "MyDbf"
      xcIndex = {"MyIndex1", "MyIndex2", "MyIndex3"}
      USE (xcDatabase) INDEX (xcIndex[1]), ;
            (xcIndex[2]), (xcIndex[3])

Seealso

CLOSE, DBRSELECT(), DBSETINDEX(), DBUSEAREA(), NETERR()

Advertisements

SET EXCLUSIVE

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()

APPEND BLANK

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()

C5_NETERR

 NETERR() 
 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

 Files   Library is CLIPPER.LIB.

See Also: APPEND BLANK RLOCK()

 

Clipper and Networking

Clipper and Networking

Using code blocks, again

Using code blocks again (.pdf)