A desirable characteristic of software is flexibility. A program or system shouldn't unnecessarily lock the user into one way of doing things. I'm going to show you one method of adding flexibility to programs that use control breaks. You can use this technique to let users choose break fields and sort sequences at run time.

To illustrate, I'll walk you through the development of an application. (Although the application is custom, it can be used as a starting point and modified for your reports.) Let's say we work for a company that has stores scattered throughout the state. The top managers want to be able to examine in different ways the returns of previously sold goods. For instance, sometimes they may want to concentrate on what stores are getting the most returns. At other times, they may concern themselves more with the reason customers return the goods they've bought.

We could write one program and clone it every time the boss asks for a variation, but before long we'd have more clones than we could keep up with. What we need is one program that will group the data various ways.

Defining the Plan

Let's start by identifying the results we're trying to achieve. The user can select up to four control fields for subtotals and up to four additional sort fields for returns reports. To accomplish this, we define a command which we call List Returned Goods (LSTRTNGDS). 1 contains the command source. The two parameters are a list of the control fields and a list of additional sort fields-both in major to minor order. (The additional sort fields are subsidiary to the control fields.) The report sorts by the control break fields (BRKFLD) and additional sort fields (SRTFLD), but produces subtotals on the control break fields only.

Let's start by identifying the results we're trying to achieve. The user can select up to four control fields for subtotals and up to four additional sort fields for returns reports. To accomplish this, we define a command which we call List Returned Goods (LSTRTNGDS). Figure 1 contains the command source. The two parameters are a list of the control fields and a list of additional sort fields-both in major to minor order. (The additional sort fields are subsidiary to the control fields.) The report sorts by the control break fields (BRKFLD) and additional sort fields (SRTFLD), but produces subtotals on the control break fields only.

This command is designed to be flexible. For instance, if we type

 LSTRTNGDS BRKFLD(DATE) + SRTFLD(ITEM) 

we get a report sorted by the return date and item number, with subtotals by date, as in 2. But if we type

we get a report sorted by the return date and item number, with subtotals by date, as in Figure 2. But if we type

 LSTRTNGDS BRKFLD(REASON ITEM) + SRTFLD(STORE) 

we get a report sorted by reason code, item number, and store, with subtotals at the end of each reason code and item number (see 3).

we get a report sorted by reason code, item number, and store, with subtotals at the end of each reason code and item number (see Figure 3).

That's the concept of what we're trying to accomplish. Now let's make it happen.

Setting It Up

Sales transactions are stored in a physical file named SALES. If the quantity sold field is positive, the record indicates sales, but if the quantity sold is negative, the record indicates returned goods. A logical file, RETURNS, selects only the records with a negative quantity sold. The RETURNS file, then, contains the data we need to analyze.

We could write an RPG program that reads RETURNS and breaks on certain fields, but that would not be flexible. To get variable control breaks, we must define a dummy physical file, RTN001PF, which has all the fields in RETURNS, plus four control break fields. Then, we check these break fields for control breaks. For example, if we want a control break on reason, we do not check the REASN field for a control break. Instead, we copy the reason code into one of the break fields. We leave unneeded break fields blank, so they never cause a control break.

4 contains the DDS for RTN001PF. Since the fields are referenced to the RETURNS file, I added some text to tell you more about them. The break fields are 10 bytes long; depending on the data, they may need to be longer in other applications.

Figure 4 contains the DDS for RTN001PF. Since the fields are referenced to the RETURNS file, I added some text to tell you more about them. The break fields are 10 bytes long; depending on the data, they may need to be longer in other applications.

The RTN001PF file does not contain data. Rather, the Open Query File (OPNQRYF) command reformats the RETURNS data according to the file description of RTN001PF. The RTN001PF file does not even require a member.

The program to produce the report reads the RETURNS file in the format of RTN001PF and checks for control breaks on the four BREAK fields. We'll look at the report program in detail later.

Establishing Field Values

Let's discuss how the four break fields in RTN001PF get their values. The key to this technique lies in the MAPFLD parameter of OPNQRYF. MAPFLD allows you to force OPNQRYF to assign a value to a field. If we want the lowest level break to be on reason code, for example, we need a way to copy the reason code to field BREAK1. MAPFLD lets us do that.

Now look at RPG program RTN001RG in 5. It takes a list of symbolic field names-which are easier for the user to work with than the actual field names- and builds the OPNQRYF command. The MAPFLD expressions are in positions 11-35 of compile-time array FE. Character fields, like STORE#, are copied directly into the break fields, but numeric fields and date fields have to be translated to character values. The %DIGITS function-which copies the digits, omitting signs and decimal points, into a character value-converts the numeric fields. Dates can be copied into a character field with the %CHAR function.

Now look at RPG program RTN001RG in Figure 5. It takes a list of symbolic field names-which are easier for the user to work with than the actual field names- and builds the OPNQRYF command. The MAPFLD expressions are in positions 11-35 of compile-time array FE. Character fields, like STORE#, are copied directly into the break fields, but numeric fields and date fields have to be translated to character values. The %DIGITS function-which copies the digits, omitting signs and decimal points, into a character value-converts the numeric fields. Dates can be copied into a character field with the %CHAR function.

So if we type

 LSTRTNGDS BRKFLD(REASON ITEM + STORE DATE) 

at a command line, the MAPFLD parameter generated by RTN001RG looks like the one below.

 MAPFLD((BREAK4 '%DIGITS(REASN)') + (BREAK3 '%DIGITS(ITEM#)') + (BREAK2 'STORE#') + (BREAK1 '%CHAR(XACTDT "ISO")')) 

But what if we don't define four control breaks? If we type

LSTRTNGDS BRKFLD(ITEM)

RTN001RG uses the fifth element of FE to assign blanks to the other three break fields.

 MAPFLD((BREAK4 '" "') + (BREAK3 '" "') + (BREAK2 '" "') + (BREAK1 '%DIGITS(ITEM#)')) 

Since BREAK4, BREAK3, and BREAK2 are blank, no control break occurs on those fields. (A break field is also set to blanks if an invalid symbolic field name is passed to the program.)

Sort Fields

RTN001RG builds a KEYFLD parameter to order the data. This program makes the mapped fields the primary sort keys, then adds any fields specified in the SRTFLD parameter of command LSTRTNGDS. For example,

 LSTRTNGDS BRKFLD(REASON ITEM) + SRTFLD(STORE) 

generates this KEYFLD parameter.

KEYFLD(REASN ITEM# STORE#)

The complete OPNQRYF command generated when we type

LSTRTNGDS BRKFLD(STORE ITEM) +

SRTFLD(REASON)

would be

 OPNQRYF FILE((RETURNS)) + FORMAT(RTN001PF) + KEYFLD(STORE# ITEM# REASN) + MAPFLD((BREAK4 '" "') + (BREAK3 '" "') + (BREAK2 'STORE#') + (BREAK1 '%DIGITS(ITEM#)')) 

RTN001RG has one other task. It places the descriptions of the break fields into an array, so that they can be printed in the total lines of the report. This is the meat of the variable control fields technique. The rest is pretty straightforward.

Using the Commands

6 contains the source code for CL program RTN001CL, the command processing program for command LSTRTNGDS. To summarize, the program

Figure 6 contains the source code for CL program RTN001CL, the command processing program for command LSTRTNGDS. To summarize, the program

 1. Calls RTN001RG to build the OPNQRYF command. 2. Executes the OPNQRYF command. 3. Calls RTN002RG to print the report. 

Seeing the Results

Figures 7 and 8 show the source code for the RPG print program, RTN002RG, and its associated printer file, RTN001P1. RTN002RG reads file RTN001PF. The override in the CL program makes it read the RETURNS file, reformatted to look like RTN001PF, instead.

We are implementing the levels in arrays of five elements. Element 1 is the lowest level break (L1), and element 4 is the highest level break (L4). The fifth element is for grand totals. There are accumulators for quantity returned (QT) and extended amount (XA). Array BV contains the values of the break fields, and BD has the descriptions of the break fields. A blank element of BD means that no break is defined at that level, so no subtotal prints. Subtotals accumulate into the next higher level, even if they're not printed.

All break handling in RTN002RG is handled by subroutine ENDGRP, which prints the totals for the level, accumulates into the next level, and resets the accumulators for the new control group.

Printer file RTN001P1 refers to the RETURNS file. This allows us to use established definitions, ensuring that all fields in the program and printer file agree. However, date field XACTDT must be redefined in the printer file because XACTDT is defined as a date data type (L) in the RETURNS file. The V2R3 RPG compiler doesn't support the date data type; it imports a date data type field as a 10-character field. Therefore, we must redefine the date field in the printer file DDS (see 8) instead of simply referencing it. (As of V3R1, this redefinition is not required.)

Printer file RTN001P1 refers to the RETURNS file. This allows us to use established definitions, ensuring that all fields in the program and printer file agree. However, date field XACTDT must be redefined in the printer file because XACTDT is defined as a date data type (L) in the RETURNS file. The V2R3 RPG compiler doesn't support the date data type; it imports a date data type field as a 10-character field. Therefore, we must redefine the date field in the printer file DDS (see Figure 8) instead of simply referencing it. (As of V3R1, this redefinition is not required.)

We could make one enhancement to this application. If we wanted to be able to sort on the extended amount field, we could do the calculation in the MAPFLD, rather than in the RPG program. We could have added XAMT to file RTN001PF, and added the expression below to the MAPFLD parameter of the OPNQRYF command built by RTN001RG.

(XAMT 'QTY * PRICE')

Flexible Is Better!

I have had success with this type of program, and I hope you'll give this technique a try. It's good to write programs that help people do their jobs, but it's even better to give them flexible programs that they can adapt as they rethink what it takes for them to get their jobs done.

Ted Holt can be reached through Midrange Computing.

Variable Control Breaks

Figure 1 LSTRTNGDS Source Code

 CMD PROMPT('Print returned goods report') PARM KWD(BRKFLD) TYPE(*CHAR) LEN(10) RSTD(*YES) + VALUES(REASON STORE ITEM DATE) MAX(4) + PROMPT('Break fields') PARM KWD(SRTFLD) TYPE(*CHAR) LEN(10) RSTD(*YES) + VALUES(REASON STORE ITEM DATE) MAX(4) + PROMPT('Additional sort fields') 
 
 Variable Control Breaks
 
 Figure 2 LSTRTNGDS BRKFLD(DATE) SRTFLD(ITEM) Report
 
 12/04/94 Returned Goods Page 1 Reason Item Store Seq Date Qty Price Total 1 103 VIC 78315 1994-12-01 1 9.50 9.50 2 109 BAT 78319 1994-12-01 500 1.50 750.00 2 109 NAT 78314 1994-12-01 75 1.25 93.75 3 109 NAT 78311 1994-12-01 250 1.50 375.00 Date 1994-12-01 826 1228.25 1 101 BAT 78333 1994-12-02 4 10.00 40.00 1 101 BAT 78338 1994-12-02 2 10.00 20.00 1 101 VIC 78363 1994-12-02 1 10.50 10.50 1 103 BAT 78327 1994-12-02 50 .80 40.00 2 109 OXF 78348 1994-12-02 250 1.25 312.50 2 114 NAT 78321 1994-12-02 100 .25 25.00 Date 1994-12-02 407 448.00 2 109 OXF 78388 1994-12-03 300 1.50 450.00 2 114 NAT 78392 1994-12-03 50 .25 12.50 Date 1994-12-03 350 462.50 Grand totals 1583 2138.75 
 
 Variable Control Breaks
 
 Figure 3 LSTRTNGDS BRKFLD(REASON ITEM) SRTFLD(STORE) Report
 
 12/04/94 Returned Goods Page 1 Reason Item Store Seq Date Qty Price Total 1 101 BAT 78333 1994-12-02 4 10.00 40.00 1 101 BAT 78338 1994-12-02 2 10.00 20.00 1 101 VIC 78363 1994-12-02 1 10.50 10.50 Item 101 7 70.50 1 103 BAT 78327 1994-12-02 50 .80 40.00 1 103 VIC 78315 1994-12-01 1 9.50 9.50 Item 103 51 49.50 Reason 001 58 120.00 2 109 BAT 78319 1994-12-01 500 1.50 750.00 2 109 NAT 78314 1994-12-01 75 1.25 93.75 2 109 OXF 78348 1994-12-02 250 1.25 312.50 2 109 OXF 78388 1994-12-03 300 1.50 450.00 Item 109 1125 1606.25 2 114 NAT 78321 1994-12-02 100 .25 25.00 2 114 NAT 78392 1994-12-03 50 .25 12.50 Item 114 150 37.50 Reason 002 1275 1643.75 3 109 NAT 78311 1994-12-01 250 1.50 375.00 Item 109 250 375.00 Reason 003 250 375.00 Grand totals 1583 2138.75 
 
 Variable Control Breaks
 
 Figure 4 DDS for RTN001PF
 
 *. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 A REF(RETURNS) A R RTNWR A XACT# R A XACTDT R A ITEM# R A STORE# R A QTY R A PRICE R A REASN R A BREAK1 10 A BREAK2 R REFFLD(BREAK1 *SRC) A BREAK3 R REFFLD(BREAK1 *SRC) A BREAK4 R REFFLD(BREAK1 *SRC) A K BREAK4 A K BREAK3 A K BREAK2 A K BREAK1 * * XACT# - transaction serial number numeric * XACTDT - transaction date date (ISO format) * ITEM# - item returned numeric * STORE# - item returned to store character * QTY - quantity returned numeric * PRICE - unit price numeric * REASN - return reason code numeric * *. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 
 
 Variable Control Breaks
 
 Figure 5 RPG Program RTN001RG, to Build OPNQRYF Command
 
 *. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 * BUILD OPNQRYF E FN 1 5 10 FE 45 E BRKD 4 10 BREAK DESCR E BRKF 4 10 BREAK FIELD E SRTF 4 10 SORT FIELDS IP@BRKD DS 40 I 1 40 BRKD IP@BRKF DS 42 I B 1 20BCT I 3 42 BRKF IP@SRTF DS 42 I B 1 20SCT I 3 42 SRTF I 'OPNQRYF FILE((RETURN-C CMD I 'S)) FORMAT(RTN001PF)' C *ENTRY PLIST C PARM P@BRKF 42 C PARM P@SRTF 42 C PARM P@BRKD 40 C PARM P@OQFC256 * C EXSR INIT C EXSR PRCBRK C EXSR PRCSRT C EXSR BLDCMD * C MOVE *ON *INLR *********** * PRCBRK - Process break fields *********** C PRCBRK BEGSR * C 1 DO 4 L 30 C CAT '(':1 MAPFLD C CAT 'BREAK':0 MAPFLD C 5 SUB L M 10 C MOVE M MX 1 C CAT MX:0 MAPFLD C L IFLE BCT C MOVELBRKF,L SYMNAM 10 C ELSE C MOVE *BLANKS SYMNAM C ENDIF C EXSR RTVFI C CAT MAPEXP:1 MAPFLD C CAT ')':0 MAPFLD C CAT KEYEXP:1 KEYFLD C MOVELMAPDSC BRKD,M C ENDDO * C ENDSR *********** * PRCSRT - Process additional sort fields *********** C PRCSRT BEGSR * C 1 DO SCT S 30 C MOVELSRTF,S SYMNAM C EXSR RTVFI C CAT KEYEXP:1 KEYFLD C ENDDO ....+... 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ....+... 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 * C ENDSR ********* * RTVFI - Retrieve field information ********* C RTVFI BEGSR * C Z-ADD1 F 10 C SYMNAM LOKUPFN,F 91(EQ) C *IN91 IFEQ *OFF C Z-ADD5 F C ENDIF * C SUBSTFE,F:1 KEYEXP 10 C SUBSTFE,F:11 MAPEXP 25 C SUBSTFE,F:36 MAPDSC 10 * C ENDSR *********** * BLDCMD - Build OPNQRYF command *********** C BLDCMD BEGSR * C MOVELCMD P@OQFC C KEYFLD IFNE *BLANKS C CAT 'KEYFLD':1P@OQFC C CAT '(':0 P@OQFC C CAT KEYFLD:0 P@OQFC C CAT ')':0 P@OQFC C ENDIF C CAT 'MAPFLD':1P@OQFC C CAT '(':0 P@OQFC C CAT MAPFLD:0 P@OQFC C CAT ')':0 P@OQFC * C ENDSR *********** * INIT - Initialize variables *********** C INIT BEGSR * C MOVELCMD P@OQFC P C MOVE *BLANKS P@BRKD C MOVE *BLANKS KEYFLD128 C MOVE *BLANKS MAPFLD256 * C ENDSR ** ....+....1....+....2....+....3....+....4....+ REASON REASN '%DIGITS(REASN)' Reason [1] STORE STORE# 'STORE#' Store [2] ITEM ITEM# '%DIGITS(ITEM#)' Item [3] DATE XACTDT '%CHAR(XACTDT "ISO")' Date [4] '" "' [5] 
 
 Variable Control Breaks
 
 Figure 6 CL Program RTN001CL
 
 PGM PARM(&BRKFLDS &SRTFLDS) DCL VAR(&BRKDESC) TYPE(*CHAR) LEN(50) DCL VAR(&BRKFLDS) TYPE(*CHAR) LEN(42) DCL VAR(&OQFCMD) TYPE(*CHAR) LEN(256) DCL VAR(&SRTFLDS) TYPE(*CHAR) LEN(42) CALL PGM(RTN001RG) PARM(&BRKFLDS &SRTFLDS + &BRKDESC &OQFCMD) OVRDBF FILE(RTN001PF) TOFILE(RETURNS) SHARE(*YES) CALL PGM(QCMDEXC) PARM(&OQFCMD 256) CALL PGM(RTN002RG) PARM(&BRKDESC) CLOF OPNID(RETURNS) DLTOVR FILE(RTN001PF) ENDPGM 
 
 Variable Control Breaks
 
 Figure 7 RPG Program RTN002RG, to Print the Report
 
 *. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 FRTN001PFIP E K DISK FRTN001P1O E 88 PRINTER E BD 5 10 Break descr E BV 5 10 Break value E QT 5 5 0 QTY accumul E XA 5 9 2 XAMT accumu IRTN001RF I BREAK4 BV,4 L4 I BREAK3 BV,3 L3 I BREAK2 BV,2 L2 I BREAK1 BV,1 L1 C *ENTRY PLIST C PARM BD * C QTY MULT PRICE XAMT C ADD QTY QT,1 C ADD XAMT XA,1 * C *IN88 IFEQ *ON C WRITEPAGEHDR C MOVE *OFF *IN88 C ENDIF * C WRITEDTLLINE * CL1 Z-ADD1 V 30 CL1 EXSR ENDGRP * CL2 Z-ADD2 V CL2 EXSR ENDGRP * CL3 Z-ADD3 V CL3 EXSR ENDGRP * CL4 Z-ADD4 V CL4 EXSR ENDGRP * CLR Z-ADD5 V CLR MOVE 'N' ACCUM CLR MOVEL'Grand' BD,5 P CLR MOVEL'totals' BV,5 P CLR EXSR ENDGRP *********** C ENDGRP BEGSR End contr * Print totals for this level C BD,V IFNE *BLANKS C BD,V CAT BV,V:1 T#BD P C Z-ADDQT,V T#QTY C Z-ADDXA,V T#XAMT C WRITETOTALLN C ENDIF * Accumulate into next level C ACCUM IFEQ 'Y' C V ADD 1 W 30 NEXT LEVE C ADD QT,V QT,W C ADD XA,V XA,W C ENDIF * Zero out accumulators for this level C MOVE *ZERO QT,V C MOVE *ZERO XA,V * C ENDSR *********** C *INZSR BEGSR * C WRITEPAGEHDR C MOVE 'Y' ACCUM 1 * C ENDSR *. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 
 
 Variable Control Breaks
 
 Figure 8 DDS for Printer File RTN001P1
 
 *. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 A REF(RETURNS) A R PAGEHDR SKIPB(4) A 1DATE EDTCDE(Y) A 26'Returned Goods' A 57'Page' A +0PAGNBR EDTCDE(4) SPACEA(2) A 1'Reason' A 8'Item' A 13'Store' A 26'Seq' A 34'Date' A 43'Qty' A 51'Price' A 63'Total' SPACEA(1) * A R DTLLINE SPACEB(1) A REASN R 1 A ITEM# R 8 A STORE# R 13 A XACT# R 22 A XACTDT 10 +1 A QTY R +1EDTCDE(4) A PRICE R +1 A XAMT R +3 +1REFFLD(PRICE) EDTCDE(4) * A R TOTALLN SPACEB(2) SPACEA(1) A T#BD 20 19TEXT('BREAK DESCRIPTION') A T#QTY R +1 40REFFLD(QTY) EDTCDE(4) A T#XAMT R +1 56REFFLD(XAMT *SRC) EDTCDE(4) *. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 

Ted Holt is IT manager of Manufacturing Systems Development for Day-Brite Capri Omega, a manufacturer of lighting fixtures in Tupelo, Mississippi. He has worked in the information processing industry since 1981 and is the author or co-author of seven books. 

---

MC Press books written by Ted Holt available now on the MC Press Bookstore.

		Complete CL: Fifth Edition Become a CL guru and fully leverage the abilities of your system. List Price $79.95 Now On Sale
		Complete CL: Sixth Edition Now fully updated! Get the master guide to Control Language programming. List Price $79.95 Now On Sale
		IBM i5/iSeries Primer Check out the ultimate resource and “must-have” guide for every professional working with the i5/iSeries. List Price $99.95 Now On Sale
		Qshell for iSeries Check out this Unix-style shell and utilities command interface for OS/400. List Price $79.95 Now On Sale

Also Read

H and F Position-less Specs

Practical RPG: AI and IBM i

Programming in ILE RPG - Defining Standalone Variables & Assigning Initial Values to Data