Computes totals for numeric fields in the currently selected table.
TOTAL TO TableName ON FieldName [FIELDS FieldNameList] [Scope] [FOR lExpression1] [WHILE lExpression2] [NOOPTIMIZE]
- Specifies the name of the table that will contain the totals. If the specified table doesn't exist, Visual FoxPro creates it. If the table exists and SET SAFETY is ON, Visual FoxPro asks if you would like to overwrite the existing table. If SET SAFETY is OFF, you aren't prompted, and the output table is overwritten.
- Specifies the field on which the totals are grouped. The table must be sorted on this field, or an open index or index tag must have this field as its key expression.
- FIELDS FieldNameList
- Specifies the fields to be totaled. Separate the field names in the list with commas. If you omit the FIELDS clause, all numeric fields are totaled by default.
- Specifies a range of records to total. The scope clauses are: ALL, NEXT nRecords, RECORD nRecordNumber, and REST. For more information on scope clauses, see the Scope Clauses or Overview of the Language online topics.
The default scope for TOTAL is ALL records.
- FOR lExpression1
- Specifies a condition whereby only the records that satisfy the logical condition lExpression1 are included in the totals.
Rushmore optimizes a query created with TOTAL ... FOR if lExpression1 is an optimizable expression. For best performance, use an optimizable expression in the FOR clause.
- WHILE lExpression2
- Specifies a condition whereby records from the current table are included in the totals for as long as the logical expression lExpression2 evaluates to true (.T.).
- Disables Rushmore optimization of TOTAL.
The table in the currently selected work area must be sorted or indexed. A separate total is calculated for each set of records with a common field value or unique index key value. The results are placed into records in a second table. One record is created in the second table for each common field value or unique index key value.
Numeric overflow can occur if the numeric fields in the second table aren't wide enough to contain the totals. Visual FoxPro conserves the most significant portions of the totals when numeric overflow occurs. When a field is too small to accept a total:
- Decimal places are truncated, and the remaining decimal portion of the total is rounded.
- If the total still doesn't fit, scientific notation is used if the total field contains seven or more digits.
- Finally, asterisks replace the field contents.