WAIT

WAIT*

Suspend program processing until a key is pressed

Syntax

      WAIT [<expPrompt>] [TO <idVar>]

Arguments

<expPrompt> is an expression of any data type displayed as a prompt. If no <expPrompt> is specified, the default prompt displayed is: “Press any key to continue…”

TO <idVar> is the variable, of any storage class, that holds the value of the key pressed as a character value. If <idVar> does not exist or is not visible, it is created as a private variable and then assigned the character value.

Description

WAIT is a console command and wait state that displays a prompt after sending a carriage return/line feed to the screen. It then waits for the user to press a key. If the TO clause is specified, <idVar> is assigned the keystroke as a character value. If an Alt or Ctrl key is pressed, WAIT assigns CHR(0) to <idVar>. Non-alphanumeric values entered by pressing an Alt-keypad combination assign the specified character. If the character can be displayed, it is echoed to the screen. Function keys are ignored unless assigned with SET FUNCTION or SET KEY.

WAIT is a compatibility command and, therefore, is not recommended for general usage. It is superseded by both @…GET/READ and INKEY() for getting single character input.

Notes

. WAITing without a prompt: To pause execution without displaying a prompt, specify WAIT, null string (“”), or INKEY(0). The latter is recommended since it does not disturb the current screen cursor position.

Examples

      .  This example illustrates how to store the WAIT keystroke as an
         array element:

      aVar := ARRAY(6)

      WAIT "Press a key..." TO aVar[1]
      ? aVar[1]                  // Result: key pressed in
                                 // response to WAIT
      ? aVar[2]                  // Result: NIL
      ? VALTYPE(aVar)            // Result: A
      ? VALTYPE(aVar[1])         // Result: C

Seealso

@…GET, ACCEPT*, INKEY(), INPUT*, MENU TO

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

UPDATE

UPDATE

Update current database file from another database file

Syntax

      UPDATE FROM <xcAlias>
            ON <expKey> [RANDOM]
            REPLACE <idField> WITH <exp>
            [, <idField2> WITH    <exp2>...]

Arguments

FROM <xcAlias> specifies the alias of the work area used to update records in the current work area. This argument may be specified either as a literal file name or as a character expression enclosed in parentheses.

ON <expKey> specifies the expression that defines matching records in the FROM work area.

REPLACE <idField> specifies a field in the current work area to replace with a new value.

WITH <exp> specifies the value to replace into the current field. You must reference any field contained in the FROM work area with the correct alias.

RANDOM allows records in the FROM database file to be in any order. If this option is specified, the current database file must be indexed on <expKey>.

Description

UPDATE is a database command that replaces fields in the current work area with values from another work area based on the specified key expression. UPDATE is designed to update only current work area records based on a one-to-one or one-to-many relation with the FROM work area. This means that UPDATE can only update records in the current work area with unique key values. When there is more than one instance of a key value, only the first record with the key value is updated. The FROM work area, however, can have duplicate key values.

There are two formulations of the command depending on whether the FROM work area records are sorted or indexed on <expKey> or not. If RANDOM is not specified, both the current work area and the FROM work area must be indexed or sorted in <expKey> order. If RANDOM is specified, the current work area must be indexed by <expKey>, but the FROM work area records can be in any order.

To use UPDATE in a network environment, the current database file must be locked with FLOCK() or USEed EXCLUSIVEly. The FROM database file may be used in any mode. Refer to the “Network Programming” chapter in the Programming and Utilities Guide for more information.

Notes

. Deleted records: If DELETED is OFF, deleted records in both source files are processed. Records in the file being updated retain their deleted status and are not affected by the deleted status of records in the FROM file. If DELETED is ON, however, no deleted records are processed from either source file.

Examples

      .  This example UPDATEs the Customer database file with
         outstanding invoice amounts:

      USE Invoices NEW
      USE Customer INDEX Customer NEW
      UPDATE FROM Invoices ON Last;
         REPLACE Owed WITH Owed + Invoices->Amount RANDOM

Seealso

DBCREATEIND(), INDEX, JOIN, REPLACE, SET UNIQUE*, SORT

UNLOCK

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

TYPE

Display the contents of a text file

Syntax

      TYPE <xcFile> [TO PRINTER] [TO FILE <xcOutFile>]

Arguments

<xcFile> is the name of the file, including extension, to be displayed to the screen. This argument may be specified as a literal file name or as a character expression enclosed in parentheses. <xcFile> must be specified with an extension if it has one.

TO PRINTER echoes the display to the printer.

TO FILE <xcOutFile> echoes the display to the specified file. <xcOutFile> may be specified either as a literal file name or as a character expression enclosed in parentheses. If no extension is specified, .txt is added.

Description

TYPE is a console command that displays the contents of a text file to the screen, optionally echoing the display to the printer and/or another text file. To suppress output to the screen while printing or echoing output to a file, SET CONSOLE OFF before the TYPE invocation.

If <xcFile> is specified without a path and/or drive designator, TYPE searches the current DEFAULT directory, and then, the current PATH. If <xcOutFile> is specified without a path and/or drive designator, TYPE creates the file in the current DEFAULT directory.

TYPE performs no special formatting on the listing. There are no special headings or pagination when the output is sent to the printer.

To pause output, use Ctrl-S. Note that you cannot interrupt a listing with Esc.

Examples

      .  This example illustrates the TYPE command:

      TYPE Main.prg TO PRINTER

Seealso

COPY FILE, SET DEFAULT, SET PATH, SET PRINTER

TOTAL

TOTAL

Summarize records by key value to a database (.dbf) file

Syntax

      TOTAL ON <expKey> [FIELDS <idField list>]
            TO <xcDatabase>
            [<scope>] [WHILE <lCondition>] [FOR <lCondition>]

Arguments

ON <expKey> defines the group of records that produce a new record in the target database file. To make the summarizing operation accurate, the source database file should be INDEXed or SORTed on this expression.

FIELDS <idField list> specifies the list of numeric fields to TOTAL. If the FIELDS clause is not specified, no numeric fields are totaled. Instead each numeric field in the target file contains the value for the first record matching the key expression.

TO <xcDatabase> is the name of the target file that will contain the copy of the summarized records. Specify this argument as a literal file name or as a character expression enclosed in parentheses. Unless otherwise specified, TOTAL assumes a .dbf extension.

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

Description

TOTAL is a database command that sequentially processes the current database file, summarizing records by the specified key value and copying them to a new database file. TOTAL works by first copying the structure of the current database file to <xcDatabase>, except for memo fields. It then sequentially scans the current database file within the specified scope of records. As each record with a unique <expKey> value is encountered, that record is copied to the new database file. The values of numeric fields specified in <idField list> from successive records with the same <expKey> value are added to fields with the same names in <xcDatabase>. Summarization proceeds until a record with a new key value is encountered. The process is then repeated for this record.

Since TOTAL processes the source database file sequentially, it must be INDEXed or SORTed in <expKey> order for the summarization to be correct.

To successfully TOTAL numeric fields, the source numeric fields must be large enough to hold the largest total possible for that numeric field. If not, a runtime error is generated.

Notes

. Deleted source records: If DELETED is OFF, deleted records in the source file are TOTALed. Records in the target <xcDatabase> inherit the deleted status of the first matching record in the source file, just as nontotaled fields inherit their values. If DELETED is ON, however, none of the deleted source records are TOTALed.

Examples

      .  In this example, a database file is TOTALed ON the key
         expression of the controlling index using a macro expression.  When
         the macro expression is encountered, the expression is evaluated and
         the resulting character string is substituted for the TOTAL <expKey>
         argument:

      USE Sales INDEX Branch NEW
      TOTAL ON &(INDEXKEY(0)) FIELDS Amount TO Summary

Seealso

AVERAGE, INDEX, SORT SUM

TEXT

TEXT*

Display a literal block of text

Syntax

      TEXT [TO PRINTER] [TO FILE <xcFile>]
            <text>...
         ENDTEXT

Arguments

<text> is the block of literal characters to be displayed to the screen. Text is displayed exactly as formatted.

TO PRINTER echoes the display to the printer.

TO FILE <xcFile> echoes the display to the specified file. <xcFile> may be specified as a literal file name or as a character expression enclosed in parentheses. If no extension is specified, .txt is assumed.

Description

TEXT…ENDTEXT is a console command construct that displays a block of text to the screen, optionally echoing output to the printer and/or a text file. To suppress output to the screen while printing or echoing output to a file, SET CONSOLE OFF before the TEXT command line.

Text within the TEXT construct displays exactly as formatted, including any indentation. Hard carriage returns are output as new lines, soft carriage returns as the character CHR(141). Macro variables found within TEXT…ENDTEXT are expanded. However, macro expressions are not.

TEXT…ENDTEXT is a compatibility command and not recommended. Clipper has other facilities for text processing and output. For example, MEMOLINE() in combination with MLCOUNT() can word wrap long strings according to a specified line length. ? or @…SAY can display formatted text extracted from a long string with MEMOLINE().

Examples

      .  This example demonstrates how to use TEXT...ENDTEXT to print a
         form letter:

      USE Sales NEW
      DO WHILE !EOF()
         FormLetter()
         SKIP
      ENDDO
      RETURN

      FUNCTION FormLetter
         LOCAL dDate := DTOC(DATE()), cSalesman := ;
                  RTRIM(Salesman)
         TEXT TO PRINTER
         &dDate.
         Dear &cSalesman.,
         How are you!
         ENDTEXT
         EJECT
         RETURN NIL

Seealso

?|??, @…SAY, MEMOLINE(), MLCOUNT(), SET CONSOLE