A payroll extract must group employees by department and place the highest gross pay first within each group. In Easytrieve, that requirement belongs to a separate SORT activity: it reads an input file sequentially, passes records to the installation's sort program, and writes the ordered records to an output file.
What the Easytrieve SORT activity does
The Easytrieve SORT statement is an activity, like a JOB activity, rather than a statement inside JOB logic. It sequences records from one defined file into another defined file. The actual ordering work is performed through the sort facility configured at the installation, so work-space allocation, messages, and product-specific options can differ between sites.
Keep the activity boundary in mind when reading an Easytrieve program structure. FILE definitions belong in the library section. The SORT activity follows those definitions, and a later JOB activity can read the sorted output.
Easytrieve SORT statement syntax
SORT input-file TO output-file +
USING (major-key minor-key [D] ...) +
[BEFORE procedure-name] +
[NAME sort-name]| Item | Purpose | Operational check |
|---|---|---|
input-file | Names the FILE definition read by the activity. | The organization must support sequential processing for the sort input. |
TO output-file | Names the FILE definition that receives sorted records. | Confirm record length and field layout before a downstream JOB reads it. |
USING | Lists sort keys from major to minor. | Each key must be a field associated with the input record being sorted. |
D | Sorts the immediately preceding key in descending order. | A key without D is ascending. |
BEFORE | Invokes a sort procedure for every input record before release to the sort. | The procedure must immediately follow the SORT activity. |
NAME | Assigns a name to the SORT activity. | Use a descriptive activity name; it is not a data set name. |
Complete ascending-key example
This example orders employees by department and then by name. Department is the major key because it appears first.
FILE PERSNL FB(19 1900)
NAME 1 10 A
DEPT 11 5 N
GROSS-PAY 16 4 P 2
FILE PAY-SORT FB(19 1900)
SORT-NAME 1 10 A
SORT-DEPT 11 5 N
SORT-GROSS-PAY 16 4 P 2
SORT PERSNL TO PAY-SORT +
USING (DEPT NAME) +
NAME DEPT-NAME-SORTRecords are ordered by DEPT ascending. Records with the same department are then ordered by NAME ascending. The output field names can differ, but the positions, lengths, and types must describe the record that the next activity will receive. Review the Easytrieve FILE definition guide when the layouts are not identical.
Mixed ascending and descending keys
Place D immediately after the field that must be descending:
SORT PERSNL TO PAY-SORT +
USING (DEPT GROSS-PAY D NAME) +
NAME DEPT-PAY-SORTThe result is department ascending, gross pay descending within each department, and name ascending when both earlier keys compare equal. Moving D to another position changes which key is reversed; it does not change every key that follows.
Major and minor key order
Easytrieve reads the USING list from major to minor. If payroll staff need the highest-paid employee first inside each department, code DEPT before GROSS-PAY D. Coding gross pay first would mix departments whenever employees have the same pay value.
Field type also matters. An N or packed-decimal P field is compared as its declared numeric type; an A field is character data. A wrong position, length, or type in the FILE definition can produce an order that looks like a sort failure even when the sort facility followed the supplied key definition exactly.
Filter records with a BEFORE procedure
BEFORE runs a named procedure once for each input record before that record is passed to the sort. It is the Easytrieve mechanism for screening records or changing record contents as part of the SORT activity.
SORT PERSNL TO PAY-SORT +
USING (DEPT GROSS-PAY D) +
BEFORE SELECT-HIGH-PAY +
NAME HIGH-PAY-SORT
SELECT-HIGH-PAY. PROC
IF GROSS-PAY GE 500
SELECT
END-IF
END-PROCThe procedure is placed immediately after the SORT statement. SELECT releases the current record to the sort. In this example, a record below 500 is not selected and therefore does not appear in PAY-SORT.
Why SELECT is required with BEFORE
Once a BEFORE procedure is present, each record intended for the sorted output must execute SELECT. Omitting it can leave the output empty even though the input file opened and the procedure ran. Selecting the same input record more than once does not create multiple output copies; the record is returned once.
SELECT executes for the expected input rows.Using a VIRTUAL sorted output file
A VIRTUAL file is useful when the sorted records are consumed by another activity in the same Easytrieve program and no permanent output data set is required. A compact pattern is:
FILE PAY-SORT F(19) VIRTUAL
SORT PERSNL TO PAY-SORT +
USING (DEPT GROSS-PAY D)
JOB INPUT PAY-SORT NAME PRINT-SORTED
PRINT PAY-RPTBroadcom notes that the Virtual File Manager is involved when a SORT statement is used. Treat that as runtime behavior, not as permission to ignore storage and installation settings. The program's input, output, and report flow should still be explicit. The Easytrieve JOB statement guide explains how the following activity reads the sorted file.
SORT activity versus report SEQUENCE
Use SORT when another file or activity needs records in a new order. Use the report SEQUENCE declarative when the requirement is to order report lines and support control breaks or totals without creating a separately sorted application file.
| Requirement | Use | Reason |
|---|---|---|
| Create sorted records for later processing | SORT activity | Writes ordered records to the named output file. |
| Filter records before sorting | SORT with BEFORE | The procedure evaluates each input record and SELECT controls inclusion. |
| Order only a printed report | REPORT SEQUENCE | Ordering belongs to report processing rather than a separate output file. |
| Produce subtotals by a report field | SEQUENCE with CONTROL/SUM as required | The report facility groups and totals the sequenced lines. |
See Easytrieve basic reporting for FILE, JOB, REPORT, PRINT, and LINE context.
Sort work and installation options
Easytrieve interfaces with the site's sort product. Broadcom's option-file categories include sort options for storage and sort messages. This means a valid Easytrieve statement can still fail because of missing work DD statements, insufficient temporary space, installation limits, or a site-specific option. Capture the Easytrieve message and the underlying sort product message before changing application logic.
The supported number of keys and vendor option syntax depend on the installed environment. Avoid copying sort-control options from a different site without checking the local Easytrieve 11.6 documentation and the installed sort product manual.
Common Easytrieve SORT errors
- Undefined file name: the input or output name has no matching FILE definition, or the spelling differs.
- Wrong key order: a minor key is coded before the intended major key.
- Wrong descending marker:
Dfollows the wrong field and reverses that key instead. - Missing SELECT: a BEFORE procedure executes, but no qualifying path releases records.
- Misplaced procedure: the named sort procedure does not immediately follow its SORT activity.
- Layout mismatch: the output record definition does not match the bytes written by the sort.
- Numeric field defined as character: values are ordered by character representation instead of the intended numeric value.
- Runtime sort failure: the application syntax is valid, but work-space or installation options cause the system sort to fail.
Production review checklist
- Confirm both FILE names and record layouts.
- List USING fields in major-to-minor order.
- Place
Donly after each descending key. - If BEFORE is coded, place its procedure immediately after SORT and trace every path to
SELECTor intentional rejection. - Confirm whether the output should be permanent or VIRTUAL.
- Check the downstream Easytrieve program activity that consumes the sorted records.
- Retain the Easytrieve and system-sort messages when diagnosing a failure.
Broadcom Easytrieve references
- Easytrieve product brief
- When the Easytrieve Virtual File Manager is used
- Easytrieve 11.6 option-file categories
- SEQUENCE, CONTROL, and SUM for report totals
- Broadcom Easytrieve legacy guide library
Easytrieve SORT statement FAQ
Is ascending or descending the Easytrieve SORT default?
Ascending is the default. Add D immediately after a key field when that specific key must be descending.
What does BEFORE do on an Easytrieve SORT statement?
BEFORE invokes a procedure for each input record before release to the sort. The procedure can test or modify the current record, and SELECT determines whether it enters the sorted output.
Why did a SORT with BEFORE produce an empty file?
The usual application-level cause is that no reachable path executed SELECT. Check the condition, field definition, and procedure placement before investigating sort work-space failures.
Should a report use SORT or SEQUENCE?
Use SORT when you need an ordered output file or a later activity must read ordered records. Use report SEQUENCE when only the report lines need ordering, control breaks, or totals.
Final check: read the USING list aloud as “major key, then minor key,” and verify that every D and every BEFORE-path SELECT matches that sentence.
