z/OS DFSORT Application Programming Guide · E61 user exit: modifying contr ol fields ... . 513...

z/OS

DFSORT Application Programming GuideVersion 2 Release 3

SC23-6878-30

IBM

NoteBefore using this information and the product it supports, read the information in Notices on page 913.

This edition applies to Version 2 Release 3 of z/OS (5650-ZOS) and to all subsequent releases and modificationsuntil otherwise indicated in new editions.

Last updated: July 17, 2017

Copyright IBM Corporation 1973, 2017.US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contractwith IBM Corp.

Contents

Figures . . . . . . . . . . . . . . . ix

Tables . . . . . . . . . . . . . . . xi

About this document . . . . . . . . xiiiHow to use this document . . . . . . . . . xiiiRequired product knowledge . . . . . . . . xivReferenced documents. . . . . . . . . . . xvNotational conventions . . . . . . . . . . xv

How to send your comments to IBM xixIf you have a technical problem . . . . . . . xix

Summary of changes . . . . . . . . xxiSummary of changes for z/OS Version 2 Release 3 xxi

New information . . . . . . . . . . . xxiSummary of changes for SC23-6878-01 z/OSVersion 2 Release 2 . . . . . . . . . . . xxii

New information . . . . . . . . . . . xxiiSummary of changes for SC23-6878-00 z/OSVersion 2 Release 1 . . . . . . . . . . . xxiii

New information . . . . . . . . . . . xxiiiOperational changes that may require useraction. . . . . . . . . . . . . . . xxvi

Chapter 1. Introducing DFSORT . . . . 1DFSORT overview . . . . . . . . . . . . 1DFSORT on the Web. . . . . . . . . . . . 4DFSORT FTP site . . . . . . . . . . . . . 4Invoking DFSORT . . . . . . . . . . . . 4How DFSORT works . . . . . . . . . . . 5

Operating systems . . . . . . . . . . . 5Control fields and collating sequences . . . . . 5Cultural environment considerations . . . . . 7Unicode . . . . . . . . . . . . . . . 7Unicode Environment Considerations . . . . . 8DFSORT processing . . . . . . . . . . . 8

Input data setsSORTIN and SORTINnn . . . . 12Output data setsSORTOUT and OUTFIL . . . . 13Data set considerations . . . . . . . . . . 13

Sorting or copying records . . . . . . . . 13Merging records . . . . . . . . . . . . 14Data set notes and limitations . . . . . . . 14

XTIOT, uncaptured UCBs and DSAB above 16megabytes . . . . . . . . . . . . . . . 17z/OS file system considerations . . . . . . . 17Installation defaults. . . . . . . . . . . . 18Migrating to DFSORT from other sort products . . 25DFSORT messages and return codes . . . . . . 26Use Blockset whenever possible . . . . . . . 27

Chapter 2. Invoking DFSORT with JobControl Language . . . . . . . . . . 29Using the JCL . . . . . . . . . . . . . 29

Using the JOB statement . . . . . . . . . . 31Using SET and PROC symbols in DFSORT controlstatements . . . . . . . . . . . . . . . 31Using the EXEC statement . . . . . . . . . 31

Specifying EXEC statement cataloged procedures 32Specifying EXEC/DFSPARM PARM options . . 34Aliases for PARM options . . . . . . . . 62

Using DD statements . . . . . . . . . . . 63Duplicate ddnames . . . . . . . . . . . 65Shared tape units . . . . . . . . . . . 66System DD statements. . . . . . . . . . 66Program DD statements . . . . . . . . . 68

Chapter 3. Using DFSORT programcontrol statements . . . . . . . . . 83Using program control statements . . . . . . . 83Control statement summary . . . . . . . . . 83

Describing the primary task . . . . . . . . 83Including or omitting records . . . . . . . 84Reformatting and editing records . . . . . . 84Producing multiple output and reports andconverting records . . . . . . . . . . . 84Joining two files . . . . . . . . . . . . 84Invoking additional functions and options . . . 85Using symbols . . . . . . . . . . . . 85

General coding rules . . . . . . . . . . . 85Continuation lines . . . . . . . . . . . 87Inserting comment statements . . . . . . . 89Coding restrictions . . . . . . . . . . . 90

ALTSEQ control statement . . . . . . . . . 90Altering EBCDIC collating sequenceexamples 91

DEBUG control statement . . . . . . . . . 93Specifying diagnostic optionsexamples . . . 97

END control statement . . . . . . . . . . 97Discontinue reading controlstatementsexamples . . . . . . . . . . 97

INCLUDE control statement . . . . . . . . . 98Relational condition . . . . . . . . . . 101Comparisons . . . . . . . . . . . . 101Including records in the output datasetcomparison examples . . . . . . . . 110Substring comparison tests . . . . . . . . 112Including records in the output datasetsubstring comparison example . . . . . 114Bit logic tests . . . . . . . . . . . . 114Method 1: Bit operator tests . . . . . . . 114Padding and truncation . . . . . . . . . 116Including records in the output data setbitoperator test examples . . . . . . . . . 116Method 2: Bit comparison tests . . . . . . 117Including records in the output data setbitcomparison test examples . . . . . . . . 118Date comparisons . . . . . . . . . . . 119Including records in the output data setdatecomparisons . . . . . . . . . . . . . 122

Copyright IBM Corp. 1973, 2017 iii

||||

Numeric tests . . . . . . . . . . . . 122Including records in the output dataset--numeric tests . . . . . . . . . . . 124Alphanumeric tests . . . . . . . . . . 124Including records in the output dataset--alphanumeric tests . . . . . . . . . 126INCLUDE/OMIT statement notes . . . . . 126

INREC control statement . . . . . . . . . 127INREC statement notes . . . . . . . . . 150Reformatting records before processing examples . . . . . . . . . . . . . . 152

JOINKEYS control statement . . . . . . . . 164JOIN control statement . . . . . . . . . . 164MERGE control statement . . . . . . . . . 164

Specifying a MERGE or COPYexamples . . . 167MODS control statement . . . . . . . . . 168

Identifying user exit routinesexamples . . . 171OMIT control statement . . . . . . . . . . 172

Omitting records from the output datasetexample . . . . . . . . . . . . 174

OPTION control statement . . . . . . . . . 175Aliases for OPTION statement options . . . . 221Specifying DFSORT options orCOPYexamples . . . . . . . . . . . 222

OUTFIL control statements . . . . . . . . . 226OUTFIL statements notes . . . . . . . . 377OUTFIL featuresexamples . . . . . . . 380

OUTREC control statement . . . . . . . . . 405OUTREC statement notes . . . . . . . . 427Reformatting records after processing examples . . . . . . . . . . . . . . 429

RECORD control statement. . . . . . . . . 441Describing the record format andlengthexamples . . . . . . . . . . . 444

REFORMAT control statement. . . . . . . . 445SORT control statement . . . . . . . . . . 445

SORT/MERGE statement notes . . . . . . 453Specifying a SORT or COPYexamples . . . 453

SUM control statement . . . . . . . . . . 455SUM statement notes . . . . . . . . . . 458Adding summary fieldsexamples . . . . . 459

Chapter 4. Using a JOINKEYSapplication for joining two files. . . . 461Overview. . . . . . . . . . . . . . . 461

JOINKEYS application processing . . . . . 462Sample JOINKEYS applications . . . . . . 463

JCL for a JOINKEYS application . . . . . . . 464JOINKEYS statements . . . . . . . . . . 466JOIN statement . . . . . . . . . . . . . 471REFORMAT statement . . . . . . . . . . 472JOINKEYS application notes . . . . . . . . 475JOINKEYS application examples . . . . . . . 477

Example 1 - Paired F1/F2 records withoutduplicates . . . . . . . . . . . . . 477Example 2 - Paired F1/F2 records withduplicates (cartesian) . . . . . . . . . . 479Example 3 - Paired F1 records . . . . . . . 481Example 4 - Unpaired F2 records . . . . . . 483Example 5 - Paired and unpaired F1/F2 records(indicator method). . . . . . . . . . . 486

Example 6 - Paired and unpaired F1/F2 records(FILL method) . . . . . . . . . . . . 489

Chapter 5. Using your own user exitroutines. . . . . . . . . . . . . . 491User exit routine overview . . . . . . . . . 491DFSORT program phases . . . . . . . . . 492Functions of routines at user exits . . . . . . 494

DFSORT input/user exit/output logic examples 494Opening and initializing data sets . . . . . 496Modifying control fields . . . . . . . . . 496Inserting, deleting, and altering records . . . 496Summing records . . . . . . . . . . . 496Handling special I/O. . . . . . . . . . 496VSAM user exit functions . . . . . . . . 497Determining action when intermediate storageis insufficient . . . . . . . . . . . . 497Closing data sets . . . . . . . . . . . 497Terminating DFSORT . . . . . . . . . . 497

32-bit and 64-bit parameter lists . . . . . . . 49764-bit address terminology . . . . . . . . 498

Addressing and residence modes for user exits . . 498How user exit routines affect DFSORT performance 499Summary of rules for user exit routines . . . . 499

Loading user exit routines . . . . . . . . 500User exit linkage conventions . . . . . . . 500Dynamically binding or link-editing user exitroutines . . . . . . . . . . . . . . 502

Assembler user exit routines (input phase userexits) . . . . . . . . . . . . . . . . 502

E11 user exit: opening data sets/initializingroutines . . . . . . . . . . . . . . 503E15 user exit: passing or changing records forsort and copy applications . . . . . . . . 503E16 user exit: handling intermediate storagemiscalculation . . . . . . . . . . . . 508E17 user exit: closing data sets . . . . . . 509E18 user exit: handling input data sets . . . . 509E19 user exit: handling output to work data sets 512E61 user exit: modifying control fields . . . . 513

Assembler user exit routines (output phase userexits) . . . . . . . . . . . . . . . . 515

E31 user exit: opening data sets/initializingroutines . . . . . . . . . . . . . . 515E32 user exit: handling input to a merge only 515E35 user exit: changing records . . . . . . 517E37 user exit: closing data sets . . . . . . 523E38 user exit: handling input data sets . . . . 523E39 user exit: handling output data sets . . . 524

Sample E15 and E35 routines using the 64-bitparameter lists . . . . . . . . . . . . . 525Sample routines written in assembler using the32-bit parameter lists . . . . . . . . . . . 525

E15 user exit: altering record length . . . . . 525E16 user exit: sorting current records whenNMAX is exceeded . . . . . . . . . . 526E35 user exit: altering record length . . . . . 526E61 user exit: altering control fields . . . . . 527

COBOL user exit routines . . . . . . . . . 528COBOL user exit requirements . . . . . . 528

COBOL user exit routines (input phase user exit) 530

iv z/OS DFSORT Application Programming Guide

COBOL E15 user exit: passing or changingrecords for sort . . . . . . . . . . . . 530

COBOL user exit routines (output phase user exit) 536COBOL E35 user exit: changing records . . . 536

Sample routines written in COBOL . . . . . . 542COBOL E15 user exit: altering records . . . . 542COBOL E35 user exit: inserting records. . . . 543

E15/E35 return codes and EXITCK . . . . . . 544

Chapter 6. Invoking DFSORT from aprogram . . . . . . . . . . . . . 547Invoking DFSORT dynamically . . . . . . . 547What are system macro instructions? . . . . . 547Using system macro instructions . . . . . . . 547Using JCL DD statements . . . . . . . . . 548Overriding DFSORT control statements fromprograms . . . . . . . . . . . . . . . 548Invoking DFSORT with the 24-bit parameter list 549

Entry point name . . . . . . . . . . . 549Providing program control statements . . . . 549

Invoking DFSORT with the extended (31-bit)parameter list . . . . . . . . . . . . . 556

Entry point name . . . . . . . . . . . 556Providing program control statements . . . . 556

Invoking DFSORT with the 64-bit parameter list 559Entry point name . . . . . . . . . . . 55964-bit address terminology . . . . . . . . 559Providing program control statements . . . . 560

Writing the macro instruction . . . . . . . . 565Parameter list examples . . . . . . . . . 566

Restrictions for dynamic invocation . . . . . . 567Merge restriction . . . . . . . . . . . 567Copy restrictions . . . . . . . . . . . 567

Chapter 7. Using ICETOOL. . . . . . 569Overview. . . . . . . . . . . . . . . 569

ICETOOL/DFSORT relationship . . . . . . 569ICETOOL JCL summary . . . . . . . . . 570ICETOOL operator summary . . . . . . . 571Complete ICETOOL examples . . . . . . . 572Using symbols . . . . . . . . . . . . 573Using SET and PROC symbols in controlstatements . . . . . . . . . . . . . 573Invoking ICETOOL . . . . . . . . . . 573Putting ICETOOL to use. . . . . . . . . 574

Job control language for ICETOOL . . . . . . 577JCL restrictions . . . . . . . . . . . . 579

ICETOOL statements . . . . . . . . . . . 580General coding rules . . . . . . . . . . 580

COPY operator . . . . . . . . . . . . . 581Operand descriptions. . . . . . . . . . 581Copy examples . . . . . . . . . . . . 584COPY operator with JOINKEYS example . . . 585

COUNT operator . . . . . . . . . . . . 586Operand descriptions. . . . . . . . . . 587COUNT examples . . . . . . . . . . . 592

DATASORT operator . . . . . . . . . . . 592Operand descriptions. . . . . . . . . . 594DATASORT examples . . . . . . . . . 595

DEFAULTS operator . . . . . . . . . . . 597

Operand descriptions. . . . . . . . . . 598DEFAULTS example . . . . . . . . . . 599

DISPLAY operator . . . . . . . . . . . . 601Simple report . . . . . . . . . . . . 602Tailored report . . . . . . . . . . . . 603Sectioned report . . . . . . . . . . . 604Operand descriptions. . . . . . . . . . 605

MERGE operator . . . . . . . . . . . . 649Operand descriptions. . . . . . . . . . 650MERGE examples . . . . . . . . . . . 651

MODE operator . . . . . . . . . . . . 652Operand descriptions. . . . . . . . . . 652MODE example . . . . . . . . . . . 652

OCCUR operator . . . . . . . . . . . . 653Simple report . . . . . . . . . . . . 655Tailored report . . . . . . . . . . . . 656Operand descriptions. . . . . . . . . . 656OCCUR examples . . . . . . . . . . . 666

RANGE operator . . . . . . . . . . . . 669Operand descriptions. . . . . . . . . . 669RANGE example . . . . . . . . . . . 671

RESIZE operator . . . . . . . . . . . . 671Operand descriptions. . . . . . . . . . 673RESIZE examples . . . . . . . . . . . 673

SELECT operator . . . . . . . . . . . . 675Operand descriptions. . . . . . . . . . 677SELECT examples . . . . . . . . . . . 680

SORT operator . . . . . . . . . . . . . 684Operand descriptions. . . . . . . . . . 685Sort examples . . . . . . . . . . . . 687SORT operator with JOINKEYS example . . . 688

SPLICE operator . . . . . . . . . . . . 689Operand descriptions. . . . . . . . . . 695SPLICE examples . . . . . . . . . . . 698

STATS operator. . . . . . . . . . . . . 716Operand descriptions. . . . . . . . . . 716STATS example. . . . . . . . . . . . 717

SUBSET operator . . . . . . . . . . . . 718Operand descriptions. . . . . . . . . . 719SUBSET examples . . . . . . . . . . . 723

UNIQUE operator . . . . . . . . . . . . 725Operand descriptions. . . . . . . . . . 725UNIQUE example . . . . . . . . . . . 727

VERIFY operator . . . . . . . . . . . . 727Operand descriptions. . . . . . . . . . 727VERIFY example . . . . . . . . . . . 728

Calling ICETOOL from a program . . . . . . 729TOOLIN interface . . . . . . . . . . . 729Parameter list interface . . . . . . . . . 729

ICETOOL notes and restrictions . . . . . . . 734Notes on using JOINKEYS with COPY and SORT 735ICETOOL return codes . . . . . . . . . . 735

Chapter 8. Using symbols for fieldsand constants . . . . . . . . . . . 737Field and constant symbols overview . . . . . 737

DFSORT example . . . . . . . . . . . 738SYMNAMES DD statement. . . . . . . . . 739SYMNOUT DD statement . . . . . . . . . 740SYMNAMES statements . . . . . . . . . . 740

Comment and blank statements . . . . . . 740

Contents v

Symbol statements . . . . . . . . . . 740Keyword statements . . . . . . . . . . 750Using SYMNOUT to check your SYMNAMESstatements . . . . . . . . . . . . . 752

Using symbols in DFSORT statements . . . . . 753SORT and MERGE . . . . . . . . . . 754SUM . . . . . . . . . . . . . . . 754INCLUDE and OMIT. . . . . . . . . . 755INREC and OUTREC. . . . . . . . . . 756OUTFIL . . . . . . . . . . . . . . 758JOINKEYS . . . . . . . . . . . . . 761REFORMAT . . . . . . . . . . . . . 762OPTION . . . . . . . . . . . . . . 762

Using symbols in ICETOOL operators . . . . . 762COUNT . . . . . . . . . . . . . . 763DATASORT . . . . . . . . . . . . . 763DISPLAY . . . . . . . . . . . . . . 763OCCUR . . . . . . . . . . . . . . 763RANGE . . . . . . . . . . . . . . 764SELECT . . . . . . . . . . . . . . 764SPLICE . . . . . . . . . . . . . . 764STATS, UNIQUE and VERIFY . . . . . . . 764SUBSET . . . . . . . . . . . . . . 764ICETOOL Example . . . . . . . . . . 764

Using SET and PROC symbols in DFSORT andICETOOL statements . . . . . . . . . . . 766

Using JPn parameters in EXEC PARM forDFSORT . . . . . . . . . . . . . . 767Using JPn parameters in EXEC PARM forICETOOL . . . . . . . . . . . . . 767Description of JPn"string" . . . . . . . . 767Example 1 . . . . . . . . . . . . . 768Example 2 . . . . . . . . . . . . . 769

Notes for symbols . . . . . . . . . . . . 770

Chapter 9. Using extended functionsupport . . . . . . . . . . . . . . 773Using EFS . . . . . . . . . . . . . . 773Addressing and residence mode of the EFSprogram . . . . . . . . . . . . . . . 774How EFS works . . . . . . . . . . . . 774

DFSORT program phases . . . . . . . . 774DFSORT calls to your EFS program . . . . . 775

What you can do with EFS . . . . . . . . . 779Opening and initializing data sets . . . . . 780Examining, altering, or ignoring controlstatements . . . . . . . . . . . . . 780Processing user-defined data types with EFSprogram user exit routines . . . . . . . . 782Supplying messages for printing to the messagedata set . . . . . . . . . . . . . . 782Terminating DFSORT . . . . . . . . . . 782Closing data sets and housekeeping . . . . . 782

Structure of the EFS interface parameter list . . . 782Action codes . . . . . . . . . . . . 785Control statement request list . . . . . . . 785Control statement string sent to the EFSprogram . . . . . . . . . . . . . . 785Control statement string returned by the EFSprogram . . . . . . . . . . . . . . 787

EFS formats for SORT, MERGE, INCLUDE, andOMIT control statements . . . . . . . . 789D1 format on FIELDS operand . . . . . . 789D2 format on COND operand . . . . . . . 790Length of original control statement . . . . . 791Length of the altered control statement . . . . 791EFS program context area . . . . . . . . 791Extract buffer offsets list . . . . . . . . . 791Record lengths list. . . . . . . . . . . 792Information flags . . . . . . . . . . . 792Message list . . . . . . . . . . . . . 794

EFS program exit routines . . . . . . . . . 794EFS01 and EFS02 function description . . . . 795EFS01 user exit routine . . . . . . . . . 795EFS02 user exit routine . . . . . . . . . 796Addressing and residence mode of EFS programuser exit routines . . . . . . . . . . . 798

EFS program return codes you must supply . . . 799Record processing order . . . . . . . . . . 799How to request a SNAP dump . . . . . . . 801EFS program example . . . . . . . . . . 802

DFSORT initialization phase: . . . . . . . 802DFSORT termination phase. . . . . . . . 804

Chapter 10. Improving efficiency . . . 805Improving performance . . . . . . . . . . 805Design your applications to maximize performance 805

Directly invoke DFSORT processing . . . . . 805Plan ahead when designing new applications 806Specify efficient sort/merge techniques . . . . 806Specify input/output data set characteristicsaccurately . . . . . . . . . . . . . 807Use extended format data sets. . . . . . . 808Use DFSMSrmm-managed tapes, or ICETPEX 808Specify devices that improve elapsed time. . . 808Use options that enhance performance . . . . 808Use DFSORT's fast, efficient productivityfeatures . . . . . . . . . . . . . . 811Avoid options that degrade performance . . . 812Use main storage efficiently . . . . . . . 813Allocate temporary work space efficiently . . . 816Use Hipersorting . . . . . . . . . . . 817Sort with data space . . . . . . . . . . 818Use memory object sorting . . . . . . . . 819Use ICEGENER instead of IEBGENER . . . . 819ICEGENER return codes. . . . . . . . . 822

Use DFSORT's performance booster for The SASSystem . . . . . . . . . . . . . . . 823Use DFSORT's BLDINDEX support . . . . . . 823

Chapter 11. Examples of DFSORT jobstreams . . . . . . . . . . . . . . 825Summary of examples . . . . . . . . . . 825Storage administrator examples . . . . . . . 825REXX examples . . . . . . . . . . . . 826CLIST examples . . . . . . . . . . . . 827Sort examples . . . . . . . . . . . . . 827

Example 1. Sort with ALTSEQ . . . . . . . 827Example 2. Sort with OMIT, SUM, OUTREC,DYNALLOC and ZDPRINT . . . . . . . 828

vi z/OS DFSORT Application Programming Guide

Example 3. Sort with ASCII tapes . . . . . 830Example 4. Sort with E15, E35, FILSZ,AVGRLEN and DYNALLOC . . . . . . . 831Example 5. Called sort with SORTCNTL,CHALT, DYNALLOC and FILSZ . . . . . . 832Example 6. Sort with VSAM input/output,DFSPARM and option override . . . . . . 833Example 7. Sort with COBOL E15, EXEC PARMand MSGDDN . . . . . . . . . . . . 834Example 8. Sort with dynamic link-editing ofexits . . . . . . . . . . . . . . . 835Example 9. Sort with the extended parameterlist interface . . . . . . . . . . . . . 837Example 10. Sort with OUTFIL . . . . . . 839Example 11. Sort with Pipes and OUTFIL SPLIT 841Example 12. Sort with INCLUDE and LOCALE 842Example 13: Sort with z/OS UNIX files . . . 843Example 14. Sort with IFTHEN . . . . . . 844Example 15. Sort with 64-bit parameter lists,E15, E35 and OUTFIL . . . . . . . . . 845

MERGE examples . . . . . . . . . . . . 850Example 1. Merge with EQUALS . . . . . . 850Example 2. Merge with LOCALE and OUTFIL 851

Copy examples . . . . . . . . . . . . . 852Example 1. Copy with EXEC PARMs, SKIPREC,MSGPRT and ABEND . . . . . . . . . 853Example 2. Copy with INCLUDE and VLSHRT 853Example 3. Copy with OUTREC, PARSE andBUILD . . . . . . . . . . . . . . 854

ICEGENER example . . . . . . . . . . . 855ICETOOL example . . . . . . . . . . . 856

Appendix A. Using work space . . . . 859Introduction . . . . . . . . . . . . . . 859Central storage . . . . . . . . . . . . . 859Work data set devices . . . . . . . . . . 860

Disk and tape devices . . . . . . . . . 860Number of devices . . . . . . . . . . 860Non-synchronous storage subsystems . . . . 861

Allocation of work data sets . . . . . . . . 861Dynamic allocation of work data sets . . . . 862Dynamic over-allocation of work space . . . . 864JCL allocation of work data sets . . . . . . 864

Disk capacity considerations . . . . . . . . 865Exceeding disk work space capacity . . . . . 866

Tape capacity considerations . . . . . . . . 866Exceeding tape work space capacity . . . . . 867

Appendix B. Specification/override ofDFSORT options . . . . . . . . . . 869Main features of sources of DFSORT options . . . 870

DFSPARM data set . . . . . . . . . . 870EXEC statement PARM options . . . . . . 871SORTCNTL data set . . . . . . . . . . 871SYSIN data set . . . . . . . . . . . . 871Parameter lists . . . . . . . . . . . . 871Override tables . . . . . . . . . . . . 871

Directly invoked DFSORT . . . . . . . . . 872Notes to directly invoked DFSORT table . . . 876

Program invoked DFSORT with the extendedparameter list . . . . . . . . . . . . . 876

Notes to extended parameter list table . . . . 880Program invoked DFSORT with the 24-bitparameter list . . . . . . . . . . . . . 880

Notes to 24-bit list table . . . . . . . . . 884

Appendix C. Data format descriptions 885DFSORT data formats . . . . . . . . . . 885Where DFSORT formats can be used . . . . . 893DFSORT formats for COBOL data types . . . . 896

Appendix D. EBCDIC and ASCIIcollating sequences . . . . . . . . 899EBCDIC . . . . . . . . . . . . . . . 899ASCII . . . . . . . . . . . . . . . . 901

Appendix E. DFSORT abendprocessing . . . . . . . . . . . . 905Checkpoint/restart . . . . . . . . . . . 905DFSORT abend categories . . . . . . . . . 906Abend recovery processing for unexpected abends 906Processing of error abends with A-type messages 907CTRx abend processing . . . . . . . . . . 907

Appendix F. Accessibility . . . . . . 909Accessibility features . . . . . . . . . . . 909Consult assistive technologies . . . . . . . . 909Keyboard navigation of the user interface . . . . 909Dotted decimal syntax diagrams . . . . . . . 909

Notices . . . . . . . . . . . . . . 913Terms and conditions for product documentation 915IBM Online Privacy Statement. . . . . . . . 916Policy for unsupported hardware. . . . . . . 916Minimum supported hardware . . . . . . . 916Programming interface information . . . . . . 917Trademarks . . . . . . . . . . . . . . 917

Index . . . . . . . . . . . . . . . 919

Contents vii

viii z/OS DFSORT Application Programming Guide

Figures

1. Control Fields . . . . . . . . . . . . 62. Record Processing Order . . . . . . . . 103. Using ICETOOL to List Installation Defaults 194. Control Statement Format . . . . . . . . 865. Continuation Line Format. . . . . . . . 886. Sample Records . . . . . . . . . . . 1127. OUTFIL Processing Order . . . . . . . 2338. Examples of Notation for Binary Fields 4489. JOINKEYS Application Processing . . . . 462

10. Examples of DFSORT Input/UserExit/Output Logic . . . . . . . . . . 493

11. E18 User Exit Example . . . . . . . . 51212. E38 User Exit Example . . . . . . . . 52413. E39 User Exit Example . . . . . . . . 52514. E15 User Exit Example . . . . . . . . 52615. E16 User Exit Example . . . . . . . . 52616. E35 User Exit Example . . . . . . . . 52717. E61 User Exit Example . . . . . . . . 52818. E15 DFSORT Interface with COBOL . . . . 53219. LINKAGE SECTION Code Example for E15

(Fixed-Length Records) . . . . . . . . 53320. LINKAGE SECTION Code Example for E15

(Variable-Length Record). . . . . . . . 53321. E35 Interface with COBOL . . . . . . . 53822. LINKAGE SECTION Code Example for E35

(Fixed-Length Records) . . . . . . . . 53923. LINKAGE SECTION Code Example for E35

(Variable-Length Records) . . . . . . . 539

24. COBOL E15 Routine Example (FLR) . . . . 54325. COBOL E35 Routine Example (VLR) 54426. The 24-Bit Parameter List . . . . . . . 55127. The Extended Parameter List . . . . . . 55728. The 64-Bit Parameter List . . . . . . . 56129. Coding a 24-Bit Parameter List. . . . . . 56630. Coding an Extended Parameter List . . . . 56731. Simple ICETOOL Job . . . . . . . . . 57332. Parameter List for Parameter List Interface 73033. ICETOOL Parameter List Interface Example 73334. JCL for Parameter List Interface Program

Example . . . . . . . . . . . . . 73435. Relationship Between DFSORT and an EFS

Program . . . . . . . . . . . . . 77436. EFS Program Calls for a Sort . . . . . . 77537. EFS Program Calls for a Merge or Copy 77638. Control Statement Processing Sequence 78139. EFS Interface Parameter List . . . . . . 78440. Information Flags . . . . . . . . . . 79341. DFSORT Register Convention . . . . . . 79542. Calling Sequence to EFS02 by DFSORT 79743. EFS Record Processing Sequence for a Sort or

Merge . . . . . . . . . . . . . . 80044. EFS Record Processing Sequence for a Copy 80145. Faster Sorting with COBOL . . . . . . . 810

Copyright IBM Corp. 1973, 2017 ix

x z/OS DFSORT Application Programming Guide

Tables

1. Related documentation . . . . . . . . xiv2. Reference documentation . . . . . . . . xv3. Documents to help you work more effectively

with DFSORT. . . . . . . . . . . . xv4. Options That Can Ease Migration . . . . . 255. FILSZ Variations Summary. . . . . . . . 456. Aliases for MSGPRT/MSGCON Options 507. Aliases for PARM Options . . . . . . . 628. DD Statement Parameters Used by DFSORT 649. DCB Subparameters Used by DFSORT . . . 65

10. Compare Field Formats and Lengths 10211. Permissable Field-to-Field Comparisons for

INCLUDE/OMIT (Group 1) . . . . . . 10312. Permissable Field-to-Field Comparisons for

INCLUDE/OMIT (Group 2) . . . . . . 10313. Permissible Field-to-Constant Comparisons

for INCLUDE/OMIT . . . . . . . . . 10414. Valid and Invalid Decimal Constants 10515. Decimal Numbers for Current Date . . . . 10516. Decimal Numbers for Future Dates . . . . 10617. Decimal Numbers for Past Dates . . . . . 10618. Valid and Invalid Character String Constants 10619. Valid and Invalid Strings with Double-Byte

Data . . . . . . . . . . . . . . 10720. Character Strings for Current Date . . . . 10721. Character Strings for Future Dates . . . . 10822. Character Strings for Past Dates . . . . . 10923. Valid and Invalid Hexadecimal Constants 10924. Bit Comparison Example 2: Results for

Selected Field Values . . . . . . . . . 11625. Bit Comparison Example 3: Results for



Selected Field Values . . . . . . . . . 11928. Permissible Comparisons for Dates . . . . 12129. Logic Table for INCLUDE/OMIT. . . . . . 12630. Examples of Valid and Invalid Column

Alignment . . . . . . . . . . . . 13231. Examples of Valid and Invalid Blank

Separation . . . . . . . . . . . . 13332. Examples of Valid and Invalid Binary Zero

Separation . . . . . . . . . . . . 13333. Examples of Valid and Invalid Character

String Separation . . . . . . . . . . 13334. Examples of Valid and Invalid Hexadecimal

String Separation . . . . . . . . . . 13435. Example of DYNSPC Primary Space . . . . 18636. FILSZ Variations Summary . . . . . . . 19137. SIZE Variations Summary . . . . . . . 19138. SDB=LARGE Block Sizes for Tape Output

Data Sets . . . . . . . . . . . . . 20739. Aliases for OPTION Statement Options 22140. Current date constants . . . . . . . . 26141. Future Date Constants . . . . . . . . 262

42. Past Date Constants . . . . . . . . . 26343. Current time constants . . . . . . . . 26444. TRAN=ATOE ASCII-to-EBCDIC translation 26945. TRAN=ETOA ASCII-to-EBCDIC translation 27046. Edit Field Formats and Lengths . . . . . 27247. Edit Mask Patterns. . . . . . . . . . 27448. Edit Mask Signs . . . . . . . . . . 27649. Digits Needed for Numeric Fields . . . . 27750. Edit Mask Output Field Lengths . . . . . 27751. To Output Field Lengths . . . . . . . . 28352. Input and result fields for Yxx date editing 28753. Input fields for p,m,Yxx date conversion 28954. TOJUL and TOGREG output date fields 29055. Output for weekdays . . . . . . . . . 29056. Output for weeknum . . . . . . . . . 29157. p,m,Yxx fields for date arithmetic . . . . . 29458. Input and result fields for Yxx(s) date editing 29859. Input and result fields for Yxx(s) date editing 29960. Digits for TOTAL Fields . . . . . . . . 35161. Control Field Formats and Lengths . . . . 44862. Summary Field Formats and Lengths 45663. Functions of Routines at Program User Exits

(Sort) . . . . . . . . . . . . . . 49564. Functions of Routines at Program User Exits

(Copy and Merge) . . . . . . . . . . 49565. Summary of 64-bit Terminology for Exits 49866. Addressing Mode Flags for Exits in 64-bit

Parameter List . . . . . . . . . . . 49967. Block list parameters for E15 exit . . . . . 50568. 32-bit E15 User Exit Parameter List . . . . 50669. 64-bit E15 User Exit Parameter List . . . . 50670. 32-bit E32 User Exit Parameter List . . . . 51671. 64-bit E32 User Exit Parameter List . . . . 51672. Block list parameters for E35 exit . . . . . 51973. 32-bit E35 User Exit Parameter List . . . . 52074. 64-bit E35 User Exit Parameter List . . . . 52175. E15 Without a SORTIN Data Set . . . . . 54576. E15 With a SORTIN Data Set Before End of

Input . . . . . . . . . . . . . . 54577. E15 With a SORTIN Data Set After End of

Input . . . . . . . . . . . . . . 54578. E35 With a SORTOUT or OUTFIL Data Set

Before End of Input . . . . . . . . . 54579. E35 Without a SORTOUT or OUTFIL Data Set

Before End of Input . . . . . . . . . 54680. E35 With a SORTOUT or OUTFIL Data Set

After End of Input . . . . . . . . . . 54681. E35 without a SORTOUT or OUTFIL Data Set

After End of Input . . . . . . . . . . 54682. Aliases for Message Option . . . . . . . 55483. Summary of 64-bit Terminology for Programs 55984. Obtaining Various Statistics . . . . . . . 57485. Creating Multiple Versions/Combinations of

Data Sets . . . . . . . . . . . . . 57586. JCL Statements for ICETOOL . . . . . . 57787. Attributes of Edit Masks . . . . . . . . 608

Copyright IBM Corp. 1973, 2017 xi

||

||

88. Edit Mask Patterns. . . . . . . . . . 60989. Return Area Lengths/Operation-Specific

Values . . . . . . . . . . . . . . 73190. Functions of an Extended Function Support

(EFS) Program . . . . . . . . . . . 77991. D1 Format Returned by an EFS Program 79092. Correlator Identifier and D2 Format Returned

by an EFS Program . . . . . . . . . 79193. Original and Altered Control Statements 80394. Number of Tracks per Cylinder for Disk

Devices . . . . . . . . . . . . . 80795. Minimum Storage Required for Various File

Sizes . . . . . . . . . . . . . . 86196. Work Space Requirements for Various Input

Characteristics . . . . . . . . . . . 86597. Number of Tracks per Cylinder for Disk

Devices . . . . . . . . . . . . . 866

98. Work Space Requirements of the Various TapeTechniques . . . . . . . . . . . . 866

99. Directly Invoked DFSORT OptionSpecification/Override . . . . . . . . 872

100. Extended Parameter List DFSORT OptionSpecification/Override . . . . . . . . 876

101. 24-Bit List DFSORT OptionSpecification/Override . . . . . . . . 881

102. Allowed with Frequently Used Data Types 893103. Allowed with Other Data Types . . . . . 894104. UTF8/UTF16/UTF32 . . . . . . . . . 895105. Equivalent DFSORT formats for various

COBOL data types . . . . . . . . . . 897106. EBCDIC Collating Sequence . . . . . . 899107. ASCII Collating Sequence . . . . . . . 901

xii z/OS DFSORT Application Programming Guide

||

About this document

This document is intended to help you to sort, merge, and copy data sets usingDFSORT. This document is not designed to teach you how to use DFSORT, but isfor programmers who already have a basic understanding of DFSORT, and need atask-oriented guide and reference to its functions and options. If you are a newuser, then you should read z/OS DFSORT: Getting Started first.

z/OS DFSORT: Getting Started is a self-study guide that tells you what you need toknow to begin using DFSORT quickly, with step-by-step examples andillustrations.

How to use this documentThe various sections of this document present related information groupedaccording to tasks you want to do. The first three chapters of the document explainwhat you need to know to invoke and use DFSORT's primary record-processingfunctions. The remaining chapters explain more specialized features. Theappendixes provide specific information about various topics.v Chapter 1, Introducing DFSORT, on page 1, presents an overview of DFSORT,

explaining what you can do with DFSORT and how you invoke DFSORTprocessing. It describes how DFSORT works, discusses data set formats andlimitations, and explains how installation defaults can affect your DFSORTapplications.

v Chapter 2, Invoking DFSORT with Job Control Language, on page 29, explainshow to use job control language (JCL) to run your DFSORT jobs. It explains howto code JOB, EXEC, and DD statements, and how you can use catalogedprocedures and EXEC PARM options to simplify your JCL and overrideinstallation defaults.

v Chapter 3, Using DFSORT program control statements, on page 83, presentsthe DFSORT control statements you use to sort, merge, and copy data. Itexplains how to filter your data so you work only with the records you need,how to edit data by reformatting and summing records, and how to producemultiple output data sets and reports. It explains how to write statements thatdirect DFSORT to use your own routines during processing.

v Chapter 4, Using a JOINKEYS application for joining two files, on page 461explains how you can perform various types of "join" applications on two files(F1 and F2) by one or more keys with DFSORT. It explains the JCL and controlstatements you can use for JOINKEYS applications.

v Chapter 5, Using your own user exit routines, on page 491, describes how touse DFSORT's program exits to call your own routines during programprocessing. You can write routines to delete, insert, alter, and summarize records,and you can incorporate your own error-recovery routines.

v Chapter 6, Invoking DFSORT from a program, on page 547, describes how youuse a system macro instruction to initiate DFSORT processing from your ownassembler program. It also lists specific restrictions on invoking DFSORT fromPL/I and COBOL.

v Chapter 7, Using ICETOOL, on page 569, describes how to use themulti-purpose DFSORT utility ICETOOL. It explains the JCL and operators youcan use to perform a variety of tasks with ICETOOL.

Copyright IBM Corp. 1973, 2017 xiii

v Chapter 8, Using symbols for fields and constants, on page 737, explains howto define symbols and use them in DFSORT control statements and ICETOOLoperators.

v Chapter 9, Using extended function support, on page 773, explains how to usethe Extended Function Support (EFS) interface to tailor control statements, tohandle user-defined data types and collating sequences, and to have DFSORTissue customized informational messages during processing.

v Chapter 10, Improving efficiency, on page 805, recommends ways with whichyou can maximize DFSORT processing efficiency. This chapter covers a widespectrum of improvements you can make, from designing individualapplications for efficient processing at your site to using DFSORT features suchas Hipersorting, dataspace sorting, and ICEGENER.

v Chapter 11, Examples of DFSORT job streams, on page 825, contains annotatedexample job streams for sorting, merging, and copying records.

v Appendix A, Using work space, on page 859, explains main storageconsiderations and how to estimate the amount of intermediate storage youmight require when sorting data.

v Appendix B, Specification/override of DFSORT options, on page 869, containsa series of tables you can use to find the order of override for similar optionsthat are specified in different sources.

v Appendix C, Data format descriptions, on page 885, gives examples of theassembled data formats.

v Appendix D, EBCDIC and ASCII collating sequences, on page 899, lists thecollating sequences from low to high order for EBCDIC and ASCII characters.

v Appendix E, DFSORT abend processing, on page 905, describes the ESTAErecovery routine for processing abends, and the Checkpoint/Restart facility.

Required product knowledgeTo use this document effectively, you should be familiar with the followinginformation:v Job control language (JCL)v Data managementv Tape and disk hardware

You should also be familiar with the information presented in the following relateddocuments:

Table 1. Related documentation

Related Documentation

z/OS DFSORT Messages, Codes and Diagnosis Guide

z/OS MVS JCL Reference

z/OS MVS JCL User's Guide

z/OS DFSMS Using Data Sets

z/OS DFSMS Using Magnetic Tapes

xiv z/OS DFSORT Application Programming Guide

Referenced documentsThis document refers to the following documents:

Table 2. Reference documentation

Reference documentation

z/OS DFSMSdfp Checkpoint/Restart

z/OS DFSMS Macro Instructions for Data Sets

z/OS DFSMS Using Data Sets

z/OS MVS JCL Reference

z/OS MVS JCL User's Guide

z/OS MVS Programming: Assembler Services Reference IAR-XCT

z/OS MVS Programming: Assembler Services Guide

z/OS Install/Migration page (www.ibm.com/systems/z/os/zos/installation)

z/OS UNIX System Services User's Guide

The z/OS DFSORT Application Programming Guide is a part of a more extensiveDFSORT library. These documents can help you work with DFSORT moreeffectively.

Table 3. Documents to help you work more effectively with DFSORT.

Task Documentation

Planning for and Customizing DFSORT z/OS DFSORT Installation and Customization

Learning to use DFSORT z/OS DFSORT: Getting Started

Diagnosing DFSORT Failures andInterpreting DFSORT Messages

z/OS DFSORT Messages, Codes and DiagnosisGuide

Tuning DFSORT z/OS DFSORT Tuning Guide

Notational conventionsThe syntax diagrams in this document are designed to make coding DFSORTprogram control statements simple and unambiguous. The lines and arrowsrepresent a path or flowchart that connects operators, parameters, and delimiters inthe order and syntax in which they must appear in your completed statement.Construct a statement by tracing a path through the appropriate diagram thatincludes all the parameters you need, and code them in the order that the diagramrequires you to follow. Any path through the diagram gives you a correctly codedstatement, if you observe these conventions:v Read the syntax diagrams from left to right and from top to bottom.v Begin coding your statement at the spot marked with the double arrowhead.

v A single arrowhead at the end of a line indicates that the diagram continues onthe next line or at an indicated spot.

About this document xv

http://www.ibm.com/systems/z/os/zos/installation

A continuation line begins with a single arrowhead.

v Strings in upper-case letters, and punctuation (parentheses, apostrophes, and soon), must be coded exactly as shown. Semicolons are interchangeable with commas in program control statements

and the EXEC PARM string. For clarity, only commas are shown in thisdocument.

v Strings in all lowercase letters represent information that you supply.v Required parameters appear on the same horizontal line (the main path) as the

operator, while optional parameters appear in a branch below the main path.

RequiredOptional

v Where you can make one choice between two or more parameters, thealternatives are stacked vertically.

Operator Required Choice 1Required Choice 2Required Choice 3

Optional Choice 1Optional Choice 2

If one choice within the stack lies on the main path (as in this example, left), youmust specify one of the alternatives. If the stack is placed below the main path(as in this example, right), then selections are optional, and you can chooseeither one or none of them.

v The repeat symbol shows where you can return to an earlier position in thesyntax diagram to specify a parameter more than once (see the first examplelater in this section), to specify more than one choice at a time from the samestack (see the second example later in this section), or to nest parentheses (seethe third example later in this section).

Do not interpret a repeat symbol to mean that you can specify incompatibleparameters. For instance, do not specify both ABEND and NOABEND in thesame EXEC statement, or attempt to nest parentheses incorrectly.Use any punctuation or delimiters that appear within the repeat symbol toseparate repeated items.

v A double arrowhead at the end of a line indicates the end of the syntax diagram.

a,b,c Choice-1Choice-2Choice-3

, (,

Notational Conventions

xvi z/OS DFSORT Application Programming Guide


About this document xvii


xviii z/OS DFSORT Application Programming Guide

How to send your comments to IBM

We appreciate your input on this documentation. Please provide us with anyfeedback that you have, including comments on the clarity, accuracy, orcompleteness of the information.

Use one of the following methods to send your comments:

Important: If your comment regards a technical problem, see instead If you havea technical problem.v Send an email to [email protected] Send an email from the Contact z/OS web page (www.ibm.com/systems/z/os/

zos/webqs.html).

Include the following information:v Your name and addressv Your email addressv Your phone or fax numberv The publication title and order number:

z/OS DFSORT Application Programming GuideSC23-6878-30

v The topic and page number or URL of the specific information to which yourcomment relates

v The text of your comment.

When you send comments to IBM, you grant IBM a nonexclusive right to use ordistribute the comments in any way appropriate without incurring any obligationto you.

IBM or any other organizations use the personal information that you supply tocontact you only about the issues that you submit.

If you have a technical problemDo not use the feedback methods that are listed for sending comments. Instead,take one or more of the following actions:v Visit the IBM Support Portal (support.ibm.com).v Contact your IBM service representative.v Call IBM technical support.

Copyright IBM Corp. 1973, 2017 xix

mailto:[email protected]://www.ibm.com/systems/z/os/zos/webqs.htmlhttp://www.ibm.com/systems/z/os/zos/webqs.htmlhttp://support.ibm.com

xx z/OS DFSORT Application Programming Guide

Summary of changes

Summary of changes for z/OS Version 2 Release 3This document contains information that was previously presented in z/OSDFSORT Application Programming Guide, SC23-6878-01, which supported z/OSVersion 2 Release 2.

The following sections summarize the changes to that information.

The message ICE290A is will be issued for the following additional situation:v The E15 or E35 exit was specified with block support, but the required address

of the user block list parameter area was not present in the 64-bit invocationparameter list or the block list type is invalid in the user block list parameterarea.

Any automated actions based on the presence of this message should be evaluated.

New informationThis edition includes the following new enhancements:

Sort/Merge of Unicode data:DFSORT now supports the Sorting and Merging of Unicode data. This supportallows users to:v SORT/MERGE Unicode Data with control field length of 1 to 450 Unicode

characters for UTF-8 format data.v SORT/MERGE Unicode Data with control field length of 1 to 450 Unicode

characters for UTF-16 format data.v SORT/MERGE Unicode Data with control field length of 1 to 450 Unicode

characters for UTF-32 format data.

E15/E35 Block supportE15/E35 exits have been enhanced to support the transfer of block of recordsbetween DFSORT and the E15/E35 exits.

Performance ImprovementsDFSORT is enhanced to provide performance improvements for several DFSORTfunctions that generate code at run time. The enhancements will improveperformance in both CPU and elapsed times. The design of performanceimprovements are based on the concept of storing data into the "256 byte area forthe Instruction Cache". DFSORT's design has the ability to write data directly intothe instruction cache stream. Modern processors can also access a portion of thiscache and may invalidate the instructions stored by DFSORT. In the modernprocessors like z13, the instruction cache stream is considered to be any locationwithin the same 256-byte block of storage where an instruction resides, regardlessof whether that location contains an actual instruction. This means that storingdata into the same 256 byte block of an instruction can cause an impact onperformance.

The following functions will see improvements in both CPU and elapsed times.v INCLUDE COND Processing

Copyright IBM Corp. 1973, 2017 xxi

v OMIT COND processingv SORT statement with more than 5 keys

Message changesThe following changes are made to z/OS Version 2 Release 3 (V2R3).

The following messages are new, changed, or no longer issued for z/OS DFSORTApplication Programming Guide in z/OS V2R3.

New

The following messages are new.ICE292AICE500AICE501AICE502AICE503AICE504AICE505AICE506I

New Reserved Words for SymbolsThe following are new DFSORT/ICETOOL reserved words which are no longerallowed as symbols: UTF8, UTF16, UTF32, and COLLKEY. If you used any of thesewords as a symbol previously, you must change them. For example, if you usedUTF8, you can change it to utf8.

Summary of changes for SC23-6878-01 z/OS Version 2 Release 2This document contains information that was previously presented in z/OSDFSORT Application Programming Guide, SC28-6878-00, which supported z/OSVersion 2 Release 1.


The message ICE099A is enhanced to list the failing member name in case of anerror. Any automated actions based on the presence of this message should beevaluated.

The text for existing DFSORT messages ICE000I and ICE288I has been changed.Any automated actions based on the presence of these messages should beevaluated.


High Performance Ficon (HPF) ExploitationA program that invokes DFSORT, ICETOOL or ICEGENER will now be able toexploit the High Performance Ficon (zHPF) hardware. When zHPF is available,DFSORT SORT or MERGE applications will use BSAM for SORTIN, SORTOUT,and OUTFIL data sets.

xxii z/OS DFSORT Application Programming Guide

Date functionsTwo new date functions to calculate the week number of a given date and Age asdate duration are added.

WEEKNUM function converts a given Julian/Gregorian date to number of week.There are 2 versions of this function, the standard USA format and the ISO format.

WEEKNUM=USA function returns an integer in the range of 1 to 54 thatrepresents the week of the year. The week starts with Sunday, and January 1 isalways in the first week.

WEEKNUM=ISO function returns an integer in the range of 1 to 53 that representsthe week of the year. The week starts with Monday and includes 7 days. Week 1 isthe first week of the year to contain a Thursday, which is equivalent to the firstweek containing January 4.

AGE function returns a date duration that specifies the number of years, months,and days between an input date and current date.

Age=YMD produces an 8-byte result which has duration in years (0-9999), months(00-12), and days (00-31).

Age=YM produces a 6-byte result which has duration in years (0-9999), months(00-12).

Age=YD produces a 7-byte result which has duration in years (0-9999), days(00-366).

Message changesThe text for existing DFSORT messages has been changed. Any automated actionsbased on the presence of these messages should be evaluated.

ICE000IICE099AICE121AICE288I

Summary of changes for SC23-6878-00 z/OS Version 2 Release 1This document contains information that was previously presented in z/OSDFSORT Application Programming Guide, SC26-7523-07, which supported z/OSVersion 1.



64-bit supportEligible user programs and exits can now be written to:v Call DFSORT from a program in 64-bit addressing mode (AMODE 64) using a

new 64-bit parameter list and the entry name ICEMAN64 or SORT64v Use DFSORT E15, E35 and E32 exits running in 64-bit addressing mode

(AMODE 64)

Summary of changes xxiii

v Pass 64-bit addressed records to DFSORT using new 64-bit parameter lists forE15, E32 and E35 exits.

Performance and resource usage improvementsDFSORT has been enhanced to improve use of central storage in relation to systemactivity. The existing EXPMAX, EXPOLD and EXPRES installation options will nowbe evaluated in conjunction with available resources at run-time which can giveyou better control over how DFSORT uses available central storage resources. Thelikelihood of over committed central storage resources and excessive paging hasbeen reduced, which can provide improved reliability and performance for allworkloads including DFSORT.

The shipped default for EXPOLD is changed from MAX to 50%. The shippeddefault for EXPRES is changed from 0 to 10%.

DFSORT has been enhanced to allocate storage in smaller increments and thencheck resource availability before each additional increment is reserved. This canallow concurrent sort applications to better share available storage and allows sortsto stop allocating additional storage if resources are no longer available.Additionally, DFSORT's dynamic allocation of work data sets will be adjusted toreduce the likelihood of failure when a sort application is unable to obtain all ofthe expected central storage and must then use more disk work space thanexpected.

A new TUNE installation default allows you to specify whether DFSORT shouldallocate storage in increments with additional disk work space to minimize the riskof failure, or to allocate all storage at initialization so disk work space allocationcan be reduced.

Blockset merge applications can now use storage above 16 MB virtual with morefunctions (such as E61, INREC, OUTREC, INCLUDE, OMIT and SUM), providingimproved performance and virtual storage constraint relief.

XTIOT, uncaptured UCBs and DSAB above 16 megabytes virtualWork data sets dynamically allocated by DFSORT will use options for XTIOT,uncaptured UCBs, and DSAB above 16 megabyte virtual to the extent that z/OSsupports them.

Extended address volumesDFSORT support for EAS-eligible data set types on Extended Address Volumes hasbeen enhanced to increase the maximum size of a DFSORT work data set. With fulltrack blocking, the maximum number of tracks that can be used for a single workdata set has been increased from 1048576 to 16777215. In situations where DFSORTmust use a reduced block size for the work data sets, less than 16777215 tracks canbe used.

Alphanumeric comparison testsNew UC, LC, MC, UN, LN and MN keywords (similar to the previously availableNUM keyword) now allow you to test a field for various combinations ofalphanumeric characters or non-alphanumeric characters using binary (BI) format.

The new keywords allow you to select any of the following alphanumericcharacter sets:v UC: Uppercase characters (A-Z)v LC: Lowercase characters (a-z)v MC: Mixed case characters (A-Z, a-z)

xxiv z/OS DFSORT Application Programming Guide

v UN: Uppercase and numeric characters (A-Z, 0-9)v LN: Lowercase and numeric characters (a-z, 0-9)v MN: Mixed case and numeric characters (A-Z, a-z, 0-9)

You can use these new keywords in the following comparison operands: COND,INCLUDE, OMIT, BEGIN, END, WHEN and TRLID.

More PARSE fieldsYou can now use up to 1000 parsed fields (%0-%999) with the PARSE function; theprevious limit was 100 parsed fields (%0-%99).

Repeating PARSE fieldsREPEAT=v is a new PARSE option that can be used to repeat a particular parsefield definition multiple times.

REPEAT=v can be used with % to specify v identically defined consecutive parsedfields to be ignored.

REPEAT=v can be used with %n, %nn or %nnn to specify v identically definedconsecutive parsed fields for which data is to be extracted. The parsed fields willstart with the %n, %nn or %nnn field you select and be incremented by one foreach repeated parsed field.

Alphanumeric tests for PARSE fieldsSTARTAFT=an, STARTAT=an, ENDBEFR=an and ENDAT=an can now be usedwith the PARSE function to start or end when a character from any of variousalphanumeric character sets is found. New keywords for an allow you to selectany of the following alphanumeric character sets:v UC: Uppercase characters (A-Z)v LC: Lowercase characters (a-z)v MC: Mixed case characters (A-Z, a-z)v UN: Uppercase and numeric characters (A-Z, 0-9)v LN: Lowercase and numeric characters (a-z, 0-9)v MN: Mixed case and numeric characters (A-Z, a-z, 0-9)v NUM: Numeric characters (0-9)

Insert a string at the end of variable-length recordsVLTRAIL=string is a new OUTFIL option that allows you to insert a characterstring (C'string') or hexadecimal string (X'yy...yy') at the end of each variable-lengthOUTFIL output record.

Symbol enhancementsDFSORT Symbols can now be used for many more operands. The followingoperands of the form KEYWORD=n can now be specified as KEYWORD=symbolwhere symbol represents an equivalent number (for example, if you haveNew_Length,25 in SYMNAMES, you can use LENGTH=New_Length whereveryou can use LENGTH=25): ABSPOS, ACCEPT, ADDPOS, AVGRLEN, DO,ENDPOS, ENDREC, FIXLEN, ID, IFOUTLEN, INCR, LENGTH, LINES, MAXLEN,RECORDS, REPEAT, SAMPLE, SEQ, SKIPREC, SPLIT1R, SPLITBY, START,STARTPOS, STARTREC, STOPAFT and SUBPOS.

A symbol for a number can now be used for the length of the output field with theCHANGE operand, and for the length of the sequence number with the SEQNUMoperand.

Summary of changes xxv

A symbol can be used for any of the new %000-%999 parsed fields.

A symbol can be used for string with the new VLTRAIL=string operand.

Improved diagnosticsDFSORT now provides specific reason codes and associated documentation to aidin diagnosing and correcting errors associated with messages ICE083A andICE141A.

The text for message ICE118I has been changed to recommend the use ofFILSZ=En.

The ICE236I options-in-effect message now includes values for TUNE, EXPMAX,EXPOLD and EXPRES.

The text for message ICE285A has been changed for clarification.

Operational changes that may require user actionThe following are operational changes that may require user action for existingDFSORT/ICETOOL applications that use certain functions as specified:

Central storage controlsThe IBM-supplied default for the existing EXPOLD installation option has beenchanged to EXPOLD=50%. If you want DFSORT to use EXPOLD, as in previousreleases, you can set EXPOLD=MAX.

The IBM-supplied default for the existing EXPRES installation option has beenchanged to EXPRES=10%. If you want DFSORT to use EXPRES, as in previousreleases, you can set EXPRES=0.

The IBM-supplied default for the new TUNE installation option is TUNE=STORwhich specifies allocation of available central storage as needed in increments sizedto balance resource usage for concurrent sorts. If you want DFSORT to allocateavailable central storage using fixed sized increments, as in previous releases, youcan set TUNE=OLD.

Message changesThe text for existing DFSORT messages ICE000I, ICE083A, ICE118I, ICE141A,ICE236I and ICE285A has been changed. Any automated actions based on thepresence of these messages should be evaluated.

New Reserved Words for SymbolsThe following are new DFSORT/ICETOOL reserved words which are no longerallowed as symbols: LC, LN, MC, MN, UC and UN.

If you used any of these words as a symbol previously, you must change them. Forexample, if you used MC, you can change it to mc.

xxvi z/OS DFSORT Application Programming Guide

Chapter 1. Introducing DFSORT

DFSORT overviewThis chapter introduces IBM z/OS DFSORT Licensed Program 5650-ZOS.

DFSORT is intended to run in problem state and in a user key ( that is, key 8 orhigher).

DFSORT is a program you use to sort, merge, and copy information.v When you sort records, you arrange them in a particular sequence, choosing an

order more useful to you than the original one.v When you merge records, you combine the contents of two or more previously

sorted data sets into one.v When you copy records, you make an exact duplicate of each record in your data

set.

Merging records first requires that the input data sets are identically sorted for theinformation you will use to merge them and that they are in the same orderrequired for output. You can merge up to 100 different data sets at a time.

In addition to the three basic functions, you can perform other processingsimultaneously:

You can control which records to keep in the final output data set of a DFSORTrun by using INCLUDE and OMIT statements in your application. Thesestatements work like filters, testing each record against criteria that you supplyand retaining only the ones you want for the output data set. For example, youmight choose to work only with records that have a value of Kuala Lumpur inthe field reserved for office location. Or perhaps you want to leave out any recorddated after 2001 if it also contains a value greater than 20 for the number ofemployees.

You can parse, edit, and reformat your records before or after other processing byusing INREC and OUTREC statements. INREC and OUTREC statements support awide variety of reformatting tasks including:v The use of fixed position/length fields or variable position/length fields. For

fixed fields, you specify the starting position and length of the field directly. Forvariable fields, such as delimited fields, comma separated values (CSV), tabseparated values, blank separated values, keyword separated fields,null-terminated strings (and many other types), you define rules that allowDFSORT to extract the relevant data into fixed parsed fields, and then use theparsed fields as you would use fixed fields.

v Insertion of blanks, zeros, strings, current date, future date, past date, currenttime, sequence numbers, decimal constants, and the results of arithmeticexpressions before, between, and after the input fields in the reformattedrecords.

v Sophisticated conversion capabilities, such as find and replace, hexadecimaldisplay, bit display, translation of EBCDIC letters from lowercase to uppercase oruppercase to lowercase, translation of characters from EBCDIC to ASCII andfrom ASCII to EBCDIC, translation of characters using the ALTSEQ translationtable, conversion of numeric values from one format to another, left-justify or

Copyright IBM Corp. 1973, 2017 1

left-squeeze (remove leading blanks or all blanks and shift left), and right-justifyor right-squeeze (remove trailing blanks or all blanks and shift right).

v Sophisticated editing capabilities, such as control of the way numeric fields arepresented with respect to length, leading or suppressed zeros, thousandsseparators, decimal points, leading and trailing positive and negative signs, andso on.Twenty-seven pre-defined editing masks are available for commonly usednumeric editing patterns, encompassing many of the numeric notations usedthroughout the world. In addition, a virtually unlimited number of numericediting patterns are available via user-defined editing masks.

v Transformation of SMF, TOD, and ETOD date and time values to more usableforms.

v Conversion of input date fields of one type (CH, ZD, PD, 2-digit year, 4-digityear, Julian, Gregorian) to corresponding output date fields of another type or toa corresponding day of the week.

v Various types of arithmetic operations for input date fields.v Selection of a character constant, hexadecimal constant, or input field from a

lookup table for output, based on a character, hexadecimal, or bit string as input(that is, lookup and change).

You can create the reformatted INREC or OUTREC records in one of the followingways:v By building the entire record one item at a time.v By only overlaying specific columns.v By performing find and replace operations.v By using sophisticated conditional logic or group operations to choose how

different records are reformatted.

You can sum numeric information from many records into one record with theSUM statement. For example, if you want to know the total amount of a yearlypayroll, you can add the values for a field containing salaries from the records ofall your employees.

You can create one or more output data sets for a sort, copy, or merge applicationfrom a single pass over one or more input data sets by using OUTFIL controlstatements. You can use multiple OUTFIL statements, with each statementspecifying the OUTFIL processing to be performed for one or more output datasets. OUTFIL processing begins after all other processing ends (that is, afterprocessing for exits, options, and other control statements). OUTFIL statementssupport a wide variety of output data set tasks, including:v Creation of multiple output data sets containing unedited or edited records from

a single pass over one or more input data sets.v Creation of multiple output data sets containing different ranges or subsets of

records from a single pass over one or more input data sets. In addition, recordsthat are not selected for any subset can be saved in a separate output data set.

v Conversion of variable-length record data sets to fixed-length record data sets.v Conversion of fixed-length record data sets to variable-length record data sets.v A wide variety of parsing, editing and reformatting tasks including:

The use of fixed position/length fields or variable position/length fields. Forfixed fields, you specify the starting position and length of the field directly.For variable fields, such as delimited fields, comma separated values (CSV),tab separated values, blank separated values, keyword separated fields,

DFSORT Overview

2 z/OS DFSORT Application Programming Guide

null-terminated strings (and many other types), you define rules that allowDFSORT to extract the relevant data into fixed parsed fields, and then use theparsed fields as you would use fixed fields.

Insertion of blanks, zeros, strings, current date, future date, past date, currenttime, sequence numbers, decimal constants, and the results of arithmeticexpressions before, between, and after the input fields in the reformattedrecords.

Sophisticated conversion capabilities, such as find and replace, hexadecimaldisplay, bit display, translation of EBCDIC letters from lowercase to uppercaseor uppercase to lowercase, translation of characters from EBCDIC to ASCII orfrom ASCII to EBCDIC, translation of characters using the ALTSEQtranslation table, conversion of numeric values from one format to another,left-justify or left-squeeze (remove leading blanks or all blanks and shift left),and right-justify or right-squeeze (remove trailing blanks or all blanks andshift right).

Sophisticated editing capabilities, such as control of the way numeric fieldsare presented with respect to length, leading or suppressed zeros, thousandsseparators, decimal points, leading and trailing positive and negative signs,and so on.Twenty-seven pre-defined editing masks are available for commonly usednumeric editing patterns, encompassing many of the numeric notations usedthroughout the world. In addition, a virtually unlimited number of numericediting patterns are available via user-defined editing masks.

Transformation of SMF, TOD, and ETOD date and time values to more usableforms.

Conversion of input date fields of one type (CH, ZD, PD, 2-digit year, 4-digityear, Julian, Gregorian) to corresponding output date fields of another type orto a corresponding day of the week.

Various types of arithmetic operations for input date fields. Selection of a character constant, hexadecimal constant, or input field from a

lookup table for output, based on a character, hexadecimal, or bit string asinput (that is, lookup and change).

v Creation of the reformatted records in one of the following ways: By building the entire record one item at a time. By only overlaying specific columns. By performing find and replace operations. By using sophisticated conditional logic or group operations to choose how

different records are reformatted.v Highly detailed three-level (report, page, and section) reports containing a

variety of report elements you can specify (for example, current date, currenttime, edited or converted page numbers, character strings, and blank lines) orderive from the input records (for example, character fields; unedited, edited, orconverted numeric input fields; edited or converted record counts; and edited orconverted totals, maximums, minimums, and averages for numeric input fields).

v Creation of multiple output records from each input record, with or withoutintervening blank output records.

v Repetition and sampling of data records.v Splitting of data records in rotation among a set of output data sets.

You can perform various "join" operations on two files by one or more keys. AJOINKEYS application allows you to create joined records in a variety of waysincluding inner join, full outer join, left outer join, right outer join and unpaired

DFSORT Overview

Chapter 1. Introducing DFSORT 3

combinations. The two input files can be of different types (fixed, variable, VSAM,and so on) and have keys in different locations. The records from the two inputfiles can be processed in a variety of ways before and after they are joined.

You can control DFSORT functions with other control statements by specifyingalternate collating sequences, invoking user exit routines, overriding installationdefaults, and so on.

You can direct DFSORT to pass control during run time to routines you designand write yourself. For example, you can write user exit routines to summarize,insert, delete, shorten, or otherwise alter records during processing. However, keepin mind that the extensive editing capabilities provided by the INCLUDE, OMIT,INREC, OUTREC, SUM, and OUTFIL statements can eliminate the need to writeuser exit routines. You can write your own routines to correct I/O errors thatDFSORT does not handle, or to perform any necessary abnormal end-of-taskoperation before DFSORT terminates.

You can write an EFS (Extended Function Support) program to intercept DFSORTcontrol statements and PARM options for modification prior to use by DFSORT orto provide alternate sequence support for user-defined data.

You can define and use a symbol for any field, constant, or output column that isrecognized in a DFSORT control statement or ICETOOL operator. This makes iteasy to create and reuse collections of symbols (that is, mappings) representinginformation associated with various record layouts. You can use system symbols(for example, &JOBNAME.) in your symbol constants. You can use SET and PROCsymbols in your symbol constants. See Chapter 8, Using symbols for fields andconstants, on page 737.

DFSORT on the WebFor articles, online documents, news, tips, techniques, examples, and more, visitthe DFSORT Home Page (www.ibm.com/storage/dfsort).

DFSORT FTP siteYou can obtain DFSORT articles and examples via anonymous FTP to:ftp.software.ibm.com/storage/dfsort/mvs/

Invoking DFSORTYou can invoke DFSORT processing in the following ways:v With an EXEC job control statement in the input stream using the name of the

program (for example, PGM=ICEMAN or PGM=SORT) or the name of acataloged procedure (for example, SORTD). See Chapter 2, Invoking DFSORTwith Job Control Language, on page 29.TSO users can allocate the needed ddnames (for example, SYSOUT, SORTIN,SORTOUT and SYSIN), and invoke DFSORT using a calling method equivalentto PGM=ICEMAN. For example:

call *(iceman)

Restriction: TSO users cannot invoke DFSORT using:iceman

or any other alias for DFSORT (for example, SORT) in this form.

DFSORT Overview


http://www.ibm.com/storage/dfsort

See Chapter 11, Examples of DFSORT job streams, on page 825 for examples ofinvoking DFSORT from REXX and CLISTs.

v With a program written in basic assembler language using a system macroinstruction. See Chapter 6, Invoking DFSORT from a program, on page 547.

v With programs written in either COBOL or PL/I with a special facility of thelanguage. See the programmer's guide describing the compiler version availableat your location.

v With the ICETOOL utility. See Chapter 7, Using ICETOOL, on page 569.

In this document, the term directly invoked means that DFSORT is not initiated fromanother program. The term program invoked means that DFSORT is initiated fromanother program.

How DFSORT worksThis section contains a list of the operating systems supported by DFSORT and anexplanation of how DFSORT uses control fields and collating sequences to sort,merge, and copy the records of a data set.

The Blockset technique is DFSORT's most efficient technique for sorting, mergingand copying data sets. DFSORT uses the Blockset technique whenever possible totake advantage of its highly optimized internal algorithms and efficient utilizationof IBM hardware. If Blockset cannot be used, DFSORT uses another of itstechniques Peerage/Vale or Conventional.

Operating systemsDFSORT runs under control of your z/OS operating system and must be initiatedaccording to the appropriate conventions.

Additionally, DFSORT runs under z/OS when it is running as a guest underz/VM.

DFSORT is compatible with all of the IBM processors supported by z/OS. Inaddition to any device supported by z/OS for program residence, DFSORT alsooperates with any device QSAM or VSAM uses for input or output.

Control fields and collating sequencesYou define control fields to identify the information you want DFSORT to sort ormerge. When thinking of the contents of your data sets, you probably think ofnames, dates, account numbers, or similar pieces of useful information. Forexample, when sorting your data sets, you might choose to arrange your records inalphabetical order, by family name. By using the byte position and length (in bytes)of the portion of each record containing a family name, you can define it as acontrol field to manipulate with DFSORT.

DFSORT uses the control fields you define as keys in processing. A key is aconcept, such as family name, that you have in mind when you design a recordprocessing strategy for a particular application. A control field, on the other hand,is a discrete portion of a record that contains the text or symbols corresponding tothat information in a form that can be used by DFSORT to identify and sort, ormerge the records. For all practical purposes, you can think of keys as equivalentto the control fields DFSORT uses in processing.

Invoking DFSORT


To arrange your records in a specific order, identify one or more control fields ofyour records to use as keys. The sequence in which you list the control fieldsbecomes the order of priority DFSORT uses to arrange your records. The firstcontrol field you specify is called the major control field. Subsequent control fieldsare called minor control fields, as in first, second, third minor control fields, and soon.

If two or more records have identical values for the first control field, they arearranged according to the values in the second. Records with identical values forthe first and second are arranged according to the third, and so on, until adifference is found or no more control fields are available.

Records with identical values for all the control fields specified retain their originalinput order or are arranged randomly, depending upon which of the two options,EQUALS or NOEQUALS, is in effect. You can direct DFSORT to retain the originalinput order for records with identical values for all control fields by specifyingEQUALS.

Control fields may overlap, or be contained within other control fields (such as athree-digit area code, within a 10-digit telephone number). They do not need to becontiguous but must be located within the first 32752 bytes of the record (seeFigure 1).

DFSORT offers several standard collating sequences. You can choose to arrange yourrecords according to these standard collating sequences or according to a collatingsequence defined in the active locale. Conceptually, a collating sequence is aspecific arrangement of character priority used to determine which of two valuesin the same control field of two different records should come first. DFSORT usesEBCDIC, the standard IBM collating sequence, or the ASCII collating sequencewhen sorting or merging records. If locale processing is in effect, DFSORT will usethe collating sequence defined in the active locale.

The collating sequence for character data and binary data is absolute; character andbinary fields are not interpreted as having signs. For packed decimal, zoneddecimal, fixed-point, normalized floating-point, and the signed numeric dataformats, collating is algebraic; each quantity is interpreted as having an algebraicsign.

You can modify the standard EBCDIC sequence to collate differently if, forexample, you want to allow alphabetic collating of national characters. An alternatecollating sequence can be defined with the ALTSEQ installation option, or you candefine it yourself at run-time with the ALTSEQ program control statement. You canalso specify a modified collating sequence with an E61 user exit or with an EFSprogram.

Controlfield 3

Controlfield 4

Control field 1(major)

Controlfield 2

Record

Figure 1. Control Fields. Control fields may overlap, or be contained within other control fields.

How DFSORT Works


You can specify the LOCALE installation or run-time option to use an activelocale's collating rules.

Cultural environment considerationsDFSORT's collating behavior can be modified according to your culturalenvironment. Your cultural environment is defined to DFSORT using the X/Open**locale model. A locale is a collection of data grouped into categories that describesthe information about your cultural environment.

The collate category of a locale is a collection of sequence declarations that definesthe relative order between collating elements (single character and multi-charactercollating elements). The sequence declarations define the collating rules.

The cultural environment is established by selecting the active locale. The activelocale affects the behavior of locale-sensitive functions. In particular, the activelocale's collating rules affect DFSORT's SORT, MERGE, INCLUDE, and OMITprocessing as follows:v Sort and Merge

DFSORT produces sorted or merged records for output according to the collatingrules defined in the active locale. This provides sorting and merging for single-or multi-byte character data based on defined collating rules that retain thecultural and local characteristics of a language.

v Include and OmitDFSORT includes or omits records for output according to the collating rulesdefined in the active locale. This provides inclusion or omission for single- ormulti-byte character data based on defined collating rules that retain the culturaland local characteristics of a language.

Note: Locale processing is not used for IFTRAIL TRLID or IFTHEN WHEN,BEGIN or END constants or compare fields.

The DFSORT option LOCALE specifies whether locale processing is to be usedand, if so, designates the active locale. Only one locale can be active at a time forany DFSORT application.

UnicodeThe Unicode Standard provides a single character set that covers the languages ofthe world, and a small number of machine-friendly encoding forms and schemesto fit the needs of existing applications and protocols. It is designed for bestinteroperability with both ASCII and ISO-8859-1, the most widely used charactersets, to make it easier for Unicode to be used in applications and protocols.

A special number is assigned to every single character. You can refer to TheUnicode Consortium (www.unicode.org) to find out more about Unicode. You canfind the code charts, which show you which number is assigned to whichcharacter within the Unicode standard on the Unicode Character Code Charts(www.unicode.org/charts). If you prefer to have a list of all available characters onyour workstation so that you do not have to be online every time you want to finda specific character in the Unicode code page, you can download the UnibookCharacter Browser (www.unicode.org/unibook).

Currently, the following three forms of Unicode encoding are supported:

UTF8:

How DFSORT Works


|

|||||

||||||||

|

||

http://www.unicode.orghttp://www.unicode.orghttp://www.unicode.org/chartshttp://www.unicode.org/chartshttp://www.unicode.org/unibookhttp://www.unicode.org/unibook

Unicode Transformation Format in 8 bits that uses 1 to 4 bytes, dependingon the character.

UTF16:

Unicode Transformation Format in 16 bits that uses either 2 or 4 bytes torepresent a character.

UTF32:

Unicode Transformation Format in 32 bits.

Unicode Environment ConsiderationsDFSORT's Unicode Collation behavior can be modified according to your culturalenvironment. A new COLLKEY parameter allows specifying the Unicode standardcharacter suite for national collation sequences. Your Unicode environment isdefined to DFSORT using the COLLKEY=value

Collation supports customization, which means that collation service might behaveaccording to some specific collation rules. Collation rules can be specified using aLocale or User Collation Rules (UCR).

The active collation rules affects the behavior of locale-sensitive functions. Inparticular, the active locale's collating rules affect DFSORT's SORT and MERGEprocessing as follows:

Sort and Merge

DFSORT produces sorted or merged records for output according to thecollating rules defined in the active locale. This provides sorting andmerging for single-or multi-byte character data based on defined collatingrules that retain the cultural and local characteristics of a language.

For supported Locales settings, see Appendix E. Locales for collation in z/OSUnicode Services User's Guide and Reference

DFSORT processingYou must prepare job control language (JCL) statements and DFSORT programcontrol statements to invoke DFSORT processing. JCL statements (see Chapter 6,Invoking DFSORT from a program, on page 547) are processed by youroperating system. They describe your data sets to the operating system and initiateDFSORT processing. DFSORT program control statements (see Chapter 3, UsingDFSORT program control statements, on page 83) are processed by the DFSORTprogram. They describe the functions you want to perform and invoke theprocessing you request.

A sort application usually requires intermediate storage as working space duringthe program run. This storage can be one of the following:1. Hiperspace, using DFSORT's Hipersorting feature.2. Work data setseither allocated dynamically by DFSORT's DYNALLOC facility

or specified by the user, using JCL DD statements. If specified by the user, theintermediate storage devices and the amount of work space must be indicated.Methods for determining the amount of work space to allocate are explained inAppendix A, Using work space, on page 859.

3. A combination of Hiperspace and work data sets.

Merge and copy applications do not require intermediate storage.

Cultural Environment Considerations


||

|

||

|

|

|

||||

|||

|||

|

||||

||

Figure 2 on page 10 illustrates the processing order for record handling, exits,statements, and options. Use this diagram with the text following it to understandthe order DFSORT uses to run your job.

DFSORT Processing


As shown in Figure 2, DFSORT processing follows this order:

Figure 2. Record Processing Order

DFSORT Processing


1. DFSORT first checks whether you supplied a SORTIN data set for SORT andCOPY jobs or SORTINnn data sets for MERGE jobs. If so, DFSORT reads theinput records from them.v If no SORTIN data set is present for a SORT or COPY job, you must use an

E15 user exit to insert all the records. (This is also true if you invokeDFSORT from a program with the address of an E15 user exit in theparameter list, because SORTIN will be ignored.) DFSORT can use aCOBOL E15 routine if you specified the E15 user exit in the MODSstatement.

v If no SORTINnn data sets are present for a MERGE job, you must use anE32 user exit to insert all the records.

2. If input records for SORT or COPY jobs are read from a SORTIN data set,DFSORT performs processing specified with the SKIPREC option. DFSORTdeletes records until the SKIPREC count is satisfied. Eliminating recordsbefore a SORT or COPY gives better performance.

3. If the input records for a SORT or COPY job are read from a SORTIN data set,DFSORT checks whether you specified an E15 user exit. If so, DFSORTtransfers control to the user exit routine. You can use a COBOL E15 routine ifthe E15 user exit is specified in the MODS statement. The E15 routine caninsert, delete, or reformat records.

4. DFSORT performs processing specified on an INCLUDE or OMIT statement.If you used an E15 user exit routine to reformat the records, theINCLUDE/OMIT fields you specify must apply to the current format ratherthan to the original format. If you use the INCLUDE or OMIT statements todelete unnecessary records before SORT, MERGE, or COPY processing, yourjobs run more efficiently.

5. For SORT or COPY jobs, DFSORT performs processing specified with theSTOPAFT option. Record input stops after the maximum number of records(n) you specify have been accepted. DFSORT accepts records for processing ifthey are:v Read from SORTIN or inserted by E15v Not deleted by SKIPRECv Not deleted by E15v Not deleted by an INCLUDE or OMIT statement.

6. DFSORT performs processing specified in an INREC statement. Data recordsare parsed, edited and reformatted according to the options specified. If youreformatted the records before this step, the INREC fields you specify mustapply to the current format rather than to the original format.

7. DFSORT performs processing specified in the SORT, MERGE, or OPTIONCOPY statement.v For SORT, all input records are processed before any output record is

processed.v For COPY or MERGE, an output record is processed after an input record is

processed.v For SORT or MERGE, if a SUM statement is present, DFSORT processes it

during the SORT or MERGE processing. DFSORT summarizes the recordsand deletes duplicates. If you reformatted the records before this step, theSORT or MERGE and SUM fields you specify must apply to the currentformat rather than to the original format.

8. DFSORT performs processing specified in an OUTREC statement. Datarecords are parsed, edited and reformatted according to the options specified.

DFSORT Processing


If you reformatted the records before this step, the OUTREC fields you specifymust apply to the current format rather than to the original format.

9. If an E35 user exit is present, DFSORT transfers control to your user exitroutine after all statement processing (except OUTFIL) is completed. If youreformatted the records, the E35 user exit receives the records in the currentformat rather than in the original format. You can use a COBOL E35 routine ifyou specify the E35 user exit in the MODS statement. You can use the E35 exitroutine to add, delete, or reformat records.If SORTOUT and OUTFIL data sets are not present, the E35 exit must disposeof all the records because DFSORT treats these records as deleted. (This is alsotrue if you do not specify OUTFIL data sets and DFSORT is invoked with theaddress of an E35 user exit in the parameter list, because SORTOUT will beignored.)

10. DFSORT writes your records to the SORTOUT data set, if present.11. DFSORT performs processing specified in one or more OUTFIL statements, if

present:v DFSORT performs processing specified with the STARTREC, SAMPLE, and

ENDREC options. Record input for the OUTFIL data sets starts with therecord indicated by STARTREC, ends with the record indicated byENDREC, and is sampled according to the records indicated by SAMPLE.

v DFSORT performs processing specified with the INCLUDE, OMIT, or SAVEoption. Records are included or omitted from the OUTFIL data setsaccording to the criteria specified.

v DFSORT performs processing specified with the ACCEPT option. Recordprocessing ends when the ACCEP

z/OS DFSORT Application Programming Guide · E61 user exit: modifying contr ol fields ... . 513...

Documents

Transcript of z/OS DFSORT Application Programming Guide · E61 user exit: modifying contr ol fields ... . 513...