On STATEMENT

PURPOSE: The ON statement specifies the master; DS fields whose values control execution of a block of statements within the TOTALS section or the SUBHEADINGS section of a PM. Whenever there is a change of value in any field specified by the ON statement, ACCENT R executes the ON block for that field plus all preceding ON blocks in the TOTALS section, then the ON block for that field plus all following ON blocks in the SUBHEADINGS section. Control breaks are determined by successive qualified master records.

SYNTAX

ON {\ [-] fields\; @EOF} […NEXT ON \\[-]fields\\] [USE VALUES IF; UNLESS clause]

[-] field	is one or more field names from the master DS. Fields that have multiple occurrences must be subscripted with an integer. To indicate that the records are arranged by descending value in a field, precede that field name with a minus sign (-). Otherwise, the ON statement assumes the records are arranged by ascending values in the field. The identifier :M cannot be used on the field name in the ON statement since only field form the master data set can be used here.
@EOF	specifies that the following blocks of statements are to be executed at the end-of-file. @EOF is a system field that changes from NO to YES when ACCENT R reaches the end of the master DS. Records used in calculating final totals can be specified by including @EOF with the USE VALUES clause. @EOF should be used only in the TOTALS section.
NEXT ON	specifies additional fields that control TOTALS or SUBHEADINGS. Each NEXT clause is equivalent to an identical ON sub-section, but it eliminates duplication of statements following the ON (see example).
USE VALUES	can be used only in the TOTALS section of a PM. It qualifies which records are to be used in the inter-record function (SUM, MIN, MAX, AVG, or STD_DEV). If USE VALUES is not specified, each qualified master record causes the functions to be incremented.

Example

When identical output is desired for subheadings or subtotals of various fields, combine the requests in a single ON statement.

ON ORD_NUM
   PRINT SUM AMT

ON STORE_CODE
   PRINT SUM AMT
   ON TITLE_CODE

PRINT SUM AMT

The preceding statements can be shortened to:

00080  ON ORD_NUM NEXT ON STORE_CODE NEXT ON TITLE_CODE
00090    PRINT SUM AMT

The following PM shows the relationship of ON statements in the SUBHEADINGS and TOTALS sections. The DS has been sorted on REGION, CITY, DISTRICT before the PM is executed. No detail is specified so that the pattern of subheading lines and total lines is obvious.

The first record causes execution of all levels of the SUBHEADINGS section. The last record causes execution of all levels of the TOTALS section. Within the Data Set, when the value in REGION changes, the ON district, ON city then ON region is executed, then in the SUBHEADINGS section the on region, on city and ON district are executed. When the value in CITY changes, in the TOTALS section the ON district and ON city are executed, then in the SUBHEADINGS section the ON city and ON district are executed. When the value in DISTRICT changes, in the TOTALS section only the ON DISTRICT is executed then the ON DISTRICT in the SUBHEADINGS section are executed.

*LIST PM BOOK_SALES

CONTROL SECTION
   RELATE DS BSALES AS MASTER
   RELATE TERMINAL AS REPORT 1

HEADINGS SECTION
   SKIP 1
   CENTER "EXAMPLE OF ON STATEMENTS" AT 35
   CENTER "IN SUBHEADINGS AND TOTALS SECTIONS" AT 35
   SKIP 1
   PRINT 36B,"SALES PER", 2B, "SALES PER", 2B, "SALES PER"
   PRINT 36B,"DISTRICT", 5B, "CITY", 6B, "REGION"

SUBHEADINGS SECTION
   ON REGION
      PRINT "REGION: ",REGION
   ON CITY
      PRINT 5B, "CITY:", CITY
   ON DISTRICT
      PRINT 10B, "DISTRICT:", DISTRICT

DETAILS SECTION
   PRINT"", NOCR

TOTALS SECTION
   ON DISTRICT
      PRINT 10B,"TOTAL FOR DISTRICT:",DISTRICT,TAB 37,& SUM SALES
   ON CITY
      PRINT 5B,"TOTAL FOR CITY:",CITY, TAB 48,SUM SALES
   ON REGION
      PRINT "TOTAL FOR REGION:",REGION, TAB 59,&SUM SALES,@CR

FINAL SECTION
   PRINT "GRAND TOTAL ", TAB 59, SUM SALES

*USE DS BSALES

*REPORT VIA BOOK_SALES

EXAMPLE OF ON STATEMENTS IN SUBHEADINGS AND TOTALS SECTIONS
	SALES PER DISTRICT	SALES PER CITY	SALES PER\ REGION
REGION: EASTERN
CITY: ATLANTA
DISTRICT: 321
TOTAL FOR DISTRICT:321	15000
TOTAL FOR CITY: ATLANTA		15000
CITY: CHICAGO
DISTRICT: 201	11000
TOTAL FOR DISTRICT:201
DISTRICT: 271
TOTAL FOR DISTRICT:271	11000
TOTAL FOR CITY: CHICAGO		22000
CITY: NEW YORK
DISTRICT: 217
TOTAL FOR DISTRICT:217	5000
DISTRICT: 280
TOTAL FOR DISTRICT:280	15000
DISTRICT: 283
TOTAL FOR DISTRICT: 283	6000
TOTAL FOR CITY: NEW YORK		26000
TOTAL FOR REGION: EASTERN			63000

REGION: WESTERN
CITY: LOS ANGELES
DISTRICT: 551
TOTAL FOR DISTRICT:551	9000
DISTRICT: 574
TOTAL FOR DISTRICT:547	15000
TOTAL FOR CITY: LOS ANGELES		24000
CITY: SAN FRANCISCO
DISTRICT: 517
TOTAL FOR DISTRICT:517	18000
DISTRICT: 525
TOTAL FOR DISTRICT:525	15000
TOTAL FOR CITY: SAN FRANCISCO		33000
TOTAL FOR REGION: WESTERN			57000
GRAND TOTAL			120000

NOTES: The ON statement can be used in PM’s that do not create reports. In a reporting PM, each ON statement is generally followed with a PRINT statement that indicates which values are to be printed.

Several ON statements can occur together. Each is followed by statements to be executed when the values of the fields given change. Whenever there is a value change in a field that is specified by an ON statement, ACCENT R executes all preceding ON blocks in the TOTALS section, then all following ON blocks in the SUBHEADINGS section.

A clause applies only to the ON statement in which it occurs. If the ON statement is in a hierarchy of ON statements, a USE VALUES clause in one statement has no effect on the other ON statements.

Before executing a PM that contains ON statements, the records in the current DS must be sorted or indexed according to the field list given in the ON statement. If a minus sign (-) precedes a field name in the ON statement, it must also be specified in the SORT command or in the Data Index (DI).

The ON statements in the SUBHEADINGS section and the TOTALS section are complementary to one another. The ON statements in the SUBHEADINGS section should be in reverse order from those in the TOTALS section. Furthermore, the order of ON statements in the TOTALS section is usually the reverse of the current sort or the domain sequence.