Daily Archives: February 17, 2014

WAIT

Posted on by vivaclipper

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

Posted on by vivaclipper

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

Posted on by vivaclipper

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

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

TYPE

Posted on by vivaclipper

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

Posted on by vivaclipper

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

Posted on by vivaclipper

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

SUM

Posted on by vivaclipper

SUM

Sum numeric expressions and assign results to variables

Syntax

      SUM <nExp list> TO <idVar list>
            [<scope>] [WHILE <lCondition>] [FOR <lCondition>]

Arguments

<nExp list> is the list of numeric values to sum for each record processed.

TO <idVar list> identifies the receiving variables to be assigned assign the results of the sum. Variables that either do not exist or are not visible are created as private variables. <idVar list> must contain the same number of elements as <nExp list>.

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

Description

SUM is a database command that totals a series of numeric expressions for a range of records in the current work area and assigns the results to a series of variables. The variables specified in <idVar list> can be field, local, private, public, or static.

Note that the <nExp list> is required and not optional as it is in other dialects.

Examples

      .  This example illustrates the use of SUM:

      LOCAL nTotalPrice, nTotalAmount
      USE Sales NEW
      SUM Price * .10, Amount TO nTotalPrice, nTotalAmount
      //
      ? nTotalPrice               // Result: 151515.00
      ? nTotalAmount              // Result: 150675.00

Seealso

AVERAGE, DBEVAL(), TOTAL

STORE

Posted on by vivaclipper

STORE*

Assign a value to one or more variables

Syntax

      STORE <exp> TO <idVar list>
         <idVar> = <exp>
         <idVar> := [ <idVar2> := ...] <exp>

Arguments

<exp> is a value of any data type that is assigned to the specified variables.

TO <idVar list> defines a list of one or more local, static, public, private, or field variables that are assigned the value <exp>. If any <idVar> is not visible or does not exist, a private variable is created and assigned <exp>.

Description

STORE assigns a value to one or more variables of any storage class. The storage classes of Clipper variables are local, static, field, private, and public. STORE is identical to the simple assignment operators (=) and (:=). In fact, a STORE statement is preprocessed into an assignment statement using the inline operator (:=). Like all of the assignment operators, STORE assigns to the most recently declared and visible variable referenced by <idVar>. If, however, the variable reference is ambiguous (i.e., not declared at compile time or not explicitly qualified with an alias), it is assumed to be MEMVAR. At runtime, if no private or public variable exists with the specified name, a private variable is created.

To override a declaration, you can specify the <idVar> prefaced by an alias. If <idVar> is a field variable, use the name of the work area. For private and public variables, you can use the memory variable alias (MEMVAR->). To assign to a field variable in the currently selected work area (as opposed to a particular named work area), you can use the field alias (FIELD->).

As a matter of principle, all variables other than field variables should be declared. Preface field variables with the alias. Use of private and public variables is discouraged since they violate basic principles of modular programming and are much slower than local and static variables.

Note that the STORE command is a compatibility command and not recommended for any assignment operation. Clipper provides assignment operators that supersede the STORE command, including the inline assignment operator (:=), the increment and decrement operators (++) and (–), and the compound assignment operators (+=, -=, *=, /=). Refer to the Operators and Variables sections of the “Basic Concepts” chapter in the Programming and Utilities Guide for more information.

Notes

. Assigning a value to an entire array: In Clipper, neither the STORE command nor the assignment operators can assign a single value to an entire array. Use the AFILL() function for this purpose.

. Memo fields: Assigning a memo field to a variable assigns a character value to that variable.

Examples

      .  These statements create and assign values to undeclared
         private variables:

      STORE "string" TO cVar1, cVar2, cVar3
      cVar1:= "string2"
      cVar2:= MEMVAR->cVar1

      .  These statements assign multiple variables using both STORE
         and the inline assignment operator (:=).  The methods produce
         identical code:

      STORE "value" to cVar1, cVar2, cVar3
      cVar1 := cVar2 := cVar3 := "value"

      .  These statements assign values to the same field referenced
         explicitly with an alias.  The first assignment uses the field alias
         (FIELD->), where the second uses the actual alias name:

      USE Sales NEW
      FIELD->CustBal = 1200.98
      Sales->CustBal = 1200.98

Seealso

AFILL(), LOCAL, PRIVATE, PUBLIC, RELEASE, REPLACE

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