xHarbour Reference Documentation > Command Reference

TOTAL

Creates a new database summarizing numeric fields by an expression.

Syntax

   TOTAL ON <expression> ;
    [FIELDS <fieldName,...>] ;
         TO <xcDatabase> ;
           [<Scope>] ;
     [WHILE <lWhileCondition>] ;
       [FOR <lForCondition>]
  [CODEPAGE <cCodePage> ]  ;
[CONNECTION <nConnection>] ]

Arguments

ON <expression>

This is an expression whose value identifies groups of records to summarize. Each time the value of <expression> changes, a new record is added to the target database and a new calculation begins. Records in the current work area should be indexed or sorted by <expression>.

FIELDS <fieldNames,...>

The names of the numeric fields to summarize can be specified as a comma separated list of literal field names or character expressions enclosed in parentheses. When this option is omitted, no calculation is performed. Instead, only the records that match <expression> first are added to the target database.

TO <cDatabase>

This is name of the database file to create. It can include path and file extension. When no path is given, the file is created in the current directory. The default file extension is DBF. <cDatabase> can be specified as a literal file name or as a character expression enclosed in parentheses.

<Scope>

This option defines the number of records to process. It defaults to ALL. The NEXT <nCount> processes the next <nCount> records, while the REST scope totals records beginning with the current record down to the end of file.

WHILE <lWhileCondition>

This is a logical expression indicating to continue calculation while the condition is true. The TOTAL operation stops as soon as <lWhileCondition> yields .F. (false).

FOR <lForCondition>

This is a logical expression which is evaluated for all records in the current work area. Those records where <lForCondition> yields .T. (true) are included in the calculation.

CODEPAGE <cCodePage>

This is a character string specifying the code page to use for character strings stored in the new database. It defaults to the return value of HB_SetCodePage().

CONNECTION <nConnection>

This option specifies a numeric server connection handle. It is returned by a server connection function which establishes a connection to a database server, such as SR_AddConnection() of the xHarbour Builder SQLRDD. When CONNECTION is used, the TOTAL command creates a database on the server.

Description

The TOTAL command is used to calculate numeric totals for groups of records. A record group is identified by the value of <expression>. Each time this value changes, a new record is added to the target database and the values of numeric fields listed in <fieldName,...> are summarized until <expression> changes again. As a consequence, the records in the current work area must be indexed or sorted by <expression> for a correct calculation.

The target database has the same structure as the source database. This requires the field length of numeric fields be large enough to hold total values. If the result is too large, a runtime error is generated.

Records marked for deletion are not included in the calculation when SET DELETED is set to ON.

Info

See also:	AVERAGE, INDEX, SORT, SUM
Category:	Database commands
Source:	rdd\dbcmd.c
LIB:	xhb.lib
DLL:	xhbdll.dll

Example

// The example calculates total sales from an invoice database
// by part number

   PROCEDURE Main
      USE Invoice
      INDEX ON PartNo TO Temp

      TOTAL ON PartNo TO TotalSales

      USE TotalSales
      Browse()

      CLOSE ALL
   RETURN