Easytrieve Sorting Overview

Why Sorting Exists in Easytrieve Programs

Easytrieve is not a sort product—it is a report generator that can call one. When your program contains a SORT statement, you declare a SORT activity: a processing phase separate from JOB, SCREEN, and PROGRAM blocks. That activity reads a sequentially processable input file, applies keys from the USING parameter, and writes a TO output file whose records share the same layout as input unless a BEFORE procedure or variable-length rules change lengths. The sorted file becomes input for the next step—almost always JOB INPUT of the work file—so reports, totals, and file updates see stable key order. Without that step, you rely on whoever built the upstream extract to deliver sorted data, which is a fragile assumption across nightly reruns and vendor feeds.

Report SEQUENCE solves a narrower problem. You already decided which records PRINT to a report; you only need those spool rows in a different order before TITLE and LINE formatting run. SEQUENCE names sort keys on the REPORT declaration. When PRINT executes, Easytrieve writes report data to a temporary work file, sorts only the fields required for that report (not necessarily the full input record), then formats pages from the sorted spool. Broadcom describes this combination as optimized for report efficiency because the sort works on a slim spool record and feeds printing directly from sort output. Choose SORT when downstream logic needs a file; choose SEQUENCE when one report's presentation order is the only requirement.

SORT Activity Versus REPORT SEQUENCE

A beginner mistake is coding SEQUENCE on three reports that share identical keys when one SORT before JOB would have ordered input once. The opposite mistake is running SORT for a single flat listing that only needs SEQUENCE on one REPORT—extra I/O and a work file the JOB must still read. Sketch your data flow on paper: if only report layout cares about order, SEQUENCE may suffice; if JOB logic, synchronized files, or multiple reports with the same keys need order, SORT once upstream.

SORT Statement Structure and Key Order

The SORT statement opens the activity. Broadcom format lists INPUT file, TO output file, USING keys, optional COMMIT for recoverable resources, SIZE and WORK for sort utility tuning, BEFORE for prescreen procedures, and NAME for documentation and EXECUTE references. Keys in USING appear in major-to-minor order—the first key dominates, the second breaks ties within equal first keys, and so on. A payroll file sorted USING (REGION, BRANCH, DEPT) groups all rows for a region, then orders branches inside each region, then departments inside each branch. Swapping DEPT before REGION would sort by department globally first, which destroys regional control breaks even though the same three fields appear in both lists.

1
2
3
4
5
6
7
SORT input-file-name TO sorted-file-name +
  USING (sort-key-field-name [D] ...) +
  [COMMIT ([ACTIVITY|NOACTIVITY] [TERMINAL|NOTERMINAL])] +
  [SIZE record-count] +
  [WORK number-of-work-data-sets] +
  [BEFORE proc-name] +
  [NAME sort-name]

Line by line: input-file-name must reference a FILE supporting sequential processing—SAM, VSAM sequential access, relative, or VFM per your release. TO sorted-file-name names the output; it can match input only when your file type allows in-place rewrite (not VSAM or ISAM in classic guidance). USING lists parenthesized keys with optional D immediately after a field for descending on that key only. COMMIT controls commit points for SQL or recoverable environments. SIZE supplies record count when Easytrieve cannot infer volume from a prior activity. WORK tells the sort program how many work data sets to allocate (0 means DD statements supplied, 1–31 dynamic allocation). BEFORE names a prescreen procedure. NAME labels the activity for maps and conditional EXECUTE in PROGRAM activities.

Complete sort-then-report skeleton

1
2
3
4
5
6
7
8
9
10
11
12
13
14
FILE PERSNL FB(150 1800)
%PERSNL
FILE SORTWRK FB(150 1800) VIRTUAL
COPY PERSNL
 
SORT PERSNL TO SORTWRK USING (REGION, BRANCH) NAME MYSORT
 
JOB INPUT SORTWRK NAME MYPROG
   PRINT REPORT1
 
REPORT REPORT1
  CONTROL REGION BRANCH
  TITLE 1 'PERSONNEL BY REGION AND BRANCH'
  LINE REGION BRANCH EMPNAME PAY-NET

PERSNL is the production extract. SORTWRK is a VIRTUAL file whose COPY PERSNL macro duplicates field definitions so record pictures align without maintaining two layouts by hand. SORT reads every PERSNL record (unless BEFORE filters), orders by REGION then BRANCH ascending, and writes SORTWRK. JOB reads SORTWRK explicitly; if INPUT were omitted, Broadcom default still selects the immediately preceding SORT output. REPORT1 uses CONTROL on the same keys as SORT so break headers fire when values change. Mismatch between USING and CONTROL is the most common reason sorted jobs still look broken on spool.

Ascending and Descending Key Comparisons

Default order is ascending for every key: numeric fields compare low to high, character fields follow the collating sequence (with optional alternate sequence tables via site options or PARM SORT when installed). Append D directly after a field name for descending on that key alone: USING (DEPT, GROSS-PAY D) lists departments ascending and, within each department, highest gross pay first. USING (PAY-NET D, EMP-NUM) sorts entire file by pay descending first—a valid pattern for a top-earner extract but wrong for departmental subtotals. Never assume D propagates to later keys; each field needs its own D if descending is required.

REPORT SEQUENCE follows the same D rule: SEQUENCE REGION BRANCH PAY-NET D orders region ascending, branch ascending, net pay descending within each branch. SEQUENCE fields need not appear on LINE—they can sort on a key you suppress from print columns. Keys must be active file fields or W-type working storage, under 256 bytes, and cannot be varying length, K, or M types—the same restrictions as SORT USING keys.

BEFORE Procedures and SELECT

Easytrieve normally passes every input record to the sort utility. BEFORE proc-name interrupts that flow: each record enters your procedure first. You may compute working storage, modify fields allowed in sort procs, and branch with IF logic—but you cannot issue GET, PUT, READ, PRINT, or other I/O statements Broadcom lists as invalid in sort procedures. DISPLAY to SYSPRINT is permitted for debugging. To retain a record, execute SELECT. To drop it, fall through without SELECT. STOP in the procedure ends prescreening early (useful in tests; dangerous in production if misapplied).

Broadcom documents no AFTER parameter on SORT. Prescreen logic is always BEFORE relative to the sort utility. After sorted records exist, processing moves to the next activity—typically JOB—or to the sort utility output phase internally. Do not confuse SORT BEFORE with REPORT BEFORE-BREAK or AFTER-BREAK procedures; those fire around control breaks during formatting and assume spool or input order already supports break detection. REPORT break procs are not substitutes for SORT BEFORE filtering.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
SORT PERSNL TO SORTWRK USING (REGION, BRANCH, DEPT, +
    NAME-LAST, NAME-FIRST) +
    NAME MYSORT BEFORE SCREENER
 
SCREENER. PROC
   IF MARITAL-STAT = 'S' AND SEX = 1
      SELECT
   END-IF
END-PROC
 
JOB INPUT SORTWRK NAME MYPROG
   PRINT REPORT1
 
REPORT REPORT1
  LINE REGION BRANCH DEPT NAME-LAST NAME-FIRST

SCREENER runs once per PERSNL record before keys are evaluated. Only single female records (per this example's coded values) receive SELECT and therefore appear on SORTWRK. All other records are skipped entirely—they never compete in the sort. Keys still apply to the filtered set: survivors sort by REGION, BRANCH, DEPT, then name fields. If the procedure forgot SELECT on a kept row, that row vanishes from output even when the IF condition was true, a silent data loss pattern that record-count checks catch quickly.

SELECT Semantics and Duplicate Records

SELECT during sort prescreening only flips an inclusion switch; it does not write immediately. Broadcom states three duplicate rules that confuse beginners. First, selecting the same record twice in one procedure pass still outputs one copy on the sorted file—SELECT is idempotent for inclusion. Second, executing SELECT and then STOP on the same record excludes it—STOP wins for that pass. Third, records never selected do not appear on the TO file at all; they are not sorted and not written.

Duplicate keys are not duplicate records. If fifty employees share DEPT 100, all fifty remain in sort output when keys match—they are not collapsed into one row. Easytrieve SORT does not deduplicate by key. If you need only one row per key, prescreen with logic in BEFORE or process sorted output in JOB using FIRST-DUP, LAST-DUP, and DUPLICATE relational conditions that compare the current record to adjacent records on a named file. Those tests apply after sort order exists; they do not remove rows during SORT unless your logic skips PRINT or omits SELECT.

Stable order among equal keys

When two records compare equal on every USING key, their relative order in output depends on the installation sort program invoked through Easytrieve—DFSORT, Syncsort, or another product—not on Easytrieve language rules alone. Broadcom directs you to the installation sort manual for whether equal keys preserve input order (stable sort). Do not rely on undocumented stability for financial tie-breaks; add a further minor key such as employee number or sequence number when order among ties must be deterministic.

Work Files: SORT Output and Report Spool

Work files appear in both sorting paths with different shapes. For SORT, the TO file is commonly defined VIRTUAL with COPY of the input layout. VIRTUAL files live for the execution pass unless FILE definition routes them to permanent datasets; they avoid catalog clutter while chaining SORT to JOB in one step. SIZE and WORK parameters tune how the external sort allocates memory and sort work data sets—coordinate with operations rather than copying numbers from tutorials.

For REPORT SEQUENCE, Broadcom states PRINT spools to a temporary work file transparently. Only report fields enter that file, reducing sort volume versus sorting full 4K records when LINE prints ten columns. After sort completes, formatting retrieves sorted spool data and applies TITLE, LINE, CONTROL, and SUM. Multiple reports in one JOB may each use SEQUENCE independently—three sort passes on three spool files if three reports declare different keys—where one SORT before JOB would have ordered input once for all PRINT statements.

1
2
3
4
5
6
7
JOB INPUT PERSNL NAME PAYROLL-JOB
   PRINT PERSNL-REPORT
 
REPORT PERSNL-REPORT SEQUENCE REGION BRANCH PAY-NET D
  CONTROL REGION BRANCH
  TITLE 'PERSONNEL REPORT'
  LINE REGION BRANCH EMPNAME PAY-NET

This pattern is taken from Broadcom's SEQUENCE statement example. JOB reads PERSNL in arrival order and PRINT spools each selected row. SEQUENCE declares sort keys: region and branch ascending, net pay descending within branch. CONTROL uses REGION and BRANCH so break processing aligns with sequence keys. No SORT activity appears in the program—order is entirely a report-time concern. If a second report in the same JOB needed the same keys, consider SORT PERSNL once upstream instead of duplicating SEQUENCE cost.

Chaining Activities and Default Input

Implied PROGRAM executes JOB and SORT activities in source order until SCREEN. A typical batch chain is SORT, then JOB, then REPORT definitions. When JOB omits INPUT, Easytrieve defaults to the TO file of the immediately preceding SORT if one exists; otherwise the first eligible FILE in Library that is not a table, punch, or printer file. Explicit JOB INPUT sorted-file-name is clearer for maintainers even when defaults work. PROGRAM activities can EXECUTE named SORT activities conditionally—sort only when a parameter flag requests it—while SCREEN may EXECUTE SORT before online reporting.

On z/OS, Easytrieve invokes the installation sort program using conventional E15 input and E35 output exits; BEFORE procedures attach to the prescreen side of that interface. CICS and non-mainframe environments use the sort packaged with Easytrieve instead. Variable-length input sorted to maximum record length defined on FILE is a documented special case—verify spool and downstream COPY expectations when LRECL changes.

Performance and Operational Considerations

Broadcom explicitly warns that sorting files during Easytrieve program execution significantly increases CPU overhead. SORT on a million-row extract inside every nightly report job multiplies cost compared with a standalone DFSORT step in JCL that feeds an already-sorted file to Easytrieve with no SORT activity. SEQUENCE reduces work relative to full-file SORT when only one report needs order, because spool records are shorter and formatting follows sort immediately. Conversely, three reports each with SEQUENCE on the same keys can triple sort cost inside one program where one SORT before JOB would sort once and let every PRINT benefit from ordered input—though CONTROL on unsorted input still fails unless SEQUENCE or SORT aligns keys per report.

• Pre-sort large extracts in JCL when many programs consume the same order.
• Match SIZE to approximate record counts when input was not created by a prior Easytrieve activity.
• Use WORK and site SORT options (SORTMAX, SORTWRK, FASTSRT where supported) with operations guidance.
• Prefer one SORT plus explicit JOB INPUT over repeated SEQUENCE when keys and reports align.
• Filter early with BEFORE and SELECT to shrink sort volume when only a subset needs reordering.
• Compare wall-clock and CPU with SORT removed when stakeholders debate report-time SEQUENCE only.

In-place SORT where input and TO names match rewrites the same dataset—powerful for permanent reorder steps, dangerous when downstream jobs still expect the original arrival order. VSAM and ISAM restrictions on same-name TO prevent some in-place patterns; use separate work files until production proves safety.

Choosing a Pattern: Decision Guide

1. List every consumer of ordered data—reports, writes, synchronized files, extracts.
2. If more than one consumer needs the same keys, strongly favor one SORT activity and shared input.
3. If only one report cares and no JOB logic needs order, SEQUENCE on that REPORT may suffice.
4. If subset sorting is required, plan BEFORE proc-name and SELECT before coding keys.
5. Align CONTROL and SEQUENCE or USING keys major-to-minor identically unless breaks are intentional.
6. Add tie-breaker keys when equal keys must appear in predictable order.
7. Document VIRTUAL work files and JCL DD requirements for permanent TO datasets.

Common Beginner Errors

Explain It Like I'm Five

Imagine a shoe box full of index cards, each card listing a kid's name, classroom, and score. You want to read them aloud in classroom order at assembly. One way is to empty the box, sort every card on the floor by classroom, put them back in a new box, and then read—that is SORT: the whole box gets reorganized before story time. Another way is to pull cards one at a time during story time and stick them onto a bulletin board in the order you want to read them, sorting only what is on the board before you speak—that is SEQUENCE: you only rearrange the cards you plan to show, not the entire shoe box. BEFORE is a friend who looks at each card before it goes into the new box and only keeps cards that pass a rule—like only kids who brought lunch—by putting a SELECT sticker on them. Cards with the same classroom still stay separate kids; sorting does not merge twins into one card. If you need everyone in the school in classroom order for many activities, sort the whole box once (SORT). If only the assembly reading needs order, the bulletin board trick (SEQUENCE) might be enough.

Exercises

1. Draw a flowchart with PERSNL extract, optional SORT to SORTWRK, JOB, and two REPORT blocks—one with SEQUENCE and one without. Label where work files appear.
2. Write USING (REGION D, BRANCH, PAY-NET D) and describe the first three records you expect when REGION values are 10, 10, 20 and PAY-NET varies within region 10.
3. Add a BEFORE procedure that SELECTs only records with PAY-NET GE 500 to the Broadcom SCREENER example and predict output record count given ten input records with four above the threshold.
4. Explain why CONTROL REGION BRANCH fails when input is random and REPORT omits SEQUENCE but JOB also skipped SORT.
5. List five invalid statements in a sort procedure per Broadcom and explain why GET is forbidden.
6. Compare CPU impact: one SORT plus two reports reading sorted input versus two reports each with SEQUENCE on identical keys—state which you would recommend for a million-row file and why.
7. Write JOB logic using IF FIRST-DUP after SORT on ADDR-STATE to count duplicate groups without removing records during SORT.