880-FILTER-DBAGOF-<Index>

Name

880-FILTER-DBAGOF-<Index>

Description

The 880-FILTER-DBAGOF-<Index> API is similar to the 880-CALC-DBAGOF-<Index> API, with the difference that it provides for the use of a filter. As with 880-CALC-DBAGOF-<Index>, if the aggregate result is too large for the field it would be stored in, a flag is set indicating an overflow occurred. You can then add code to control what the program does in the event of an overflow.

Using the API in a Program

Using the 880-FILTER-DBAGOF-<Index> API is similar to using the 880-CALC-DBAG-<Index> API. The difference is the use of a filter and that a flag is set in the WS-DB-AGG-OVERFLOW field to indicate whether or not an overflow occurred. For more information on setting up the aggregate function, see 880-INIT-DBAG-<Index> and 880-CALC-DBAG-<Index>. For information on setting up the filter, see How Do the Filter Routines Work? and Setting the Filter Parameter Value.

Input Values

Field Description

<Index>

You must specify the index in the statement.
Record retrieval variables (also known as DB fields) Define the beginning and ending values of the last key by moving the appropriate values to the record retrieval fields named DB- <KeyFieldName> and DBRNG- <KeyFieldName>.
WS-DB-SUB-RNG

Identify the range key by moving the symbolic constant <IndexName>-<IndexFieldName> to WS-DB-SUB-RNG

  • DBAVG-<Index>-<FieldName>

    Average

  • DBMAX-<Index>-<FieldName>

    Maximum

  • DBMIN-<Index>-<FieldName>

    Minimum

  • DBSUM-<Index>-<FieldName>

    Sum

Use a set of Boolean fields to identify the columns in the table to be returned and the aggregate function to be applied. These fields are named using the following convention:

<Index> corresponds to and must match the Index that is specified in the 880-INIT-DBAG-<Index> and 880-FILTER-DBAGOF-<Index> API calls.

<FieldName> identifies the column to be aggregated

You can request more than one column in a single API call by using the appropriate Boolean field several times with a different field name each time, and you may specify more than one function for each call.

Return Values

Unlike all other database APIs, the values returned by 880-FILTER-DBAGOF-<Index> are not part of the regular file record area. In fact, nothing related to the aggregate range routines alters the contents of the file record area in any way. The return values for the aggregate functions are dimensioned to the maximum allowable field size of 18 digits. The number of decimal positions is inherited from the database field. The naming convention for these return value fields is shown in the following table.

Field Description

DBAG-<Function>-<Index>-<FieldName>

You must code the SET prior to the call. See the following usage example, where <FUNCTION> is AVG, MAX, MIN, or SUM.

SET DB<FUNCTION>-<Index>-<FIELD> TO TRUE

WS-DB-AGG-OVERFLOW The field containing the flag to indicate whether or not an overflow occurred ("1" indicates an overflow, "0" indicates no overflow). You must add code to determine what the program does in the event of an overflow.