In DFSORT IFTHEN, WHEN=GROUP is used for group-level operations: actions that depend on groups of records rather than on a single record's condition. Typical uses are adding a sequence number within each group (e.g. 1, 2, 3 for records in the same control-break group), adding a group identifier (the same value for every record in the group, incrementing for each new group), or other group-based calculations. WHEN=GROUP is processed early, like WHEN=INIT, before WHEN=(logical expression) and WHEN=NONE. You define groups using BEGIN=, END=, or RECORDS=, and use operands such as SEQ= and ID= to add sequence numbers and group IDs. This page explains what WHEN=GROUP does, how groups are defined, and how it fits with the rest of IFTHEN processing.
Most IFTHEN clauses ask: "Does this record meet a condition?" (e.g. byte 1 = 'H'). WHEN=GROUP asks: "Where does this record fall in a group of records?" So you can do things that require knowing the record's position within a group—for example, "record 1 of this group," "record 2 of this group," or "this is group number 3." That is useful for control-break reporting (e.g. subtotals per department), for adding line numbers within each section, or for tagging every record with a group ID so that downstream programs can tell which group it belongs to.
WHEN=GROUP is processed in the same early phase as WHEN=INIT. So the group sequence numbers or IDs are applied before any WHEN=(logexp) or WHEN=NONE. That way the record already has the group-based fields when the conditional clauses run, and you can overlay or use them as needed.
A group is a set of consecutive records. You define when a group starts or ends (or how big it is) using one or more of these operands in the WHEN=GROUP clause:
| Operand | Meaning |
|---|---|
| BEGIN=(logexp) | A logical expression that when true marks the start of a new group (e.g. when a control field changes). |
| END=(logexp) | A logical expression that when true marks the end of the current group. |
| RECORDS=n | Maximum number of records in a group (e.g. every n records start a new group). |
At least one of BEGIN=, END=, or RECORDS= must be specified so that DFSORT knows how to form groups. The exact syntax and the way BEGIN= and END= interact (e.g. control field change) are documented in the IBM DFSORT manual. Typically, after a sort on a control field (e.g. department), BEGIN= might be "when department value changes" so that each department is one group.
SEQ=n adds a sequence number (zoned decimal, length n) to each record. The important behavior is that the sequence restarts at 1 for the first record of each new group and increments by 1 for each subsequent record in that group. So within group 1 you get 1, 2, 3, ...; when group 2 starts, you get 1, 2, 3, ... again. That gives you a line number or item number within each control-break group. You use PUSH= (or the appropriate operand in your DFSORT version) to specify where in the record to place the sequence number. The length n is 1 to 15 digits.
Example idea: records are sorted by department (bytes 1–10). You want to add a 5-byte sequence number at position 11 that is 1 for the first record in each department, 2 for the second, and so on. You would use WHEN=GROUP with BEGIN= (or the equivalent) to define the group by department, and SEQ=5 with PUSH=(11:...) to put the number at position 11. The exact control statement syntax depends on your DFSORT version; refer to the IBM documentation.
ID=n adds a group identifier (zoned decimal, length n) to every record in the group. Unlike SEQ, the ID is the same for all records in the same group and increments by 1 for each new group. So the first group gets ID 1, the second group gets ID 2, and so on. That lets you tag each record with "which group I belong to" without having to carry the full control field. Again, you use PUSH= or the equivalent to place the ID in the record. Length n is 1 to 15 digits.
So SEQ gives you "record number within group" (1, 2, 3, ... per group). ID gives you "group number" (1, 1, 1 for group 1; 2, 2, 2 for group 2).
WHEN=GROUP can be used in INREC, OUTREC, and OUTFIL, just like other IFTHEN WHEN types. Use it in INREC when the group sequence or ID must be part of the record for the sort or for INCLUDE/OMIT (e.g. you sort by group ID and then by sequence within group). Use it in OUTREC when you only need the group numbering in the final output. Use it in OUTFIL when you are building additional output files (e.g. reports) that need group-based fields.
Because WHEN=GROUP is processed early, the record that later WHEN=(logexp) or WHEN=NONE see already has the SEQ or ID (or other group operations) in place. So you can overlay or test those values in conditional clauses if needed.
Group-based operations assume that records are in the order that defines the groups. So you typically sort (or merge) on the control field first (e.g. department, account), so that all records in the same group are consecutive. Then WHEN=GROUP with BEGIN=(control field changes) (or the equivalent) forms one group per department. If the file is not in the right order, "groups" will not align with the control field and sequence/ID values may not match what you expect. So WHEN=GROUP usually follows a SORT (or MERGE) that orders the data by the group key.
The full syntax for WHEN=GROUP—including BEGIN=, END=, RECORDS=, PUSH=, SEQ=, ID=, and any other operands—is in the IBM DFSORT (and ICETOOL) documentation. Syntax and availability can vary by product level and PTF. When implementing group-level operations, refer to your site's DFSORT manual or IBM Knowledge Center for the exact keywords and examples. This page gives the conceptual picture: WHEN=GROUP is for group-level operations, processed early, with groups defined by BEGIN/END/RECORDS and sequence/ID added via SEQ and ID.
Imagine you have rows of chairs: row 1 has three chairs, row 2 has five chairs, row 3 has two chairs. WHEN=GROUP is like putting a number on each chair: "row number" (the same for the whole row—row 1, row 1, row 1; then row 2, row 2, ...) and "seat number in the row" (1, 2, 3 for the first row; then 1, 2, 3, 4, 5 for the second row; then 1, 2 for the third). So the computer looks at the rows (groups) and numbers each seat within the row and labels which row it is. That way every chair knows its row and its seat number in that row.
1. When is WHEN=GROUP processed relative to WHEN=(logexp)?
2. What is a typical use of WHEN=GROUP?
3. How do you define a group in WHEN=GROUP?
4. What does SEQ=n in WHEN=GROUP do?
5. Can WHEN=GROUP be used in INREC as well as OUTREC?